Seclab Taskflows Fuzzing

Un pipeline de fuzzing de style OSS-Fuzz piloté par LLM pour les projets natifs C/C++. AFL++ pour l'exécution, clang+lcov pour la couverture, un agent LLM pour l'écriture de harness, les décisions basées sur le retour de couverture, le triage et le reporting.

• Entièrement autonome : donnez-lui un dépôt GitHub et il gère tout, de l'identification de la cible aux rapports de vulnérabilité.
• Techniques de style OSS-Fuzz : mutateurs/dictionnaires par format, épissage de tokens sensible à la structure, améliorations de harness guidées par la couverture.
• Produit des rapports de crash lisibles par machine avec verdicts d'exploitabilité et correctifs suggérés.
• Tableau de bord HTML en direct pour la surveillance des campagnes en temps réel.
• Écrit en Python (taskflows/toolboxes/configs) avec génération de harness C pour AFL++.
• Statut : Développement actif.

Contexte

Ce dépôt contient le taskflow de fuzzing pour le GitHub Security Lab Taskflow Agent. Il dépend du dépôt compagnon seclab-taskflows pour quelques blocs de construction partagés (taskflow fetch_source_code, toolboxes local_file_viewer / gh_file_viewer, et le model_config par défaut) — ceux-ci sont installés automatiquement en tant que dépendance Python.

Les contributions sont les bienvenues ! Veuillez consulter CONTRIBUTING.md pour les directives.

Prérequis

• Python 3.11+
• Un environnement Linux (ou Codespace) avec accès à apt
• AFL++, clang, lcov, ctags, cscope, graphviz (auto-installés par le pipeline s'ils sont manquants)
• Git et GitHub CLI (gh)

Installation

pip install git+https://github.com/GitHubSecurityLab/seclab-taskflows-fuzzing

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 soit résolue depuis la distribution parente à l'exécution.

---

Table des matières

1. Ce que c'est
2. Démarrage rapide
3. Architecture
4. Le pipeline, étape par étape
5. La boucle de rétroaction de couverture
6. Fuzzing sensible à la structure
7. Corpus persistant à travers les itérations et les campagnes
8. Triage et rapports de vulnérabilité
9. Tableau de bord en direct
10. Fichiers de sortie
11. Schéma de base de données
12. Outils MCP (le vocabulaire de l'agent)
13. Paramètres ajustables (variables d'environnement)
14. Étendre le pipeline
15. Projets de référence et résultats
16. Limitations et pièges
17. Avertissement de sécurité
18. Développement : tests, linting, contribution
19. Glossaire

---

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 et compiler la bibliothèque cible trois fois : avec l'instrumentation de couverture de branches AFL++ plus les sanitizers, avec l'instrumentation AFL++ CMPLOG, et avec l'instrumentation de couverture basée sur le code source de clang,
5. écrire un ou plusieurs candidats de harness par cible, compiler chacun comme un binaire .afl instrumenté par AFL++, un binaire .cmplog instrumenté par AFL++ CMPLOG et un binaire .cov instrumenté par la couverture clang,
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 harness 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

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

C'est toute l'interface. Le script est autonome ; il installera AFL++ au premier lancement, puis pilotera le reste du flux de tâches. Les fichiers de sortie sont écrits dans ~/.local/share/seclab-taskflow-agent/seclab-taskflows/.

Le tableau de bord démarre automatiquement en arrière-plan ; dans un Codespace, le port 8765 est automatiquement redirigé — ouvrez-le dans n'importe quel navigateur pour suivre la progression en direct.

Pour un test rapide, utilisez une petite cible :

./scripts/fuzzing/run_fuzzing.sh DaveGamble/cJSON

---

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                           │
└────────────────────────────────────────────────────────────────────┘

Règles de conception clés :