Do Controlado à Natureza: Avaliação de Agentes de Pentest no Mundo Real

Os agentes de pentest baseados em IA são cada vez mais credíveis como sistemas de segurança ofensiva, mas os benchmarks atuais ainda oferecem orientação limitada sobre quais sistemas terão melhor desempenho em alvos do mundo real. A maioria das avaliações existentes avalia e otimiza para objetivos predefinidos, como captura de bandeira, execução remota de código, reprodução de exploração ou similaridade de trajetória, em ambientes simplificados ou restritos. Esses benchmarks são valiosos para medir capacidades limitadas, mas não capturam adequadamente a complexidade, a exploração aberta e a tomada de decisão estratégica exigidas num pentest realista. Apresentamos um framework prático de avaliação que desloca a avaliação da conclusão de tarefas para a descoberta validada de vulnerabilidades, permitindo a avaliação em alvos suficientemente complexos que abrangem múltiplas superfícies de ataque e classes de vulnerabilidade. O framework combina ground-truth estruturado com correspondência semântica baseada em LLM para identificar vulnerabilidades, resolução bipartida para pontuar descobertas sob ambiguidade realista, manutenção contínua do ground-truth, avaliação repetida e cumulativa de agentes estocásticos, métricas de eficiência e seleção reduzida de conjuntos para experimentação sustentável. Esta metodologia amplia o estado da arte, permitindo uma comparação mais realista e operacionalmente informativa de agentes de pentest baseados em IA. Para permitir reprodutibilidade, também disponibilizamos ground-truth anotado por especialistas e código para o protocolo de avaliação proposto.

Pipeline de avaliação para ferramentas de teste de segurança. Compara as descobertas das ferramentas com conjuntos de dados ground-truth usando correspondência baseada em LLM e produz métricas de precisão, recall, F1 e F0.5.

Instalação

poetry install

Requer Python 3.11+ e Poetry instalado.

Início Rápido

# 1. Set your LLM API key
export OPENAI_API_KEY="..."

# 2. Run evaluation
ethibench evaluate ./my_experiment --dataset path/to/dataset.yaml

# 3. View results
cat ./my_experiment/evaluation_outputs/summary.md

Comandos CLI

ethibench evaluate

Executa o pipeline completo de avaliação num diretório de experimento.

ethibench evaluate <experiment_dir> --dataset <dataset.yaml> [options]

# Batch: evaluate all experiments in a folder
ethibench evaluate --parent-dir final_experiments/ --dataset <dataset.yaml>

# Force re-evaluation (ignore cached artifacts)
ethibench evaluate <experiment_dir> --dataset <dataset.yaml> --force

Argumentos:

• experiment_dir — (opcional) Diretório contendo os subdiretórios de alvo (ou subdiretórios run_* cada um com subdiretórios de alvo). Pode ser omitido ao usar --parent-dir.

Opções:

• --dataset, -d — (obrigatório) Caminho para o ficheiro YAML do conjunto de dados.
• --gt-dir, -g — Diretório do ground-truth. O padrão é gt/ junto ao YAML do conjunto de dados.
• --output-dir, -o — Diretório de saída. O padrão é evaluation_outputs/ dentro do diretório do experimento. Ignorado no modo batch.
• --replicates, -n — Número de réplicas de correspondência LLM (padrão: 1).
• --force, -f — Reexecuta todas as etapas, ignorando artefactos em cache. Por defeito, os resultados intermédios existentes (correspondências brutas, correspondências bipartidas, métricas) são reutilizados.
• --parent-dir, -p — Pasta principal contendo múltiplos diretórios de experimento a avaliar em lote. Todos os subdiretórios imediatos são tratados como experimentos.

O que faz:

1. Recolhe descobertas — examina subdiretórios de alvo (nome da pasta = target_id), carrega cada findings.jsonl, atribui subset_name a partir do YAML do conjunto de dados.
2. Correspondência LLM bruta — compara cada descoberta com cada entrada do ground-truth usando um LLM.
3. Correspondência bipartida — algoritmo Húngaro para encontrar a atribuição 1-para-1 ótima.
4. Métricas — calcula TP, FP, FN, duplicados, precisão, recall, F1, F0.5 e pontuação de severidade por subconjunto.
5. Agregação — faz a média entre réplicas e execuções, calcula o total ponderado/não ponderado.
6. Métricas de custo — carrega metrics.json por alvo se presente, agrega custo/token/duração.
7. Gráficos — gera gráficos PNG em evaluation_outputs/plots/.
8. Resumo — escreve evaluation_outputs/summary.md.

ethibench analyze

Executa ferramentas de análise sobre saídas de avaliação existentes.

ethibench analyze <experiment_dir> --dataset <dataset.yaml> [options]

# Batch: analyze all experiments and produce aggregated results
ethibench analyze --parent-dir final_experiments/ --dataset <dataset.yaml>

Argumentos:

• experiment_dir — (opcional) Diretório do experimento a analisar. Pode ser omitido ao usar --parent-dir.

Opções:

• --dataset, -d — (obrigatório) Caminho para o ficheiro YAML do conjunto de dados.
• --gt-dir, -g — Diretório do ground-truth. O padrão é gt/ junto ao YAML do conjunto de dados.
• --output-dir, -o — Diretório das saídas de avaliação. O padrão é evaluation_outputs/ dentro do diretório do experimento.
• --parent-dir, -p — Pasta principal contendo múltiplos diretórios de experimento a analisar em lote. Produz análise por experimento mais resultados agregados.

Saídas por experimento (evaluation_outputs/analysis/):

• duplicates.json — descobertas correspondidas na correspondência bruta mas removidas pela otimização bipartida.
• unmatched.json — descobertas sem correspondência no ground-truth (falsos positivos).
• statistics.json — estatísticas de cobertura do GT, distribuição de descobertas por GT.

Saídas agregadas (apenas com --parent-dir, em <parent-dir>/aggregated_analysis/):

• all_duplicates.jsonl — todas as descobertas duplicadas de todos os experimentos (JSONL, objetos completos de descoberta com campo experiment).
• all_false_positives.jsonl — todas as descobertas não correspondidas/falsos positivos de todos os experimentos (formato JSONL).
• gt_statistics_avg.json — cobertura média do GT por subconjunto, mais resumo de cobertura por experimento.

ethibench compare

Compara resultados de avaliação entre múltiplos experimentos, produzindo gráficos lado a lado e um relatório resumido. Cada experimento deve já ter saídas de avaliação (execute ethibench evaluate primeiro). Os rótulos são sempre os nomes dos diretórios.

# Explicit experiment directories
ethibench compare exp-gpt4o/ exp-claude/ --output-dir comparison/

# Auto-discover all experiments under a parent folder
ethibench compare --parent-dir all-experiments/ --output-dir comparison/

# Mix: explicit dirs + auto-discovery
ethibench compare exp-extra/ --parent-dir all-experiments/ --output-dir comparison/

Argumentos:

• experiment_dirs — (opcional) Um ou mais diretórios de experimento a incluir explicitamente.

Opções:

• --output-dir, -o — (obrigatório) Diretório de saída para os resultados da comparação.
• --parent-dir, -p — Pasta principal para descobrir automaticamente experimentos. Qualquer subdiretório imediato que contenha uma pasta evaluation_outputs/ é incluído, ordenado alfabeticamente. Pode ser combinado com experiment_dirs explícitos.

Saídas (em --output-dir):

• comparison.json — dados brutos da comparação para todos os experimentos.
• plots/ — gráficos PNG lado a lado.
• comparison.md — resumo em Markdown.
• pairwise_comparison.md — comparação estatística A/B par a par (top 4 experimentos por F1).
• pairwise_comparison.tex — versão LaTeX da tabela par a par.
• cumulative-analysis/ — (se existirem dados cumulativos) análise delta comparando F1 médio vs cumulativo, mais gráficos de comparação cumulativa.

Formatos de Ficheiro

Descobertas (findings.jsonl)