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](#what-this-is)
2. [Schnellstart](#quick-start)
3. [Architektur](#architecture)
4. [Die Pipeline, Stufe für Stufe](#the-pipeline-stage-by-stage)
5. [Die Coverage-Feedback-Schleife](#the-coverage-feedback-loop)
6. [Strukturbewusstes Fuzzing](#structure-aware-fuzzing)
7. [Persistenter Korpus über Iterationen und Kampagnen hinweg](#persistent-corpus-across-iterations-and-campaigns)
8. [Triage und Schwachstellenberichte](#triage-and-vulnerability-reports)
9. [Live-Dashboard](#live-dashboard)
10. [Ausgabedateien](#output-files)
11. [Datenbankschema](#database-schema)
12. [MCP-Tools (das Vokabular des Agenten)](#mcp-tools-the-agents-vocabulary)
13. [Einstellbare Parameter (Umgebungsvariablen)](#tunable-knobs-environment-variables)
14. [Erweiterung der Pipeline](#extending-the-pipeline)
15. [Benchmark-Projekte und Ergebnisse](#benchmark-projects-and-results)
16. [Einschränkungen und Fallstricke](#limitations-and-gotchas)
17. [Sicherheitswarnung](#security-warning)
18. [Entwicklung: Testen, Linting, Mitwirken](#development-testing-linting-contributing)
19. [Glossar](#glossary)

---

## Was das ist

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

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,
5. einen oder mehrere Harness-Kandidaten pro Ziel schreiben, jeden sowohl als
   AFL-instrumentierte `.afl`-Binärdatei als auch als coverage-instrumentierte `.cov`-Binärdatei bauen,
6. (optional) Kandidaten durch 60-sekündige Coverage qualifizieren und die besten behalten,
7. eine Fuzz/Coverage/Improve-Schleife mit sich verdoppelnden Zeitbudgets ausführen,
8. jeden Absturz triagieren, bestätigen, dass zuvor bekannte Abstürze weiterhin reproduzierbar sind, und
   pro Absturz Markdown-Schwachstellenberichte mit Urteilen, Ausnutzbarkeit,
   vorgeschlagenen Patches und Skizzen für Regressionstests schreiben,
9. einen Call-Graph + Untouched-API-Bericht im Fuzz-Introspector-Stil 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 (Mutators und Dictionaries pro Format, strukturbewusstes Token-
Splicing, coverage-getriebene Harness-Verbesserungen, maschinenlesbare Berichte,
deduplizierte stack-gehashte Abstürze), ist aber viel kleiner und eigenständig.

---

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

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

Pro Iteration, pro Harness führt der Agent Folgendes aus:

1. Fragt `get_persistent_corpus_dir(harness_id)` für das stabile
   Corpus-Verzeichnis dieses Harness ab.
2. Ruft `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>,
   output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)` auf.
3. Ruft `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue,
   output_dir=<run>/coverage)` auf, um eine LCOV-Tracefile und einen HTML-Report zu erzeugen.
4. Ruft `store_coverage_from_lcov(run_id, lcov_path, html_path)` auf, um
   eine `coverage_report`-Zeile + pro unentdecktem Element `coverage_gap`-Zeilen zu persistieren.
5. Ruft `fold_queue_into_persistent_corpus(...)` auf, um die Iterations-Queue von AFL in den persistenten Corpus zu mergen und `cmin` auszuführen, um die Größe begrenzt zu halten.
6. Liest `get_coverage_summary` + `get_coverage_gaps` und dann entweder:
   - fügt einen neuen Seed hinzu (getaggt mit `coverage_feedback`), um einen unentdeckten
     Branch zu erreichen,
   - bearbeitet den Harness-Quellcode, um eine zusätzliche API aufzurufen,
   - ruft `enrich_dictionary_from_uncovered(...)` auf, um automatisch Dictionary-
     Einträge für die Magic-Konstanten hinzuzufügen, die AFL benötigt, um einen Guard zu erfüllen, oder
   - überspringt die Lücke (kalter Fehlerpfad / Vendor-Code).
7. Ruft `store_iteration_note(repo, iteration_number, harness_id, note=<one
   line summary>)` auf, damit die Iterations-Timeline des Dashboards nachverfolgt, was
   sich geändert hat.

**Plateau-Erkennung.** Die Schleife wird früh beendet, sobald zwei aufeinanderfolgende Iterationen beide < `FUZZ_PLATEAU_THRESHOLD_PCT` (Standard `1.0`) absolute
Prozentpunkte an Zeilenabdeckung hinzugewonnen haben.

---

## Strukturbewusstes Fuzzing

Drei komplementäre Mechanismen erzeugen stärkere Eingaben als reine Byte-Mutation.

### 1. Format-spezifische Dictionaries + Custom-Mutatoren

Für Targets, deren `input_kind` einem bekannten Format entspricht, liefert die Taskflow
vorgefertigte Dictionaries und `LLVMFuzzerCustomMutator`-C-Quelldateien:

| Format | Dictionary | Mutator | Hinweise |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | Token-Splice, balancierte Klammer-Dup/Drop, Typ-Flip |
| `xml` | `xml.dict` | `xml_mutator.c` | Tags, Entities, DTDs, Billion-Laughs-Token |
| `regex` | `regex.dict` | `regex_mutator.c` | Anker, Klassen, Quantifizierer, echte ReDoS-Muster |
| `binary_tlv` | _(keine)_ | `binary_tlv_mutator.c` | Längenpräfixierte Records: Längenüberlauf / Dup / Drop |
| `png` | `png.dict` | _(verwendet binary_tlv wieder)_ | PNG-Dictionary + binary_tlv-Mutator |

Diese werden automatisch von `write_initial_harnesses` (Dictionary
neben Seeds kopiert) und `build_harnesses` (Mutator in die AFL-Binary gelinkt) aufgenommen. Jeder Mutator delegiert 50 % der Mutationen an den Standard-Byte-Mutator von AFL, damit wir die Randomisierung der Engine nicht verlieren.

Um ein neues Format hinzuzufügen: Legen Sie eine `<name>.dict` und/oder eine `<name>_mutator.c` in
`src/seclab_taskflows/dictionaries/` ab und registrieren Sie es in der
`_FORMAT_ASSETS`-Map am Ende von `fuzz_runner.py`.

### 2. Quellcode-bewusster (projektspezifischer) Smart-Mutator

Für unbekannte Formate oder wann immer Sie stärkere projektspezifische
Token wünschen, scannt `generate_smart_mutator` die eigenen `.c`/`.h`-Dateien des Ziel-Repos und erzeugt eine `LLVMFuzzerCustomMutator`-C-Datei, deren Splice-Dictionaries extrahiert werden aus:

- String-Literalen mit ≥3 alphabetischen Zeichen (nach Filterung von Compiler-/Lizenz-
  Rauschen, Pfaden, Headern, Asm-Constraints, Format-Spezifizierern),
- 32-Bit-numerischen Konstanten aus `#define`, `case` und `enum` (nach
  Filterung von generischem Small-Int-Rauschen wie 0, 1, 256, 0xff…).

Drei Fokusse sind verfügbar:

| Fokus | Was gespliced wird | Wann zu verwenden |
|-------|-----------------|-------------|
| `strings` | Nur Projekt-String-Literale | Textformate (JSON, XML, YAML, CSV) |
| `constants` | Nur 32-Bit-numerische Magic-Werte | Binärprotokolle, Header mit Magic Numbers |
| `combined` | Beides | Standard; meist am besten |

Kombinieren Sie `generate_smart_mutators(...)` (Plural) mit `HARNESS_CANDIDATES >= 3`,
damit jeder Fokus zu einem Kandidaten-Harness in der Qualifier-Runde wird.

### 3. Projektbewusstes AFL-Dictionary + Coverage-getriebene Anreicherung

Zwei komplementäre Tools bauen und erweitern ein AFL-`-x`-Dictionary im
Verlauf der Kampagne:

- **`generate_project_dictionary(source_root, output_path)`** — läuft einmal
  vor Iteration 1, extrahiert statisch denselben Quell-Token-Satz, der vom
  Smart-Mutator verwendet wird, und schreibt ihn als AFL-Dictionary. Numerische Konstanten
  werden in BEIDEN Endianness ausgegeben, damit der Fuzzer
  `memcmp(x, &magic, 4)` unabhängig von der Host-Byte-Reihenfolge erfüllen kann.

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path,
  uncovered_locations)`** — läuft nach dem Coverage-Schritt jeder Iteration,
  scannt den umgebenden Quellcode nach bedingten Guards
  (`strncmp/memcmp/strstr`, `case 0xN:`, `== 0xN`, `== 'X'`) in der Nähe der
  unentdeckten Zeilen und HÄNGT alle neuen Token an das Dictionary an. Idempotent:
  fügt niemals einen Eintrag erneut hinzu, der bereits vorhanden ist.

### 4. Corpus-Splice-Operation

Wenn `corpus_dir` an `generate_smart_mutator` übergeben wird, erhält das generierte C
auch einen Corpus-Splice-Operator: Beim ersten Aufruf lädt es bis zu 64 Dateien
aus diesem Verzeichnis (jeweils auf 4 KiB begrenzt), und kann von da an zufällige Teilbereiche dieser Dateien in die mutierte Eingabe splicen. Dies gibt
dem Mutator einen Rekombinations-Operator, den AFLs Standard-Havoc nicht
gut beherrscht. Kombinieren Sie dies mit `get_persistent_corpus_dir(...)`, damit die Splice-Bibliothek
"remixen kann, was AFL bereits entdeckt hat".

---

## Persistenter Corpus über Iterationen und Kampagnen hinweg

Jeder Harness hat ein stabiles Corpus-Verzeichnis unter:```
<workspace>/corpus/harness_<id>/

---

## Ausgabedateien

Alle unter `~/.local/share/seclab-taskflow-agent/seclab-taskflows/`.

| Pfad | Inhalt |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — Ziele, Harnesses, Läufe, Coverage, Crashes, Verdicts, Call Graphs, Harness-Vorschläge, Iterationsnotizen |
| `fuzz_runner/builds/` | Gebaute `.afl`- und `.cov`-Binärdateien |
| `fuzz_runner/runs/` | AFL-Ausgabeverzeichnisse + LCOV-Dateien + HTML-Coverage-Berichte |
| `fuzz_runner/corpus/harness_<id>/` | Persistenter Korpus pro Harness (bleibt über Iterationen & Kampagnen hinweg erhalten) |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Markdown-Kampagnenzusammenfassung, Crashes gruppiert nach Verdict |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | Markdown-Schwachstellenbericht pro Crash |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | Statischer Call Graph + Overlay für erreichte/nicht erreichte Funktionen |

---

## Datenbankschema

Tabellen in `fuzz_context.db` (SQLite via SQLAlchemy):

| Tabelle | Relevante Spalten |
|-------|--------------------|
| `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` |

Schema-Migrationen befinden sich in `_migrate()` in `fuzz_context.py`. Neue TABLES werden
automatisch von `Base.metadata.create_all()` erstellt; nur neue COLUMNS benötigen
PRAGMA-basiertes `ALTER TABLE`.

---

## MCP-Tools (das Vokabular des Agenten)

Der Agent ruft niemals AFL oder clang direkt auf — er setzt die Pipeline zusammen,
indem er MCP-Tools aufruft. Der vollständige Satz, gruppiert nach Zweck:

### Persistenz (`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 / Coverage (`fuzz_runner.py`)

- `check_tooling`, `workspace_paths`
- `compile_harness` — baut `.afl`- und `.cov`-Binärdateien
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — spielt die AFL-Queue gegen die `.cov`-Binärdatei ab, exportiert LCOV
- `extract_dictionary` — extrahiert druckbare Strings aus einer Binärdatei
- `package_reproducer` — bündelt einen Single-Crash-`.tgz`

### Persistenter Korpus (v8)

- `get_persistent_corpus_dir`, `fold_queue_into_persistent_corpus`

### Format-Assets (C5)

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

### Smart Mutator + projektbewusstes Wörterbuch

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

Tool-Funktionen sind mit `@mcp.tool()` (FastMCP) dekoriert. In Tests
ruft man sie über das `.fn`-Attribut auf, z. B.
`fr.run_afl_for.fn(afl_binary_path=..., ...)`.

---

## Einstellbare Parameter (Umgebungsvariablen)

| Variable | Standardwert | Zweck |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | Anzahl der Kandidaten-Harnesses, die pro Ziel geschrieben werden. Auf 2 oder 3 für OSS-Fuzz-Gen-artigen Wettbewerb setzen. Die Qualifizierungsphase führt jeden für `QUALIFIER_SECONDS` aus und behält den besten nach Zeilen-%. |
| `QUALIFIER_SECONDS` | `60` | Wall-Clock-Budget pro Kandidat in der Qualifizierungsphase. |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | Zeilen-Coverage-Zuwachs (in absoluten pp), unterhalb dessen zwei aufeinanderfolgende Iterationen als Plateau gelten und die Schleife frühzeitig stoppt. |
| `FUZZ_DASHBOARD_PORT` | `8765` | Port für das Live-Dashboard. |
| `FUZZ_NO_DASHBOARD` | (nicht gesetzt) | Auf `1` setzen, um den Start des Dashboards zu überspringen. |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | Subprozess-Timeout pro Tool in `fuzz_runner` (Sekunden). |
| `LOCAL_SHELL_TIMEOUT` | `180` | Timeout pro Befehl in `local_shell` (Sekunden). |

Dazu die Standard-Agent-Variablen (`COPILOT_TOKEN`, `LOG_DIR`,
`FUZZ_CONTEXT_DIR`, …). Die vollständige Liste findet sich im README des Projekt-Roots.

---

## Erweitern der Pipeline

### Hinzufügen eines neuen Formats (Mutator + Wörterbuch)

1. `dictionaries/<name>.dict` (AFL `-x`-Format) und/oder
   `dictionaries/<name>_mutator.c` (libFuzzer Custom Mutator) ablegen.
2. In `_FORMAT_ASSETS` am Ende von `fuzz_runner.py` registrieren:   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

Codebase-Konventionen (siehe auch `benchmark/improvements.md` für die
Kampagnenverlaufs-Version dieser):

- Verwende `os.environ.get(NAME) or "default"` statt
  `os.environ.get(NAME, "default")`. Leere Strings aus der YAML-Template-
  Substitution würden andernfalls zurückgegeben.
- Verwende `X | None` (PEP 604) in neuen Annotationen, nicht `Optional[X]`.
- Tests rufen MCP-Tools über `.fn(...)` auf, nicht über den dekorierten Namen direkt.
- Vermeide `/tmp/...`-Literale in Tests — verwende die `tmp_path`-pytest-Fixture
  (Lint-Regel `S108`).
- Alle Inline-Imports innerhalb von Testmethoden benötigen `# noqa: PLC0415`, wenn du
  sie nicht an den Anfang der Datei verschieben kannst (z. B. bei bedingtem Import
  nach einem `pytest.skip`).
- Eine Assertion pro Zeile für zusammengesetzte Wahrheitstests (Lint-Regel `PT018`).

Der Verbesserungs-Tracker (`benchmark/improvements.md`) ist das persistente
Protokoll dessen, was über die Versionen hinweg zur Pipeline hinzugefügt wurde. Wenn du ein
substanzielles Feature hinzufügst, füge dort einen Abschnitt hinzu, der beschreibt, was sich geändert hat, wo es
sich befindet und welche Tests es absichern.

---

## Glossar

- **AFL++** — Coverage-gesteuerter Greybox-Fuzzer; die hier verwendete Ausführungs-Engine.
- **libAFLDriver** — Statische Bibliothek, die es AFL++-Harnesses ermöglicht, die
  libFuzzer-Einstiegspunkt-Konvention (`LLVMFuzzerTestOneInput`) zu verwenden.
- **LCOV** — Industriestandard-Coverage-Tracefile-Format. Wir exportieren dorthin
  über `llvm-cov export -format=lcov` und parsen es selbst.
- **`stack_top_hash`** — Ein 16-Zeichen-Hash der obersten N normalisierten Frames
  eines ASan/UBSan-Stack-Trace. Wird zur Crash-Deduplizierung verwendet.
- **Persistent corpus** — Verzeichnis pro Harness unter
  `<workspace>/corpus/harness_<id>/`, das AFLs interessante Inputs
  über Iterationen und erneute Ausführungen derselben Kampagne hinweg trägt.
- **Smart mutator** — Ein `LLVMFuzzerCustomMutator`, dessen Splice-Tokens aus
  dem Quellcode des Ziels extrahiert werden (`generate_smart_mutator`).
- **Custom mutator (libFuzzer)** — Eine vom Benutzer bereitgestellte C-Funktion, die von
  der Engine mit voller Freiheit darüber aufgerufen wird, wie ein Puffer mutiert wird; AFL++ unterstützt
  dieselbe ABI.
- **MCP tool** — Eine FastMCP-dekorierte Funktion, die der LLM-Agent aufrufen kann.
- **OSS-Fuzz / Fuzz-Introspector** — Googles Open-Source-Fuzzing-
  Infrastruktur und das zugehörige Call-Graph-/Coverage-Analyse-Tool.
  Mehrere Funktionen dieses Taskflows (Format-spezifische Mutatoren, Dedup-by-Stack,
  Call-Graph- + Untouched-API-Bericht, Multi-Candidate-Harnesses) sind
  von ihnen inspiriert.

---

## Lizenz

Dieses Projekt ist unter den Bedingungen der MIT-Open-Source-Lizenz lizenziert. Bitte beachte die [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt)-Datei für die vollständigen Bedingungen.

## Maintainer

Siehe [CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS) oder wende dich an das GitHub Security Lab Team.

## Support

Siehe [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md) für Details dazu, wie du Hilfe zu diesem Projekt erhältst.

## Danksagung

Dieses Projekt baut auf den Konzepten und Techniken von [AFL++](https://github.com/AFLplusplus/AFLplusplus), [OSS-Fuzz](https://github.com/google/oss-fuzz) und [Fuzz-Introspector](https://github.com/ossf/fuzz-introspector) auf.