renweimeng/vlun-agent-xVulnAgent-X: रिपॉजिटरी-स्तरीय भेद्यता पहचान के लिए एक स्तरित एजेंटिक फ्रेमवर्क
VulnAgent-X एक पेपर पुनरुत्पादन-उन्मुख मल्टी-एजेंट भेद्यता/दोष डिटेक्शन प्रोटोटाइप है। यह स्थानीय रिपॉजिटरी या diff इनपुट लेता है, और संरचित findings, साक्ष्य श्रृंखला, स्थानीकरण परिणाम, आत्मविश्वास स्कोर और प्रयोग लॉग आउटपुट करता है।
repo path या unified diffscreening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusionissue_typelocation(file + line range)evidence_summaryconfidenceseverityoptional_cwefix_hintevidence_chaincounter_evidencescreening: संदिग्ध क्षेत्रों का त्वरित स्क्रीनिंग (नियम + मेटाडेटा सिग्नल)context_expansion: "न्यूनतम पर्याप्त संदर्भ" खींचना (संदिग्ध स्थानों के अनुसार विंडो निकालना)scheduler: आत्मविश्वास और जोखिम के आधार पर एस्केलेशन रणनीति (early_exit / expert_review / verification)router_agent: प्रत्येक संदिग्ध क्षेत्र के लिए विशेषज्ञ Agent चुननाsemantic/security/logic: विभिन्न दृष्टिकोणों से संरचित दावे और साक्ष्य देनाsceptic_agent: प्रतिपक्ष साक्ष्य (counter-evidence) और दंड सिग्नल उत्पन्न करनाverification: वैकल्पिक गतिशील सत्यापन (वर्तमान में सुरक्षित प्लेसहोल्डर कार्यान्वयन)evidence_fusion: एकीकृत रूप से फ़्यूज़ करना और अंतिम findings आउटपुट करनाआवश्यकता: Python 3.11+ (वर्तमान में उच्च संस्करणों पर भी चल सकता है)
cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
पूरे रिपॉजिटरी का विश्लेषण करें:
.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
सेवा प्रारंभ करें:
.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"}'
docker compose -f docker/docker-compose.yml up --build
.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)| फ़ाइल | उपयोग |
|---|---|
src/vulnagentx/__init__.py | पैकेज संस्करण और पैकेज एक्सपोर्ट परिभाषाएँ। |
src/vulnagentx/app/__init__.py | app उपपैकेज आरंभीकरण। |
src/vulnagentx/app/cli.py | CLI एंट्री पॉइंट (vulnagentx analyze)। |
src/vulnagentx/app/api.py | FastAPI सेवा एंट्री पॉइंट (/health, /analyze)। |
src/vulnagentx/app/schemas.py | API अनुरोध/प्रतिक्रिया के Pydantic Schema। |
src/vulnagentx/core/__init__.py | core उपपैकेज आरंभीकरण। |
src/vulnagentx/core/state.py | वैश्विक स्थिति मॉडल: क्षेत्र, साक्ष्य, Agent आउटपुट, Finding, लॉग, मीट्रिक्स। |
src/vulnagentx/core/screening.py | पहले चरण का त्वरित स्क्रीनिंग, संदिग्ध क्षेत्र निकालना। |
src/vulnagentx/core/context_expansion.py | संदर्भ विस्तार: स्थानीकरण के अनुसार न्यूनतम कोड विंडो निकालना। |
src/vulnagentx/core/scheduler.py | आत्मविश्वास-जागरूक एस्केलेशन रणनीति (early_exit/expert_review/verification)। |
src/vulnagentx/core/verification.py | वैकल्पिक गतिशील सत्यापन मॉड्यूल (वर्तमान में सुरक्षित प्लेसहोल्डर संस्करण)। |
src/vulnagentx/core/evidence_fusion.py | मल्टी-एजेंट साक्ष्य फ़्यूज़न, अंतिम findings आउटपुट। |
src/vulnagentx/core/workflow.py | एंड-टू-एंड ऑर्केस्ट्रेशन एंट्री VulnAgentWorkflow। |
src/vulnagentx/agents/__init__.py | Agent एक्सपोर्ट एग्रीगेशन। |
src/vulnagentx/agents/base.py | Agent एब्स्ट्रैक्ट बेस क्लास और संदर्भ प्राप्ति उपकरण। |
src/vulnagentx/agents/router_agent.py | रूटिंग Agent: प्रत्येक संदिग्ध क्षेत्र के लिए विशेषज्ञ Agent आवंटित करता है। |
src/vulnagentx/agents/semantic_agent.py | सिमेंटिक Agent: सिमेंटिक परत जोखिम (जैसे null pointer, डिसीरियलाइज़ेशन, अपवाद निगलना)। |
tests)| फ़ाइल | उपयोग |
|---|---|
tests/test_agents.py | यूनिट परीक्षण: प्रत्येक Agent का संरचित आउटपुट और प्रतिपक्ष तर्क। |
tests/test_end_to_end.py | एंड-टू-एंड परीक्षण: इनपुट रिपॉजिटरी से अंतिम findings तक का मुख्य प्रवाह। |
tests/test_research_modules.py | नए मॉड्यूल परीक्षण: Tree-sitter ग्राफ़ निर्माण, verification निष्पादन श्रृंखला, मूल्यांकन मीट्रिक्स। |
OpenAI + स्थानीय Ollama + स्वचालित फ़ैक्टरी स्विचिंगsrc/vulnagentx/agents/security_agent.py | सुरक्षा Agent: सुरक्षा भेद्यता नियम (कमांड इंजेक्शन, SQL इंजेक्शन, बाउंड्स से बाहर, आदि)। |
src/vulnagentx/agents/logic_bug_agent.py | लॉजिक Agent: व्यावसायिक/नियंत्रण-प्रवाह दोष (सीमाएँ, शून्य से विभाजन, अनुपस्थित प्राधिकरण, आदि)। |
src/vulnagentx/agents/sceptic_agent.py | संदेहवादी Agent: प्रतिपक्ष साक्ष्य, संघर्ष दंड, आत्मविश्वास में कमी उत्पन्न करता है। |
src/vulnagentx/adapters/__init__.py | एडेप्टर उपपैकेज आरंभीकरण। |
src/vulnagentx/adapters/sandbox_adapter.py | प्रतिबंधित सबप्रोसेस सैंडबॉक्स निष्पादक (टाइमआउट, कोई shell नहीं) verification के लिए। |
src/vulnagentx/adapters/semgrep_adapter.py | Semgrep CLI एडेप्टर (वैकल्पिक रूप से सक्षम)। |
src/vulnagentx/adapters/treesitter_adapter.py | वास्तविक Tree-sitter एडेप्टर (उपलब्ध होने पर AST तथा कॉल/इम्पोर्ट संबंध पार्स करता है, अनुपलब्ध होने पर डीग्रेड करता है)। |
src/vulnagentx/adapters/llm/__init__.py | LLM एडेप्टर एक्सपोर्ट एग्रीगेशन। |
src/vulnagentx/adapters/llm/base.py | LLM एडेप्टर प्रोटोकॉल इंटरफ़ेस। |
src/vulnagentx/adapters/llm/mock_adapter.py | ऑफ़लाइन परीक्षण योग्य Mock LLM। |
src/vulnagentx/adapters/llm/openai_adapter.py | OpenAI आधिकारिक SDK एडेप्टर। |
src/vulnagentx/adapters/llm/local_adapter.py | स्थानीय मॉडल एडेप्टर (Ollama HTTP API)। |
src/vulnagentx/adapters/llm/factory.py | कॉन्फ़िगरेशन के अनुसार स्वचालित रूप से LLM एडेप्टर चुनता है और Mock पर फ़ॉलबैक करता है। |
src/vulnagentx/retrieval/repo_graph.py | कोड ग्राफ़ इंडेक्स और पड़ोसी फ़ाइल पुनर्प्राप्ति (AST प्रतीक ओवरलैप पर आधारित)। |
src/vulnagentx/datasets/base.py | सामान्य डेटासेट नमूना संरचना और JSONL/CSV पढ़ना। |
src/vulnagentx/datasets/devign.py | Devign डेटा लोडिंग एंट्री। |
src/vulnagentx/datasets/bigvul.py | Big-Vul डेटा लोडिंग एंट्री। |
src/vulnagentx/datasets/primevul.py | PrimeVul डेटा लोडिंग एंट्री। |
src/vulnagentx/datasets/jit.py | JIT डेटा लोडिंग एंट्री। |
src/vulnagentx/eval/detection_metrics.py | डिटेक्शन मीट्रिक्स (Precision/Recall/F1/Accuracy)। |
src/vulnagentx/eval/localization_metrics.py | स्थानीकरण मीट्रिक्स (Top-1/Top-3/MRR)। |
src/vulnagentx/eval/efficiency_metrics.py | दक्षता मीट्रिक्स (औसत समय, P95, औसत findings)। |
src/vulnagentx/eval/ablations.py | एब्लेशन प्रयोग निष्पादन तर्क। |
src/vulnagentx/utils/config.py | वर्कफ़्लो कॉन्फ़िगरेशन केंद्र (env/CLI/API स्विच)। |