Nécessite Python 3.11+ et Poetry installés.

Quick Start

Commandes CLI

ethibench evaluate

Exécute le pipeline d’évaluation complet sur un répertoire d’expérience.

Arguments :

• experiment_dir — (facultatif) Répertoire contenant les sous-répertoires de cibles (ou des sous-répertoires run_* contenant chacun des sous-répertoires de cibles). Peut être omis lors de l’utilisation de --parent-dir.

Options :

• --dataset, -d — (obligatoire) Chemin vers le fichier YAML du jeu de données.
• --gt-dir, -g — Répertoire de vérité terrain. Par défaut gt/ à côté du fichier YAML du jeu de données.
• --output-dir, -o — Répertoire de sortie. Par défaut evaluation_outputs/ dans le répertoire d’expérience. Ignoré en mode batch.
• --replicates, -n — Nombre de répliques de correspondance LLM (défaut : 1).
• --force, -f — Réexécute toutes les étapes, en ignorant les artefacts en cache. Par défaut, les résultats intermédiaires existants (correspondances brutes, correspondances biparties, métriques) sont réutilisés.
• --parent-dir, -p — Dossier parent contenant plusieurs répertoires d’expériences à évaluer en batch. Tous les sous-répertoires immédiats sont traités comme des expériences.

Ce qu’il fait :

1. Collecte des constatations — analyse les sous-répertoires de cibles (nom de dossier = target_id), charge chaque findings.jsonl, attribue subset_name depuis le YAML du jeu de données.
2. Correspondance LLM brute — compare chaque constatation à chaque entrée de vérité terrain à l’aide d’un LLM.
3. Correspondance bipartie — algorithme hongrois pour trouver l’affectation optimale 1 pour 1.
4. Métriques — calcule TP, FP, FN, doublons, précision, rappel, F1, F0.5 et le score de sévérité par sous-ensemble.
5. Agrégation — calcule la moyenne sur les répliques et les exécutions, et les résultats globaux pondérés/non pondérés.
6. Métriques de coût — charge metrics.json par cible s’il existe, agrège coût/tokens/durée.
7. Graphiques — génère des diagrammes PNG dans evaluation_outputs/plots/.
8. Résumé — écrit evaluation_outputs/summary.md.

ethibench analyze

Exécute les outils d’analyse sur des sorties d’évaluation existantes.

Arguments :

• experiment_dir — (facultatif) Répertoire d’expérience à analyser. Peut être omis lors de l’utilisation de --parent-dir.

Options :

• --dataset, -d — (obligatoire) Chemin vers le fichier YAML du jeu de données.
• --gt-dir, -g — Répertoire de vérité terrain. Par défaut gt/ à côté du fichier YAML du jeu de données.
• --output-dir, -o — Répertoire des sorties d’évaluation. Par défaut evaluation_outputs/ dans le répertoire d’expérience.
• --parent-dir, -p — Dossier parent contenant plusieurs répertoires d’expériences à analyser en batch. Produit une analyse par expérience ainsi que des résultats agrégés.

Sorties par expérience (evaluation_outputs/analysis/) :

• duplicates.json — constatations qui correspondaient lors de la correspondance brute mais qui ont été supprimées par l’optimisation bipartie.
• unmatched.json — constatations sans correspondance avec la vérité terrain (faux positifs).
• statistics.json — statistiques de couverture GT, distribution des constatations par GT.

Sorties agrégées (uniquement avec --parent-dir, dans <parent-dir>/aggregated_analysis/) :

• all_duplicates.jsonl — toutes les constatations en double dans toutes les expériences (JSONL, objets de constatation complets avec le champ experiment).
• all_false_positives.jsonl — toutes les constatations sans correspondance / faux positifs dans toutes les expériences (format JSONL).
• gt_statistics_avg.json — couverture GT moyenne par sous-ensemble, plus résumé de couverture par expérience.

ethibench compare

Compare les résultats d’évaluation de plusieurs expériences, en produisant des graphiques côte à côte et un rapport récapitulatif. Chaque expérience doit déjà avoir des sorties d’évaluation (exécutez ethibench evaluate d’abord). Les libellés correspondent toujours aux noms de répertoires.

Arguments :

• experiment_dirs — (facultatif) Un ou plusieurs répertoires d’expériences à inclure explicitement.

Options :

• --output-dir, -o — (obligatoire) Répertoire de sortie pour les résultats de comparaison.
• --parent-dir, -p — Dossier parent pour la découverte automatique des expériences. Tout sous-répertoire immédiat contenant un dossier evaluation_outputs/ est inclus, trié par ordre alphabétique. Peut être combiné avec des experiment_dirs explicites.

Sorties (dans --output-dir) :

• comparison.json — données de comparaison brutes pour toutes les expériences.
• plots/ — graphiques PNG côte à côte.
• comparison.md — résumé Markdown.
• pairwise_comparison.md — comparaison statistique par paires A/B (top 4 des expériences selon le F1).
• pairwise_comparison.tex — version LaTeX du tableau de comparaison par paires.
• cumulative-analysis/ — (si des données cumulatives existent) analyse delta comparant le F1 moyen au F1 cumulatif, plus des graphiques de comparaison cumulative.

Formats de fichiers

Constatations (findings.jsonl)

Un objet JSON par ligne. Champ obligatoire : title, description. Facultatifs : url, cwe, severity, score, steps, evidence, metadata, etc.

Chaque findings.jsonl se trouve dans un répertoire de cible — le nom du répertoire détermine la cible à laquelle appartiennent les constatations.

Vérité terrain (*_gt.jsonl)

Un objet JSON par ligne.

Jeu de données YAML

Le target_id doit correspondre au nom du répertoire sous chaque dossier d’exécution. Lors de l’évaluation, ethibench parcourt le répertoire d’exécution à la recherche de sous-répertoires correspondant aux valeurs target_id connues, charge leurs findings.jsonl et les attribue au sous-ensemble correspondant. Le champ facultatif gt_file spécifie un chemin personnalisé vers un fichier GT.

Configuration

Toute la configuration s’effectue via des variables d’environnement :

Structure des répertoires

Entrée

Exécution unique :

Exécutions multiples :

Sortie

Sortie de l’analyse par lot (avec --parent-dir) :

Analyse cumulative

Pour les expériences comportant plusieurs exécutions (sous-répertoires run_*), ethibench produit automatiquement une analyse cumulative qui fusionne toutes les exécutions en un seul jeu de données combiné et recalcule la correspondance bipartie et les métriques sur les données fusionnées. Cette étape s’exécute en dernier dans ethibench evaluate pour les expériences multi-exécutions.

Ce qu’il fait

1. Fusionne les constatations — concatène les findings_parsed.jsonl de toutes les exécutions (sans déduplication).
2. Fusionne les correspondances brutes — combine les correspondances LLM brutes de chaque exécution. Aucun appel LLM supplémentaire n’est nécessaire.
3. Recalcule la correspondance bipartie — exécute l’algorithme hongrois sur les données fusionnées pour trouver l’affectation optimale 1 pour 1 sur toutes les exécutions combinées.
4. Calcule les métriques — TP/FP/FN/doublons et scores dérivés sur le jeu de données combiné.
5. Analyse du chevauchement des exécutions — analyse quelles vulnérabilités de vérité terrain chaque exécution a trouvées, en calculant la similarité de Jaccard entre les exécutions et la fréquence de découverte.
6. Génère les graphiques — produit les graphiques d’évaluation standard pour les résultats cumulatifs ainsi que deux diagrammes spécifiques au chevauchement.

Analyse du chevauchement des exécutions

L’analyse du chevauchement (run_overlap.json) répond à la question : les différentes exécutions découvrent-elles les mêmes vulnérabilités ? Elle utilise les correspondances biparties (affectations TP de référence) de chaque exécution individuelle.

Pour chaque sous-ensemble et globalement :

• Matrice de couverture GT — quelles exécutions ont trouvé chaque entrée de vérité terrain.
• Similarité de Jaccard par paire — similarité entre les ensembles de TP de chaque paire d’exécutions, ainsi que la moyenne sur toutes les paires.
• Fréquence de découverte — combien d’entrées GT ont été trouvées par exactement 0, 1, 2, ..., N exécutions. Les vulnérabilités trouvées par toutes les exécutions sont « faciles » ; celles trouvées par une seule sont « difficiles ».
• Partitions d’ensembles — found_by_all, found_by_some, found_by_one, found_by_none.

Graphiques de chevauchement

• jaccard_similarity.png — diagramme en barres de la similarité de Jaccard par paire entre les exécutions, avec une ligne pointillée indiquant la moyenne.
• vulnerability_frequency.png — diagramme en barres montrant combien de vulnérabilités GT ont été trouvées par exactement N exécutions (code couleur allant du rouge=0 au jaune, jusqu’au vert=toutes).

Structure des sorties

Comment fonctionne la correspondance

1. Correspondance brute : chaque constatation est comparée à chaque entrée de vérité terrain par un LLM. Le LLM décide YES/NO pour chaque paire. Cela produit une correspondance plusieurs-à-plusieurs.

2. Correspondance bipartie : l’algorithme hongrois (scipy.optimize.linear_sum_assignment) trouve l’affectation optimale un-à-un qui maximise le nombre de paires correspondantes.

3. Classification :

   • TP (True Positive) : la constatation a une correspondance dans l’affectation finale 1 pour 1.
   • FP (False Positive) : la constatation n’a eu aucune correspondance, même dans la correspondance brute.
   • Doublon : la constatation correspondait à une entrée GT dans la correspondance brute mais a été supprimée lors de l’optimisation bipartie (une autre constatation correspondait mieux à cette GT).
   • FN (False Negative) : entrées GT sans correspondance avec une quelconque constatation.

4. Métriques :

   • Précision = TP / (TP + FP)
   • Rappel = TP / (TP + FN)
   • F1 = 2 × P × R / (P + R)
   • F0.5 = 1.25 × P × R / (0.25 × P + R)
   • Score de sévérité = somme des points basés sur le CVSS pour chaque TP (None/0→0, ≤3.9→3, ≤6.9→15, ≤8.9→30, >8.9→50)

Architecture