socbench

최첨단 추론 LLM을 원시 NetFlow 데이터에서 SOC 에이전트로 벤치마킹합니다.

socbench는 최첨단 추론 모델을 SOC 에이전트로 벤치마킹합니다: 각 모델은 결정론적이고 사전 인덱싱된 NetFlow 코퍼스를 대상으로 제한된 다중 턴 에이전트 루프를 실행하며, 페르소나 범위의 읽기 전용 도구, 조사당 고정 달러 상한, 엄격한 최종 답변 JSON 계약을 따릅니다. 네 가지 페르소나 (SOC 분석가, 위협 분석가, 적대자 헌터, 탐지 엔지니어)와 세 가지 공급자 (OpenAI, Anthropic, Google)가 동일한 평가 단위, 채점 렌즈, 절제 표면을 공유하여 주요 수치와 tools_off / playbooks_off 델타를 직접 비교할 수 있습니다.

이 저장소는 로컬 우선입니다. 노트북, 세 개의 API 키, 저장소에 커밋된 샘플 파켓 파일만 있으면 10달러 미만의 예산으로 스모크 테스트를 재현할 수 있습니다.

상태

알파. 전체 파이프라인이 종단 간 실행됩니다. 구축 범위:

• 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. 파켓 데이터셋에서 콘텐츠 주소 인덱스 구축

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)에서 결정론적입니다. 각 (단위 × 페르소나 × 공급자) 렌더링은 제한된 다중 턴 에이전트 루프를 실행합니다. 결과는 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 델타)

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 임포트는 지연되므로 종속성은 선택 사항입니다.

방법론

전체 방법론 (평가 단위, 페르소나 x 도구 매트릭스, 에이전트 루프, 채점, 비용 모델, 수리 정책, 샘플링, 절제, 실행 아티팩트)은 src/socbench/의 모듈 수준 파일 전체에 걸쳐 구현되어 있습니다 (각 파일은 집중된 모듈 독스트링을 포함합니다).

라이선스

Apache-2.0. LICENSE를 참조하십시오.