Protótipo de Pesquisa VulnAgent-X

VulnAgent-X é um protótipo de detecção de vulnerabilidades/defeitos baseado em múltiplos Agents, voltado à reprodução de pesquisas acadêmicas. A entrada é um repositório local ou um diff, e a saída inclui findings estruturados, cadeia de evidências, resultados de localização, confiança e logs de experimentos.

Capacidades principais

• Forma de entrada: repo path ou unified diff
• Fluxo de trabalho: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• Campos de saída:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• Interface: CLI + FastAPI
• Experimentos reproduzíveis: pytest / mypy / ruff + suporte a execução via Docker

Visão geral do fluxo de trabalho

1. screening: triagem rápida de regiões suspeitas (regras + sinais de metadados)
2. context_expansion: recupera o "contexto mínimo suficiente" (extrai janelas ao redor das localizações suspeitas)
3. scheduler: aplica estratégias de escalonamento com base em confiança e risco (early_exit / expert_review / verification)
4. router_agent: seleciona um Agent especialista para cada região suspeita
5. semantic/security/logic: fornecem alegações e evidências estruturadas sob diferentes perspectivas
6. sceptic_agent: gera contraprovas e sinais de penalização
7. verification: verificação dinâmica opcional (atualmente uma implementação stub segura)
8. evidence_fusion: realiza a fusão unificada e gera os findings finais

Tutorial de instalação e execução

1) Preparação do ambiente

Requisitos: Python 3.11+ (também é executado em versões mais recentes)

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

2) Uso via CLI

Analisar o repositório inteiro:

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

Analisar um arquivo de diff:

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

Saída resumida:

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

3) Uso da API

Iniciar o serviço:

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

Verificação de integridade (health check):

curl http://127.0.0.1:8000/health

Enviar uma análise:

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

4) Execução com Docker

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

5) Verificação de qualidade e testes

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

Exemplo de saída

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

Explicação da finalidade dos arquivos (arquivo por arquivo)

Diretório raiz e arquivos do projeto

Código-fonte principal (src/vulnagentx)

Arquivos de teste (tests)

Módulos de aprimoramento implementados nesta versão

• Adaptadores LLM reais: OpenAI + Ollama local + alternância automática via factory
• AST real com Tree-sitter e grafo de código: analisa funções/importações/relações de chamadas e suporta expansão de contexto para arquivos vizinhos
• Conjunto real de regras Semgrep: arquivos de regras integrados e conectado à fase de screening
• Cadeia de execução da sandbox de verification: planejamento de tarefas, execução restrita, controle de timeout e gravação estruturada dos resultados
• Avaliação em datasets e ablação: carregadores de dados, módulos de métricas e scripts de experimentos e ablação