Prototipo de investigación de VulnAgentX

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.

Capacidades principales

• Forma de entrada: repo path o unified diff
• Flujo de trabajo: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• Campos de salida:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• Interfaz: CLI + FastAPI
• Experimentos reproducibles: pytest / mypy / ruff + soporte de ejecución con Docker

Resumen del flujo de trabajo

1. screening: detección rápida de regiones sospechosas (reglas + señales de metadatos)
2. context_expansion: obtiene el «contexto mínimo suficiente» (extrae ventanas según las ubicaciones sospechosas)
3. scheduler: aplica una estrategia de escalado basada en la confianza y el riesgo (early_exit / expert_review / verification)
4. router_agent: selecciona un Agente experto para cada región sospechosa
5. semantic/security/logic: proporcionan afirmaciones estructuradas y evidencia desde diferentes perspectivas
6. sceptic_agent: genera contraevidencia y señales de penalización
7. verification: verificación dinámica opcional (actualmente una implementación segura provisional)
8. evidence_fusion: fusiona de forma unificada y emite los hallazgos finales

Guía de instalación y ejecución

1) Preparación del entorno

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

2) Uso de la CLI

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

3) Uso de la API

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

4) Ejecución con Docker

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

5) Control de calidad y pruebas

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

Ejemplo de salida

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

Descripción de los archivos (archivo por archivo)

Archivos raíz y del proyecto

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

Código fuente principal (src/vulnagentx)