Cela intègre `seclab-taskflow-agent` et `seclab-taskflows` (parent)
de manière transitive, de sorte que chaque référence pointée de la forme
`seclab_taskflows.taskflows.audit.*`,
`seclab_taskflows.toolboxes.local_file_viewer`,
`seclab_taskflows.toolboxes.gh_file_viewer`, et
`seclab_taskflows.configs.model_config` se résout à partir de la distribution
parente à l'exécution.

---

## Table des matières

1. [Ce que c'est](#what-this-is)
2. [Démarrage rapide](#quick-start)
3. [Architecture](#architecture)
4. [Le pipeline, étape par étape](#the-pipeline-stage-by-stage)
5. [La boucle de rétroaction de couverture](#the-coverage-feedback-loop)
6. [Fuzzing sensible à la structure](#structure-aware-fuzzing)
7. [Corpus persistant à travers les itérations et les campagnes](#persistent-corpus-across-iterations-and-campaigns)
8. [Triage et rapports de vulnérabilité](#triage-and-vulnerability-reports)
9. [Tableau de bord en direct](#live-dashboard)
10. [Fichiers de sortie](#output-files)
11. [Schéma de base de données](#database-schema)
12. [Outils MCP (le vocabulaire de l'agent)](#mcp-tools-the-agents-vocabulary)
13. [Paramètres ajustables (variables d'environnement)](#tunable-knobs-environment-variables)
14. [Étendre le pipeline](#extending-the-pipeline)
15. [Projets de référence et résultats](#benchmark-projects-and-results)
16. [Limitations et pièges](#limitations-and-gotchas)
17. [Avertissement de sécurité](#security-warning)
18. [Développement : tests, linting, contribution](#development-testing-linting-contributing)
19. [Glossaire](#glossary)

---

## Ce que c'est

Ce taskflow est un pipeline de fuzzing entièrement autonome. Étant donné un dépôt GitHub
d'un projet natif C/C++, il va :

1. installer AFL++ + clang/llvm/lcov + ctags/cscope/graphviz s'ils sont absents,
2. récupérer le code source,
3. identifier les cibles de fuzzing candidates (parseurs, décodeurs, validateurs, …),
4. analyser le système de build,
5. écrire un ou plusieurs candidats de harnais par cible, compiler chacun à la fois comme un
   binaire `.afl` instrumenté par AFL et un binaire `.cov` instrumenté pour la couverture,
6. (optionnellement) qualifier les candidats par une couverture de 60 secondes et garder le meilleur,
7. exécuter une boucle fuzz/couverture/amélioration avec des budgets de temps doublés,
8. trier chaque crash, confirmer que les crashes précédemment connus se reproduisent toujours, et
   écrire des rapports de vulnérabilité markdown par crash avec des verdicts, l'exploitabilité,
   des correctifs suggérés, et des esquisses de tests de régression,
9. construire un graphe d'appels de style Fuzz-Introspector + un rapport d'API non touchée pour la
   campagne suivante,
10. publier le tout sur un tableau de bord HTML en direct.

Le pipeline est **de style OSS-Fuzz** dans l'esprit : il utilise un grand nombre des mêmes
techniques (mutateurs et dictionnaires par format, épissage de tokens sensible à la structure,
améliorations de harnais guidées par la couverture, rapports lisibles par machine,
crashes dédupliqués par hachage de pile) mais il est beaucoup plus petit et autonome.

---

## Démarrage rapide```bash
# Inside the codespace (or a host with python + git available):
./scripts/fuzzing/run_fuzzing.sh tukaani-project/xz

## Architecture

Trois couches, de haut en bas :```
┌────────────────────────────────────────────────────────────────────┐
│  scripts/fuzzing/run_fuzzing.sh                                    │
│      shell driver; chains the taskflow stages with `set +e`        │
└────────────────────┬───────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/taskflows/fuzzing/*.yaml                     │
│      LLM agent prompts; one YAML per pipeline stage                │
└────────────────────┬───────────────────────────────────────────────┘
                     │  (calls MCP tools)
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/mcp_servers/                                 │
│   ├ fuzz_context.py    persistence (SQLite via SQLAlchemy)         │
│   └ fuzz_runner.py     subprocess wrappers (AFL, clang, lcov, ...) │
│                                                                    │
│  scripts/fuzzing/dashboard.py                                      │
│   read-only HTML view of fuzz_context.db                           │
└────────────────────────────────────────────────────────────────────┘

À chaque itération, pour chaque harness, l'agent :

1. Demande `get_persistent_corpus_dir(harness_id)` pour obtenir le répertoire
   de corpus stable de ce harness.
2. Appelle `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>,
   output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)`.
3. Appelle `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue,
   output_dir=<run>/coverage)` pour produire un fichier de trace LCOV et un rapport HTML.
4. Appelle `store_coverage_from_lcov(run_id, lcov_path, html_path)` pour persister
   une ligne `coverage_report` + des lignes `coverage_gap` par élément non couvert.
5. Appelle `fold_queue_into_persistent_corpus(...)` pour fusionner la file d'attente
   d'itération d'AFL dans le corpus persistant et exécuter `cmin` pour maintenir la taille bornée.
6. Lit `get_coverage_summary` + `get_coverage_gaps`, puis soit :
   - ajoute une nouvelle graine (étiquetée `coverage_feedback`) pour atteindre une
     branche non couverte,
   - modifie la source du harness pour appeler une API supplémentaire,
   - appelle `enrich_dictionary_from_uncovered(...)` pour ajouter automatiquement des entrées
     de dictionnaire pour les constantes magiques dont AFL a besoin pour satisfaire une garde, ou
   - ignore la lacune (chemin d'erreur froid / code fournisseur).
7. Appelle `store_iteration_note(repo, iteration_number, harness_id, note=<résumé
   en une ligne>)` afin que la chronologie des itérations du tableau de bord suive ce qui
   a changé.

**Détection de plateau.** La boucle se termine prématurément dès que deux itérations consécutives
ont toutes deux gagné < `FUZZ_PLATEAU_THRESHOLD_PCT` (par défaut `1.0`) points de pourcentage
absolus de couverture de lignes.

---

## Fuzzing conscient de la structure

Trois mécanismes complémentaires produisent des entrées plus fortes que la mutation brute d'octets.

### 1. Dictionnaires par format + mutateurs personnalisés

Pour les cibles dont `input_kind` correspond à un format connu, le taskflow fournit
des dictionnaires préconstruits et des fichiers source C `LLVMFuzzerCustomMutator` :

| Format | Dictionnaire | Mutateur | Notes |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | Épissage de tokens, duplication/suppression de crochets équilibrés, inversion de type |
| `xml` | `xml.dict` | `xml_mutator.c` | Balises, entités, DTD, tokens billion-laughs |
| `regex` | `regex.dict` | `regex_mutator.c` | Ancres, classes, quantificateurs, motifs ReDoS réels |
| `binary_tlv` | _(aucun)_ | `binary_tlv_mutator.c` | Enregistrements préfixés par longueur : dépassement de longueur / duplication / suppression |
| `png` | `png.dict` | _(réutilise binary_tlv)_ | Dictionnaire PNG + mutateur binary_tlv |

Ceux-ci sont récupérés automatiquement par `write_initial_harnesses` (dictionnaire
copié à côté des graines) et `build_harnesses` (mutateur lié dans le binaire
AFL). Chaque mutateur délègue 50 % des mutations au mutateur d'octets par défaut d'AFL
afin de ne pas perdre la randomisation du moteur.

Pour ajouter un nouveau format : déposez un `<name>.dict` et/ou un `<name>_mutator.c` dans
`src/seclab_taskflows/dictionaries/`, puis enregistrez-le dans la
map `_FORMAT_ASSETS` en bas de `fuzz_runner.py`.

### 2. Mutateur intelligent conscient de la source (spécifique au projet)

Pour les formats inconnus, ou chaque fois que vous voulez des tokens plus forts
spécifiques au projet, `generate_smart_mutator` analyse les propres fichiers `.c`/`.h`
du dépôt cible et émet un fichier C `LLVMFuzzerCustomMutator` dont les dictionnaires
d'épissage sont extraits de :

- littéraux de chaîne avec ≥3 caractères alphabétiques (après filtrage du bruit
  du compilateur/licence, des chemins, des en-têtes, des contraintes asm, des spécificateurs de format),
- constantes numériques 32 bits issues de `#define`, `case` et `enum` (après
  filtrage du bruit générique de petits entiers comme 0, 1, 256, 0xff…).

Trois focus sont disponibles :

| Focus | Ce qu'il épisse | Quand l'utiliser |
|-------|-----------------|-------------|
| `strings` | Littéraux de chaîne du projet uniquement | Formats texte (JSON, XML, YAML, CSV) |
| `constants` | Valeurs magiques numériques 32 bits uniquement | Protocoles binaires, en-têtes avec nombres magiques |
| `combined` | Les deux | Par défaut ; généralement le meilleur |

Associez `generate_smart_mutators(...)` (au pluriel) avec `HARNESS_CANDIDATES >= 3`
afin que chaque focus devienne un harness candidat lors du tour de qualification.

### 3. Dictionnaire AFL conscient du projet + enrichissement piloté par la couverture

Deux outils complémentaires construisent et développent un dictionnaire AFL `-x` au
fur et à mesure de la campagne :

- **`generate_project_dictionary(source_root, output_path)`** — s'exécute une fois
  avant l'itération 1, extrait statiquement le même ensemble de tokens source que
  celui utilisé par le mutateur intelligent et l'écrit sous forme de dictionnaire AFL. Les constantes
  numériques sont émises dans LES DEUX endianness afin que le fuzzer puisse satisfaire
  `memcmp(x, &magic, 4)` quel que soit l'ordre des octets de l'hôte.

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path,
  uncovered_locations)`** — s'exécute après l'étape de couverture de chaque itération,
  analyse la source environnante pour les gardes conditionnelles
  (`strncmp/memcmp/strstr`, `case 0xN:`, `== 0xN`, `== 'X'`) à proximité des
  lignes non couvertes, et AJOUTE tous les nouveaux tokens au dictionnaire. Idempotent :
  ne rajoute jamais une entrée déjà présente.

### 4. Opération d'épissage de corpus

Lorsque `corpus_dir` est passé à `generate_smart_mutator`, le C généré
reçoit également un opérateur d'épissage de corpus : au premier appel, il charge jusqu'à 64 fichiers
depuis ce répertoire (plafonnés à 4 Kio chacun), et à partir de là peut épisser
des sous-régions aléatoires de ces fichiers dans l'entrée mutée. Cela donne au
mutateur un opérateur de style recombinaison que le havoc standard d'AFL ne fait pas
bien. Associez-le à `get_persistent_corpus_dir(...)` afin que la bibliothèque d'épissage
soit « remixez ce qu'AFL a déjà découvert ».

---

## Corpus persistant à travers les itérations et les campagnes

Chaque harness dispose d'un répertoire de corpus stable à l'emplacement :```
<workspace>/corpus/harness_<id>/

---

## Fichiers de sortie

Tous sous `~/.local/share/seclab-taskflow-agent/seclab-taskflows/`.

| Chemin | Contenu |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — cibles, harnesses, exécutions, couverture, crashes, verdicts, graphes d'appels, suggestions de harness, notes d'itération |
| `fuzz_runner/builds/` | Binaires `.afl` et `.cov` compilés |
| `fuzz_runner/runs/` | Répertoires de sortie AFL + fichiers LCOV + rapports de couverture HTML |
| `fuzz_runner/corpus/harness_<id>/` | Corpus persistant par harness (conservé entre les itérations et les campagnes) |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Résumé de campagne Markdown, crashes groupés par verdict |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | Rapport de vulnérabilité Markdown par crash |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | Graphe d'appels statique + superposition atteint/non atteint |

---

## Schéma de la base de données

Tables dans `fuzz_context.db` (SQLite via SQLAlchemy) :

| Table | Colonnes d'intérêt |
|-------|--------------------|
| `fuzz_target` | `repo, file, function, signature, input_kind` |
| `harness` | `target_id, repo, harness_path, afl_binary_path, cov_binary_path, build_status, version, sanitizers` |
| `seed_corpus` | `target_id, source, path, bytes_count, added_in_iteration` |
| `fuzz_run` | `harness_id, iteration_number, exec_per_sec, paths_total, crashes_count, status, output_dir, started_at, ended_at` |
| `coverage_report` | `run_id, lines_total, lines_hit, line_pct, fns_*, branches_*, lcov_path, html_path` |
| `coverage_gap` | `report_id, file, function, line, kind, reason_hint` |
| `crash` | `run_id, input_blob_path, minimized_path, stack_top_hash, sanitizer_output, verdict, bug_class, cwe, severity, vuln_report_path, reproducer_path, classification, notes` |
| `call_graph` | `repo, target_id, dot_path, svg_path, functions_total, functions_in_graph, functions_reached, functions_unreached, untouched_surface_json` |
| `harness_suggestion` | `repo, function_name, file, rationale, input_kind, priority` |
| `iteration_note` | `repo, harness_id, iteration_number, note, created_at` |

Les migrations de schéma se trouvent dans `_migrate()` dans `fuzz_context.py`. Les nouvelles TABLES sont
créées automatiquement par `Base.metadata.create_all()` ; seules les nouvelles COLONNES nécessitent
un `ALTER TABLE` basé sur PRAGMA.

---

## Outils MCP (le vocabulaire de l'agent)

L'agent n'appelle jamais AFL ou clang directement — il compose le pipeline en
appelant des outils MCP. L'ensemble complet, groupé par objectif :

### Persistance (`fuzz_context.py`)

- `store_fuzz_target`, `get_fuzz_targets`
- `store_harness`, `update_harness_build`, `get_harnesses`
- `store_seed`, `start_fuzz_run`, `finish_fuzz_run`, `get_fuzz_runs`
- `store_coverage_from_lcov`, `get_coverage_summary`, `get_coverage_gaps`,
  `coverage_plateau_reached`
- `store_crash`, `update_crash_verdict`, `get_crashes`,
  `get_crashes_grouped`, `suggest_severity`
- `store_call_graph`, `get_call_graphs`, `get_repo_reached_functions`
- `store_harness_suggestion`, `get_harness_suggestions`
- `store_iteration_note`, `get_iteration_notes`

### Build / fuzz / couverture (`fuzz_runner.py`)

- `check_tooling`, `workspace_paths`
- `compile_harness` — compile les binaires `.afl` et `.cov`
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — rejoue la file d'attente AFL contre le binaire `.cov`, exporte LCOV
- `extract_dictionary` — extrait les chaînes imprimables d'un binaire
- `package_reproducer` — regroupe un `.tgz` pour un crash unique

### Corpus persistant (v8)

- `get_persistent_corpus_dir`, `fold_queue_into_persistent_corpus`

### Ressources de format (C5)

- `list_format_assets`, `get_format_dictionary`, `write_format_mutator`

### Mutateur intelligent + dictionnaire conscient du projet

- `generate_smart_mutator`, `generate_smart_mutators`
- `generate_project_dictionary`, `enrich_dictionary_from_uncovered`

Les fonctions d'outil sont décorées avec `@mcp.tool()` (FastMCP). Dans les tests,
invoquez-les via l'attribut `.fn`, par ex.
`fr.run_afl_for.fn(afl_binary_path=..., ...)`.

---

## Paramètres ajustables (variables d'environnement)

| Variable | Défaut | Objectif |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | Nombre de harnesses candidats écrits par cible. Définir à 2 ou 3 pour une compétition de style OSS-Fuzz-Gen. L'étape de qualification exécute chacun pendant `QUALIFIER_SECONDS` et conserve le meilleur selon le % de lignes. |
| `QUALIFIER_SECONDS` | `60` | Budget en temps réel par candidat dans l'étape de qualification. |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | Gain de couverture de lignes (en pp absolus) en dessous duquel deux itérations consécutives sont considérées comme un plateau et la boucle s'arrête prématurément. |
| `FUZZ_DASHBOARD_PORT` | `8765` | Port pour le tableau de bord en direct. |
| `FUZZ_NO_DASHBOARD` | (non défini) | Définir à `1` pour ignorer le démarrage du tableau de bord. |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | Délai d'expiration du sous-processus par outil dans `fuzz_runner` (secondes). |
| `LOCAL_SHELL_TIMEOUT` | `180` | Délai d'expiration par commande dans `local_shell` (secondes). |

Plus les variables d'agent standard (`COPILOT_TOKEN`, `LOG_DIR`,
`FUZZ_CONTEXT_DIR`, …). Voir le README à la racine du projet pour la liste complète.

---

## Étendre le pipeline

### Ajouter un nouveau format (mutateur + dictionnaire)

1. Déposez `dictionaries/<name>.dict` (format AFL `-x`) et/ou
   `dictionaries/<name>_mutator.c` (mutateur personnalisé libFuzzer).
2. Enregistrez dans `_FORMAT_ASSETS` en bas de `fuzz_runner.py` :   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

Conventions de base de code (voir aussi `benchmark/improvements.md` pour la version historique de campagne de celles-ci) :

- Utilisez `os.environ.get(NAME) or "default"` plutôt que
  `os.environ.get(NAME, "default")`. Les chaînes vides issues de la substitution
  de template YAML seraient sinon retournées.
- Utilisez `X | None` (PEP 604) dans les nouvelles annotations, pas `Optional[X]`.
- Les tests invoquent les outils MCP via `.fn(...)`, pas le nom décoré directement.
- Évitez les littéraux `/tmp/...` dans les tests — utilisez la fixture pytest `tmp_path`
  (règle de lint `S108`).
- Tous les imports en ligne à l'intérieur des méthodes de test nécessitent `# noqa: PLC0415` si vous
  ne pouvez pas les déplacer en haut du fichier (par exemple lorsqu'ils sont importés conditionnellement
  après un `pytest.skip`).
- Une seule assertion par ligne pour les tests de vérité composés (règle de lint `PT018`).

Le suivi des améliorations (`benchmark/improvements.md`) est le journal persistant
de ce qui a été ajouté au pipeline au fil des versions. Lorsque vous ajoutez une
fonctionnalité substantielle, ajoutez-y une section décrivant ce qui a changé, où cela
se trouve, et quels tests le protègent.

---

## Glossaire

- **AFL++** — Fuzzer greybox guidé par la couverture ; le moteur d'exécution ici.
- **libAFLDriver** — Bibliothèque statique qui permet aux harnais AFL++ d'utiliser
  la convention de point d'entrée libFuzzer (`LLVMFuzzerTestOneInput`).
- **LCOV** — Format de fichier de trace de couverture standard de l'industrie. Nous exportons vers celui-ci
  via `llvm-cov export -format=lcov` et le parsons nous-mêmes.
- **`stack_top_hash`** — Un hash de 16 caractères des N premières trames normalisées d'une
  trace de pile ASan/UBSan. Utilisé pour la déduplication des crashs.
- **Corpus persistant** — Répertoire par harnais à
  `<workspace>/corpus/harness_<id>/` qui conserve les entrées intéressantes d'AFL
  à travers les itérations et les ré-exécutions d'une même campagne.
- **Mutateur intelligent** — Un `LLVMFuzzerCustomMutator` dont les jetons de splice sont
  extraits du propre code source de la cible (`generate_smart_mutator`).
- **Mutateur personnalisé (libFuzzer)** — Une fonction C fournie par l'utilisateur appelée par
  le moteur avec une liberté totale sur la façon de muter un buffer ; AFL++ prend en charge
  la même ABI.
- **Outil MCP** — Une fonction décorée par FastMCP que l'agent LLM peut appeler.
- **OSS-Fuzz / Fuzz-Introspector** — L'infrastructure de fuzzing open-source de Google
  et son outil compagnon d'analyse de graphe d'appels/couverture.
  Plusieurs fonctionnalités de ce taskflow (mutateurs par format, déduplication par pile,
  rapport de graphe d'appels + API non touchées, harnais multi-candidats) sont
  inspirées par ceux-ci.

---

## Licence

Ce projet est sous licence selon les termes de la licence open source MIT. Veuillez vous référer au fichier [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt) pour les termes complets.

## Mainteneurs

Voir [CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS) ou contactez l'équipe GitHub Security Lab.

## Support

Voir [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md) pour plus de détails sur la façon d'obtenir de l'aide avec ce projet.

## Remerciements

Ce projet s'appuie sur les concepts et techniques d'[AFL++](https://github.com/AFLplusplus/AFLplusplus), [OSS-Fuzz](https://github.com/google/oss-fuzz), et [Fuzz-Introspector](https://github.com/ossf/fuzz-introspector).