Seclab Taskflows Fuzzing

Eine LLM-gesteuerte Fuzzing-Pipeline im OSS-Fuzz-Stil für native C/C++-Projekte. AFL++ für die Ausführung, clang+lcov für die Coverage, ein LLM-Agent für das Schreiben von Harnesses, Coverage-Feedback-Entscheidungen, Triage und Reporting.

• Vollständig autonom: Gib ihm ein GitHub-Repo und es übernimmt alles von der Zielidentifikation bis zu Schwachstellenberichten.
• Techniken im OSS-Fuzz-Stil: format-spezifische Mutatoren/Wörterbücher, strukturbewusstes Token-Splicing, coverage-gesteuerte Harness-Verbesserungen.
• Erzeugt maschinenlesbare Crash-Berichte mit Ausnutzbarkeitsurteilen und vorgeschlagenen Patches.
• Live-HTML-Dashboard zur Echtzeit-Überwachung der Kampagne.
• Geschrieben in Python (taskflows/toolboxes/configs) mit C-Harness-Generierung für AFL++.
• Status: Aktive Entwicklung.

Hintergrund

Dieses Repository enthält den Fuzzing-Taskflow für den GitHub Security Lab Taskflow Agent. Es hängt vom seclab-taskflows Begleit-Repository für einige gemeinsame Bausteine ab (fetch_source_code-Taskflow, local_file_viewer / gh_file_viewer Toolboxes und die Standard-model_config) — diese werden automatisch als Python-Abhängigkeit installiert.

Beiträge sind willkommen! Bitte siehe CONTRIBUTING.md für Richtlinien.

Anforderungen

• Python 3.11+
• Eine Linux-Umgebung (oder Codespace) mit Zugriff auf apt
• AFL++, clang, lcov, ctags, cscope, graphviz (werden von der Pipeline automatisch installiert, falls nicht vorhanden)
• Git und GitHub CLI (gh)

Installation

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

Dies zieht seclab-taskflow-agent und seclab-taskflows (Parent) transitiv mit ein, sodass jede punktierte Referenz der Form seclab_taskflows.taskflows.audit.*, seclab_taskflows.toolboxes.local_file_viewer, seclab_taskflows.toolboxes.gh_file_viewer und seclab_taskflows.configs.model_config zur Laufzeit aus der Parent- Distribution aufgelöst wird.

---

Inhaltsverzeichnis

1. Was das ist
2. Schnellstart
3. Architektur
4. Die Pipeline, Stufe für Stufe
5. Die Coverage-Feedback-Schleife
6. Strukturbewusstes Fuzzing
7. Persistenter Korpus über Iterationen und Kampagnen hinweg
8. Triage und Schwachstellenberichte
9. Live-Dashboard
10. Ausgabedateien
11. Datenbankschema
12. MCP-Tools (das Vokabular des Agenten)
13. Einstellbare Stellschrauben (Umgebungsvariablen)
14. Erweitern der Pipeline
15. Benchmark-Projekte und Ergebnisse
16. Einschränkungen und Stolperfallen
17. Sicherheitswarnung
18. Entwicklung: Testen, Linting, Mitwirken
19. Glossar

---

Was das ist

Dieser Taskflow ist eine vollständig autonome Fuzzing-Pipeline. Ausgehend von einem GitHub-Repo eines nativen C/C++-Projekts wird er:

1. AFL++ + clang/llvm/lcov + ctags/cscope/graphviz installieren, falls nicht vorhanden,
2. den Quellcode abrufen,
3. Kandidaten für Fuzz-Ziele identifizieren (Parser, Decoder, Validatoren, …),
4. das Build-System analysieren und die Zielbibliothek dreimal bauen: mit AFL++-Edge-Coverage-Instrumentierung plus Sanitizern, mit AFL++-CMPLOG- Instrumentierung und mit clang-quellcodebasierter Coverage-Instrumentierung,
5. einen oder mehrere Harness-Kandidaten pro Ziel schreiben, jeden als AFL++-instrumentiertes .afl-Binary, ein AFL++-CMPLOG-instrumentiertes .cmplog- Binary und ein clang-coverage-instrumentiertes .cov-Binary bauen,
6. (optional) Kandidaten durch 60-sekündige Coverage qualifizieren und den besten behalten,
7. eine Fuzz-/Coverage-/Verbesserungsschleife mit sich verdoppelnden Zeitbudgets ausführen,
8. jeden Absturz triagieren, bestätigen, dass zuvor bekannte Abstürze weiterhin reproduzieren, und pro Absturz Markdown-Schwachstellenberichte mit Urteilen, Ausnutzbarkeit, vorgeschlagenen Patches und Skizzen für Regressionstests schreiben,
9. einen Call-Graph im Fuzz-Introspector-Stil + Bericht über unberührte APIs für die nächste Kampagne erstellen,
10. alles in einem Live-HTML-Dashboard veröffentlichen.

Die Pipeline ist im Geiste OSS-Fuzz-artig: Sie verwendet viele derselben Techniken (Mutator und Wörterbücher pro Format, strukturbewusstes Token- Splicing, coverage-getriebene Harness-Verbesserungen, maschinenlesbare Berichte, deduplizierte stack-gehashte Abstürze), ist aber viel kleiner und eigenständig.

---

Schnellstart

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

Das ist die gesamte Oberfläche. Das Skript ist autonom; es installiert AFL++ beim ersten Lauf und steuert dann den Rest des Taskflows. Ausgabedateien werden nach ~/.local/share/seclab-taskflow-agent/seclab-taskflows/ geschrieben.

Das Dashboard startet automatisch im Hintergrund; in einem Codespace wird Port 8765 automatisch weitergeleitet — öffne ihn in einem beliebigen Browser, um den Fortschritt live zu verfolgen.

Für einen schnellen Smoke-Test verwende ein kleines Ziel:

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

---

Architektur

Drei Schichten, von oben nach unten:

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

Wichtige Designregeln: