在原始 NetFlow 数据上，将前沿推理大语言模型作为 SOC 智能体 进行基准测试。

socbench 将前沿推理模型作为 SOC 智能体进行基准测试：每个模型运行一个有界多轮智能体循环，针对确定性的、预先索引的 NetFlow 语料库，使用角色限定范围的只读工具、每项调查固定的美元预算上限，以及严格的最终答案 JSON 合约。四个角色（SOC 分析师、威胁分析师、对手猎手、检测工程师）和三个提供商（OpenAI、Anthropic、Google）共享相同的评估单元、评分视角和消融表面，因此总体数字和 tools_off / playbooks_off 差值可直接比较。

该仓库是 本地优先 的。一台笔记本电脑、三个 API 密钥以及仓库中提交的样本 parquet 文件，就足以在 10 美元预算内复现一次烟雾测试。

Alpha 阶段。完整管道端到端运行。构建覆盖内容：

• 步骤 1：包骨架、契约、配置、模式
• 步骤 2：索引构建器（socbench build-index），具有确定性内容寻址索引
• 步骤 3：带角色白名单的只读工具层 + 样本构建器
• 步骤 4：角色、剧本、提示词组合 + 禁用令牌检查
• 步骤 5：提供商适配器（OpenAI / Anthropic / Gemini + 始终可用的模拟器）以及带预算上限和成本/延迟汇总的多轮智能体循环
• 步骤 6：评分（每流/每对/每主机 F1 分数）、分层采样、消融聚合
• 步骤 7：快速入门 + 结果探索笔记本；REPRODUCE.md 中的复现说明

您现在可以使用模拟提供程序运行完整的烟雾测试，无需 API 密钥（参见快速入门第 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. 从 parquet 数据集构建内容寻址索引

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

这将根据 config/schema.json 规范化 parquet 文件，按 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) 中是确定性的。每个 (单元 × 角色 × 提供程序) 渲染运行一个有界多轮智能体循环；结果保存在 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>//ablation_summary.json (tools_off → 主要差值)

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，在 providers/base.py 的 build_adapter 工厂中注册，并在 config/benchmark_config.yaml 的 providers: 下添加条目。定价放在 config/pricing.yaml 中。SDK 导入保持惰性，因此依赖项是可选的。
• 新角色：在 config/benchmark_config.yaml 的 agent.personas: 下添加一个块，包含其预算和 tools: 白名单。
• 新评分视角：在 src/socbench/scoring.py 的 score_unit 中添加一个视角，并在 models.py 的 EvalUnitSummary 中添加匹配字段。
• 新消融：扩展 prompts.py / agent.py 中的 Ablation 处理以及 aggregate.py 中的标签列表。

完整的方法论（评估单元、角色 x 工具矩阵、智能体循环、评分、成本模型、修复策略、采样、消融、运行产物）在 src/socbench/ 中的模块级文件中实现（每个文件都带有聚焦的模块文档字符串）。

Apache-2.0。请参见 LICENSE。

Benchmark frontier reasoning LLMs as SOC agents on raw NetFlow data.

socbench benchmarks frontier reasoning models as SOC agents: each model runs a bounded multi-turn agent loop against a deterministic, pre-indexed NetFlow corpus, with persona-scoped read-only tools, fixed dollar caps per investigation, and a strict final-answer JSON contract. Four personas (SOC Analyst, Threat Analyst, Adversary Hunter, Detection Engineer) and three providers (OpenAI, Anthropic, Google) share the same eval units, scoring lenses, and ablation surface so the headline numbers and tools_off / playbooks_off deltas are directly comparable.

The repository is local-first. A laptop, three API keys, and a sample parquet committed to the repo are enough to reproduce a smoke under a $10 budget.

Alpha. The full pipeline runs end-to-end. Build-out covered:

• Step 1 : package skeleton, contracts, configs, schema
• Step 2 : the index builder (socbench build-index) with deterministic content-addressed indexes
• Step 3 : read-only tools layer with persona allowlist + sample builder
• Step 4 : personas, playbooks, prompt compose + forbidden-token check
• Step 5 : provider adapters (OpenAI / Anthropic / Gemini + always-on mock) and the multi-turn agent loop with budget caps and cost/latency rollups
• Step 6 : scoring (per-flow / per-pair / per-host F1), stratified sampling, ablation aggregation
• Step 7 : quickstart + results-explorer notebooks; reproduction instructions in REPRODUCE.md

You can run a complete smoke today with no API keys via the mock provider (see Quickstart step 3, or notebooks/quickstart.ipynb).

socbench ships as a standard PEP 621 / hatchling project. Either install path works.

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


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

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

Either way, socbench --help should now list the available subcommands.

config/benchmark_config.yaml ships safe defaults: smoke cost_budget_usd: 10, full cost_budget_usd: 900, fixed cost_usd_cap_per_rendering: 0.50. Paths inside it that point at sibling config files (schema_path, pricing_path) resolve relative to the YAML's own directory, so renaming or relocating config/ doesn't require any code edits.

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

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

This normalizes the parquet against config/schema.json, sorts globally by ts_start with deterministic tie-breaking, assigns stable flow_ids, derives pair_timeline / host_egress eval units, computes rollups, and writes to indexes/<dataset_hash>/.

Re-running the command on the same data is a no-op. Pass --rebuild to force a rebuild.

2. Inspect the tool layer

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

This invokes every tool in the persona's allowlist against the built index and prints a summary, with no model calls.

# 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

Unit selection defaults to stratified sampling, deterministic in (dataset_hash, sample_seed, mode). Each (unit × persona × provider) rendering runs a bounded multi-turn agent loop; results land under runs/<run_id>/ with summary.json (scoring + cost + cache rollups), eval_units_summary.jsonl, predictions_raw.jsonl, renderings.jsonl, tool_calls.jsonl, and 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 → main deltas)

notebooks/quickstart.ipynb runs the whole loop (it synthesizes a sample dataset so it needs no committed data) and plots per-persona F1. notebooks/results_explorer.ipynb loads any runs/<run_id>/ and slices the results by stratum, persona, and provider. Install with pip install -e ".[notebooks]".

Every interface designed to evolve is a registry or a YAML key:

• New tool : drop a new file under src/socbench/tools/catalog/<name>.py with a Tool subclass, register it in src/socbench/tools/catalog/__init__.py by appending to ALL_TOOLS, then add its name to the appropriate persona tools: lists in config/benchmark_config.yaml. The tools_manifest_sha shifts automatically. Filename, YAML name, and matrix entry are 1:1 by design.
• New eval-unit type : add an assigner to src/socbench/index.py and a matching Literal to EvalUnitType in src/socbench/models.py.
• New provider adapter : implement the Adapter ABC in a new src/socbench/providers/<name>_adapter.py, register it in the build_adapter factory in providers/base.py, and add an entry under providers: in config/benchmark_config.yaml. Pricing goes in config/pricing.yaml. SDK imports stay lazy so the dependency is optional.
• New persona : add a block under agent.personas: in config/benchmark_config.yaml with its budget and tools: allowlist.
• New scoring lens : add a lens to score_unit in src/socbench/scoring.py and a matching field to EvalUnitSummary in models.py.
• New ablation : extend the Ablation handling in prompts.py / agent.py and the tag list in aggregate.py.

The full methodology (eval units, persona x tool matrix, agent loop, scoring, cost model, repair policy, sampling, ablations, run artifacts) is implemented across the module-level files in src/socbench/ (each carries a focused module docstring).

Apache-2.0. See LICENSE.