socbench

معيار لتقييم نماذج الاستدلال المتطورة (LLMs) كـ وكلاء SOC على بيانات NetFlow الخام.

socbench يقوم بقياس أداء نماذج الاستدلال المتطورة كوكلاء SOC: كل نموذج ينفذ حلقة وكيل متعددة الخطوات محدودة ضد مجموعة بيانات NetFlow محددة مسبقًا ومفهرسة، مع أدوات للقراءة فقط مخصصة للشخصية، وحدود تكلفة دولارية ثابتة لكل تحقيق، وعقد صارم لصيغة الإجابة النهائية JSON. أربع شخصيات (محلل SOC، محلل تهديدات، صائد خصوم، مهندس كشف) وثلاثة مزودين (OpenAI, Anthropic, Google) يتشاركون نفس وحدات التقييم، وعدسات التهديف، وسطح الاختزال بحيث تكون الأرقام الرئيسية وفروقات tools_off / playbooks_off قابلة للمقارنة مباشرة.

المستودع محلي أولاً. يكفي جهاز لابتوب وثلاثة مفاتيح API وعينة parquet مثبتة في المستودع لإعادة إنتاج اختبار دخاني بميزانية أقل من 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. بناء فهرس محدد المحتوى من مجموعة بيانات 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. تشغيل المعيار

# مجاني، حتمي، بدون مفاتيح 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، ثم أضف اسمها إلى قوائم tools: المناسبة للشخصية في config/benchmark_config.yaml. tools_manifest_sha يتغير تلقائيًا. اسم الملف واسم YAML وإدخال المصفوفة متطابقان 1:1 بالتصميم.
• نوع وحدة تقييم جديدة: أضف معينًا إلى src/socbench/index.py و Literal مطابقًا لـ EvalUnitType في src/socbench/models.py.
• محول مزود جديد: قم بتطبيق واجهة Adapter المجردة في ملف جديد src/socbench/providers/<name>_adapter.py، سجلها في مصنع في ، وأضف إدخالًا تحت في . الأسعار توضع في . تستورد SDK بشكل متأخر للحفاظ على الاعتماد اختياريًا.

المنهجية

المنهجية الكاملة (وحدات التقييم، مصفوفة الشخصية × الأداة، حلقة الوكيل، التهديف، نموذج التكلفة، سياسة الإصلاح، أخذ العينات، الاختزالات، نتائج التشغيل) منفذة عبر ملفات الوحدة في src/socbench/ (كل ملف يحمل وثيقة وحدة مركزة).

الترخيص

Apache-2.0. راجع LICENSE.