socbench

最先端の推論LLMをSOCエージェントとして、生のNetFlowデータ上でベンチマークする。

socbenchは、最先端の推論モデルをSOCエージェントとしてベンチマークします。各モデルは、決定論的で事前にインデックス化されたNetFlowコーパスに対して、制限付きマルチターンエージェントループを実行します。ツールはペルソナスコープで読み取り専用、調査ごとに固定のドル上限があり、厳格な最終回答JSON契約に従います。4つのペルソナ（SOCアナリスト、脅威アナリスト、アドバーサリーハンター、ディテクションエンジニア）と3つのプロバイダ（OpenAI、Anthropic、Google）が同じ評価単位、スコアリングレンズ、アブレーションサーフェスを共有するため、主要数値やtools_off / playbooks_offの差分が直接比較可能です。

このリポジトリはローカルファーストです。ノートパソコン、3つのAPIキー、そしてリポジトリにコミットされたサンプルparquetファイルがあれば、10ドル未満の予算でスモークテストを再現できます。

ステータス

アルファ版。パイプライン全体がエンドツーエンドで動作します。構築済みの範囲は以下の通りです。

• Step 1: パッケージの骨格、契約、設定、スキーマ
• Step 2: インデックスビルダー（socbench build-index）と決定論的なコンテンツアドレスインデックス
• Step 3: ペルソナ許可リストとサンプルビルダーを備えた読み取り専用ツール層
• Step 4: ペルソナ、プレイブック、プロンプト構成 + 禁止トークンチェック
• Step 5: プロバイダアダプター（OpenAI / Anthropic / Gemini + 常時利用可能なモック）と、予算上限とコスト/レイテンシ集計を備えたマルチターンエージェントループ
• Step 6: スコアリング（フロー単位 / ペア単位 / ホスト単位のF1）、層別サンプリング、アブレーション集計
• Step 7: クイックスタート + 結果エクスプローラーノートブック。再現手順はREPRODUCE.mdに記載

モックプロバイダを使用すれば、APIキーなしで完全なスモークテストを今日実行できます（Quickstartのステップ3、またはnotebooks/quickstart.ipynbを参照）。

インストール

socbenchは標準的なPEP 621 / hatchlingプロジェクトとして提供されます。どちらのインストール方法でも動作します。

uvを使用する場合（開発に推奨）

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を使用する場合

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

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

どちらの方法でも、socbench --helpで利用可能なサブコマンドが表示されるはずです。

設定

config/benchmark_config.yamlには安全なデフォルトが同梱されています。スモーク用cost_budget_usd: 10、フル用cost_budget_usd: 900、固定cost_usd_cap_per_rendering: 0.50。このファイル内で兄弟設定ファイルを指すパス（schema_path、pricing_path）は、YAML自身のディレクトリからの相対パスで解決されるため、config/の名前変更や移動にコードの修正は不要です。

クイックスタート

1. パーケットデータセットからコンテンツアドレスインデックスを構築する

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

これにより、パーケットファイルがconfig/schema.jsonに対して正規化され、決定論的な同値判定でグローバルにts_startでソートされ、安定したflow_idが割り当てられ、pair_timeline / host_egress評価単位が導出され、ロールアップが計算され、indexes/<dataset_hash>/に書き込まれます。

同じデータに対してコマンドを再実行しても何も起こりません。強制的に再構築するには--rebuildを指定します。

2. ツール層を検査する

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

これにより、ペルソナの許可リストにあるすべてのツールが構築済みインデックスに対して呼び出され、モデル呼び出しなしでサマリーが出力されます。

3. ベンチマークを実行する

# 無料、決定論的、APIキー不要（モックプロバイダ）：
socbench run --dataset-hash <dataset_hash> --providers mock --personas all

# 実際のモデル（`pip install -e ".[providers]"` + APIキーのエクスポート後）：
socbench run --dataset-hash <dataset_hash> --providers all --personas all

ユニット選択のデフォルトは層別サンプリングで、(dataset_hash, sample_seed, mode)で決定論的です。各(unit × persona × provider)のレンダリングは制限付きマルチターンエージェントループを実行し、結果はruns/<run_id>/以下に配置されます。summary.json（スコアリング＋コスト＋キャッシュ集計）、eval_units_summary.jsonl、predictions_raw.jsonl、renderings.jsonl、tool_calls.jsonl、prompts_used/が含まれます。

4. アブレーションを実行し、差分を集計する

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 → main deltas)

5. 探索する

notebooks/quickstart.ipynbでループ全体を実行し（サンプルデータセットを合成するため、コミットされたデータは不要）、ペルソナごとのF1をプロットします。notebooks/results_explorer.ipynbは任意のruns/<run_id>/をロードし、層、ペルソナ、プロバイダで結果をスライスします。インストールはpip install -e ".[notebooks]"。

ベンチマークの拡張

進化するように設計されたすべてのインターフェースは、レジストリまたはYAMLキーです。

• 新しいツール: src/socbench/tools/catalog/<name>.pyにToolサブクラスを持つ新しいファイルを作成し、src/socbench/tools/catalog/__init__.pyのALL_TOOLSに追加して登録し、config/benchmark_config.yamlの該当するペルソナtools:リストに名前を追加します。tools_manifest_shaは自動的に変わります。ファイル名、YAML名、マトリックスエントリは1:1で一致するように設計されています。
• 新しい評価単位タイプ: src/socbench/index.pyにアサイナーを追加し、src/socbench/models.pyのEvalUnitTypeに対応するLiteralを追加します。
• 新しいプロバイダアダプター: 新しいsrc/socbench/providers/<name>_adapter.pyでAdapter ABCを実装し、のファクトリに登録し、のにエントリを追加します。価格はに追加します。SDKのインポートは遅延されるため、依存関係はオプションです。

方法論

完全な方法論（評価単位、ペルソナ×ツールマトリックス、エージェントループ、スコアリング、コストモデル、修復ポリシー、サンプリング、アブレーション、実行アーティファクト）は、src/socbench/内のモジュールレベルのファイルに実装されています（各ファイルには焦点を絞ったモジュールドキュメント文字列があります）。

ライセンス

Apache-2.0。 LICENSE を参照。