deeptempo/socbenchUn arnés y punto de referencia abiertos para la IA en operaciones de ciberseguridad.
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.
Alfa. El pipeline completo funciona de punta a punta. El desarrollo cubre:
socbench build-index) con índices
deterministas direccionados por contenidoREPRODUCE.mdPuede ejecutar un smoke completo hoy sin claves API mediante el proveedor
mock (consulte Inicio rápido paso 3, o notebooks/quickstart.ipynb).
socbench se distribuye como un proyecto estándar PEP 621 / hatchling.
Cualquiera de las rutas de instalación funciona.
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]"
pip simplegit 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.
| Superficie | Valor por defecto | Ubicación |
|---|---|---|
| Valores predeterminados del benchmark (muestreo, presupuestos de agente, proveedores, matriz persona × herramienta) | benchmark_config.yaml | config/ |
| Esquema canónico de NetFlow + alias de normalización | schema.json | config/ |
| Instantánea de precios del proveedor (USD por 1M tokens) | pricing.yaml | config/ |
| Claves API de proveedores | variables de entorno OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY | shell env |
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.
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.
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.
# 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/.
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)
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]".
Cada interfaz diseñada para evolucionar es un registro o una clave YAML:
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.src/socbench/index.py y un Literal correspondiente a EvalUnitType
en src/socbench/models.py.Adapter en un nuevo
src/socbench/providers/<name>_adapter.py, regístrelo en la fábrica
build_adapter en providers/base.py, y añada una entrada en providers:
en config/benchmark_config.yaml. Los precios van en config/pricing.yaml.
Las importaciones del SDK se mantienen perezosas para que la dependencia sea
opcional.agent.personas: en
config/benchmark_config.yaml con su presupuesto y lista blanca tools:.score_unit en
src/socbench/scoring.py y un campo correspondiente a EvalUnitSummary
en models.py.Ablation en prompts.py /
agent.py y la lista de etiquetas en aggregate.py.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).
Apache-2.0. Ver LICENSE.