VulnAgent-X Forschungsprototyp

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.

Kernfunktionen

• Eingabeform: repo path oder unified diff
• Workflow: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• Ausgabefelder:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• Schnittstellen: CLI + FastAPI
• Reproduzierbare Experimente: pytest / mypy / ruff + Unterstützung für Docker-Ausführung

Workflow-Übersicht

1. screening: Schnelles Screening verdächtiger Bereiche (Regeln + Metadaten-Signale)
2. context_expansion: Abruf des „minimal hinreichenden Kontexts“ (Extrahieren von Fenstern anhand verdächtiger Stellen)
3. scheduler: Eskalationsstrategie auf Basis von Konfidenz und Risiko (early_exit / expert_review / verification)
4. router_agent: Auswahl eines Experten-Agenten für jeden verdächtigen Bereich
5. semantic/security/logic: liefern strukturierte Behauptungen und Beweise aus unterschiedlichen Perspektiven
6. sceptic_agent: erzeugt Gegenbeweise und Bestrafungssignale
7. verification: optionale dynamische Verifikation (derzeit als sicherer Platzhalter implementiert)
8. evidence_fusion: einheitliche Fusion und Ausgabe der endgültigen Findings

Installations- und Nutzungsanleitung

1) Umgebungsvorbereitung

Voraussetzung: 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]'

2) CLI-Nutzung

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

3) API-Nutzung

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"}'

4) Ausführung mit Docker

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

5) Qualitätsprüfung und Tests

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

Beispielausgabe

{
  "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": []
}

Dateibeschreibungen (Datei für Datei)

Root-Verzeichnis und Projektdateien

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).

Kernquellcode (src/vulnagentx)