Go fuzzing 失败语料的最小化与回归保留

Go fuzzing 找到失败输入后，最稳妥的处理方式不是把整段原始输入直接提交，而是先让 fuzzing 引擎尝试最小化，再把仍能稳定触发问题的样本保留到对应的 testdata/fuzz/FuzzXxx 目录。这样既能缩短复现路径，也能让修复后的普通 go test 自动执行这条回归样本。

官方地址：https://go.dev/doc/security/fuzz/

最小化的目标是保留“仍然失败”的条件，而不是单纯追求文件更小；真正应提交的是可解释、可复现、修复后能持续运行的失败语料。

先把三类语料分清楚

Go 原生 fuzzing 的语料大致分成三类。第一类是代码里的 f.Add 种子，适合表达少量、稳定、具有代表性的基础输入；第二类是包目录中的 testdata/fuzz/FuzzXxx 文件，其中包含失败输入和团队主动维护的种子；第三类是 fuzzing 过程中产生的缓存语料，通常位于 GOCACHE/fuzz，主要服务于继续探索覆盖率。

标题所说的“失败语料”重点是第二类。它属于源码和测试资产的一部分，可以进入版本控制；生成语料缓存则是本机或构建环境中的探索状态，不应因为一次本地运行就整体提交。

失败输入为什么要最小化

模糊测试经常从多个种子和变异操作出发。一个失败样本可能包含大量无关字节，但真正触发 bug 的只是很短的前缀、某个分隔符或一组参数组合。直接保存大样本会让排查变慢，也会把无关业务数据带进测试。

Go 文档说明，出现 panic、测试失败、不可恢复错误或执行超时后，fuzzing 引擎会尝试把输入缩到仍能产生错误、同时更容易阅读的值。这个过程不是把内容按长度截断，而是反复尝试删除、修改或缩减输入，并重新判断失败条件是否还存在。

用参数控制最小化，而不是手工猜样本

通常可以先用短时间运行 fuzzing，让工具自行寻找并缩减失败输入：

# 只运行指定 fuzz 测试，并限制探索时间
go test -run=^$ -fuzz=FuzzParse -fuzztime=30s

# 给每次失败输入的最小化尝试设定 10 秒预算
go test -run=^$ -fuzz=FuzzParse -fuzztime=30s -fuzzminimizetime=10s

-fuzztime 控制整体 fuzzing 的时间或迭代次数；-fuzzminimizetime 控制每次最小化尝试的时间或迭代次数。默认设置适合多数场景，但在 CI 中设置明确预算，更容易控制任务时长。

如果已经拿到失败样本，不需要重复长时间探索。命令输出会给出类似 go test -run=FuzzParse/... 的复现入口，可以直接执行这个精确的测试名：

# 按 fuzzing 输出的完整测试名只重放一个失败样本
go test -run='^FuzzParse/[a-f0-9]+$'

# 只运行该 fuzz 测试的种子语料，确认样本仍会触发当前问题
go test -run=^FuzzParse$

第二条命令会按普通测试模式执行该 fuzz 测试的种子语料。它适合修复后重复运行，判断失败样本是否已经变成通过状态。

查看并整理 testdata/fuzz 里的失败文件

失败输入会被写入测试包下的 testdata/fuzz/FuzzParse。每个文件使用 Go fuzz v1 语料格式：第一行是格式标记，后面是与 fuzz 函数参数顺序和类型完全一致的值。

go test fuzz v1
[]byte("header:bad")
int64(3)

不要把这类严格格式改成普通 JSON，也不要改变字段顺序。fuzz target 的参数必须和语料里的类型一致；否则样本无法作为该目标的种子正常加载。

整理目录时建议保留能说明业务边界的文件名或旁边的说明文档，但不要手工改写 Go 自动生成的哈希文件名来表达结论。真正重要的是样本内容、对应的 fuzz target，以及修复后仍能通过普通测试。

修复后如何让失败语料变成回归测试

Go 官方文档明确指出，fuzzing 引擎写入的失败输入会成为该 fuzz 测试的 seed corpus。修复代码后，普通 go test 默认就会重新执行这些种子。如果样本不再失败，说明这条回归输入已经通过；如果又失败，说明修复并没有覆盖原来的触发条件。

# 修复实现后，先执行全部测试并包含种子语料
go test ./...

# 在修改前后都可单独运行这个 fuzz 测试，缩小排查范围
go test -run=^FuzzParse$ ./parser

这里的关键不是让 fuzzing 每次都跑很久，而是把已经发现的失败样本变成短、稳、可重复的输入。后续仍可以定期用 -fuzz 扩充覆盖率，但回归保护本身不应依赖某一次随机探索恰好再次找到同一个样本。

按负载和约束选择语料保留策略

如果团队把 fuzzing 放进持续集成，需要把语料维护当成测试资产管理问题来处理。下面的取舍可以帮助确定哪些输入应进入仓库：

这套策略的核心是“回归价值优先”。文件更小不代表更好；如果最小化后丢失了能说明问题的结构，就应该保留一个略大但更容易读懂的样本，并在测试旁边解释它覆盖的边界。

一份可执行的落地清单

1. 确认 fuzz target 快速且尽量确定性，避免状态残留影响复现。
2. 用 -fuzztime 设定探索预算，用 -fuzzminimizetime 设定最小化预算。
3. 从输出复制完整的单样本 go test -run 命令，先固定复现入口。
4. 检查失败文件是否位于对应的 testdata/fuzz/FuzzXxx 目录，并保持 fuzz v1 格式。
5. 修复代码后运行普通 go test，让失败样本成为持续回归保护。
6. 排除生成缓存、真实敏感数据和重复样本，只提交有明确回归价值的语料。

当失败样本已经可以被普通测试稳定执行时，fuzzing 的一次性发现就变成了长期工程资产：探索负责找到边界，最小化负责降低理解成本，源码中的 seed corpus 负责守住修复结果。

常见问题

最小化后文件仍然很大，应该手工删到最短吗？

不建议只按文件大小手工删除。应先保留能稳定触发原失败的结构，再评估是否有业务字段可以脱敏或拆分；如果手工修改导致测试通过，就已经改变了问题。

生成语料为什么不直接提交到仓库？

生成语料主要是 fuzzing 引擎为覆盖率探索维护的缓存，位置和内容受本地缓存状态影响。提交前应挑选有明确回归意义的失败样本或种子，而不是把整个缓存目录纳入版本控制。

修复后还要保留失败样本吗？

要保留。修复后的样本不再是“当前失败输入”，而是验证修复不会回退的回归输入；删除它会丢失这次 fuzzing 找到的边界。