jd0965199-oss/ethibenchAI पैठ परीक्षण एजेंटों के लिए मूल्यांकन ढांचा जो LLM-आधारित सिमेंटिक मिलान, द्विदलीय समाधान, और वास्तविक-विश्व लक्ष्यों पर संचयी विश्लेषण का उपयोग करके मान्य प्राप्त भेद्यता खोज को मापता है।
एआई पेंटेस्टिंग एजेंट आक्रामक सुरक्षा प्रणालियों के रूप में तेजी से विश्वसनीय होते जा रहे हैं, लेकिन वर्तमान बेंचमार्क अभी भी इस बारे में सीमित मार्गदर्शन प्रदान करते हैं कि कौन सी प्रणालियाँ वास्तविक-विश्व लक्ष्यों पर सर्वश्रेष्ठ प्रदर्शन करेंगी। अधिकांश मौजूदा मूल्यांकन सरलीकृत या संकीर्ण सेटिंग्स में फ़्लैग कैप्चर, दूरस्थ कोड निष्पादन, एक्सप्लॉइट पुनरुत्पादन, या प्रक्षेपवक्र समानता जैसे पूर्वनिर्धारित लक्ष्यों का आकलन और अनुकूलन करते हैं। ये बेंचमार्क सीमित क्षमताओं को मापने के लिए मूल्यवान हैं, फिर भी ये यथार्थवादी पेंटेस्टिंग में आवश्यक जटिलता, खुले-अंत अन्वेषण और रणनीतिक निर्णय-निर्माण को पर्याप्त रूप से नहीं दर्शाते हैं। हम एक व्यावहारिक मूल्यांकन ढांचा प्रस्तुत करते हैं जो आकलन को कार्य पूर्णता से मान्य भेद्यता खोज की ओर स्थानांतरित करता है, जिससे कई आक्रमण सतहों और भेद्यता वर्गों को शामिल करने वाले पर्याप्त जटिल लक्ष्यों में मूल्यांकन संभव होता है। यह ढांचा भेद्यताओं की पहचान करने के लिए संरचित ग्राउंड-ट्रुथ को LLM-आधारित अर्थगत मिलान के साथ जोड़ता है, यथार्थवादी अस्पष्टता के तहत निष्कर्षों को स्कोर करने के लिए द्विदलीय समाधान, निरंतर ग्राउंड-ट्रुथ रखरखाव, स्टोकेस्टिक एजेंटों का बार-बार और संचयी मूल्यांकन, दक्षता मेट्रिक्स, और सतत प्रयोग के लिए कम-सुइट चयन। यह पद्धति एआई पेंटेस्टिंग एजेंटों की अधिक यथार्थवादी और परिचालन रूप से सूचनाप्रद तुलना को सक्षम करके वर्तमान तकनीकी स्तर को आगे बढ़ाती है। पुनरुत्पादनीयता सक्षम करने के लिए, हम प्रस्तावित मूल्यांकन प्रोटोकॉल के लिए विशेषज्ञ-एनोटेटेड ग्राउंड-ट्रुथ और कोड भी जारी करते हैं।
सुरक्षा परीक्षण उपकरणों के लिए मूल्यांकन पाइपलाइन। LLM-आधारित मिलान का उपयोग करके उपकरण निष्कर्षों की तुलना ग्राउंड ट्रुथ डेटासेट से करता है और precision, recall, 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
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 — ग्राउंड ट्रुथ निर्देशिका। डिफ़ॉल्ट रूप से डेटासेट YAML के पास gt/ होता है।--output-dir, -o — आउटपुट निर्देशिका। डिफ़ॉल्ट रूप से प्रयोग निर्देशिका के अंदर evaluation_outputs/ होती है। बैच मोड में अनदेखा किया जाता है।--replicates, -n — LLM मिलान replicates की संख्या (डिफ़ॉल्ट: 1)।--force, -f — कैश्ड आर्टिफैक्ट को अनदेखा करते हुए सभी चरणों को फिर से चलाएँ। डिफ़ॉल्ट रूप से, मौजूदा मध्यवर्ती परिणाम (रॉ matchings, bipartite matchings, मेट्रिक्स) पुनः उपयोग किए जाते हैं।--parent-dir, -p — एकाधिक प्रयोग निर्देशिकाओं वाला पैरेंट फ़ोल्डर, जिनका बैच में मूल्यांकन करना है। सभी सीधी उपनिर्देशिकाओं को प्रयोग माना जाता है।यह क्या करता है:
target_id), प्रत्येक findings.jsonl लोड करता है, डेटासेट YAML से subset_name निर्दिष्ट करता है।metrics.json लोड करता है (यदि मौजूद है), लागत/टोकन/अवधि एकत्र करता है।evaluation_outputs/plots/ में PNG चार्ट उत्पन्न करता है।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 — ग्राउंड ट्रुथ निर्देशिका। डिफ़ॉल्ट रूप से डेटासेट YAML के पास gt/ होता है।--output-dir, -o — मूल्यांकन आउटपुट निर्देशिका। डिफ़ॉल्ट रूप से प्रयोग निर्देशिका के अंदर evaluation_outputs/ होती है।--parent-dir, -p — एकाधिक प्रयोग निर्देशिकाओं वाला पैरेंट फ़ोल्डर, जिनका बैच में विश्लेषण करना है। प्रति-प्रयोग विश्लेषण के साथ एकत्रित परिणाम तैयार करता है।प्रति-प्रयोग आउटपुट (evaluation_outputs/analysis/):
duplicates.json — कच्चे मिलान में मिले लेकिन द्विदलीय अनुकूलन द्वारा हटाए गए निष्कर्ष।unmatched.json — ऐसे निष्कर्ष जिनका कोई ग्राउंड ट्रुथ मिलान नहीं है (false positives)।statistics.json — GT कवरेज आँकड़े, प्रति-GT निष्कर्ष वितरण।एकत्रित आउटपुट (केवल --parent-dir के साथ, <parent-dir>/aggregated_analysis/ में):
all_duplicates.jsonl — सभी प्रयोगों में सभी डुप्लिकेट निष्कर्ष (JSONL, experiment फ़ील्ड के साथ पूर्ण निष्कर्ष ऑब्जेक्ट)।all_false_positives.jsonl — सभी प्रयोगों में सभी अमिलान/गलत-सकारात्मक (false positive) निष्कर्ष (JSONL प्रारूप)।gt_statistics_avg.json — प्रति सबसेट औसत GT कवरेज, साथ ही प्रति-प्रयोग कवरेज सारांश।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 — मार्कडाउन सारांश।pairwise_comparison.md — युग्मवार A/B सांख्यिकीय तुलना (F1 द्वारा शीर्ष 4 प्रयोग)।pairwise_comparison.tex — युग्मवार तालिका का LaTeX संस्करण।cumulative-analysis/ — (यदि संचयी डेटा मौजूद है) डेल्टा विश्लेषण जो औसत बनाम संचयी 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}
- subset: "MyApp"
weight: 1.0
targets:
- target_id: "app"
target_id को प्रत्येक रन फ़ोल्डर के अंतर्गत निर्देशिका नाम से मेल खाना चाहिए। मूल्यांकन करते समय, ethibench रन निर्देशिका को ज्ञात target_id मानों से मेल खाती उपनिर्देशिकाओं के लिए स्कैन करता है, उनके findings.jsonl लोड करता है, और उन्हें संबंधित सबसेट को निर्दिष्ट करता है। वैकल्पिक gt_file फ़ील्ड एक कस्टम GT फ़ाइल पथ निर्दिष्ट करता है।
सभी कॉन्फ़िगरेशन पर्यावरण चरों के माध्यम से होता है:
| चर | डिफ़ॉल्ट | विवरण |
|---|---|---|
ETHIBENCH_LLM_PROVIDER | openai | LLM प्रदाता: openai, anthropic, ollama, gemini |
ETHIBENCH_LLM_MODEL | gpt-5.4-mini | मॉडल नाम |
ETHIBENCH_TEMPERATURE | 0.3 | सैंपलिंग तापमान |
ETHIBENCH_API_URL | — | कस्टम API एंडपॉइंट (Ollama या संगत APIs के लिए) |
ETHIBENCH_CONCURRENCY | 50 | अधिकतम समवर्ती LLM कॉल |
ETHIBENCH_MAX_RETRIES | 5 | प्रति LLM कॉल अधिकतम पुनर्प्रयास |
ETHIBENCH_MAX_PARALLEL_RUNS | 3 | एक प्रयोग के भीतर समानांतर रूप से मूल्यांकित अधिकतम रन |
ANTHROPIC_API_KEY | — | Anthropic API कुंजी |
OPENAI_API_KEY | — | OpenAI API कुंजी |
GEMINI_API_KEY | — | Google Gemini API कुंजी |
एकल रन:
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 के अंतिम चरण के रूप में चलता है।
findings_parsed.jsonl को जोड़ता है (कोई डिडुप्लिकेशन नहीं)।ओवरलैप विश्लेषण (run_overlap.json) इस प्रश्न का उत्तर देता है: क्या विभिन्न रन समान भेद्यताओं की खोज कर रहे हैं? यह प्रत्येक व्यक्तिगत रन से द्विदलीय मिलानों (आधिकारिक TP असाइनमेंट) का उपयोग करता है।
प्रत्येक सबसेट और वैश्विक रूप से:
found_by_all, found_by_some, found_by_one, found_by_none।jaccard_similarity.png — रनों के बीच युग्मवार Jaccard समानता का बार चार्ट, जिसमें माध्य दिखाने वाली धराशायी रेखा होती है।vulnerability_frequency.png — बार चार्ट दिखाता है कि कितनी GT भेद्यताएँ ठीक 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
कच्चा मिलान: प्रत्येक निष्कर्ष की तुलना प्रत्येक ग्राउंड ट्रुथ प्रविष्टि से एक LLM द्वारा की जाती है। LLM प्रत्येक जोड़ी के लिए YES/NO का निर्णय करता है। यह एक कई-से-कई (many-to-many) मैपिंग उत्पन्न करता है।
द्विदलीय मिलान: हंगेरियन एल्गोरिथ्म (scipy.optimize.linear_sum_assignment) इष्टतम एक-से-एक असाइनमेंट खोजता है जो मिलान की गई जोड़ियों की संख्या को अधिकतम करता है।
वर्गीकरण:
मेट्रिक्स:
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