socbench

将前沿推理LLM作为SOC分析师在原始NetFlow数据上进行基准测试。

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中的复现说明

你现在可以通过模拟提供商（参见快速入门步骤3，或 notebooks/quickstart.ipynb）在无需API密钥的情况下运行一个完整的烟雾测试。

安装

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>/<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名称和矩阵条目被设计为一一对应。
• 新评估单元类型：向 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。