这会传递性地引入 `seclab-taskflow-agent` 和 `seclab-taskflows`（父级），因此所有形如
`seclab_taskflows.taskflows.audit.*`、
`seclab_taskflows.toolboxes.local_file_viewer`、
`seclab_taskflows.toolboxes.gh_file_viewer` 以及
`seclab_taskflows.configs.model_config` 的点分引用在运行时都会从父级发行版中解析。

---

## 目录

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 工具（智能体的词汇表）](#mcp-tools-the-agents-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)

---

## 这是什么

此任务流是一个完全自主的模糊测试流水线。给定一个原生 C/C++ 项目的 GitHub 仓库，它将：

1. 在缺失时安装 AFL++ + clang/llvm/lcov + ctags/cscope/graphviz，
2. 获取源代码，
3. 识别候选模糊测试目标（解析器、解码器、验证器等），
4. 分析构建系统，
5. 为每个目标编写一个或多个测试桩候选，将每个构建为 AFL 插桩的 `.afl` 二进制文件和覆盖率插桩的 `.cov` 二进制文件，
6. （可选）通过 60 秒覆盖率对候选进行资格筛选并保留最佳者，
7. 运行模糊测试/覆盖率/改进循环，时间预算逐轮翻倍，
8. 对每个崩溃进行分类，确认先前已知的崩溃仍可复现，并编写每个崩溃的 markdown 漏洞报告，包含判定、可利用性、建议补丁和回归测试草图，
9. 为下一轮活动构建 Fuzz-Introspector 风格的调用图 + 未触及 API 报告，
10. 将所有内容发布到实时 HTML 仪表盘。

该流水线在精神上是 **OSS-Fuzz 风格**的：它使用许多相同的技术（按格式的变异器和字典、结构感知的令牌拼接、覆盖率驱动的测试桩改进、机器可读报告、去重的栈哈希崩溃），但它要小得多且自包含。

---

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

---

## 架构

三层结构，自上而下：```
┌────────────────────────────────────────────────────────────────────┐
│  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                           │
└────────────────────────────────────────────────────────────────────┘

每次迭代、每个 harness，agent 会：

1. 调用 `get_persistent_corpus_dir(harness_id)` 获取该 harness 的稳定
   corpus 目录。
2. 调用 `run_afl_for(afl_binary_path, seed_dir=<persistent corpus>,
   output_dir=<run dir>, seconds=<budget>, dictionary=<auto.dict>)`。
3. 调用 `run_coverage(cov_binary_path, inputs_dir=<run>/default/queue,
   output_dir=<run>/coverage)` 生成 LCOV tracefile 和 HTML 报告。
4. 调用 `store_coverage_from_lcov(run_id, lcov_path, html_path)` 持久化
   一条 `coverage_report` 记录 + 每个未覆盖项的 `coverage_gap` 记录。
5. 调用 `fold_queue_into_persistent_corpus(...)` 将 AFL 的迭代
   queue 合并到持久化 corpus 中，并运行 `cmin` 以保持大小有界。
6. 读取 `get_coverage_summary` + `get_coverage_gaps`，然后要么：
   - 添加一个新种子（标记为 `coverage_feedback`）以到达未覆盖的
     分支，
   - 编辑 harness 源码以调用额外的 API，
   - 调用 `enrich_dictionary_from_uncovered(...)` 自动为 AFL 满足 guard 所需的 magic 常量添加字典
     条目，或者
   - 跳过该 gap（冷错误路径 / 厂商代码）。
7. 调用 `store_iteration_note(repo, iteration_number, harness_id, note=<one
   line summary>)`，以便 dashboard 的迭代时间线跟踪
   变更内容。

**平台期检测。** 一旦连续两次迭代的行覆盖率绝对百分点增益均 < `FUZZ_PLATEAU_THRESHOLD_PCT`（默认 `1.0`），循环就会提前退出。

---

## 结构感知模糊测试

三种互补机制可产生比原始字节变异更强的输入。

### 1. 按格式的字典 + 自定义变异器

对于 `input_kind` 匹配已知格式的目标，taskflow 附带
预构建的字典和 `LLVMFuzzerCustomMutator` C 源文件：

| 格式 | 字典 | 变异器 | 备注 |
|--------|------------|---------|-------|
| `json` | `json.dict` | `json_mutator.c` | Token 拼接、平衡括号复制/删除、类型翻转 |
| `xml` | `xml.dict` | `xml_mutator.c` | 标签、实体、DTD、billion-laughs token |
| `regex` | `regex.dict` | `regex_mutator.c` | 锚点、字符类、量词、真实 ReDoS 模式 |
| `binary_tlv` | _(none)_ | `binary_tlv_mutator.c` | 长度前缀记录：长度溢出 / 复制 / 删除 |
| `png` | `png.dict` | _(reuses binary_tlv)_ | PNG 字典 + binary_tlv 变异器 |

这些会被 `write_initial_harnesses`（字典复制到种子旁边）和
`build_harnesses`（变异器链接到 AFL 二进制文件中）自动拾取。每个变异器将 50% 的变异委托给 AFL 的默认字节
变异器，这样我们就不会丢失引擎的随机化能力。

要添加新格式：将 `<name>.dict` 和/或 `<name>_mutator.c` 放入
`src/seclab_taskflows/dictionaries/`，然后在
`fuzz_runner.py` 底部的 `_FORMAT_ASSETS` 映射中注册它。

### 2. 源码感知（项目特定）智能变异器

对于不熟悉的格式，或者当你想要更强的项目特定
token 时，`generate_smart_mutator` 会扫描目标仓库自身的 `.c`/`.h`
文件，并生成一个 `LLVMFuzzerCustomMutator` C 文件，其拼接
字典提取自：

- 具有 ≥3 个字母字符的字符串字面量（在过滤编译器/许可证
  噪声、路径、头文件、asm 约束、格式说明符之后），
- 来自 `#define`、`case` 和 `enum` 的 32 位数值常量（在
  过滤 0、1、256、0xff… 等通用小整数噪声之后）。

有三种 focus 可用：

| Focus | 拼接内容 | 使用时机 |
|-------|-----------------|-------------|
| `strings` | 仅项目字符串字面量 | 文本格式（JSON、XML、YAML、CSV） |
| `constants` | 仅 32 位数值 magic 值 | 二进制协议、带 magic number 的头文件 |
| `combined` | 两者 | 默认；通常最佳 |

将 `generate_smart_mutators(...)`（复数）与 `HARNESS_CANDIDATES >= 3`
配对，这样每个 focus 都会成为资格轮中的一个候选 harness。

### 3. 项目感知 AFL 字典 + 覆盖率驱动增强

两个互补工具会在 campaign 进行过程中构建并扩展 AFL `-x` 字典：

- **`generate_project_dictionary(source_root, output_path)`** — 在第 1 次迭代前运行一次，静态提取与
  智能变异器相同的源码 token 集，并将其写为 AFL 字典。数值常量
  会以两种字节序同时输出，这样无论主机字节序如何，fuzzer 都能满足
  `memcmp(x, &magic, 4)`。

- **`enrich_dictionary_from_uncovered(source_root, dictionary_path,
  uncovered_locations)`** — 在每次迭代的覆盖率步骤之后运行，
  扫描未覆盖行附近的条件 guard
  （`strncmp/memcmp/strstr`、`case 0xN:`、`== 0xN`、`== 'X'`），并将任何新 token 追加到字典中。幂等：
  绝不会重新添加已存在的条目。

### 4. Corpus 拼接操作

当将 `corpus_dir` 传递给 `generate_smart_mutator` 时，生成的 C
还会获得一个 corpus 拼接操作符：首次调用时，它会从该目录加载最多 64 个文件
（每个上限为 4 KiB），此后可以将这些文件的随机子区域拼接到变异后的输入中。这为
变异器提供了一个重组式操作符，而 AFL 自带的 havoc 在这方面做得不好。与 `get_persistent_corpus_dir(...)` 配对，这样拼接库
就是“重新混合 AFL 已经发现的内容”。

---

## 跨迭代和 campaign 的持久化 corpus

每个 harness 都有一个稳定的 corpus 目录，位于：```
<workspace>/corpus/harness_<id>/

---

## 输出文件

全部位于 `~/.local/share/seclab-taskflow-agent/seclab-taskflows/` 下。

| 路径 | 内容 |
|------|----------|
| `fuzz_context/fuzz_context.db` | SQLite — 目标、测试框架、运行记录、覆盖率、崩溃、判定结果、调用图、测试框架建议、迭代笔记 |
| `fuzz_runner/builds/` | 构建的 `.afl` 和 `.cov` 二进制文件 |
| `fuzz_runner/runs/` | AFL 输出目录 + LCOV 文件 + HTML 覆盖率报告 |
| `fuzz_runner/corpus/harness_<id>/` | 每个测试框架的持久化语料库（跨迭代和活动周期保留） |
| `fuzz_runner/repo/<owner>__<repo>/REPORT.md` | Markdown 活动摘要，崩溃按判定结果分组 |
| `fuzz_runner/repo/<owner>__<repo>/vuln_<crash_id>.md` | 每个崩溃的 Markdown 漏洞报告 |
| `fuzz_runner/repo/<owner>__<repo>/call_graph.{dot,svg,md}` | 静态调用图 + 已到达/未到达覆盖层 |

---

## 数据库模式

`fuzz_context.db` 中的表（通过 SQLAlchemy 使用 SQLite）：

| 表 | 关注的列 |
|-------|--------------------|
| `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` |

模式迁移位于 `fuzz_context.py` 中的 `_migrate()`。新表由
`Base.metadata.create_all()` 自动创建；只有新增列需要
基于 PRAGMA 的 `ALTER TABLE`。

---

## MCP 工具（智能体的词汇表）

智能体从不直接调用 AFL 或 clang — 它通过调用 MCP 工具来组合流水线。
完整工具集按用途分组如下：

### 持久化（`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`

### 构建 / 模糊测试 / 覆盖率（`fuzz_runner.py`）

- `check_tooling`, `workspace_paths`
- `compile_harness` — 构建 `.afl` 和 `.cov` 二进制文件
- `run_afl_for`, `cmin`, `tmin`, `replay_under_asan`, `reproduce_crash`
- `run_coverage` — 针对 `.cov` 二进制文件重放 AFL 队列，导出 LCOV
- `extract_dictionary` — 从二进制文件中挖掘可打印字符串
- `package_reproducer` — 打包单个崩溃的 `.tgz`

### 持久化语料库（v8）

- `get_persistent_corpus_dir`, `fold_queue_into_persistent_corpus`

### 格式资产（C5）

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

### 智能变异器 + 项目感知字典

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

工具函数使用 `@mcp.tool()`（FastMCP）装饰。在测试中，
通过 `.fn` 属性调用它们，例如
`fr.run_afl_for.fn(afl_binary_path=..., ...)`。

---

## 可调参数（环境变量）

| 变量 | 默认值 | 用途 |
|----------|---------|---------|
| `HARNESS_CANDIDATES` | `1` | 每个目标生成的候选测试框架数量。设为 2 或 3 以进行 OSS-Fuzz-Gen 风格的竞争。资格筛选阶段对每个候选运行 `QUALIFIER_SECONDS` 秒，并按行覆盖率百分比保留最佳者。 |
| `QUALIFIER_SECONDS` | `60` | 资格筛选阶段中每个候选的墙钟时间预算。 |
| `FUZZ_PLATEAU_THRESHOLD_PCT` | `1.0` | 行覆盖率增益（以绝对百分点计）低于此值时，连续两次迭代被视为进入平台期，循环提前停止。 |
| `FUZZ_DASHBOARD_PORT` | `8765` | 实时仪表盘的端口。 |
| `FUZZ_NO_DASHBOARD` | （未设置） | 设为 `1` 以跳过启动仪表盘。 |
| `FUZZ_RUNNER_TIMEOUT` | `1200` | `fuzz_runner` 中每个工具子进程的超时时间（秒）。 |
| `LOCAL_SHELL_TIMEOUT` | `180` | `local_shell` 中每条命令的超时时间（秒）。 |

以及标准智能体变量（`COPILOT_TOKEN`、`LOG_DIR`、
`FUZZ_CONTEXT_DIR`、……）。完整列表请参阅项目根目录 README。

---

## 扩展流水线

### 添加新格式（变异器 + 字典）

1. 放入 `dictionaries/<name>.dict`（AFL `-x` 格式）和/或
   `dictionaries/<name>_mutator.c`（libFuzzer 自定义变异器）。
2. 在 `fuzz_runner.py` 底部的 `_FORMAT_ASSETS` 中注册：   ```python
   "<name>": {
       "dictionary": "<name>.dict",
       "mutator": "<name>_mutator.c",
       "description": "Short one-liner about the format",
   },

代码库约定（另请参阅 `benchmark/improvements.md` 中这些约定的活动历史版本）：

- 使用 `os.environ.get(NAME) or "default"` 而非
  `os.environ.get(NAME, "default")`。否则 YAML 模板替换产生的空字符串
  会被返回。
- 在新注解中使用 `X | None`（PEP 604），而非 `Optional[X]`。
- 测试通过 `.fn(...)` 调用 MCP 工具，而非直接使用装饰后的名称。
- 避免在测试中使用 `/tmp/...` 字面量——使用 `tmp_path` pytest fixture
  （lint 规则 `S108`）。
- 测试方法内的所有内联导入，如果无法将其移至文件顶部（例如在
  `pytest.skip` 之后条件导入时），都需要添加 `# noqa: PLC0415`。
- 复合真值测试每行仅一个断言（lint 规则 `PT018`）。

改进追踪器（`benchmark/improvements.md`）是跨版本记录流水线中新增内容的
持久日志。当你添加实质性功能时，请在其中添加一节，描述变更内容、
所在位置以及哪些测试对其进行守护。

---

## 术语表

- **AFL++** — 覆盖率引导的灰盒模糊测试器；此处的执行引擎。
- **libAFLDriver** — 静态库，允许 AFL++ 测试框架使用
  libFuzzer 入口点约定（`LLVMFuzzerTestOneInput`）。
- **LCOV** — 行业标准的覆盖率跟踪文件格式。我们通过
  `llvm-cov export -format=lcov` 导出并自行解析。
- **`stack_top_hash`** — ASan/UBSan 堆栈跟踪中顶部 N 个规范化帧的
  16 字符哈希。用于崩溃去重。
- **持久语料库** — 位于
  `<workspace>/corpus/harness_<id>/` 的每个测试框架目录，用于在迭代和
  同一活动的重新运行之间保留 AFL 的有趣输入。
- **智能变异器** — 一种 `LLVMFuzzerCustomMutator`，其拼接令牌从
  目标自身的源代码中提取（`generate_smart_mutator`）。
- **自定义变异器（libFuzzer）** — 用户提供的 C 函数，由引擎调用，
  可完全自由地决定如何变异缓冲区；AFL++ 支持相同的 ABI。
- **MCP 工具** — 经 FastMCP 装饰的函数，LLM 代理可调用。
- **OSS-Fuzz / Fuzz-Introspector** — Google 的开源模糊测试
  基础设施及其配套的调用图/覆盖率分析工具。
  此任务流的若干功能（按格式变异器、按堆栈去重、
  调用图 + 未触及 API 报告、多候选测试框架）均受其启发。

---

## 许可证

本项目根据 MIT 开源许可证的条款授权。请参阅 [LICENSE](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/LICENSE.txt) 文件了解完整条款。

## 维护者

请参阅 [CODEOWNERS](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/CODEOWNERS) 或联系 GitHub Security Lab 团队。

## 支持

请参阅 [SUPPORT.md](https://github.com/githubsecuritylab/seclab-taskflows-fuzzing/blob/main/SUPPORT.md) 了解如何获取此项目帮助的详细信息。

## 致谢

本项目基于 [AFL++](https://github.com/AFLplusplus/AFLplusplus)、[OSS-Fuzz](https://github.com/google/oss-fuzz) 和 [Fuzz-Introspector](https://github.com/ossf/fuzz-introspector) 的概念和技术构建。