Seclab Taskflows Fuzzing

An LLM-driven, OSS-Fuzz-style fuzzing pipeline for native C/C++ projects. AFL++ for execution, clang+lcov for coverage, an LLM agent for harness writing, coverage-feedback decisions, triage, and reporting.

• Fully autonomous: give it a GitHub repo and it handles everything from target identification to vulnerability reports.
• OSS-Fuzz-style techniques: per-format mutators/dictionaries, structure-aware token splicing, coverage-driven harness improvements.
• Produces machine-readable crash reports with exploitability verdicts and suggested patches.
• Live HTML dashboard for real-time campaign monitoring.
• Written in Python (taskflows/toolboxes/configs) with C harness generation for AFL++.
• Status: Active development.

Background

This repository contains the fuzzing taskflow for the GitHub Security Lab Taskflow Agent. It depends on the seclab-taskflows companion repository for a few shared building blocks (fetch_source_code taskflow, local_file_viewer / gh_file_viewer toolboxes, and the default model_config) — those are installed automatically as a Python dependency.

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Requirements

• Python 3.11+
• A Linux environment (or Codespace) with access to apt
• AFL++, clang, lcov, ctags, cscope, graphviz (auto-installed by the pipeline if missing)
• Git and GitHub CLI (gh)

Installation

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

This pulls in seclab-taskflow-agent and seclab-taskflows (parent) transitively, so every dotted reference of the form seclab_taskflows.taskflows.audit.*, seclab_taskflows.toolboxes.local_file_viewer, seclab_taskflows.toolboxes.gh_file_viewer, and seclab_taskflows.configs.model_config resolves out of the parent distribution at runtime.

---

Table of contents

1. What this is
2. Quick start
3. Architecture
4. The pipeline, stage by stage
5. The coverage-feedback loop
6. Structure-aware fuzzing
7. Persistent corpus across iterations and campaigns
8. Triage and vulnerability reports
9. Live dashboard
10. Output files
11. Database schema
12. MCP tools (the agent's vocabulary)
13. Tunable knobs (environment variables)
14. Extending the pipeline
15. Benchmark projects and results
16. Limitations and gotchas
17. Security warning
18. Development: testing, linting, contributing
19. Glossary

---

What this is

This taskflow is a fully autonomous fuzzing pipeline. Given a GitHub repo of a native C/C++ project, it will:

1. install AFL++ + clang/llvm/lcov + ctags/cscope/graphviz if missing,
2. fetch the source,
3. identify candidate fuzz targets (parsers, decoders, validators, …),
4. analyse the build system and build the target library three times: with AFL++ edge-coverage instrumentation plus sanitizers, with AFL++ CMPLOG instrumentation, and with clang source-based coverage instrumentation,
5. write one or more harness candidates per target, build each as an AFL++-instrumented .afl binary, an AFL++ CMPLOG-instrumented .cmplog binary and a clang coverage-instrumented .cov binary,
6. (optionally) qualify candidates by 60-second coverage and keep the best,
7. run a fuzz/coverage/improve loop with doubling time budgets,
8. triage every crash, confirm previously-known crashes still reproduce, and write per-crash markdown vuln reports with verdicts, exploitability, suggested patches, and regression-test sketches,
9. build a Fuzz-Introspector-style call graph + untouched-API report for the next campaign,
10. publish everything to a live HTML dashboard.

The pipeline is OSS-Fuzz-style in spirit: it uses many of the same techniques (per-format mutators and dictionaries, structure-aware token splicing, coverage-driven harness improvements, machine-readable reports, deduped stack-hashed crashes) but it is much smaller and self-contained.

---

Quick start

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

That's the whole interface. The script is autonomous; it will install AFL++ on first run, then drive the rest of the taskflow. Output files are written to ~/.local/share/seclab-taskflow-agent/seclab-taskflows/.

The dashboard auto-starts in the background; in a Codespace, port 8765 is auto-forwarded — open it in any browser to watch progress live.

For a quick smoke-test, use a small target:

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

---

Architecture

Three layers, top to bottom:

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

Key design rules: