socbench

Бенчмарк для проверки передовых рассуждающих LLM как агентов SOC на сырых данных NetFlow.

socbench тестирует передовые рассуждающие модели в качестве агентов SOC: каждая модель выполняет ограниченный многошаговый цикл агента над детерминированным, предварительно проиндексированным корпусом NetFlow, используя инструменты только для чтения, ограниченные по персоне, фиксированные долларовые лимиты на расследование и строгий контракт на вывод в формате JSON. Четыре персоны (SOC Analyst, Threat Analyst, Adversary Hunter, Detection Engineer) и три провайдера (OpenAI, Anthropic, Google) используют одни и те же единицы оценки, скоринговые объективы и поверхность для абляции, так что основные числа и дельты tools_off / playbooks_off напрямую сравнимы.

Репозиторий ориентирован на локальное использование. Ноутбука, трёх ключей API и образца parquet, добавленного в репозиторий, достаточно, чтобы воспроизвести smoke-тест в рамках бюджета в 10 долларов.

Статус

Альфа. Полный конвейер работает от начала до конца. Охваченные этапы разработки:

• Шаг 1: скелет пакета, контракты, конфигурации, схема
• Шаг 2: построитель индекса (socbench build-index) с детерминированными индексами по содержимому
• Шаг 3: слой инструментов только для чтения с белым списком персон и построителем образцов
• Шаг 4: персоны, плейбуки, композиция промптов + проверка запрещённых токенов
• Шаг 5: адаптеры провайдеров (OpenAI / Anthropic / Gemini + всегда включённый mock) и многошаговый цикл агента с бюджетными лимитами и сводками стоимости/задержки
• Шаг 6: скоринг (F1 на поток / на пару / на хост), стратифицированная выборка, агрегация абляций
• Шаг 7: блокноты быстрого старта и исследования результатов; инструкции по воспроизведению в REPRODUCE.md

Вы можете запустить полный smoke-тест уже сегодня без ключей API с помощью mock-провайдера (см. 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 содержит безопасные настройки по умолчанию: smoke 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

Это нормализует parquet в соответствии с 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. Запуск бенчмарка

# 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

Выбор единиц по умолчанию осуществляет стратифицированную выборку, детерминированную в (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, затем добавьте его имя в соответствующие списки tools: персоны в config/benchmark_config.yaml. tools_manifest_sha изменяется автоматически. Имя файла, имя в YAML и запись в матрице соответствуют 1:1 по замыслу.
• Новый тип оценочной единицы: добавьте назначитель в src/socbench/index.py и соответствующий Literal к EvalUnitType в src/socbench/models.py.
• Новый адаптер провайдера: реализуйте ABC Adapter в новом файле , зарегистрируйте его в фабрике в и добавьте запись в раздел в . Цены указываются в . Импорты SDK остаются ленивыми, чтобы зависимость была опциональной.

Методология

Полная методология (оценочные единицы, матрица персона × инструменты, цикл агента, скоринг, модель стоимости, политика восстановления, семплирование, абляции, артефакты запуска) реализована в модульных файлах на уровне src/socbench/ (каждый файл содержит сфокусированную документацию модуля).

Лицензия

Apache-2.0. См. LICENSE.