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

Arquivo	Finalidade
.env.example	Modelo de variáveis de ambiente (configurações opcionais, como nível de log).
pyproject.toml	Build do projeto, dependências, entradas de scripts e configuração de pytest/ruff/mypy.
README.md	README principal (com botões de troca de idioma; padrão: chinês).
README.zh.md	Documentação completa em chinês.
README.en.md	Documentação completa em inglês.
docker/Dockerfile	Arquivo de construção da imagem do contêiner do serviço de API.
docker/docker-compose.yml	Sobe os serviços de contêiner localmente com um clique.
rules/semgrep/vulnagentx-rules.yml	Conjunto de regras Semgrep integradas (injeção de comandos/injeção de SQL/desserialização/API C insegura).
scripts/run_experiment.py	Script de execução de experimentos em lote sobre datasets; gera predições em JSONL.
scripts/evaluate.py	Lê as saídas dos experimentos e calcula métricas de detecção/localização/eficiência.
scripts/run_ablation.py	Script de experimentos de ablação (no_semgrep/no_treesitter/no_sceptic/no_verification).

Código-fonte principal (src/vulnagentx)