socbench

Benchmark les LLMs de raisonnement de pointe en tant qu'agents SOC sur des données NetFlow brutes.

socbench benchmark les modèles de raisonnement de pointe en tant qu'agents SOC : chaque modèle exécute une boucle agent multi-tours limitée sur un corpus NetFlow déterministe et pré-indexé, avec des outils en lecture seule limités par persona, des plafonds de dollars fixes par investigation, et un contrat JSON de réponse finale strict. Quatre personas (Analyste SOC, Analyste Menace, Chasseur d'Adversaires, Ingénieur Détection) et trois fournisseurs (OpenAI, Anthropic, Google) partagent les mêmes unités d'évaluation, objectifs de notation et surface d'ablation, de sorte que les chiffres clés et les deltas tools_off / playbooks_off sont directement comparables.

Le dépôt est local-first. Un ordinateur portable, trois clés API et un échantillon parquet engagé dans le dépôt suffisent pour reproduire un test sous un budget de 10 $.

Status

Alpha. Le pipeline complet s'exécute de bout en bout. La construction couverte :

• Step 1 : squelette du paquet, contrats, configurations, schéma
• Step 2 : le constructeur d'index (socbench build-index) avec des index à adressage par contenu déterministes
• Step 3 : couche d'outils en lecture seule avec liste blanche de personas + constructeur d'échantillon
• Step 4 : personas, playbooks, composition de prompt + vérification des tokens interdits
• Step 5 : adaptateurs de fournisseurs (OpenAI / Anthropic / Gemini + mock toujours actif) et la boucle agent multi-tours avec plafonds de budget et cumuls de coûts/latence
• Step 6 : notation (F1 par flux / par paire / par hôte), échantillonnage stratifié, agrégation d'ablation
• Step 7 : notebooks quickstart + exploration des résultats ; instructions de reproduction dans REPRODUCE.md

Vous pouvez exécuter un test complet aujourd'hui sans clés API via le fournisseur mock (voir Quickstart étape 3, ou notebooks/quickstart.ipynb).

Install

socbench est fourni comme un projet standard PEP 621 / hatchling. Les deux méthodes d'installation fonctionnent.

With uv (recommended for development)

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

With plain pip

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

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

Dans les deux cas, socbench --help devrait maintenant lister les sous-commandes disponibles.

Configuration

config/benchmark_config.yaml est livré avec des valeurs par défaut sûres : smoke cost_budget_usd: 10, full cost_budget_usd: 900, fixed cost_usd_cap_per_rendering: 0.50. Les chemins à l'intérieur qui pointent vers des fichiers de configuration frères (schema_path, pricing_path) sont résolus de manière relative au répertoire du YAML lui-même, donc renommer ou déplacer config/ ne nécessite aucune modification de code.

Quickstart

1. Build a content-addressed index from a parquet dataset

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

Cela normalise le parquet par rapport à config/schema.json, trie globalement par ts_start avec un départage déterministe, attribue des flow_id stables, dérive les unités d'évaluation pair_timeline / host_egress, calcule les cumuls et écrit dans indexes/<dataset_hash>/.

Réexécuter la commande sur les mêmes données est sans effet. Passez --rebuild pour forcer une reconstruction.

2. Inspect the tool layer

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

Cela invoque chaque outil dans la liste blanche du persona sur l'index construit et imprime un résumé, sans appels de modèle.

3. Run the benchmark

# Free, deterministic, no API keys (the mock provider):
socbench run --dataset-hash <dataset_hash> --providers mock --personas all

# Real models (after `pip install -e ".[providers]"` + exporting API keys):
socbench run --dataset-hash <dataset_hash> --providers all --personas all

La sélection des unités par défaut est un échantillonnage stratifié, déterministe dans (dataset_hash, sample_seed, mode). Chaque rendu (unité × persona × fournisseur) exécute une boucle agent multi-tours limitée ; les résultats atterrissent dans runs/<run_id>/ avec summary.json (cumuls de notation + coût + cache), eval_units_summary.jsonl, predictions_raw.jsonl, renderings.jsonl, tool_calls.jsonl et prompts_used/.

4. Run ablations and aggregate the 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 principaux)

5. Explore

notebooks/quickstart.ipynb exécute toute la boucle (il synthétise un jeu de données échantillon donc il n'a besoin d'aucune donnée engagée) et trace le F1 par persona. notebooks/results_explorer.ipynb charge n'importe quel runs/<run_id>/ et découpe les résultats par strate, persona et fournisseur. Installez avec pip install -e ".[notebooks]".

Extending the benchmark

Chaque interface conçue pour évoluer est un registre ou une clé YAML :

• New tool : déposez un nouveau fichier sous src/socbench/tools/catalog/<name>.py avec une sous-classe Tool, enregistrez-le dans src/socbench/tools/catalog/__init__.py en l'ajoutant à ALL_TOOLS, puis ajoutez son nom aux listes tools: du persona approprié dans config/benchmark_config.yaml. Le tools_manifest_sha change automatiquement. Le nom de fichier, le nom YAML et l'entrée de matrice sont en correspondance 1:1 par conception.
• New eval-unit type : ajoutez un assignateur à src/socbench/index.py et un Literal correspondant à EvalUnitType dans src/socbench/models.py.
• New provider adapter : implémentez l'ABC Adapter dans un nouveau , enregistrez-le dans la fabrique dans , et ajoutez une entrée sous dans . Les prix vont dans . Les imports SDK restent paresseux donc la dépendance est optionnelle.

Methodology

La méthodologie complète (unités d'évaluation, matrice persona x outil, boucle agent, notation, modèle de coût, politique de réparation, échantillonnage, ablations, artefacts d'exécution) est implémentée dans les fichiers au niveau du module dans src/socbench/ (chacun porte une docstring de module ciblée).

License

Apache-2.0. Voir LICENSE.