renweimeng/vlun-agent-xVulnAgent-X: Un framework agéntico en capas para la detección de vulnerabilidades a nivel de repositorio
VulnAgentX es un prototipo de detección de vulnerabilidades/defectos multi-agente orientado a la reproducción de investigaciones. Recibe un repositorio local o un diff como entrada y produce hallazgos estructurados, cadenas de evidencia, resultados de localización, niveles de confianza y registros de experimentos.
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: detección rápida de regiones sospechosas (reglas + señales de metadatos)context_expansion: obtiene el «contexto mínimo suficiente» (extrae ventanas según las ubicaciones sospechosas)scheduler: aplica una estrategia de escalado basada en la confianza y el riesgo (early_exit / expert_review / verification)router_agent: selecciona un Agente experto para cada región sospechosasemantic/security/logic: proporcionan afirmaciones estructuradas y evidencia desde diferentes perspectivassceptic_agent: genera contraevidencia y señales de penalizaciónverification: verificación dinámica opcional (actualmente una implementación segura provisional)evidence_fusion: fusiona de forma unificada y emite los hallazgos finalesRequisitos: Python 3.11+ (también funciona en versiones superiores)
cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
Analizar un repositorio completo:
.venv/bin/vulnagentx analyze --repo /path/to/repo --output json
Analizar un archivo diff:
.venv/bin/vulnagentx analyze --diff-file /path/to/patch.diff --output json
Salida resumida:
.venv/bin/vulnagentx analyze --repo /path/to/repo --output summary
Iniciar el servicio:
.venv/bin/uvicorn vulnagentx.app.api:app --reload
Comprobación de estado:
curl http://127.0.0.1:8000/health
Iniciar un análisis:
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": []
}
| Archivo | Propósito |
|---|---|
.env.example | Plantilla de variables de entorno (configuración opcional como el nivel de registro). |
pyproject.toml | Construcción del proyecto, dependencias, entradas de scripts, configuración de pytest/ruff/mypy. |
README.md | README principal (con botón de cambio de idioma, chino por defecto). |
README.zh.md | Documentación completa en chino. |
README.en.md | Documentación completa en inglés. |
docker/Dockerfile | Archivo de construcción de la imagen de contenedor del servicio API. |
docker/docker-compose.yml | Levanta el servicio de contenedores localmente con un solo comando. |
rules/semgrep/vulnagentx-rules.yml | Conjunto de reglas Semgrep integradas (inyección de comandos/inyección SQL/deserialización/API C insegura). |
scripts/run_experiment.py | Script de ejecución de experimentos por lotes sobre datasets, genera predicciones en JSONL. |
scripts/evaluate.py | Lee la salida de los experimentos y calcula métricas de detección/localización/eficiencia. |
scripts/run_ablation.py | Script de experimentos de ablación (no_semgrep/no_treesitter/no_sceptic/no_verification). |
src/vulnagentx)| Archivo | Propósito |
|---|---|
src/vulnagentx/__init__.py | Definición de la versión del paquete y sus exportaciones. |
src/vulnagentx/app/__init__.py | Inicialización del subpaquete app. |
src/vulnagentx/app/cli.py | Entrada de la CLI (vulnagentx analyze). |
src/vulnagentx/app/api.py | Entrada del servicio FastAPI (/health, /analyze). |
src/vulnagentx/app/schemas.py | Esquemas Pydantic de solicitudes/respuestas de la API. |
src/vulnagentx/core/__init__.py | Inicialización del subpaquete core. |
src/vulnagentx/core/state.py | Modelo de estado global: regiones, evidencia, salidas de los Agentes, hallazgos, registros y métricas. |
src/vulnagentx/core/screening.py | Detección rápida de la primera fase, extrae regiones sospechosas. |
src/vulnagentx/core/context_expansion.py | Expansión de contexto: extrae ventanas de código mínimas según la localización. |
src/vulnagentx/core/scheduler.py | Estrategia de escalado consciente de la confianza (early_exit/expert_review/verification). |
src/vulnagentx/core/verification.py | Módulo de verificación dinámica opcional (actualmente una versión segura provisional). |
src/vulnagentx/core/evidence_fusion.py | Fusión de evidencia de múltiples Agentes, emite los hallazgos finales. |
src/vulnagentx/core/workflow.py | Entrada de orquestación de extremo a extremo VulnAgentWorkflow. |
src/vulnagentx/agents/__init__.py | Agregación de exportaciones de los Agentes. |
src/vulnagentx/agents/base.py | Clase base abstracta del Agente y utilidades de obtención de contexto. |
src/vulnagentx/agents/router_agent.py | Agente de enrutamiento: asigna un Agente experto a cada región sospechosa. |
tests)| Archivo | Propósito |
|---|---|
tests/test_agents.py | Pruebas unitarias: salidas estructuradas de cada Agente y lógica de contraevidencia. |
tests/test_end_to_end.py | Pruebas de extremo a extremo: flujo principal desde el repositorio de entrada hasta los hallazgos finales. |
tests/test_research_modules.py | Pruebas de los nuevos módulos: construcción del grafo Tree-sitter, cadena de ejecución de la verificación y métricas de evaluación. |
OpenAI + Ollama local + conmutación automática mediante fábricasrc/vulnagentx/agents/semantic_agent.py | Agente semántico: riesgos a nivel semántico (p. ej., punteros nulos, deserialización, excepciones tragadas). |
src/vulnagentx/agents/security_agent.py | Agente de seguridad: reglas de vulnerabilidades de seguridad (inyección de comandos, inyección SQL, fuera de límites, etc.). |
src/vulnagentx/agents/logic_bug_agent.py | Agente de lógica: defectos de negocio/flujo de control (límites, división por cero, falta de autorización, etc.). |
src/vulnagentx/agents/sceptic_agent.py | Agente escéptico: genera contraevidencia, penalizaciones por conflicto y reduce la confianza. |
src/vulnagentx/adapters/__init__.py | Inicialización del subpaquete de adaptadores. |
src/vulnagentx/adapters/sandbox_adapter.py | Ejecutor de sandbox de subprocesos restringidos (timeout, sin shell) para la verificación. |
src/vulnagentx/adapters/semgrep_adapter.py | Adaptador de la CLI de Semgrep (activación opcional). |
src/vulnagentx/adapters/treesitter_adapter.py | Adaptador real de Tree-sitter (analiza el AST y las relaciones de llamadas/importaciones cuando está disponible; degrada si no lo está). |
src/vulnagentx/adapters/llm/__init__.py | Agregación de exportaciones de adaptadores LLM. |
src/vulnagentx/adapters/llm/base.py | Interfaz de protocolo del adaptador LLM. |
src/vulnagentx/adapters/llm/mock_adapter.py | LLM simulado (Mock) comprobable sin conexión. |
src/vulnagentx/adapters/llm/openai_adapter.py | Adaptador del SDK oficial de OpenAI. |
src/vulnagentx/adapters/llm/local_adapter.py | Adaptador de modelo local (API HTTP de Ollama). |
src/vulnagentx/adapters/llm/factory.py | Selecciona automáticamente el adaptador LLM según la configuración y recurre a Mock como respaldo. |
src/vulnagentx/retrieval/repo_graph.py | Índice de grafo de código y recuperación de archivos vecinos (basado en solapamiento de símbolos del AST). |
src/vulnagentx/datasets/base.py | Estructura de muestras de dataset genérica y lectura de JSONL/CSV. |
src/vulnagentx/datasets/devign.py | Entrada de carga de datos de Devign. |
src/vulnagentx/datasets/bigvul.py | Entrada de carga de datos de Big-Vul. |
src/vulnagentx/datasets/primevul.py | Entrada de carga de datos de PrimeVul. |
src/vulnagentx/datasets/jit.py | Entrada de carga de datos de JIT. |
src/vulnagentx/eval/detection_metrics.py | Métricas de detección (Precision/Recall/F1/Accuracy). |
src/vulnagentx/eval/localization_metrics.py | Métricas de localización (Top-1/Top-3/MRR). |
src/vulnagentx/eval/efficiency_metrics.py | Métricas de eficiencia (tiempo medio, P95, media de hallazgos). |
src/vulnagentx/eval/ablations.py | Lógica de ejecución de experimentos de ablación. |
src/vulnagentx/utils/config.py | Centro de configuración del flujo de trabajo (interruptores env/CLI/API). |