renweimeng/vlun-agent-xVulnAgent-X: Um Framework Agêntico em Camadas para Detecção de Vulnerabilidades em Nível de Repositório
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.
repo path ou unified diffscreening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusionissue_typelocation(file + line range)evidence_summaryconfidenceseverityoptional_cwefix_hintevidence_chaincounter_evidencescreening: triagem rápida de regiões suspeitas (regras + sinais de metadados)context_expansion: recupera o "contexto mínimo suficiente" (extrai janelas ao redor das localizações suspeitas)scheduler: aplica estratégias de escalonamento com base em confiança e risco (early_exit / expert_review / verification)router_agent: seleciona um Agent especialista para cada região suspeitasemantic/security/logic: fornecem alegações e evidências estruturadas sob diferentes perspectivassceptic_agent: gera contraprovas e sinais de penalizaçãoverification: verificação dinâmica opcional (atualmente uma implementação stub segura)evidence_fusion: realiza a fusão unificada e gera os findings finaisRequisitos: 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]'
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
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"}'
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": []
}
| 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). |
src/vulnagentx)| Arquivo | Finalidade |
|---|---|
src/vulnagentx/__init__.py | Definição da versão e das exportações do pacote. |
src/vulnagentx/app/__init__.py | Inicialização do subpacote app. |
src/vulnagentx/app/cli.py | Ponto de entrada da CLI (vulnagentx analyze). |
src/vulnagentx/app/api.py | Ponto de entrada do serviço FastAPI (/health, /analyze). |
src/vulnagentx/app/schemas.py | Schemas Pydantic de requisição/resposta da API. |
src/vulnagentx/core/__init__.py | Inicialização do subpacote core. |
src/vulnagentx/core/state.py | Modelo de estado global: regiões, evidências, saídas dos Agents, Findings, logs e métricas. |
src/vulnagentx/core/screening.py | Triagem rápida da primeira fase; extrai regiões suspeitas. |
src/vulnagentx/core/context_expansion.py | Expansão de contexto: extrai janelas mínimas de código ao redor das localizações. |
src/vulnagentx/core/scheduler.py | Estratégia de escalonamento ciente da confiança (early_exit/expert_review/verification). |
src/vulnagentx/core/verification.py | Módulo de verificação dinâmica opcional (atualmente uma versão stub segura). |
src/vulnagentx/core/evidence_fusion.py | Fusão de evidências de múltiplos Agents; gera os findings finais. |
src/vulnagentx/core/workflow.py | Ponto de entrada de orquestração de ponta a ponta VulnAgentWorkflow. |
src/vulnagentx/agents/__init__.py | Agregação das exportações dos Agents. |
src/vulnagentx/agents/base.py | Classe base abstrata dos Agents e utilitários de obtenção de contexto. |
src/vulnagentx/agents/router_agent.py | Agent roteador: atribui um Agent especialista a cada região suspeita. |
tests)| Arquivo | Finalidade |
|---|---|
tests/test_agents.py | Testes unitários: saídas estruturadas de cada Agent e lógica de contraprovas. |
tests/test_end_to_end.py | Teste de ponta a ponta: fluxo principal do repositório de entrada até os findings finais. |
tests/test_research_modules.py | Testes dos novos módulos: construção do grafo com Tree-sitter, cadeia de execução da verification e métricas de avaliação. |
OpenAI + Ollama local + alternância automática via factorysrc/vulnagentx/agents/semantic_agent.py |
| Agent semântico: riscos na camada semântica (ex.: ponteiro nulo, desserialização, exceções engolidas). |
src/vulnagentx/agents/security_agent.py | Agent de segurança: regras de vulnerabilidades de segurança (injeção de comandos, injeção de SQL, estouro de limites etc.). |
src/vulnagentx/agents/logic_bug_agent.py | Agent de lógica: defeitos de negócio/fluxo de controle (limites, divisão por zero, autorização ausente etc.). |
src/vulnagentx/agents/sceptic_agent.py | Agent cético: gera contraprovas, penaliza conflitos e reduz a confiança. |
src/vulnagentx/adapters/__init__.py | Inicialização do subpacote de adaptadores. |
src/vulnagentx/adapters/sandbox_adapter.py | Executor de sandbox em subprocesso restrito (com timeout, sem shell) usado para a verification. |
src/vulnagentx/adapters/semgrep_adapter.py | Adaptador da CLI do Semgrep (habilitação opcional). |
src/vulnagentx/adapters/treesitter_adapter.py | Adaptador real de Tree-sitter (analisa AST e relações de chamadas/importações quando disponível; faz fallback quando indisponível). |
src/vulnagentx/adapters/llm/__init__.py | Agregação das exportações dos adaptadores LLM. |
src/vulnagentx/adapters/llm/base.py | Interface de protocolo dos adaptadores LLM. |
src/vulnagentx/adapters/llm/mock_adapter.py | LLM Mock testável offline. |
src/vulnagentx/adapters/llm/openai_adapter.py | Adaptador do SDK oficial da OpenAI. |
src/vulnagentx/adapters/llm/local_adapter.py | Adaptador para modelos locais (API HTTP do Ollama). |
src/vulnagentx/adapters/llm/factory.py | Seleciona automaticamente o adaptador LLM conforme a configuração e faz fallback para o Mock. |
src/vulnagentx/retrieval/repo_graph.py | Índice do grafo de código e recuperação de arquivos vizinhos (com base na sobreposição de símbolos da AST). |
src/vulnagentx/datasets/base.py | Estrutura genérica de amostras de datasets e leitura de JSONL/CSV. |
src/vulnagentx/datasets/devign.py | Ponto de entrada de carregamento dos dados Devign. |
src/vulnagentx/datasets/bigvul.py | Ponto de entrada de carregamento dos dados Big-Vul. |
src/vulnagentx/datasets/primevul.py | Ponto de entrada de carregamento dos dados PrimeVul. |
src/vulnagentx/datasets/jit.py | Ponto de entrada de carregamento dos dados JIT. |
src/vulnagentx/eval/detection_metrics.py | Métricas de detecção (Precision/Recall/F1/Accuracy). |
src/vulnagentx/eval/localization_metrics.py | Métricas de localização (Top-1/Top-3/MRR). |
src/vulnagentx/eval/efficiency_metrics.py | Métricas de eficiência (tempo médio, P95, média de findings). |
src/vulnagentx/eval/ablations.py | Lógica de execução dos experimentos de ablação. |
src/vulnagentx/utils/config.py | Centro de configuração do fluxo de trabalho (chaves via env/CLI/API). |