socbench

Benchmark per modelli di ragionamento all'avanguardia come agenti SOC su dati NetFlow grezzi.

socbench esegue benchmark dei modelli di ragionamento all'avanguardia come agenti SOC: ogni modello esegue un ciclo ad agenti multi-turno limitato su un corpus NetFlow deterministico e pre-indicizzato, con strumenti di sola lettura limitati al ruolo, un tetto di spesa fisso per indagine e un contratto JSON di risposta finale rigoroso. Quattro ruoli (Analista SOC, Analista di Minacce, Cacciatore di Avversari, Ingegnere di Rilevamento) e tre provider (OpenAI, Anthropic, Google) condividono le stesse unità di valutazione, le stesse lenti di punteggio e la stessa superficie di ablazione, in modo che i numeri principali e i delta tools_off / playbooks_off siano direttamente confrontabili.

Il repository è locale-primo. Un laptop, tre chiavi API e un parquet di esempio impegnato nel repository sono sufficienti per riprodurre un test rapido con un budget inferiore a $10.

Stato

Alpha. L'intera pipeline è eseguibile dall'inizio alla fine. Costruzione coperta:

• Passo 1: scheletro del pacchetto, contratti, configurazioni, schema
• Passo 2: il costruttore di indici (socbench build-index) con indici indirizzabili deterministicamente per contenuto
• Passo 3: livello di strumenti di sola lettura con lista consentita per ruolo e costruttore di campioni
• Passo 4: ruoli, playbook, composizione dei prompt + controllo token proibiti
• Passo 5: adattatori provider (OpenAI / Anthropic / Gemini + mock sempre attivo) e ciclo ad agenti multi-turno con limiti di budget e riepiloghi costi/latenza
• Passo 6: punteggio (F1 per flusso / per coppia / per host), campionamento stratificato, aggregazione delle ablazioni
• Passo 7: notebook di avvio rapido ed esplorazione dei risultati; istruzioni di riproduzione in REPRODUCE.md

Puoi eseguire un test completo oggi senza chiavi API utilizzando il provider mock (vedi Avvio rapido passo 3, o notebooks/quickstart.ipynb).

Installazione

socbench viene distribuito come progetto standard PEP 621 / hatchling. Entrambi i percorsi di installazione funzionano.

Con uv (consigliato per lo sviluppo)

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 semplice

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

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

In entrambi i casi, socbench --help dovrebbe ora elencare i sottocomandi disponibili.

Configurazione

config/benchmark_config.yaml include valori predefiniti sicuri: cost_budget_usd: 10 per test rapido, cost_budget_usd: 900 completo, cost_usd_cap_per_rendering: 0.50 fisso. I percorsi al suo interno che puntano a file di configurazione fratelli (schema_path, pricing_path) si risolvono in relazione alla directory dello YAML stesso, quindi rinominare o spostare config/ non richiede modifiche al codice.

Avvio rapido

1. Costruisci un indice indirizzabile per contenuto da un dataset parquet

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

Questo normalizza il parquet rispetto a config/schema.json, ordina globalmente per ts_start con risoluzione di parità deterministica, assegna flow_id stabili, ricava le unità di valutazione pair_timeline / host_egress, calcola i riepiloghi e scrive in indexes/<dataset_hash>/.

Rieseguire il comando sugli stessi dati non produce alcun effetto. Passa --rebuild per forzare una ricostruzione.

2. Ispeziona il livello degli strumenti

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

Questo invoca ogni strumento nella lista consentita del ruolo contro l'indice costruito e stampa un riepilogo, senza chiamate al modello.

3. Esegui il benchmark

# Gratuito, deterministico, nessuna chiave API (provider mock):
socbench run --dataset-hash <dataset_hash> --providers mock --personas all

# Modelli reali (dopo `pip install -e ".[providers]"` + esportazione delle chiavi API):
socbench run --dataset-hash <dataset_hash> --providers all --personas all

La selezione delle unità predefinisce il campionamento stratificato, deterministico in (dataset_hash, sample_seed, mode). Ogni rendering (unità × ruolo × provider) esegue un ciclo ad agenti multi-turno limitato; i risultati vengono salvati in runs/<run_id>/ con summary.json (punteggio + costo + rollup cache), eval_units_summary.jsonl, predictions_raw.jsonl, renderings.jsonl, tool_calls.jsonl e prompts_used/.

4. Esegui ablazioni e aggrega i delta

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 → delta principali)

5. Esplora

notebooks/quickstart.ipynb esegue l'intero ciclo (sintetizza un dataset di esempio quindi non necessita di dati impegnati) e traccia l'F1 per ruolo. notebooks/results_explorer.ipynb carica qualsiasi runs/<run_id>/ e seziona i risultati per strato, ruolo e provider. Installa con pip install -e ".[notebooks]".

Estendere il benchmark

Ogni interfaccia progettata per evolversi è un registro o una chiave YAML:

• Nuovo strumento: inserisci un nuovo file sotto src/socbench/tools/catalog/<name>.py con una sottoclasse di Tool, registralo in src/socbench/tools/catalog/__init__.py aggiungendo a ALL_TOOLS, quindi aggiungi il suo nome alle liste tools: appropriate del ruolo in config/benchmark_config.yaml. Il tools_manifest_sha si sposta automaticamente. Nome file, nome YAML e voce della matrice sono 1:1 per progettazione.
• Nuovo tipo di unità di valutazione: aggiungi un assegnatore a src/socbench/index.py e un Literal corrispondente a EvalUnitType in src/socbench/models.py.
• Nuovo adattatore provider: implementa l'ABC Adapter in un nuovo , registralo nella factory in e aggiungi una voce sotto in . I prezzi vanno in . Le importazioni SDK rimangono lazy in modo che la dipendenza sia opzionale.

Metodologia

La metodologia completa (unità di valutazione, matrice ruolo × strumento, ciclo agente, punteggio, modello di costo, politica di riparazione, campionamento, ablazioni, artefatti di esecuzione) è implementata nei file a livello di modulo in src/socbench/ (ciascuno include una docstring di modulo mirata).

Licenza

Apache-2.0. Vedi LICENSE.