من البيئات المُتحكَّم بها إلى العالم الحقيقي: تقييم وكلاء اختبار الاختراق في العالم الواقعي

أصبحت وكلاء اختبار الاختراق القائمة على الذكاء الاصطناعي ذات مصداقية متزايدة بوصفها أنظمة أمن هجومية، لكن المعايير الحالية ما تزال تقدم إرشادات محدودة حول الأنظمة التي ستحقق أفضل أداء على الأهداف الواقعية. تُقيّم معظم التقييمات الحالية أهدافًا محددة مسبقًا وتحسّن الأداء وفقًا لها، مثل التقاط الأعلام، وتنفيذ الأكواد عن بُعد، وإعادة إنتاج الاستغلالات، أو تشابه المسارات، وذلك في بيئات مبسطة أو ضيقة النطاق. هذه المعايير قيّمة لقياس القدرات المحدودة، لكنها لا تلتقط بشكل كافٍ التعقيد، والاستكشاف مفتوح النهاية، واتخاذ القرارات الاستراتيجية المطلوبة في اختبار الاختراق الواقعي. نقدّم إطار عمل تقييم عمليًا ينقل التقييم من إنجاز المهام إلى اكتشاف الثغرات المُتحقق منه، مما يتيح التقييم على أهداف معقدة بما يكفي تمتد عبر أسطح هجوم متعددة وفئات ثغرات متنوعة. يجمع الإطار بين الحقيقة الأرضية المنظمة والمطابقة الدلالية القائمة على نماذج اللغة الكبيرة (LLM) لتحديد الثغرات، والحل ثنائي الأجزاء لتسجيل النتائج تحت الغموض الواقعي، والصيانة المستمرة للحقيقة الأرضية، والتقييم المتكرر والتراكمي للوكلاء العشوائيين، ومقاييس الكفاءة، واختيار حزمة مصغّرة من أجل تجريب مستدام. توسّع هذه المنهجية أحدث ما وصلت إليه التقنيات من خلال تمكين مقارنة أكثر واقعية وفائدة تشغيلية لوكلاء اختبار الاختراق القائمين على الذكاء الاصطناعي. ولتمكين إمكانية إعادة الإنتاج، ننشر أيضًا الحقيقة الأرضية المُعلَّقة من قِبل خبراء والكود الخاص ببروتوكول التقييم المقترح.

خط أنابيب التقييم لأدوات اختبار الأمان. يقارن نتائج الأدوات مع مجموعات بيانات الحقيقة الأرضية باستخدام المطابقة القائمة على نماذج اللغة الكبيرة وينتج مقاييس الدقة والاستدعاء وF1 وF0.5.

التثبيت

poetry install

يتطلب تثبيت Python 3.11+ وPoetry.

البداية السريعة

# 1. Set your LLM API key
export OPENAI_API_KEY="..."

# 2. Run evaluation
ethibench evaluate ./my_experiment --dataset path/to/dataset.yaml

# 3. View results
cat ./my_experiment/evaluation_outputs/summary.md

أوامر CLI

ethibench evaluate

يشغّل خط أنابيب التقييم الكامل على دليل تجربة.

ethibench evaluate <experiment_dir> --dataset <dataset.yaml> [options]

# Batch: evaluate all experiments in a folder
ethibench evaluate --parent-dir final_experiments/ --dataset <dataset.yaml>

# Force re-evaluation (ignore cached artifacts)
ethibench evaluate <experiment_dir> --dataset <dataset.yaml> --force

الوسائط:

• experiment_dir — (اختياري) دليل يحتوي على أدلة فرعية للأهداف (أو أدلة فرعية run_* يحتوي كل منها على أدلة فرعية للأهداف). يمكن حذفه عند استخدام --parent-dir.

الخيارات:

• --dataset, -d — (مطلوب) مسار ملف YAML الخاص بمجموعة البيانات.
• --gt-dir, -g — دليل الحقيقة الأرضية. الافتراضي هو gt/ بجوار ملف YAML الخاص بمجموعة البيانات.
• --output-dir, -o — دليل الإخراج. الافتراضي هو evaluation_outputs/ داخل دليل التجربة. يُتجاهل في وضع الدُفعات.
• --replicates, -n — عدد نسخ المطابقة عبر نماذج اللغة الكبيرة (الافتراضي: 1).
• --force, -f — إعادة تشغيل جميع الخطوات، متجاهلًا المخرجات المخزنة مؤقتًا. افتراضيًا، تُعاد استخدام النتائج الوسيطة الموجودة (المطابقات الأولية، المطابقات ثنائية الأجزاء، المقاييس).
• --parent-dir, -p — المجلد الرئيسي الذي يحتوي على عدة أدلة تجارب لتقييمها دفعة واحدة. تُعتبر جميع الأدلة الفرعية المباشرة تجارب.

ما الذي يفعله:

1. يجمع النتائج — يفحص الأدلة الفرعية للأهداف (اسم المجلد = target_id)، ويحمّل كل ملف findings.jsonl، ويُسند subset_name من ملف YAML الخاص بمجموعة البيانات.
2. المطابقة الأولية عبر نماذج اللغة الكبيرة — يقارن كل نتيجة مع كل مُدخل في الحقيقة الأرضية باستخدام نموذج لغة كبير.
3. المطابقة ثنائية الأجزاء — خوارزمية هنغارية لإيجاد التوزيع الأمثل 1-إلى-1.
4. المقاييس — يحسب TP وFP وFN والتكرارات والدقة والاستدعاء وF1 وF0.5 ودرجة الخطورة لكل مجموعة فرعية.
5. التجميع — يحسب المتوسطات عبر النسخ والتشغيلات، ويحسب الإجمالي الموزون وغير الموزون.
6. مقاييس التكلفة — يحمّل ملف metrics.json الخاص بكل هدف إن وُجد، ويجمّع التكلفة/الرموز/المدة.
7. الرسوم البيانية — يولّد مخططات PNG في evaluation_outputs/plots/.
8. الملخص — يكتب ملف evaluation_outputs/summary.md.

ethibench analyze

يشغّل أدوات التحليل على مخرجات التقييم الموجودة.

ethibench analyze <experiment_dir> --dataset <dataset.yaml> [options]

# Batch: analyze all experiments and produce aggregated results
ethibench analyze --parent-dir final_experiments/ --dataset <dataset.yaml>

الوسائط:

• experiment_dir — (اختياري) دليل التجربة المطلوب تحليله. يمكن حذفه عند استخدام --parent-dir.

الخيارات:

• --dataset, -d — (مطلوب) مسار ملف YAML الخاص بمجموعة البيانات.
• --gt-dir, -g — دليل الحقيقة الأرضية. الافتراضي هو gt/ بجوار ملف YAML الخاص بمجموعة البيانات.
• --output-dir, -o — دليل مخرجات التقييم. الافتراضي هو evaluation_outputs/ داخل دليل التجربة.
• --parent-dir, -p — المجلد الرئيسي الذي يحتوي على عدة أدلة تجارب لتحليلها دفعة واحدة. ينتج تحليلًا لكل تجربة بالإضافة إلى نتائج مجمّعة.

مخرجات كل تجربة (evaluation_outputs/analysis/):

• duplicates.json — النتائج المتطابقة في المطابقة الأولية ولكن أُزيلت بتحسين المطابقة ثنائية الأجزاء.
• unmatched.json — النتائج التي لا تطابق أي مُدخل في الحقيقة الأرضية (إيجابيات كاذبة).
• statistics.json — إحصائيات تغطية الحقيقة الأرضية (GT)، وتوزيع النتائج لكل مُدخل في الحقيقة الأرضية.

المخرجات المجمّعة (فقط مع --parent-dir، في <parent-dir>/aggregated_analysis/):

• all_duplicates.jsonl — جميع النتائج المكررة عبر جميع التجارب (صيغة JSONL، كائنات نتائج كاملة مع حقل experiment).
• all_false_positives.jsonl — جميع النتائج غير المتطابقة/الإيجابيات الكاذبة عبر جميع التجارب (صيغة JSONL).
• gt_statistics_avg.json — متوسط تغطية الحقيقة الأرضية لكل مجموعة فرعية، بالإضافة إلى ملخص التغطية لكل تجربة.

ethibench compare

يقارن نتائج التقييم عبر تجارب متعددة، وينتج مخططات جنبًا إلى جنب وتقريرًا ملخصًا. يجب أن يكون لكل تجربة مخرجات تقييم موجودة مسبقًا (شغّل ethibench evaluate أولاً). التسميات هي دائمًا أسماء الأدلة.

# Explicit experiment directories
ethibench compare exp-gpt4o/ exp-claude/ --output-dir comparison/

# Auto-discover all experiments under a parent folder
ethibench compare --parent-dir all-experiments/ --output-dir comparison/

# Mix: explicit dirs + auto-discovery
ethibench compare exp-extra/ --parent-dir all-experiments/ --output-dir comparison/

الوسائط:

• experiment_dirs — (اختياري) دليل تجربة واحد أو أكثر لإدراجها بشكل صريح.

الخيارات:

• --output-dir, -o — (مطلوب) دليل الإخراج لنتائج المقارنة.
• --parent-dir, -p — المجلد الرئيسي لاكتشاف التجارب تلقائيًا. يُدرج أي دليل فرعي مباشر يحتوي على مجلد evaluation_outputs/، مرتبًا أبجديًا. يمكن دمجه مع قيم experiment_dirs الصريحة.

المخرجات (في --output-dir):

• comparison.json — بيانات المقارنة الأولية لجميع التجارب.
• plots/ — مخططات PNG جنبًا إلى جنب.
• comparison.md — ملخص Markdown.
• pairwise_comparison.md — مقارنة إحصائية ثنائية A/B (أفضل 4 تجارب حسب F1).
• pairwise_comparison.tex — نسخة LaTeX من الجدول الثنائي.
• cumulative-analysis/ — (إذا وُجدت بيانات تراكمية) تحليل الفارق (delta) الذي يقارن متوسط F1 بالتراكمي، بالإضافة إلى مخططات المقارنة التراكمية.

صيغ الملفات

النتائج (findings.jsonl)

كائن JSON واحد لكل سطر. الحقلان المطلوبان: title، description. اختيارية: url، cwe، severity، score، steps، evidence، metadata، وغيرها.

يوجد كل ملف findings.jsonl داخل دليل هدف — اسم الدليل يحدد الهدف الذي تنتمي إليه النتائج.

{"title": "SQL Injection in Login", "description": "User input not sanitized", "cwe": "89"}

الحقيقة الأرضية (*_gt.jsonl)

كائن JSON واحد لكل سطر.

{"id": "gt-001", "name": "SQL Injection", "subset_name": "MyApp", "target_id": "app", "category": "CWE-89", "description": "Database query vulnerability", "cvss": 9.8}

مجموعة البيانات YAML

- subset: "MyApp"
  weight: 1.0
  targets:
    - target_id: "app"

يجب أن يطابق target_id اسم الدليل داخل كل مجلد تشغيل. عند التقييم، يفحص ethibench دليل التشغيل بحثًا عن أدلة فرعية تطابق قيم target_id المعروفة، ويحمّل ملفات findings.jsonl الخاصة بها، ويُسندها إلى المجموعة الفرعية المقابلة. يحدد الحقل الاختياري gt_file مسارًا مخصصًا لملف الحقيقة الأرضية.

الإعدادات

جميع الإعدادات تتم عبر متغيرات البيئة:

بنية الدليل

المدخلات

تشغيل واحد:

my_experiment/
├── app.example.com/         # target_id as directory name
│   ├── findings.jsonl       # findings for this target
│   └── metrics.json         # optional: cost/token info
├── api.example.com/
│   ├── findings.jsonl
│   └── metrics.json

تشغيلات متعددة:

my_experiment/
├── run_001/
│   ├── app.example.com/
│   │   ├── findings.jsonl
│   │   └── metrics.json
│   └── api.example.com/
│       └── findings.jsonl
├── run_002/
│   ├── app.example.com/
│   │   └── findings.jsonl
│   └── api.example.com/
│       └── findings.jsonl

المخرجات

my_experiment/
└── evaluation_outputs/
    ├── findings_parsed.jsonl  # unified findings with target_id/subset_name
    ├── raw_matchings/         # Step 1: LLM comparison results
    │   └── matchings_MyApp.json
    ├── matchings/             # Step 2: optimal 1-to-1 assignments
    │   └── matchings_MyApp.json
    ├── results/               # Step 3: per-subset metrics
    │   └── evaluation_results_MyApp.json
    ├── results_avg/           # averaged across replicates
    ├── results_avg_all/       # averaged across runs (multi-run only)
    ├── metrics_summary.json   # aggregated cost/token metrics
    ├── plots/                 # PNG charts
    │   ├── metrics_per_subset.png
    │   ├── counts_per_subset.png
    │   ├── overall_unweighted.png
    │   ├── per_target_costs.png
    │   └── per_target_duration.png
    ├── cumulative-analysis/   # multi-run only: merged findings + overlap
    │   ├── findings_parsed.jsonl
    │   ├── raw_matchings/
    │   ├── matchings/
    │   ├── results/
    │   ├── results_avg/
    │   ├── run_overlap.json   # GT-level overlap between runs
    │   └── plots/
    │       ├── metrics_per_subset.png
    │       ├── counts_per_subset.png
    │       ├── overall_unweighted.png
    │       ├── jaccard_similarity.png
    │       └── vulnerability_frequency.png
    ├── analysis/              # from `ethibench analyze`
    │   ├── duplicates.json
    │   ├── unmatched.json
    │   └── statistics.json
    └── summary.md

مخرجات التحليل الدفعي (مع --parent-dir):

parent_dir/
├── experiment_a/
│   └── evaluation_outputs/analysis/  # per-experiment analysis
├── experiment_b/
│   └── evaluation_outputs/analysis/
└── aggregated_analysis/              # cross-experiment aggregation
    ├── all_duplicates.jsonl          # all duplicates as JSONL
    ├── all_false_positives.jsonl     # all false positives as JSONL
    └── gt_statistics_avg.json        # averaged GT coverage stats

التحليل التراكمي

بالنسبة للتجارب ذات التشغيلات المتعددة (أدلة فرعية run_*)، ينتج ethibench تلقائيًا تحليلًا تراكميًا يدمج جميع التشغيلات في مجموعة بيانات واحدة موحّدة ويعيد حساب المطابقة ثنائية الأجزاء والمقاييس على البيانات المدمجة. يعمل هذا كخطوة أخيرة من ethibench evaluate للتجارب متعددة التشغيلات.

ما الذي يفعله

1. دمج النتائج — يضم ملفات findings_parsed.jsonl من جميع التشغيلات (بدون إزالة التكرارات).
2. دمج المطابقات الأولية — يجمع المطابقات الأولية لنماذج اللغة الكبيرة لكل تشغيل. لا حاجة لاستدعاءات إضافية لنماذج اللغة الكبيرة.
3. إعادة حساب المطابقة ثنائية الأجزاء — يشغّل الخوارزمية الهنغارية على البيانات المدمجة لإيجاد التوزيع الأمثل 1-إلى-1 عبر جميع التشغيلات مجتمعة.
4. حساب المقاييس — TP/FP/FN/التكرارات والدرجات المشتقة على مجموعة البيانات المجمعة.
5. تحليل تداخل التشغيلات — يحلل ثغرات الحقيقة الأرضية التي وجدها كل تشغيل، ويحسب تشابه جاكار بين التشغيلات وتكرار الاكتشاف.
6. توليد الرسوم البيانية — ينتج مخططات التقييم القياسية للنتائج التراكمية بالإضافة إلى مخططين خاصين بالتداخل.

تحليل تداخل التشغيلات

يجيب تحليل التداخل (run_overlap.json) على السؤال: هل تكتشف التشغيلات المختلفة نفس الثغرات؟ يستخدم المطابقات ثنائية الأجزاء (توزيعات TP الموثوقة) من كل تشغيل على حدة.

لكل مجموعة فرعية وعلى المستوى العام:

• مصفوفة تغطية الحقيقة الأرضية (GT) — أي التشغيلات وجدت كل مُدخل في الحقيقة الأرضية.
• تشابه جاكار الثنائي — التشابه بين مجموعات TP لكل زوج من التشغيلات، بالإضافة إلى المتوسط عبر جميع الأزواج.
• تكرار الاكتشاف — عدد مُدخلات الحقيقة الأرضية التي وجدها عدد محدد من التشغيلات (0، 1، 2، ...، N). الثغرات التي وجدتها جميع التشغيلات "سهلة"؛ أما تلك التي وجدها تشغيل واحد فقط فهي "صعبة".
• تقسيمات المجموعات — found_by_all, found_by_some, found_by_one, found_by_none.

مخططات التداخل

• jaccard_similarity.png — مخطط أعمدة لتشابه جاكار الثنائي بين التشغيلات مع خط متقطع يظهر المتوسط.
• vulnerability_frequency.png — مخطط أعمدة يوضح عدد ثغرات الحقيقة الأرضية التي وجدها عدد محدد N من التشغيلات (مرمّز بالألوان من الأحمر=0 عبر الأصفر إلى الأخضر=الكل).

هيكل المخرجات

evaluation_outputs/cumulative-analysis/
├── findings_parsed.jsonl   # merged from all runs
├── raw_matchings/          # merged from all runs
├── matchings/              # bipartite matching on merged data
├── results/                # per-subset metrics
├── results_avg/            # averaged + weighted/unweighted overall
├── run_overlap.json        # GT-level overlap between runs
└── plots/
    ├── metrics_per_subset.png
    ├── counts_per_subset.png
    ├── overall_unweighted.png
    ├── jaccard_similarity.png
    └── vulnerability_frequency.png

كيف تعمل المطابقة

1. المطابقة الأولية: يقارن نموذج اللغة الكبير كل نتيجة مع كل مُدخل في الحقيقة الأرضية. يقرر النموذج نعم/لا لكل زوج. ينتج عن ذلك تعيين متعدد-إلى-متعدد.

2. المطابقة ثنائية الأجزاء: توجد الخوارزمية الهنغارية (scipy.optimize.linear_sum_assignment) التوزيع الأمثل واحد-إلى-واحد الذي يزيد عدد الأزواج المتطابقة إلى أقصى حد.

3. التصنيف:

   • TP (إيجابي حقيقي): النتيجة لها تطابق في التوزيع النهائي 1-إلى-1.
   • FP (إيجابي كاذب): النتيجة لم يكن لها أي تطابق حتى في المطابقة الأولية.
   • مكرر (Duplicate): طابقت النتيجة بعض مُدخلات الحقيقة الأرضية في المطابقة الأولية ولكن أُزيلت أثناء تحسين المطابقة ثنائية الأجزاء (كانت نتيجة أخرى تطابقًا أفضل لذلك المُدخل).
   • FN (سلبي كاذب): مُدخلات الحقيقة الأرضية التي لم تُطابق أي نتيجة.

4. المقاييس:

   • الدقة = TP / (TP + FP)
   • الاستدعاء = TP / (TP + FN)
   • F1 = 2 × P × R / (P + R)
   • F0.5 = 1.25 × P × R / (0.25 × P + R)
   • درجة الخطورة = مجموع النقاط المستندة إلى CVSS لكل TP (لا شيء/0→0، ≤3.9→3، ≤6.9→15، ≤8.9→30، >8.9→50)

البنية المعمارية

src/ethibench/
├── cli.py              # Click CLI entry points (evaluate, convert-report, analyze, compare)
├── config.py           # Environment variable configuration
├── models.py           # Pydantic data models
├── datasets.py         # Dataset/target YAML management
├── llm.py              # LLM provider factory
├── evaluate.py         # Core 3-step evaluation pipeline
├── results.py          # Results aggregation and averaging
├── metrics.py          # Per-target cost/token/duration metrics
├── convert_report.py   # Report → findings conversion
├── cumulative_analysis.py  # Cross-run cumulative analysis + overlap
├── pairwise.py         # Pairwise A/B statistical comparison (t-test, Cohen's d)
├── plots.py            # PNG chart generation (eval, cumulative, comparison)
├── report.py           # Markdown summary generation
└── analysis/
    ├── duplicates.py   # Duplicate finding detection
    ├── unmatched.py    # Unmatched finding extraction
    └── statistics.py   # GT coverage statistics