接手一个开源项目最怕的不是功能没人用而是半夜收到邮件某个依赖你库的 downstream 项目崩了一查还是内存越界问题压在老版本代码里可能躺了好几年。这种时候我的第一反应就是为什么当初没早点把 OSS-Fuzz 接上。OSS-Fuzz 是 Google 联合多家机构推出的开源项目持续模糊测试服务简单说就是帮你把模糊测试Fuzzing这件事的基础设施整个包办它用你的项目镜像构建 fuzz target在云端大规模随机生成输入喂给你的解析代码一旦触发崩溃、超时、内存错误会自动生成最小化测试用例并私密通知维护者。对于写 C/C、Rust、Go、Python 这类项目的开发者来说接入 OSS-Fuzz 基本等于给项目请了一位全年无休的漏洞猎手。这篇文章我会从零开始完整走一遍接入 OSS-Fuzz 的流程先讲清楚它背后的运行逻辑和为什么值得接入再逐个拆解需要编写的每个文件最后结合我实际踩过的坑整理一份可以直接照抄的接入手册。不管你的项目是网络协议解析、图片解码、配置反序列化还是自定义文件格式这套流程都适用。1. 内容整体设计与思路拆解1.1 为什么选 OSS-Fuzz 而不是自己搭一套 Fuzzing 环境早些年做模糊测试是真的折腾。你要自己准备一台或者一组机器装好 Clang、配置 libFuzzer 或者 AFL再写脚本循环跑语料崩了还得手动去抓日志、做 crash 去重。更麻烦的是Fuzzing 要想跑出效果需要足够长的覆盖时间和足够大的算力个人电脑跑一个晚上可能连目标代码的深层分支都摸不到。OSS-Fuzz 把这几件事全接过去了。它依托 Google Cloud 的持续集成调度项目只要按要求提供 Dockerfile 和 fuzz target剩下的事情都是自动化的任务分发、语料库管理、覆盖率统计、回归检测、崩溃报告。你不需要自己维护集群也不需要盯着日志看有没有 crash基础设施跑完会自动把结果反馈到 issue 里。而且 OSS-Fuzz 不是简单把 libFuzzer 包了一层它背后做的工作比这深得多。它的调度系统会记录每天的 code coverage 变化对新增代码重点做变异测试语料库是云端集中管理的每次跑出的新覆盖路径会不断回流到 corpus 里后一次运行能继续在前一次的基础上做变异而不是每次都从零开始。这叫什么这叫覆盖率引导的持续 fuzzing比个人拿个 fuzzer 随便跑几个小时有效率高太多了。1.2 接入前必须想清楚的架构逻辑OSS-Fuzz 的接入逻辑用一句话概括你只负责提供 fuzz target也就是一个从内存缓冲区读取输入、把它丢给你想要测试的代码函数的入口其余真正干活的部分基础设施自动完成。这里要理解一个关键点OSS-Fuzz 并不直接测试你的整个程序。它不会把你的二进制文件拉起来然后随机敲键盘它用的是 libFuzzer 引擎在进程中反复调用一个入口函数每次喂一段字节数组进去。入口函数里面你调什么 API就测什么 API。想测配置解析就在 fuzz target 里调用解析器想测网络协议解码就在 target 里把字节流交给协议解析函数。这是整个接入思路的核心写 target 不是写单元测试而是要写一个足够宽、足够底层、能覆盖你项目中最容易出问题的输入处理代码的入口。更深一层OSS-Fuzz 默认开启多种 sanitizer特别是 AddressSanitizerASAN和 UndefinedBehaviorSanitizerUBSAN。ASAN 负责抓内存越界、释放后使用use-after-free、堆溢出这类问题UBSAN 负责抓移位溢出、整数溢出、非法空指针这类未定义行为。所以你在本地写 fuzz target 的时候也一定要用开了 ASAN 的 Clang 编译否则很多问题根本暴露不出来。没有 sanitizer 辅助模糊测试最多只能抓到那些会导致崩溃的输入而内存错误在没被触发的状态下根本不会表象化。2. 核心细节解析与实操要点2.1 先说清楚几个绕不开的角色和文件我在接一个新项目进 OSS-Fuzz 的时候一般按照下面这个角色清单来理思路fuzz target你的 C/C 源文件里面实现 LLVMFuzzerTestOneInput 函数函数体内把你想要测的代码入口以数据流调用的方式接进来。构建脚本 build.sh运行在基础设施的容器里的 shell 脚本负责用特殊编译参数编出你的 fuzz target并把生成的可执行文件复制到指定输出目录。Dockerfile用于基础设施构建镜像里面需要安装你项目编译所需的全部依赖。project.yaml给 OSS-Fuzz 基础设施看的主配置文件声明语言、fuzzing 引擎、sanitizer、联系邮箱等元信息。这里给第一次接触的人提个醒OSS-Fuzz 的官方文档里会强调它限制单次输入大小、建议用动态库方式接入但最核心的一条规则是不要在你的 fuzz target 里做输出比如打印日志到 stdout因为 fuzzing 引擎会在单位时间内跑成千上万次调用任何一次 print 都会拖慢整体执行速度还会产生海量无用日志影响崩溃分析和去重。2.2 fuzz target 内部结构的三个关键设计写 fuzz target 不是简单写一句ParseData(Data, Size)就完事。我觉得这里头有三个工程细节直接决定测试效果好坏。第一入口要宽。你的 fuzz target 不是 unit test不需要精确断言某个返回值它要尽可能宽地调用整个数据解析链路。比如在测一个 JSON 解析库不要只测parse(json)要把 tokenizer、validator、AST 构建器整条链路都喂进去。因为漏洞往往隐藏在数据被拆开、被递归下降处理的过程中只测顶层 API 可能根本没有走到深处。第二状态要隔离。libFuzzer 是在同一个进程里反复调用你的 target 的如果 target 内部用了全局变量或者缓存那么上一次调用残留的状态会污染下一次。一个比较常见的场景是解析器内部有内存池memory pool或者全局注册表在 fuzz target 的每次入口处要确保清理干净否则你测的状态根本不是真实用户的使用状态还会导致随机性 crash 事后难复现。第三结构感知structure-aware输入。一些格式有 header、校验和之类的强约束比如什么文件头幻数不对就直接 reject。这种场景下随机字节基本全部走 early-exit 分支覆盖率根本提不起来。OSS-Fuzz 支持自定义 mutator或者更简单的做法是提供一份高质量种子语料库corpus让你项目里正常工作的示例文件放进去把解析路径的基本区块都激活fuzzer 再在这个基础上做字节级变异效果就明显不同。2.3 推荐的项目目录布局我建议每个要接入的项目在仓库里单独建一个fuzzing目录里面按下面结构放fuzzing/ ├── project.yaml ├── Dockerfile ├── build.sh └── fuzzers/ ├── parse_fuzzer.cpp └── read_settings_fuzzer.cpp为什么单独建目录因为 OSS-Fuzz 的 docker build context 默认是当前目录你要是不小心把整个项目源码都塞进去镜像会变得巨大构建速度极慢。只把 fuzz 相关文件放在一个小目录里Dockerfile 内部再去git clone或者复制真正需要测试的源码这样镜像又快又干净。3. 实操过程与核心环节实现3.1 注册项目与基础设施准备在动手写代码之前有几个账号和仓库层面的准备工作要先完成。OSS-Fuzz 的项目收录由 google/oss-fuzz 仓库管理你通常需要通过 PR 方式把项目配置合入官方仓库不过在提交 PR 之前我强烈建议先把整个接入流程在本地过一遍用 infra 提供的helper.py脚本做本地构建验证。先把仓库克隆到本地git clone https://github.com/google/oss-fuzz.git cd oss-fuzz本地构建和测试需要 Docker。项目的projects/your-project目录是你需要新建的然后在这个目录下放好我们上面说的几个文件。OSS-Fuzz 提供了辅助脚本helper.py可以执行类似下面的操作python3 infra/helper.py build_image $PROJECT_NAME python3 infra/helper.py build_fuzzers --sanitizer address $PROJECT_NAME python3 infra/helper.py run_fuzzer --sanitizer address $PROJECT_NAME $FUZZER_NAME这里面的逻辑是先用本地 Dockerfile 构建一个项目基础镜像然后在镜像内部运行 build.sh 把 fuzz target 编译出来最后通过 run_fuzzer 在本地环境启动 fuzzer 验证能否正常执行。3.2 手写一份完整可用的构建文件下面我们以一个虚构项目libmagicdata为例它是一个解析自定义二进制数据格式的 C 库头文件放在项目根目录的include/libmagicdata/parser.h源文件在src/parser.cpp。接下来我会展示完整接入需要写的内容。project.yaml 最简版homepage: https://github.com/example/libmagicdata main_repo: https://github.com/example/libmagicdata.git language: c primary_contact: maintainerexample.com sanitizers: - address - undefined这几个字段看似简单但每个背后都有讲究。main_repo是指代码仓库地址OSS-Fuzz 构建镜像时会根据 build.sh 里的逻辑去拉取源码而不是自动 clonemain_repo里的代码。primary_contact是崩溃报告的接收邮箱务必填长期有人维护的地址否则崩溃报告没人看就等于白跑。语言字段决定了启用哪些 toolchain 的默认配置。Dockerfile 内容FROM gcr.io/oss-fuzz-base/base-builder:v1 RUN apt-get update apt-get install -y autoconf automake libtool RUN git clone --depth 1 https://github.com/example/libmagicdata.git magicdata WORKDIR magicdata COPY build.sh $SRC/这里有个非常重要的约定$SRC环境变量在基础镜像里已经预置通常指向/src。我们把项目源码 clone 到$SRC/magicdata把 build.sh 拷贝到$SRC下。整个工作目录切到源码目录是为了 build.sh 里执行编译命令时路径不会太长。build.sh 的核心逻辑#!/bin/bash -eu cd $SRC/magicdata # 这一步是生成构建系统很多 autotools 项目需要在编译前执行 autoreconf ./autogen.sh # OSS-Fuzz 通过环境变量 $CC、$CXX、$CFLAGS、$CXXFLAGS 传入编译器与编译参数 ./configure --disable-shared --enable-static make -j$(nproc) # 编译 fuzz target $CXX $CXXFLAGS -stdc11 -I include \ $SRC/magicdata/fuzzing/parse_fuzzer.cpp \ src/.libs/libmagicdata.a \ $LIB_FUZZING_ENGINE \ -o $OUT/parse_fuzzer这里最关键的三个环境变量是$CC、$CXXFLAGS和$LIB_FUZZING_ENGINE。OSS-Fuzz 基础镜像已经设置好 Clang 和对应的 sanitizer 编译选项$LIB_FUZZING_ENGINE会指向一个包含 fuzzer 引擎入口的库它与LLVMFuzzerTestOneInput配合完成整个 fuzzing 循环。写到这里我想特别强调一下-fsanitizefuzzer这件事。很多人在本地用 Clang 写 fuzz target 的时候习惯直接命令行加-fsanitizefuzzer,address但在 OSS-Fuzz 环境里不要这么做因为引擎已经通过$LIB_FUZZING_ENGINE以静态库形式引入了。你只需要编译 target 时带上$CXXFLAGS里已有的 sanitizer 参数然后手动把 target 的目标文件和项目静态库、以及$LIB_FUZZING_ENGINE一起链接。fuzz target 源文件parse_fuzzer.cpp#include stddef.h #include stdint.h #include libmagicdata/parser.h extern C int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size) { // 数据块大小限制不是必要的但建议对超大输入做剪裁 if (size sizeof(struct magicdata_header)) return 0; struct magicdata_context* ctx magicdata_parse_create(); if (!ctx) return 0; magicdata_parse_buffer(ctx, data, size); // 解析完成后尝试导出内部结构增加路径覆盖率 if (magicdata_validate(ctx) 0) { char* output nullptr; size_t out_size 0; magicdata_serialize(ctx, output, out_size); free(output); } magicdata_parse_destroy(ctx); return 0; }注意这里我故意没有用项目假设的 C API而是模拟了一个 C API 接口这是因为不少被接入 OSS-Fuzz 的库会暴露 C ABI使用 C 接口测试能避开 C 的对象生命周期问题减少误报。如果你的库只有 C API 也没关系可以直接在 target 内部构造对象但要注意异常安全。种子语料方面我在项目示例目录里挑了几份结构差异尽量大的真实数据文件拷进fuzzing/corpus/目录然后在 build.sh 里把它们拷贝到$OUT/parse_fuzzer_seed_corpus.zip对应的解压目录。3.3 跑通本地验证闭环文件都准备好了在提交 PR 之前一定要先在本地跑一遍。这里我给出我实际测试时使用的命令python3 infra/helper.py build_image magicdata python3 infra/helper.py build_fuzzers --sanitizer address magicdata python3 infra/helper.py run_fuzzer --sanitizer address magicdata parse_fuzzer -max_total_time60第一行构建镜像如果 Dockerfile 里有依赖安装错误在这个阶段就会暴露。第二行真正编译 fuzz target所有编译错误也在这个步骤出现。第三行会在本地容器内启动 fuzzer 运行 60 秒通常我建议第一次跑至少 5 分钟因为某些深层路径在很短时间内根本走不到但本地验证的目的不是期待立即崩溃而是确认 fuzzer 进程能正常起跑、日志里能看到覆盖率信息逐步增长。跑完以后如果一切正常日志里会出现类似下面这样#2 NEW cov: 156 ft: 204 corp: 5/1Kb lim: 1024 exec/s: 120 rss: 45Mb L: 512/512 MS: 1 ShuffleBytes- #15 NEW cov: 203 ft: 315 corp: 9/2Kb lim: 1024 exec/s: 220 rss: 46Mb L: 800/800 MS: 2 CrossOver-这里的 cov 是被覆盖的代码块数量ft 是覆盖特征数包括边、值等corp 是当前语料库大小exec/s 是每秒执行次数。如果 exec/s 低得离谱比如只有个位数说明 target 里可能做了非常重的操作或者存在死循环嫌疑需要排查。4. 常见问题与排查技巧实录4.1 崩溃报告里的复现与修复闭环OSS-Fuzz 的崩溃并不是直接通过邮件发给你一个二进制文件就完事它会附带一份经过最小化的测试用例testcase。在 issue 里你会看到一个下载链接下载这个文件后本地复现方式非常简单python3 infra/helper.py build_fuzzers --sanitizer address magicdata python3 infra/helper.py reproduce magicdata parse_fuzzer -seed1 /path/to/downloaded/testcase这个命令会用和基础设施相同的编译参数重新编译 target然后直接拿着 testcase 跑一次如果崩溃能稳定复现说明报告可信接下来就能用 gdb 或 llvm-symbolizer 回溯堆栈。有一点很容易踩坑有时候报告里说 stack-buffer-overflow但你在本地用 release 版本复现不了因为 release 没有开 ASAN。务必用--sanitizer address重新构建否则内存错误可能根本不会触发异常信号。另外本地机器架构是 x86_64基础设施也以 x86_64 为主如果是处理跨平台字符串编码类问题可能只在特定 locale 下崩溃这类问题我建议在 target 初始化时设置固定的 locale。4.2 覆盖率低跑了很久没有进展怎么办如果你观察到跑了很久 cov 数字几乎不动问题大概率出在输入校验太严格随机字节被早早 reject。常见解法有四种第一把正则校验或者幻数检查相关的代码提取出来让 fuzzer 直接在解码函数层面做变异跳过格式识别的前置条件。第二提供更丰富的种子语料并且保证这些语料能触发不同分支。第三使用-dict参数传入格式关键词字典比如文件头标志字符、常见的结构体标记等。OSS-Fuzz 支持通过 fuzzer 运行参数额外携带字典但实际上更推荐的做法是把你所有的关键词写在代码里再引导变异因为官方基础设施对 dict 文件的支持有限。第四如果项目格式实在复杂考虑直接写一个结构感知的 mutator。这是成本最高的方案但收益也最明显适合那种有 checksum 强校验的文件格式、网络协议类项目。4.3 链接错误、命名空间冲突等编译期疑难杂症编译是很多人接入时卡住的第一道门槛。最常见的问题有两个。一个是 fuzz target 里包含了项目主程序的 main 函数。有些项目会在libmain之类的库里把入口函数一并提供了链接时你和$LIB_FUZZING_ENGINE里的 main 就重复定义了。解决办法是调整编译目标只链接你需要的对象文件别图省事整个静态库一把梭。另一个问题是 C 异常跨 C 边界。如果你用extern C包装了 C 函数而内部抛出了异常没有被捕获在有-fno-exceptions的构建环境里会直接 terminate。这时候与其在 target 里到处 try-catch不如检查项目本身的编译选项是否对库代码异常安全。OSS-Fuzz 默认是启用异常的但如果你自己用-fno-exceptions编译库代码那么 target 里凡是调用可能抛异常的库函数都要自己兜住。4.4 如何高效定位崩溃根因而不被噪音带偏收到一个新 crash我最开始不会直接看堆栈最深的几帧因为 sanitizer 的输出堆栈往往很长很多帧是引擎内部或 STL 的模板展开。我更习惯先确认三个信息崩溃类型是什么stack-overflow 还是 heap-use-after-free、crash 地址所在的分配上下文是在 target 之前还是 target 内部分配的、input 的最小化样本有多大。OSS-Fuzz 的 issue 里通常已经自动做了 testcase 最小化但即便最小化后的样本也可能还有几十 KB这时候我们可以用 Clang 的-fsanitize-address-use-after-scope等参数做精细检查或者干脆在本地对 testcase 做二分裁剪辅助定位。我常用的方法是写一个十几行的 Python 脚本每次把样本切成两半分别运行 target 看是否仍然崩溃用二分法快速定位到真正触发崩溃的关键字节偏移。import subprocess import sys data open(sys.argv[1], rb).read() target ./parse_fuzzer def crashes(chunk: bytes): tmp /tmp/tc.bin open(tmp, wb).write(chunk) r subprocess.run([target, tmp], capture_outputTrue) return r.returncode ! 0 left, right 0, len(data) while right - left 1: mid (left right) // 2 if crashes(data[left:mid]): right mid else: left mid open(/tmp/min_crash.bin, wb).write(data[left:right])这个脚本的逻辑很简单但配合 ASAN 来做手工二分效率很高。如果把截断后仍然崩溃的样本慢慢缩小到几个字节基本就能一眼看出是哪个标记位、哪个长度字段触发的漏洞。5. 提交接入与长期维护建议5.1 PR 合入官方仓库的基本流程与注意点本地验证通过后就该往 google/oss-fuzz 仓库提交 PR把你的项目目录加进去。Pull Request 里建议写清楚几个信息项目是做什么的、为什么值得接入、已经本地跑过哪些验证、fuzz target 主要覆盖了哪些功能模块。维护者通常会要求你确认primary_contact是有效邮箱可能会让你在项目 README 里加一个 oss-fuzz 的 badge。在提交之前我强烈建议你到 OSS-Fuzz 的 issue tracker 里搜一下自己的项目名看是不是已经有人在 tracking 或者曾经提交过又因为某些原因被关闭了。曾经有多个项目因为构建脚本被杀毒软件误报或者覆盖范围太窄而被拒绝翻翻旧 issue 能帮你避开不少弯路。5.2 合入之后不是终点而是一个持续改进的过程很多项目在接入初期跑一段时间后会出现 crash 数量从高到低的变化。新项目刚接入时经常能挖出一批陈年漏洞这是正常的。修复完这些之后会进入一个相对平稳期但这不代表模糊测试可以放手不管了。随着项目新功能的加入fuzzer 的输入路径会变宽覆盖率也需要持续关注。建议至少每个月做一次以下检查第一去 oss-fuzz.com 看自己项目的最近的覆盖率趋势如果加了新功能模块但覆盖率没涨说明 fuzz target 没有覆盖新代码需要补充新的 seed corpus 或新的 target。第二检查崩溃队列里是否积压了未处理的 bug。第三适时新增 fuzz target。比如你在项目里新增了一个 RPC 协议解析器那就要针对这个解析器写一个新的 target而不是只改老的通用数据解析 target。真实项目里我在接入完之后最常做的一件事就是把基础设施上报的 crash 样本保存一份到内部缺陷管理系统标记好类型和修复状态。这样既能让团队看到模糊测试的实际产出也能在做安全审计时拿出历史数据证明项目经过了持续 fuzzing 验证。最后再分享一个我个人的使用习惯。除了 OSS-Fuzz 官方主仓库之外我在自己的 CI 里也加了 libFuzzer 的短时回归任务把 OSS-Fuzz 提供的 corpus 同步到本地每次代码合入前跑 3 到 5 分钟。这样做的目的是在合入前拦截掉一部分低级错误避免等到基础设施跑完一轮才发现问题。OSS-Fuzz 是最后一道防线但每天开发过程中的快速回显也同样重要。 
长河君 · 2026/9/9 4:21:57 · 阅读 1.2k 开源项目接入OSS-Fuzz：持续模糊测试完整实战指南
接手一个开源项目最怕的不是功能没人用而是半夜收到邮件某个依赖你库的 downstream 项目崩了一查还是内存越界问题压在老版本代码里可能躺了好几年。这种时候我的第一反应就是为什么当初没早点把 OSS-Fuzz 接上。OSS-Fuzz 是 Google 联合多家机构推出的开源项目持续模糊测试服务简单说就是帮你把模糊测试Fuzzing这件事的基础设施整个包办它用你的项目镜像构建 fuzz target在云端大规模随机生成输入喂给你的解析代码一旦触发崩溃、超时、内存错误会自动生成最小化测试用例并私密通知维护者。对于写 C/C、Rust、Go、Python 这类项目的开发者来说接入 OSS-Fuzz 基本等于给项目请了一位全年无休的漏洞猎手。这篇文章我会从零开始完整走一遍接入 OSS-Fuzz 的流程先讲清楚它背后的运行逻辑和为什么值得接入再逐个拆解需要编写的每个文件最后结合我实际踩过的坑整理一份可以直接照抄的接入手册。不管你的项目是网络协议解析、图片解码、配置反序列化还是自定义文件格式这套流程都适用。1. 内容整体设计与思路拆解1.1 为什么选 OSS-Fuzz 而不是自己搭一套 Fuzzing 环境早些年做模糊测试是真的折腾。你要自己准备一台或者一组机器装好 Clang、配置 libFuzzer 或者 AFL再写脚本循环跑语料崩了还得手动去抓日志、做 crash 去重。更麻烦的是Fuzzing 要想跑出效果需要足够长的覆盖时间和足够大的算力个人电脑跑一个晚上可能连目标代码的深层分支都摸不到。OSS-Fuzz 把这几件事全接过去了。它依托 Google Cloud 的持续集成调度项目只要按要求提供 Dockerfile 和 fuzz target剩下的事情都是自动化的任务分发、语料库管理、覆盖率统计、回归检测、崩溃报告。你不需要自己维护集群也不需要盯着日志看有没有 crash基础设施跑完会自动把结果反馈到 issue 里。而且 OSS-Fuzz 不是简单把 libFuzzer 包了一层它背后做的工作比这深得多。它的调度系统会记录每天的 code coverage 变化对新增代码重点做变异测试语料库是云端集中管理的每次跑出的新覆盖路径会不断回流到 corpus 里后一次运行能继续在前一次的基础上做变异而不是每次都从零开始。这叫什么这叫覆盖率引导的持续 fuzzing比个人拿个 fuzzer 随便跑几个小时有效率高太多了。1.2 接入前必须想清楚的架构逻辑OSS-Fuzz 的接入逻辑用一句话概括你只负责提供 fuzz target也就是一个从内存缓冲区读取输入、把它丢给你想要测试的代码函数的入口其余真正干活的部分基础设施自动完成。这里要理解一个关键点OSS-Fuzz 并不直接测试你的整个程序。它不会把你的二进制文件拉起来然后随机敲键盘它用的是 libFuzzer 引擎在进程中反复调用一个入口函数每次喂一段字节数组进去。入口函数里面你调什么 API就测什么 API。想测配置解析就在 fuzz target 里调用解析器想测网络协议解码就在 target 里把字节流交给协议解析函数。这是整个接入思路的核心写 target 不是写单元测试而是要写一个足够宽、足够底层、能覆盖你项目中最容易出问题的输入处理代码的入口。更深一层OSS-Fuzz 默认开启多种 sanitizer特别是 AddressSanitizerASAN和 UndefinedBehaviorSanitizerUBSAN。ASAN 负责抓内存越界、释放后使用use-after-free、堆溢出这类问题UBSAN 负责抓移位溢出、整数溢出、非法空指针这类未定义行为。所以你在本地写 fuzz target 的时候也一定要用开了 ASAN 的 Clang 编译否则很多问题根本暴露不出来。没有 sanitizer 辅助模糊测试最多只能抓到那些会导致崩溃的输入而内存错误在没被触发的状态下根本不会表象化。2. 核心细节解析与实操要点2.1 先说清楚几个绕不开的角色和文件我在接一个新项目进 OSS-Fuzz 的时候一般按照下面这个角色清单来理思路fuzz target你的 C/C 源文件里面实现 LLVMFuzzerTestOneInput 函数函数体内把你想要测的代码入口以数据流调用的方式接进来。构建脚本 build.sh运行在基础设施的容器里的 shell 脚本负责用特殊编译参数编出你的 fuzz target并把生成的可执行文件复制到指定输出目录。Dockerfile用于基础设施构建镜像里面需要安装你项目编译所需的全部依赖。project.yaml给 OSS-Fuzz 基础设施看的主配置文件声明语言、fuzzing 引擎、sanitizer、联系邮箱等元信息。这里给第一次接触的人提个醒OSS-Fuzz 的官方文档里会强调它限制单次输入大小、建议用动态库方式接入但最核心的一条规则是不要在你的 fuzz target 里做输出比如打印日志到 stdout因为 fuzzing 引擎会在单位时间内跑成千上万次调用任何一次 print 都会拖慢整体执行速度还会产生海量无用日志影响崩溃分析和去重。2.2 fuzz target 内部结构的三个关键设计写 fuzz target 不是简单写一句ParseData(Data, Size)就完事。我觉得这里头有三个工程细节直接决定测试效果好坏。第一入口要宽。你的 fuzz target 不是 unit test不需要精确断言某个返回值它要尽可能宽地调用整个数据解析链路。比如在测一个 JSON 解析库不要只测parse(json)要把 tokenizer、validator、AST 构建器整条链路都喂进去。因为漏洞往往隐藏在数据被拆开、被递归下降处理的过程中只测顶层 API 可能根本没有走到深处。第二状态要隔离。libFuzzer 是在同一个进程里反复调用你的 target 的如果 target 内部用了全局变量或者缓存那么上一次调用残留的状态会污染下一次。一个比较常见的场景是解析器内部有内存池memory pool或者全局注册表在 fuzz target 的每次入口处要确保清理干净否则你测的状态根本不是真实用户的使用状态还会导致随机性 crash 事后难复现。第三结构感知structure-aware输入。一些格式有 header、校验和之类的强约束比如什么文件头幻数不对就直接 reject。这种场景下随机字节基本全部走 early-exit 分支覆盖率根本提不起来。OSS-Fuzz 支持自定义 mutator或者更简单的做法是提供一份高质量种子语料库corpus让你项目里正常工作的示例文件放进去把解析路径的基本区块都激活fuzzer 再在这个基础上做字节级变异效果就明显不同。2.3 推荐的项目目录布局我建议每个要接入的项目在仓库里单独建一个fuzzing目录里面按下面结构放fuzzing/ ├── project.yaml ├── Dockerfile ├── build.sh └── fuzzers/ ├── parse_fuzzer.cpp └── read_settings_fuzzer.cpp为什么单独建目录因为 OSS-Fuzz 的 docker build context 默认是当前目录你要是不小心把整个项目源码都塞进去镜像会变得巨大构建速度极慢。只把 fuzz 相关文件放在一个小目录里Dockerfile 内部再去git clone或者复制真正需要测试的源码这样镜像又快又干净。3. 实操过程与核心环节实现3.1 注册项目与基础设施准备在动手写代码之前有几个账号和仓库层面的准备工作要先完成。OSS-Fuzz 的项目收录由 google/oss-fuzz 仓库管理你通常需要通过 PR 方式把项目配置合入官方仓库不过在提交 PR 之前我强烈建议先把整个接入流程在本地过一遍用 infra 提供的helper.py脚本做本地构建验证。先把仓库克隆到本地git clone https://github.com/google/oss-fuzz.git cd oss-fuzz本地构建和测试需要 Docker。项目的projects/your-project目录是你需要新建的然后在这个目录下放好我们上面说的几个文件。OSS-Fuzz 提供了辅助脚本helper.py可以执行类似下面的操作python3 infra/helper.py build_image $PROJECT_NAME python3 infra/helper.py build_fuzzers --sanitizer address $PROJECT_NAME python3 infra/helper.py run_fuzzer --sanitizer address $PROJECT_NAME $FUZZER_NAME这里面的逻辑是先用本地 Dockerfile 构建一个项目基础镜像然后在镜像内部运行 build.sh 把 fuzz target 编译出来最后通过 run_fuzzer 在本地环境启动 fuzzer 验证能否正常执行。3.2 手写一份完整可用的构建文件下面我们以一个虚构项目libmagicdata为例它是一个解析自定义二进制数据格式的 C 库头文件放在项目根目录的include/libmagicdata/parser.h源文件在src/parser.cpp。接下来我会展示完整接入需要写的内容。project.yaml 最简版homepage: https://github.com/example/libmagicdata main_repo: https://github.com/example/libmagicdata.git language: c primary_contact: maintainerexample.com sanitizers: - address - undefined这几个字段看似简单但每个背后都有讲究。main_repo是指代码仓库地址OSS-Fuzz 构建镜像时会根据 build.sh 里的逻辑去拉取源码而不是自动 clonemain_repo里的代码。primary_contact是崩溃报告的接收邮箱务必填长期有人维护的地址否则崩溃报告没人看就等于白跑。语言字段决定了启用哪些 toolchain 的默认配置。Dockerfile 内容FROM gcr.io/oss-fuzz-base/base-builder:v1 RUN apt-get update apt-get install -y autoconf automake libtool RUN git clone --depth 1 https://github.com/example/libmagicdata.git magicdata WORKDIR magicdata COPY build.sh $SRC/这里有个非常重要的约定$SRC环境变量在基础镜像里已经预置通常指向/src。我们把项目源码 clone 到$SRC/magicdata把 build.sh 拷贝到$SRC下。整个工作目录切到源码目录是为了 build.sh 里执行编译命令时路径不会太长。build.sh 的核心逻辑#!/bin/bash -eu cd $SRC/magicdata # 这一步是生成构建系统很多 autotools 项目需要在编译前执行 autoreconf ./autogen.sh # OSS-Fuzz 通过环境变量 $CC、$CXX、$CFLAGS、$CXXFLAGS 传入编译器与编译参数 ./configure --disable-shared --enable-static make -j$(nproc) # 编译 fuzz target $CXX $CXXFLAGS -stdc11 -I include \ $SRC/magicdata/fuzzing/parse_fuzzer.cpp \ src/.libs/libmagicdata.a \ $LIB_FUZZING_ENGINE \ -o $OUT/parse_fuzzer这里最关键的三个环境变量是$CC、$CXXFLAGS和$LIB_FUZZING_ENGINE。OSS-Fuzz 基础镜像已经设置好 Clang 和对应的 sanitizer 编译选项$LIB_FUZZING_ENGINE会指向一个包含 fuzzer 引擎入口的库它与LLVMFuzzerTestOneInput配合完成整个 fuzzing 循环。写到这里我想特别强调一下-fsanitizefuzzer这件事。很多人在本地用 Clang 写 fuzz target 的时候习惯直接命令行加-fsanitizefuzzer,address但在 OSS-Fuzz 环境里不要这么做因为引擎已经通过$LIB_FUZZING_ENGINE以静态库形式引入了。你只需要编译 target 时带上$CXXFLAGS里已有的 sanitizer 参数然后手动把 target 的目标文件和项目静态库、以及$LIB_FUZZING_ENGINE一起链接。fuzz target 源文件parse_fuzzer.cpp#include stddef.h #include stdint.h #include libmagicdata/parser.h extern C int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size) { // 数据块大小限制不是必要的但建议对超大输入做剪裁 if (size sizeof(struct magicdata_header)) return 0; struct magicdata_context* ctx magicdata_parse_create(); if (!ctx) return 0; magicdata_parse_buffer(ctx, data, size); // 解析完成后尝试导出内部结构增加路径覆盖率 if (magicdata_validate(ctx) 0) { char* output nullptr; size_t out_size 0; magicdata_serialize(ctx, output, out_size); free(output); } magicdata_parse_destroy(ctx); return 0; }注意这里我故意没有用项目假设的 C API而是模拟了一个 C API 接口这是因为不少被接入 OSS-Fuzz 的库会暴露 C ABI使用 C 接口测试能避开 C 的对象生命周期问题减少误报。如果你的库只有 C API 也没关系可以直接在 target 内部构造对象但要注意异常安全。种子语料方面我在项目示例目录里挑了几份结构差异尽量大的真实数据文件拷进fuzzing/corpus/目录然后在 build.sh 里把它们拷贝到$OUT/parse_fuzzer_seed_corpus.zip对应的解压目录。3.3 跑通本地验证闭环文件都准备好了在提交 PR 之前一定要先在本地跑一遍。这里我给出我实际测试时使用的命令python3 infra/helper.py build_image magicdata python3 infra/helper.py build_fuzzers --sanitizer address magicdata python3 infra/helper.py run_fuzzer --sanitizer address magicdata parse_fuzzer -max_total_time60第一行构建镜像如果 Dockerfile 里有依赖安装错误在这个阶段就会暴露。第二行真正编译 fuzz target所有编译错误也在这个步骤出现。第三行会在本地容器内启动 fuzzer 运行 60 秒通常我建议第一次跑至少 5 分钟因为某些深层路径在很短时间内根本走不到但本地验证的目的不是期待立即崩溃而是确认 fuzzer 进程能正常起跑、日志里能看到覆盖率信息逐步增长。跑完以后如果一切正常日志里会出现类似下面这样#2 NEW cov: 156 ft: 204 corp: 5/1Kb lim: 1024 exec/s: 120 rss: 45Mb L: 512/512 MS: 1 ShuffleBytes- #15 NEW cov: 203 ft: 315 corp: 9/2Kb lim: 1024 exec/s: 220 rss: 46Mb L: 800/800 MS: 2 CrossOver-这里的 cov 是被覆盖的代码块数量ft 是覆盖特征数包括边、值等corp 是当前语料库大小exec/s 是每秒执行次数。如果 exec/s 低得离谱比如只有个位数说明 target 里可能做了非常重的操作或者存在死循环嫌疑需要排查。4. 常见问题与排查技巧实录4.1 崩溃报告里的复现与修复闭环OSS-Fuzz 的崩溃并不是直接通过邮件发给你一个二进制文件就完事它会附带一份经过最小化的测试用例testcase。在 issue 里你会看到一个下载链接下载这个文件后本地复现方式非常简单python3 infra/helper.py build_fuzzers --sanitizer address magicdata python3 infra/helper.py reproduce magicdata parse_fuzzer -seed1 /path/to/downloaded/testcase这个命令会用和基础设施相同的编译参数重新编译 target然后直接拿着 testcase 跑一次如果崩溃能稳定复现说明报告可信接下来就能用 gdb 或 llvm-symbolizer 回溯堆栈。有一点很容易踩坑有时候报告里说 stack-buffer-overflow但你在本地用 release 版本复现不了因为 release 没有开 ASAN。务必用--sanitizer address重新构建否则内存错误可能根本不会触发异常信号。另外本地机器架构是 x86_64基础设施也以 x86_64 为主如果是处理跨平台字符串编码类问题可能只在特定 locale 下崩溃这类问题我建议在 target 初始化时设置固定的 locale。4.2 覆盖率低跑了很久没有进展怎么办如果你观察到跑了很久 cov 数字几乎不动问题大概率出在输入校验太严格随机字节被早早 reject。常见解法有四种第一把正则校验或者幻数检查相关的代码提取出来让 fuzzer 直接在解码函数层面做变异跳过格式识别的前置条件。第二提供更丰富的种子语料并且保证这些语料能触发不同分支。第三使用-dict参数传入格式关键词字典比如文件头标志字符、常见的结构体标记等。OSS-Fuzz 支持通过 fuzzer 运行参数额外携带字典但实际上更推荐的做法是把你所有的关键词写在代码里再引导变异因为官方基础设施对 dict 文件的支持有限。第四如果项目格式实在复杂考虑直接写一个结构感知的 mutator。这是成本最高的方案但收益也最明显适合那种有 checksum 强校验的文件格式、网络协议类项目。4.3 链接错误、命名空间冲突等编译期疑难杂症编译是很多人接入时卡住的第一道门槛。最常见的问题有两个。一个是 fuzz target 里包含了项目主程序的 main 函数。有些项目会在libmain之类的库里把入口函数一并提供了链接时你和$LIB_FUZZING_ENGINE里的 main 就重复定义了。解决办法是调整编译目标只链接你需要的对象文件别图省事整个静态库一把梭。另一个问题是 C 异常跨 C 边界。如果你用extern C包装了 C 函数而内部抛出了异常没有被捕获在有-fno-exceptions的构建环境里会直接 terminate。这时候与其在 target 里到处 try-catch不如检查项目本身的编译选项是否对库代码异常安全。OSS-Fuzz 默认是启用异常的但如果你自己用-fno-exceptions编译库代码那么 target 里凡是调用可能抛异常的库函数都要自己兜住。4.4 如何高效定位崩溃根因而不被噪音带偏收到一个新 crash我最开始不会直接看堆栈最深的几帧因为 sanitizer 的输出堆栈往往很长很多帧是引擎内部或 STL 的模板展开。我更习惯先确认三个信息崩溃类型是什么stack-overflow 还是 heap-use-after-free、crash 地址所在的分配上下文是在 target 之前还是 target 内部分配的、input 的最小化样本有多大。OSS-Fuzz 的 issue 里通常已经自动做了 testcase 最小化但即便最小化后的样本也可能还有几十 KB这时候我们可以用 Clang 的-fsanitize-address-use-after-scope等参数做精细检查或者干脆在本地对 testcase 做二分裁剪辅助定位。我常用的方法是写一个十几行的 Python 脚本每次把样本切成两半分别运行 target 看是否仍然崩溃用二分法快速定位到真正触发崩溃的关键字节偏移。import subprocess import sys data open(sys.argv[1], rb).read() target ./parse_fuzzer def crashes(chunk: bytes): tmp /tmp/tc.bin open(tmp, wb).write(chunk) r subprocess.run([target, tmp], capture_outputTrue) return r.returncode ! 0 left, right 0, len(data) while right - left 1: mid (left right) // 2 if crashes(data[left:mid]): right mid else: left mid open(/tmp/min_crash.bin, wb).write(data[left:right])这个脚本的逻辑很简单但配合 ASAN 来做手工二分效率很高。如果把截断后仍然崩溃的样本慢慢缩小到几个字节基本就能一眼看出是哪个标记位、哪个长度字段触发的漏洞。5. 提交接入与长期维护建议5.1 PR 合入官方仓库的基本流程与注意点本地验证通过后就该往 google/oss-fuzz 仓库提交 PR把你的项目目录加进去。Pull Request 里建议写清楚几个信息项目是做什么的、为什么值得接入、已经本地跑过哪些验证、fuzz target 主要覆盖了哪些功能模块。维护者通常会要求你确认primary_contact是有效邮箱可能会让你在项目 README 里加一个 oss-fuzz 的 badge。在提交之前我强烈建议你到 OSS-Fuzz 的 issue tracker 里搜一下自己的项目名看是不是已经有人在 tracking 或者曾经提交过又因为某些原因被关闭了。曾经有多个项目因为构建脚本被杀毒软件误报或者覆盖范围太窄而被拒绝翻翻旧 issue 能帮你避开不少弯路。5.2 合入之后不是终点而是一个持续改进的过程很多项目在接入初期跑一段时间后会出现 crash 数量从高到低的变化。新项目刚接入时经常能挖出一批陈年漏洞这是正常的。修复完这些之后会进入一个相对平稳期但这不代表模糊测试可以放手不管了。随着项目新功能的加入fuzzer 的输入路径会变宽覆盖率也需要持续关注。建议至少每个月做一次以下检查第一去 oss-fuzz.com 看自己项目的最近的覆盖率趋势如果加了新功能模块但覆盖率没涨说明 fuzz target 没有覆盖新代码需要补充新的 seed corpus 或新的 target。第二检查崩溃队列里是否积压了未处理的 bug。第三适时新增 fuzz target。比如你在项目里新增了一个 RPC 协议解析器那就要针对这个解析器写一个新的 target而不是只改老的通用数据解析 target。真实项目里我在接入完之后最常做的一件事就是把基础设施上报的 crash 样本保存一份到内部缺陷管理系统标记好类型和修复状态。这样既能让团队看到模糊测试的实际产出也能在做安全审计时拿出历史数据证明项目经过了持续 fuzzing 验证。最后再分享一个我个人的使用习惯。除了 OSS-Fuzz 官方主仓库之外我在自己的 CI 里也加了 libFuzzer 的短时回归任务把 OSS-Fuzz 提供的 corpus 同步到本地每次代码合入前跑 3 到 5 分钟。这样做的目的是在合入前拦截掉一部分低级错误避免等到基础设施跑完一轮才发现问题。OSS-Fuzz 是最后一道防线但每天开发过程中的快速回显也同样重要。