VulnAgent-X Prototipo di Ricerca

VulnAgent-X è un prototipo di rilevamento di vulnerabilità/difetti multi-agente orientato alla riproduzione di paper di ricerca. Accetta in input un repository locale o un diff e produce in output findings strutturati, catena di prove, risultati di localizzazione, confidenza e log degli esperimenti.

Funzionalità principali

• Modalità di input: repo path o unified diff
• Flusso di lavoro: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• Campi di output:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• Interfacce: CLI + FastAPI
• Esperimenti riproducibili: pytest / mypy / ruff + supporto all'esecuzione con Docker

Panoramica del flusso di lavoro

1. screening: screening rapido delle aree sospette (regole + segnali dai metadati)
2. context_expansion: recupero del "contesto minimo sufficiente" (estrazione di finestre basate sulle posizioni sospette)
3. scheduler: strategie di escalation basate su confidenza e rischio (early_exit / expert_review / verification)
4. router_agent: seleziona l'Agent esperto per ogni area sospetta
5. semantic/security/logic: forniscono affermazioni strutturate e prove da diverse prospettive
6. sceptic_agent: genera controprove e segnali di penalizzazione
7. verification: verifica dinamica opzionale (attualmente implementazione segnaposto sicura)
8. evidence_fusion: fusione unificata delle prove e output dei findings finali

Guida all'installazione e all'esecuzione

1) Preparazione dell'ambiente

Requisiti: Python 3.11+ (attualmente funziona anche su versioni più recenti)

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

2) Utilizzo della CLI

Analizza un intero repository:

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

Analizza un file di diff:

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

Output sintetico:

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

3) Utilizzo dell'API

Avvia il servizio:

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

Health check:

curl http://127.0.0.1:8000/health

Avvia un'analisi:

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

4) Esecuzione con Docker

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

5) Controllo di qualità e test

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

Esempio di output

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

Descrizione dei file (file per file)

File nella directory radice e file di progetto

File	Scopo
.env.example	Template delle variabili d'ambiente (impostazioni opzionali come il livello di log).
pyproject.toml	Build del progetto, dipendenze, entry point degli script, configurazione di pytest/ruff/mypy.
README.md	README principale (con pulsante di cambio lingua, default cinese).
README.zh.md	Documentazione completa in cinese.
README.en.md	Documentazione completa in inglese.
docker/Dockerfile	File di build dell'immagine container del servizio API.
docker/docker-compose.yml	Avvio locale dei servizi containerizzati con un comando.
rules/semgrep/vulnagentx-rules.yml	Set di regole Semgrep integrato (command injection/SQL injection/deserializzazione/API C non sicure).
scripts/run_experiment.py	Script per l'esecuzione di esperimenti batch sui dataset; produce previsioni in JSONL.
scripts/evaluate.py	Legge gli output degli esperimenti e calcola le metriche di rilevamento, localizzazione ed efficienza.
scripts/run_ablation.py	Script per gli esperimenti di ablazione (no_semgrep/no_treesitter/no_sceptic/no_verification).

Codice sorgente principale (src/vulnagentx)