用 OSS-Fuzz 为开源项目接入持续模糊测试并在本地复现…

当需要给开源项目接入免费的分布式持续模糊测试、或本地复现 OSS-Fuzz 崩溃报告时，用 helper.py 构建镜像/构建 harness/运行 fuzzer/出覆盖率，并按 project.yaml + Dockerfile + build.sh 三件套提交项目。

适用场景

解决思路

1. 克隆官方仓库并确认工具可用：git clone https://github.com/google/oss-fuzz，cd oss-fuzz，然后运行 uv run --no-project python infra/helper.py --help 查看所有可选子命令。
2. 构建项目镜像（会下载并构建对应的基础 Docker 镜像）：uv run --no-project python infra/helper.py build_image --pull <project-name>。
3. 构建 fuzzer 并指定 sanitizer：uv run --no-project python infra/helper.py build_fuzzers --sanitizer=address <project-name>；address 为 AddressSanitizer 加 LeakSanitizer，其他 sanitizer 视语言支持情况可用。
4. 构建产物落在 /build/out/<project-name>/，其中包含 harness 可执行文件、字典、语料和 crash 文件，从这里取产物做本地分析。
5. 运行指定 harness：uv run --no-project python infra/helper.py run_fuzzer <project-name> <harness-name> [<fuzzer-args>]；helper 脚本会在你跳过前置步骤时自动补跑缺失步骤。
6. 生成覆盖率报告：先安装 gsutil（跳过 gcloud 初始化），再执行 build_fuzzers --sanitizer=coverage <project-name>，然后执行 coverage <project-name>；只使用本地语料时加 --no-corpus-download，命令会在本地生成并托管覆盖率报告。
7. 用已收录的简单项目（如 irssi）走一遍完整流程验证环境：build_image --pull irssi、build_fuzzers --sanitizer=address irssi、run_fuzzer irssi irssi-fuzz，并核对输出中的 seed corpus、coverage、exec/s 等信息。
8. 在 projects/<your-project>/ 下创建 project.yaml 定义元数据：homepage、language、primary_contact、main_repo，以及 fuzzing_engines（如 libfuzzer、afl）和 sanitizers（如 address、undefined）列表。
9. 创建 Dockerfile 安装构建依赖：FROM gcr.io/oss-fuzz-base/base-builder，用 RUN apt-get update && apt-get install -y ... 装 autoconf/automake/libtool/pkg-config 等，再 RUN git clone --depth 1 <repo>、设置 WORKDIR，并 COPY build.sh $SRC/。
10. 创建 build.sh 构建 harness：先正常构建项目（如 ./autogen.sh、./configure --disable-shared、make -j$(nproc)），再用 $CXX $CXXFLAGS -std=c++11 -I. <harness.cc> -o $OUT/<harness> $LIB_FUZZING_ENGINE <静态库> 链接出 harness。
11. 在 build.sh 中把语料与字典复制到 $OUT：cp <repo>/fuzz/corpus.zip $OUT/<harness>_seed_corpus.zip、cp <repo>/fuzz/dictionary.dict $OUT/<harness>.dict。
12. 把 fuzz harness 放在独立仓库中维护（参考 curl-fuzzer 的做法），保持与主项目仓库的分离。
13. 不要手动把源码复制进 OSS-Fuzz 仓库：让项目 Dockerfile 负责 git clone 拉取最新版本，不要在 build.sh 里手动拉源码。
14. 把所有依赖写进 Dockerfile 的 apt-get install 等安装步骤；纳入公共 OSS-Fuzz 时新增依赖可能需要审批。
15. 参考 oss-fuzz/projects 目录下已有项目的写法作为模板。
16. 提交 PR 之前先用 helper.py 在本地把镜像构建、fuzzer 构建和运行全部跑通，避免浪费 CI 资源。
17. 定期查看 build status 页面（oss-fuzz-build-logs.storage.googleapis.com），跟踪各项目构建状态、最后成功构建日期以及构建失败及其持续时间。
18. 用 bug tracker（issues.oss-fuzz.com）按项目筛选 bug、创建新 issue、评论已有 issue，并跨所有项目搜索相似 bug 以理解问题。
19. 用 Fuzz Introspector 查看已收录项目的覆盖率、被覆盖代码的命中频率、性能分析与模糊测试阻塞点。
20. libFuzzer（C/C++，OSS-Fuzz 主引擎）：按 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) 签名写 harness；在 build.sh 中用 $LIB_FUZZING_ENGINE 变量链接；-fsanitize=fuzzer 由 OSS-Fuzz 自动处理；尽量链接静态库。
21. AFL++：在 project.yaml 的 fuzzing_engines 中加入 afl（可与 libfuzzer 并存），harness 与 libFuzzer harness 并行使用，并用 persistent mode 提升性能；引擎相关的编译参数由 OSS-Fuzz 处理。
22. Atheris（带 C 扩展的 Python 项目）：用 @atheris.instrument_func 装饰 TestOneInput，用 atheris.FuzzedDataProvider 取数据，捕获解析异常（如 cbor2.CBORDecodeError、ValueError）后忽略；main 中调用 atheris.Setup(sys.argv, TestOneInput) 和 atheris.Fuzz()。
23. Atheris 的 build.sh：执行 pip3 install .，然后 for fuzzer in $(find $SRC -name 'fuzz_*.py'); do compile_python_fuzzer $fuzzer; done，使用 OSS-Fuzz 提供的 compile_python_fuzzer 辅助脚本。
24. Rust 项目：project.yaml 中设 language: rust、fuzzing_engines 为 libfuzzer、sanitizers 只填 address（Rust 当前仅支持 AddressSanitizer + libfuzzer）；build.sh 执行 cargo fuzz build -O --debug-assertions，并把 fuzz/target/x86_64-unknown-linux-gnu/release/fuzz_target_1 复制到 $OUT/。
25. 构建报缺依赖时，把缺失的依赖用 apt-get install（或等价方式）补进 Dockerfile。
26. harness 一启动就崩溃时，在 harness 里补输入长度/大小检查等校验逻辑。
27. 覆盖率为 0% 时，检查 harness 是否真的调用了目标函数。
28. 构建超时时，优化 build.sh 或改用并行构建。
29. 构建期出现 sanitizer 报错时，改用 OSS-Fuzz 提供的环境变量中的编译标志，而不是自己另加不兼容标志。
30. 找不到源码时，在 Dockerfile 中设置 WORKDIR 或改用绝对路径。
31. 不要忽略 base image 版本：使用 OSS-Fuzz 提供的基础镜像与编译器（base_image → base_clang → base_builder → 项目镜像；运行用 base_runner / base_runner_debug），以保证构建环境一致。

适用边界 · 注意事项

• 项目是闭源、或所在项目无法通过 OSS-Fuzz 的 criticality score 门槛时（除非自行托管私有 OSS-Fuzz 实例）。
• 需要专有或专用模糊测试基础设施的场景。
• 只是模糊测试简单脚本、不值得引入整套容器与基础设施的情况。