socbench

Benchmark de modelos de raciocínio de fronteira como agentes SOC em dados brutos de NetFlow.

socbench avalia modelos de raciocínio de fronteira como agentes SOC: cada modelo executa um loop agente multi-turno limitado contra um corpus NetFlow determinístico e pré-indexado, com ferramentas somente leitura com escopo de persona, limites de dólar fixos por investigação e um contrato JSON de resposta final estrito. Quatro personas (Analista SOC, Analista de Ameaças, Caçador de Adversários, Engenheiro de Detecção) e três provedores (OpenAI, Anthropic, Google) compartilham as mesmas unidades de avaliação, lentes de pontuação e superfície de ablação, de modo que os números principais e os deltas tools_off / playbooks_off são diretamente comparáveis.

O repositório é local-first. Um laptop, três chaves de API e uma amostra parquet comprometida no repositório são suficientes para reproduzir um smoke com orçamento inferior a US$ 10.

Status

Alfa. O pipeline completo é executado de ponta a ponta. O desenvolvimento planejado abrange:

• Passo 1: esqueleto do pacote, contratos, configurações, esquema
• Passo 2: o construtor de índices (socbench build-index) com índices determinísticos endereçados por conteúdo
• Passo 3: camada de ferramentas somente leitura com lista de permissões de persona + construtor de amostra
• Passo 4: personas, playbooks, composição de prompt + verificação de token proibido
• Passo 5: adaptadores de provedor (OpenAI / Anthropic / Gemini + mock sempre ativo) e o loop agente multi-turno com limites de orçamento e resumos de custo/latência
• Passo 6: pontuação (F1 por fluxo / por par / por host), amostragem estratificada, agregação de ablação
• Passo 7: notebooks quickstart + explorador de resultados; instruções de reprodução em REPRODUCE.md

Você pode executar um smoke completo hoje sem chaves de API por meio do provedor mock (consulte o Quickstart passo 3 ou notebooks/quickstart.ipynb).

Instalar

socbench é distribuído como um projeto PEP 621 / hatchling padrão. Qualquer caminho de instalação funciona.

Com uv (recomendado para desenvolvimento)

curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/DeepTempo/socbench.git
cd socbench

uv venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[dev,providers]"

Com pip simples

git clone https://github.com/DeepTempo/socbench.git
cd socbench

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,providers]"

De qualquer forma, socbench --help agora deve listar os subcomandos disponíveis.

Configuração

config/benchmark_config.yaml vem com padrões seguros: smoke cost_budget_usd: 10, full cost_budget_usd: 900, fixo cost_usd_cap_per_rendering: 0.50. Os caminhos dentro dele que apontam para arquivos de configuração irmãos (schema_path, pricing_path) são resolvidos relativos ao próprio diretório do YAML, portanto, renomear ou realocar config/ não requer edições de código.

Quickstart

1. Construir um índice endereçado por conteúdo a partir de um dataset parquet

socbench build-index \
  --config config/benchmark_config.yaml \
  --dataset sample

Isso normaliza o parquet em relação a config/schema.json, ordena globalmente por ts_start com desempate determinístico, atribui flow_ids estáveis, deriva as unidades de avaliação pair_timeline / host_egress, calcula rollups e escreve em indexes/<dataset_hash>/.

Executar novamente o comando nos mesmos dados não faz nada. Passe --rebuild para forçar uma reconstrução.

2. Inspecionar a camada de ferramentas

socbench tools-smoke \
  --dataset-hash <dataset_hash> \
  --persona soc_analyst

Isso invoca todas as ferramentas na lista de permissões da persona contra o índice construído e imprime um resumo, sem chamadas de modelo.

3. Executar o benchmark

# Gratuito, determinístico, sem chaves de API (provedor mock):
socbench run --dataset-hash <dataset_hash> --providers mock --personas all

# Modelos reais (após `pip install -e ".[providers]"` + exportar chaves de API):
socbench run --dataset-hash <dataset_hash> --providers all --personas all

A seleção de unidade padrão é amostragem estratificada, determinística em (dataset_hash, sample_seed, mode). Cada renderização (unidade × persona × provider) executa um loop agente multi-turno limitado; os resultados vão para runs/<run_id>/ com summary.json (rollups de pontuação + custo + cache), eval_units_summary.jsonl, predictions_raw.jsonl, renderings.jsonl, tool_calls.jsonl e prompts_used/.

4. Executar ablações e agregar os deltas

socbench run --dataset-hash <dataset_hash> --ablation tools_off --providers mock --personas all
socbench aggregate --dataset-hash <dataset_hash>
# → ablations/<dataset_hash>/<seed>/ablation_summary.json  (tools_off → deltas principais)

5. Explorar

notebooks/quickstart.ipynb executa o loop completo (ele sintetiza um dataset de amostra, portanto não precisa de dados comprometidos) e plota o F1 por persona. notebooks/results_explorer.ipynb carrega qualquer runs/<run_id>/ e fatia os resultados por estrato, persona e provedor. Instale com pip install -e ".[notebooks]".

Estendendo o benchmark

Toda interface projetada para evoluir é um registro ou uma chave YAML:

• Nova ferramenta: coloque um novo arquivo em src/socbench/tools/catalog/<name>.py com uma subclasse de Tool, registre-o em src/socbench/tools/catalog/__init__.py anexando a ALL_TOOLS, depois adicione seu nome às listas tools: da persona apropriada em config/benchmark_config.yaml. O tools_manifest_sha é alterado automaticamente. Nome do arquivo, nome YAML e entrada da matriz são 1:1 por design.
• Novo tipo de unidade de avaliação: adicione um assigner a src/socbench/index.py e um Literal correspondente a EvalUnitType em src/socbench/models.py.
• Novo adaptador de provedor: implemente o ABC Adapter em um novo , registre-o na fábrica em e adicione uma entrada em em . Os preços vão em . As importações de SDK permanecem lentas para que a dependência seja opcional.

Metodologia

A metodologia completa (unidades de avaliação, matriz persona × ferramenta, loop agente, pontuação, modelo de custo, política de reparo, amostragem, ablações, artefatos de execução) é implementada nos arquivos de nível de módulo em src/socbench/ (cada um carrega uma docstring de módulo focada).

Licença

Apache-2.0. Veja LICENSE.