VulnAgent-X अनुसंधान प्रोटोटाइप

VulnAgent-X एक पेपर पुनरुत्पादन-उन्मुख मल्टी-एजेंट भेद्यता/दोष डिटेक्शन प्रोटोटाइप है। यह स्थानीय रिपॉजिटरी या diff इनपुट लेता है, और संरचित findings, साक्ष्य श्रृंखला, स्थानीकरण परिणाम, आत्मविश्वास स्कोर और प्रयोग लॉग आउटपुट करता है।

मुख्य क्षमताएँ

• इनपुट प्रारूप: repo path या unified diff
• वर्कफ़्लो: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• आउटपुट फ़ील्ड:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• इंटरफ़ेस: CLI + FastAPI
• पुनरुत्पादनीय प्रयोग: pytest / mypy / ruff + Docker रन सपोर्ट

वर्कफ़्लो अवलोकन

1. screening: संदिग्ध क्षेत्रों का त्वरित स्क्रीनिंग (नियम + मेटाडेटा सिग्नल)
2. context_expansion: "न्यूनतम पर्याप्त संदर्भ" खींचना (संदिग्ध स्थानों के अनुसार विंडो निकालना)
3. scheduler: आत्मविश्वास और जोखिम के आधार पर एस्केलेशन रणनीति (early_exit / expert_review / verification)
4. router_agent: प्रत्येक संदिग्ध क्षेत्र के लिए विशेषज्ञ Agent चुनना
5. semantic/security/logic: विभिन्न दृष्टिकोणों से संरचित दावे और साक्ष्य देना
6. sceptic_agent: प्रतिपक्ष साक्ष्य (counter-evidence) और दंड सिग्नल उत्पन्न करना
7. verification: वैकल्पिक गतिशील सत्यापन (वर्तमान में सुरक्षित प्लेसहोल्डर कार्यान्वयन)
8. evidence_fusion: एकीकृत रूप से फ़्यूज़ करना और अंतिम findings आउटपुट करना

स्थापना और चलाने के निर्देश

1) पर्यावरण तैयारी

आवश्यकता: Python 3.11+ (वर्तमान में उच्च संस्करणों पर भी चल सकता है)

cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

2) CLI उपयोग

पूरे रिपॉजिटरी का विश्लेषण करें:

.venv/bin/vulnagentx analyze --repo /path/to/repo --output json

diff फ़ाइल का विश्लेषण करें:

.venv/bin/vulnagentx analyze --diff-file /path/to/patch.diff --output json

संक्षिप्त आउटपुट:

.venv/bin/vulnagentx analyze --repo /path/to/repo --output summary

3) API उपयोग

सेवा प्रारंभ करें:

.venv/bin/uvicorn vulnagentx.app.api:app --reload

स्वास्थ्य जाँच:

curl http://127.0.0.1:8000/health

विश्लेषण आरंभ करें:

curl -X POST http://127.0.0.1:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"repo_path":"/path/to/repo"}'

4) Docker चलाना

docker compose -f docker/docker-compose.yml up --build

5) गुणवत्ता जाँच और परीक्षण

.venv/bin/ruff check src tests
.venv/bin/mypy src
.venv/bin/pytest

आउटपुट उदाहरण

{
  "run_id": "...",
  "findings": [
    {
      "issue_type": "command_injection",
      "location": {"file_path": "app.py", "start_line": 42, "end_line": 42},
      "evidence_summary": "Command execution surface detected...",
      "confidence": 0.87,
      "severity": "critical",
      "optional_cwe": "CWE-78",
      "fix_hint": "Avoid shell command composition...",
      "source_agents": ["security_agent", "semantic_agent"],
      "evidence_chain": [],
      "counter_evidence": []
    }
  ],
  "metrics": {
    "runtime_seconds": 0.07
  },
  "logs": []
}

फ़ाइल उपयोग विवरण (फ़ाइल-दर-फ़ाइल)

रूट निर्देशिका और प्रोजेक्ट फ़ाइलें

फ़ाइल	उपयोग
.env.example	पर्यावरण चर टेम्पलेट (लॉग स्तर जैसी वैकल्पिक सेटिंग्स)।
pyproject.toml	प्रोजेक्ट बिल्ड, निर्भरताएँ, स्क्रिप्ट एंट्री पॉइंट, pytest/ruff/mypy कॉन्फ़िगरेशन।
README.md	मुख्य README (भाषा स्विच बटन के साथ, डिफ़ॉल्ट चीनी)।
README.zh.md	चीनी पूर्ण संस्करण दस्तावेज़।
README.en.md	अंग्रेज़ी पूर्ण संस्करण दस्तावेज़।
docker/Dockerfile	API सेवा कंटेनर इमेज निर्माण फ़ाइल।
docker/docker-compose.yml	स्थानीय रूप से एक-क्लिक में कंटेनर सेवा शुरू करना।
rules/semgrep/vulnagentx-rules.yml	अंतर्निहित Semgrep नियम सेट (कमांड इंजेक्शन/SQL इंजेक्शन/डिसीरियलाइज़ेशन/असुरक्षित C API)।
scripts/run_experiment.py	डेटासेट बैच प्रयोग निष्पादन स्क्रिप्ट, भविष्यवाणी JSONL आउटपुट करती है।
scripts/evaluate.py	प्रयोग आउटपुट पढ़ता है और डिटेक्शन/स्थानीकरण/दक्षता मीट्रिक्स की गणना करता है।
scripts/run_ablation.py	एब्लेशन प्रयोग स्क्रिप्ट (no_semgrep/no_treesitter/no_sceptic/no_verification)।

मुख्य स्रोत कोड (src/vulnagentx)