socbench

Evalúa modelos de razonamiento de frontera como agentes SOC sobre datos NetFlow en bruto.

socbench evalúa modelos de razonamiento de frontera como agentes SOC: cada modelo ejecuta un bucle de agente multi-turno acotado contra un corpus NetFlow determinista e indexado previamente, con herramientas de solo lectura con ámbito de persona, límites fijos de dólar por investigación y un contrato JSON de respuesta final estricta. Cuatro personas (Analista SOC, Analista de Amenazas, Cazador de Adversarios, Ingeniero de Detección) y tres proveedores (OpenAI, Anthropic, Google) comparten las mismas unidades de evaluación, lentes de puntuación y superficie de ablación, por lo que los números principales y los deltas tools_off / playbooks_off son directamente comparables.

El repositorio es local-first. Un portátil, tres claves API y un parquet de muestra incluido en el repo son suficientes para reproducir un smoke por menos de $10.

Estado

Alfa. El pipeline completo funciona de punta a punta. El desarrollo cubre:

• Paso 1: esqueleto del paquete, contratos, configuraciones, esquema
• Paso 2: el constructor de índices (socbench build-index) con índices deterministas direccionados por contenido
• Paso 3: capa de herramientas de solo lectura con lista blanca de persona
  • generador de muestras
• Paso 4: personas, playbooks, composición de prompt + verificación de tokens prohibidos
• Paso 5: adaptadores de proveedor (OpenAI / Anthropic / Gemini + mock siempre activo) y el bucle de agente multi-turno con límites de presupuesto y resúmenes de costo/latencia
• Paso 6: puntuación (F1 por flujo / por par / por host), muestreo estratificado, agregación de ablaciones
• Paso 7: cuaderno de inicio rápido y explorador de resultados; instrucciones de reproducción en REPRODUCE.md

Puede ejecutar un smoke completo hoy sin claves API mediante el proveedor mock (consulte Inicio rápido paso 3, o notebooks/quickstart.ipynb).

Instalación

socbench se distribuye como un proyecto estándar PEP 621 / hatchling. Cualquiera de las rutas de instalación funciona.

Con uv (recomendado para desarrollo)

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]"

Con pip simple

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 cualquier forma, socbench --help debería listar los subcomandos disponibles.

Configuración

config/benchmark_config.yaml trae valores seguros por defecto: smoke cost_budget_usd: 10, completo cost_budget_usd: 900, fijo cost_usd_cap_per_rendering: 0.50. Las rutas internas que apuntan a archivos de configuración hermanos (schema_path, pricing_path) se resuelven relativas al propio directorio del YAML, por lo que renombrar o reubicar config/ no requiere cambios en el código.

Inicio rápido

1. Construir un índice direccionado por contenido a partir de un dataset parquet

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

Esto normaliza el parquet contra config/schema.json, ordena globalmente por ts_start con desempate determinista, asigna flow_ids estables, deriva unidades de evaluación pair_timeline / host_egress, calcula resúmenes y escribe en indexes/<dataset_hash>/.

Volver a ejecutar el comando sobre los mismos datos no tiene efecto. Pase --rebuild para forzar la reconstrucción.

2. Inspeccionar la capa de herramientas

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

Esto invoca cada herramienta en la lista blanca de la persona contra el índice construido e imprime un resumen, sin llamadas a modelos.

3. Ejecutar el benchmark

# Gratuito, determinista, sin claves API (proveedor mock):
socbench run --dataset-hash <dataset_hash> --providers mock --personas all

# Modelos reales (tras `pip install -e ".[providers]"` y exportar las claves API):
socbench run --dataset-hash <dataset_hash> --providers all --personas all

La selección de unidades por defecto usa muestreo estratificado, determinista en (dataset_hash, sample_seed, mode). Cada renderizado (unit × persona × provider) ejecuta un bucle de agente multi-turno acotado; los resultados se guardan en runs/<run_id>/ con summary.json (puntuación + costo + resúmenes de caché), eval_units_summary.jsonl, predictions_raw.jsonl, renderings.jsonl, tool_calls.jsonl y prompts_used/.

4. Ejecutar ablaciones y agregar los 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 principales)

5. Explorar

notebooks/quickstart.ipynb ejecuta el bucle completo (sintetiza un dataset de muestra, por lo que no necesita datos comprometidos) y grafica F1 por persona. notebooks/results_explorer.ipynb carga cualquier runs/<run_id>/ y segmenta los resultados por estrato, persona y proveedor. Instale con pip install -e ".[notebooks]".

Ampliar el benchmark

Cada interfaz diseñada para evolucionar es un registro o una clave YAML:

• Nueva herramienta: coloque un nuevo archivo en src/socbench/tools/catalog/<name>.py con una subclase de Tool, regístrelo en src/socbench/tools/catalog/__init__.py añadiéndolo a ALL_TOOLS, luego agregue su nombre a las listas tools: de la persona correspondiente en config/benchmark_config.yaml. El tools_manifest_sha cambia automáticamente. El nombre del archivo, el nombre en YAML y la entrada en la matriz son 1:1 por diseño.
• Nuevo tipo de unidad de evaluación: agregue un asignador en src/socbench/index.py y un Literal correspondiente a EvalUnitType en src/socbench/models.py.
• Nuevo adaptador de proveedor: implemente el ABC Adapter en un nuevo , regístrelo en la fábrica en , y añada una entrada en en . Los precios van en . Las importaciones del SDK se mantienen perezosas para que la dependencia sea opcional.

Metodología

La metodología completa (unidades de evaluación, matriz persona × herramienta, bucle de agente, puntuación, modelo de costos, política de reparación, muestreo, ablaciones, artefactos de ejecución) está implementada en los archivos a nivel de módulo en src/socbench/ (cada uno lleva un docstring de módulo enfocado).

Licencia

Apache-2.0. Ver LICENSE.