renweimeng/vlun-agent-xVulnAgent-X: Un framework agentico a strati per il rilevamento di vulnerabilità a livello di repository
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.
repo path o unified diffscreening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusionissue_typelocation(file + line range)evidence_summaryconfidenceseverityoptional_cwefix_hintevidence_chaincounter_evidencescreening: screening rapido delle aree sospette (regole + segnali dai metadati)context_expansion: recupero del "contesto minimo sufficiente" (estrazione di finestre basate sulle posizioni sospette)scheduler: strategie di escalation basate su confidenza e rischio (early_exit / expert_review / verification)router_agent: seleziona l'Agent esperto per ogni area sospettasemantic/security/logic: forniscono affermazioni strutturate e prove da diverse prospettivesceptic_agent: genera controprove e segnali di penalizzazioneverification: verifica dinamica opzionale (attualmente implementazione segnaposto sicura)evidence_fusion: fusione unificata delle prove e output dei findings finaliRequisiti: 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]'
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
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"}'
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": []
}
| 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). |
src/vulnagentx)| File | Scopo |
|---|---|
src/vulnagentx/__init__.py | Definizione della versione del pacchetto e delle esportazioni. |
src/vulnagentx/app/__init__.py | Inizializzazione del sottopacchetto app. |
src/vulnagentx/app/cli.py | Entry point CLI (vulnagentx analyze). |
src/vulnagentx/app/api.py | Entry point del servizio FastAPI (/health, /analyze). |
src/vulnagentx/app/schemas.py | Schema Pydantic per richieste/risposte API. |
src/vulnagentx/core/__init__.py | Inizializzazione del sottopacchetto core. |
src/vulnagentx/core/state.py | Modello dello stato globale: regioni, prove, output degli Agent, Finding, log, metriche. |
src/vulnagentx/core/screening.py | Screening rapido della prima fase, estrazione delle aree sospette. |
src/vulnagentx/core/context_expansion.py | Espansione del contesto: estrazione delle finestre di codice minime in base alla localizzazione. |
src/vulnagentx/core/scheduler.py | Strategie di escalation sensibili alla confidenza (early_exit/expert_review/verification). |
src/vulnagentx/core/verification.py | Modulo di verifica dinamica opzionale (attualmente versione segnaposto sicura). |
src/vulnagentx/core/evidence_fusion.py | Fusione delle prove dei molteplici Agent, output dei findings finali. |
src/vulnagentx/core/workflow.py | Entry point di orchestrazione end-to-end VulnAgentWorkflow. |
src/vulnagentx/agents/__init__.py | Aggregazione delle esportazioni degli Agent. |
src/vulnagentx/agents/base.py | Classe base astratta degli Agent e utility per l'acquisizione del contesto. |
src/vulnagentx/agents/router_agent.py | Agent di routing: assegna un Agent esperto a ogni area sospetta. |
tests)| File | Scopo |
|---|---|
tests/test_agents.py | Unit test: output strutturati dei singoli Agent e logica delle controprove. |
tests/test_end_to_end.py | Test end-to-end: flusso principale dal repository in input ai findings finali. |
tests/test_research_modules.py | Test dei moduli aggiunti: costruzione del grafo Tree-sitter, catena di esecuzione di verification, metriche di valutazione. |
OpenAI + Ollama locale + commutazione automatica tramite factorysrc/vulnagentx/agents/semantic_agent.py | Agent semantico: rischi a livello semantico (es. puntatori nulli, deserializzazione, eccezioni inghiottite). |
src/vulnagentx/agents/security_agent.py | Agent di sicurezza: regole per vulnerabilità di sicurezza (command injection, SQL injection, accessi fuori dai limiti, ecc.). |
src/vulnagentx/agents/logic_bug_agent.py | Agent logico: difetti di logica di business/flusso di controllo (condizioni limite, divisione per zero, autorizzazioni mancanti, ecc.). |
src/vulnagentx/agents/sceptic_agent.py | Agent scettico: genera controprove, penalizzazioni per conflitti e riduzione della confidenza. |
src/vulnagentx/adapters/__init__.py | Inizializzazione del sottopacchetto degli adapter. |
src/vulnagentx/adapters/sandbox_adapter.py | Esecutore sandbox per sottoprocessi limitato (timeout, niente shell) utilizzato per verification. |
src/vulnagentx/adapters/semgrep_adapter.py | Adapter per la CLI di Semgrep (attivabile opzionalmente). |
src/vulnagentx/adapters/treesitter_adapter.py | Adapter Tree-sitter reale (analizza l'AST e le relazioni di chiamata/import quando disponibile; in caso contrario effettua un fallback). |
src/vulnagentx/adapters/llm/__init__.py | Aggregazione delle esportazioni degli adapter LLM. |
src/vulnagentx/adapters/llm/base.py | Interfaccia protocollo dell'adapter LLM. |
src/vulnagentx/adapters/llm/mock_adapter.py | Mock LLM testabile offline. |
src/vulnagentx/adapters/llm/openai_adapter.py | Adapter per l'SDK ufficiale OpenAI. |
src/vulnagentx/adapters/llm/local_adapter.py | Adapter per modelli locali (Ollama HTTP API). |
src/vulnagentx/adapters/llm/factory.py | Seleziona automaticamente l'adapter LLM in base alla configurazione, con fallback al Mock. |
src/vulnagentx/retrieval/repo_graph.py | Indice del grafo del codice e recupero dei file vicini (basato sulla sovrapposizione dei simboli AST). |
src/vulnagentx/datasets/base.py | Struttura generica dei campioni del dataset e lettura di file JSONL/CSV. |
src/vulnagentx/datasets/devign.py | Entry point per il caricamento dei dati Devign. |
src/vulnagentx/datasets/bigvul.py | Entry point per il caricamento dei dati Big-Vul. |
src/vulnagentx/datasets/primevul.py | Entry point per il caricamento dei dati PrimeVul. |
src/vulnagentx/datasets/jit.py | Entry point per il caricamento dei dati JIT. |
src/vulnagentx/eval/detection_metrics.py | Metriche di rilevamento (Precision/Recall/F1/Accuracy). |
src/vulnagentx/eval/localization_metrics.py | Metriche di localizzazione (Top-1/Top-3/MRR). |
src/vulnagentx/eval/efficiency_metrics.py | Metriche di efficienza (tempo medio, P95, findings medi). |
src/vulnagentx/eval/ablations.py | Logica di esecuzione degli esperimenti di ablazione. |
src/vulnagentx/utils/config.py | Centro di configurazione del flusso di lavoro (opzioni abilitabili via env/CLI/API). |