renweimeng/vlun-agent-xVulnAgent-X: Ein mehrschichtiges agentisches Framework zur Schwachstellenerkennung auf Repository-Ebene
VulnAgent-X ist ein Multi-Agenten-Prototyp zur Erkennung von Schwachstellen/Fehlern, ausgerichtet auf die Reproduktion von Forschungsergebnissen (Paper-Reproduktion). Eingabe ist ein lokales Repository oder ein Diff; ausgegeben werden strukturierte Findings, Beweisketten, Lokalisierungsergebnisse, Konfidenzen und Experiment-Logs.
repo path oder unified diffscreening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusionissue_typelocation(file + line range)evidence_summaryconfidenceseverityoptional_cwefix_hintevidence_chaincounter_evidencescreening: Schnelles Screening verdächtiger Bereiche (Regeln + Metadaten-Signale)context_expansion: Abruf des „minimal hinreichenden Kontexts“ (Extrahieren von Fenstern anhand verdächtiger Stellen)scheduler: Eskalationsstrategie auf Basis von Konfidenz und Risiko (early_exit / expert_review / verification)router_agent: Auswahl eines Experten-Agenten für jeden verdächtigen Bereichsemantic/security/logic: liefern strukturierte Behauptungen und Beweise aus unterschiedlichen Perspektivensceptic_agent: erzeugt Gegenbeweise und Bestrafungssignaleverification: optionale dynamische Verifikation (derzeit als sicherer Platzhalter implementiert)evidence_fusion: einheitliche Fusion und Ausgabe der endgültigen FindingsVoraussetzung: Python 3.11+ (läuft derzeit auch mit neueren Versionen)
cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
Gesamtes Repository analysieren:
.venv/bin/vulnagentx analyze --repo /path/to/repo --output json
Diff-Datei analysieren:
.venv/bin/vulnagentx analyze --diff-file /path/to/patch.diff --output json
Kurzausgabe:
.venv/bin/vulnagentx analyze --repo /path/to/repo --output summary
Dienst starten:
.venv/bin/uvicorn vulnagentx.app.api:app --reload
Health-Check:
curl http://127.0.0.1:8000/health
Analyse starten:
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": []
}
| Datei | Zweck |
|---|---|
.env.example | Vorlage für Umgebungsvariablen (optionale Einstellungen wie Log-Level). |
pyproject.toml | Projekt-Build, Abhängigkeiten, Skript-Einstiegspunkte, pytest/ruff/mypy-Konfiguration. |
README.md | Haupt-README (mit Sprachumschalter, Standard: Chinesisch). |
README.zh.md | Vollständige Dokumentation auf Chinesisch. |
README.en.md | Vollständige Dokumentation auf Englisch. |
docker/Dockerfile | Build-Datei für das API-Service-Container-Image. |
docker/docker-compose.yml | Startet die Container-Dienste lokal mit einem Befehl. |
rules/semgrep/vulnagentx-rules.yml | Integrierter Semgrep-Regelsatz (Befehlsinjektion/SQL-Injektion/Deserialisierung/unsichere C-API). |
scripts/run_experiment.py | Skript zur Ausführung von Batch-Experimenten auf Datensätzen; gibt Vorhersagen als JSONL aus. |
scripts/evaluate.py | Liest Experimentausgaben und berechnet Erkennungs-/Lokalisierungs-/Effizienzmetriken. |
scripts/run_ablation.py | Skript für Ablationsstudien (no_semgrep/no_treesitter/no_sceptic/no_verification). |
src/vulnagentx)| Datei | Zweck |
|---|---|
src/vulnagentx/__init__.py | Paketversion und Exportdefinitionen. |
src/vulnagentx/app/__init__.py | Initialisierung des app-Unterpakets. |
src/vulnagentx/app/cli.py | CLI-Einstiegspunkt (vulnagentx analyze). |
src/vulnagentx/app/api.py | Einstiegspunkt für den FastAPI-Dienst (/health, /analyze). |
src/vulnagentx/app/schemas.py | Pydantic-Schemas für API-Anfragen/-Antworten. |
src/vulnagentx/core/__init__.py | Initialisierung des core-Unterpakets. |
src/vulnagentx/core/state.py | Globales Zustandsmodell: Bereiche, Beweise, Agenten-Ausgaben, Findings, Logs, Metriken. |
src/vulnagentx/core/screening.py | Schnelles Screening in Phase 1; extrahiert verdächtige Bereiche. |
src/vulnagentx/core/context_expansion.py | Kontexterweiterung: extrahiert minimale Code-Fenster anhand der Lokalisierung. |
src/vulnagentx/core/scheduler.py | Konfidenzbewusste Eskalationsstrategie (early_exit/expert_review/verification). |
src/vulnagentx/core/verification.py | Optionales dynamisches Verifikationsmodul (derzeit sichere Platzhalterversion). |
src/vulnagentx/core/evidence_fusion.py | Multi-Agenten-Beweisfusion; gibt die endgültigen Findings aus. |
src/vulnagentx/core/workflow.py | End-to-End-Orchestrierungseinstiegspunkt VulnAgentWorkflow. |
src/vulnagentx/agents/__init__.py | Aggregation der Agenten-Exporte. |
src/vulnagentx/agents/base.py | Abstrakte Basisklasse für Agenten und Werkzeuge zur Kontextabfrage. |
src/vulnagentx/agents/router_agent.py | Routing-Agent: weist jedem verdächtigen Bereich einen Experten-Agenten zu. |
tests)| Datei | Zweck |
|---|---|
tests/test_agents.py | Unit-Tests: strukturierte Ausgaben und Gegenbeweislogik der einzelnen Agenten. |
tests/test_end_to_end.py | End-to-End-Tests: Hauptablauf vom Eingabe-Repository bis zu den endgültigen Findings. |
tests/test_research_modules.py | Tests für neue Module: Tree-sitter-Graphaufbau, Verifikations-Ausführungskette, Bewertungsmetriken. |
OpenAI + lokales Ollama + automatischer Factory-Wechselsrc/vulnagentx/agents/semantic_agent.py| Semantik-Agent: Risiken auf semantischer Ebene (z. B. Nullzeiger, Deserialisierung, verschluckte Ausnahmen). |
src/vulnagentx/agents/security_agent.py | Sicherheits-Agent: Regeln für Sicherheitsschwachstellen (Befehlsinjektion, SQL-Injektion, Bereichsüberschreitung usw.). |
src/vulnagentx/agents/logic_bug_agent.py | Logik-Agent: Geschäfts-/Kontrollflussfehler (Grenzfälle, Division durch Null, fehlende Autorisierung usw.). |
src/vulnagentx/agents/sceptic_agent.py | Skeptiker-Agent: erzeugt Gegenbeweise, Konfliktbestrafung, senkt die Konfidenz. |
src/vulnagentx/adapters/__init__.py | Initialisierung des Adapter-Unterpakets. |
src/vulnagentx/adapters/sandbox_adapter.py | Eingeschränkter Subprozess-Sandbox-Executor (Timeout, kein Shell) für die Verifikation. |
src/vulnagentx/adapters/semgrep_adapter.py | Semgrep-CLI-Adapter (optional aktivierbar). |
src/vulnagentx/adapters/treesitter_adapter.py | Echter Tree-sitter-Adapter (parst AST sowie Aufruf-/Importbeziehungen, falls verfügbar; andernfalls Degradierung). |
src/vulnagentx/adapters/llm/__init__.py | Aggregation der LLM-Adapter-Exporte. |
src/vulnagentx/adapters/llm/base.py | Protokollschnittstelle für LLM-Adapter. |
src/vulnagentx/adapters/llm/mock_adapter.py | Offline testbarer Mock-LLM. |
src/vulnagentx/adapters/llm/openai_adapter.py | Adapter für das offizielle OpenAI-SDK. |
src/vulnagentx/adapters/llm/local_adapter.py | Adapter für lokale Modelle (Ollama-HTTP-API). |
src/vulnagentx/adapters/llm/factory.py | Wählt den LLM-Adapter automatisch anhand der Konfiguration aus und fällt auf den Mock zurück. |
src/vulnagentx/retrieval/repo_graph.py | Code-Graph-Index und Abruf benachbarter Dateien (basierend auf AST-Symbolüberlappung). |
src/vulnagentx/datasets/base.py | Allgemeine Datensatz-Stichprobenstruktur und JSONL/CSV-Lesen. |
src/vulnagentx/datasets/devign.py | Datenlade-Einstiegspunkt für Devign. |
src/vulnagentx/datasets/bigvul.py | Datenlade-Einstiegspunkt für Big-Vul. |
src/vulnagentx/datasets/primevul.py | Datenlade-Einstiegspunkt für PrimeVul. |
src/vulnagentx/datasets/jit.py | Datenlade-Einstiegspunkt für JIT. |
src/vulnagentx/eval/detection_metrics.py | Erkennungsmetriken (Precision/Recall/F1/Accuracy). |
src/vulnagentx/eval/localization_metrics.py | Lokalisierungsmetriken (Top-1/Top-3/MRR). |
src/vulnagentx/eval/efficiency_metrics.py | Effizienzmetriken (durchschnittliche Laufzeit, P95, durchschnittliche Findings). |
src/vulnagentx/eval/ablations.py | Ausführungslogik für Ablationsstudien. |
src/vulnagentx/utils/config.py | Workflow-Konfigurationszentrum (env/CLI/API-Schalter). |