Go fuzz 测试怎样为结构化输入设计种子语料

Go fuzz 测试遇到结构化请求时，最稳妥的做法不是把一个自定义结构体直接传给 f.Add，而是把它拆成若干受支持的基础类型，再在 fuzz target 内恢复成业务对象。这样既能表达字段之间的组合关系，也能让失败输入落到可读、可回归的语料文件中。

本文只讨论三件事：种子参数怎样设计、文件语料怎样保存、发现失败后怎样保留为回归测试。Go 官方文档规定，F.Add 与 F.Fuzz 的参数类型和顺序必须一致，seed corpus 既可以来自 f.Add，也可以来自 testdata/fuzz/。

从结构体拆成可变参数

先把业务对象和 fuzz 边界分开。下面的 Request 是业务层结构体，但 fuzz target 使用的是字符串、字节切片、整数和布尔值。每个 f.Add 调用都必须按同样顺序提供这四类参数。

type Request struct {
    Method string
    Body   []byte
    Limit  int
    Auth   bool
}

func FuzzDecodeRequest(f *testing.F) {
    // 种子覆盖空请求、典型请求和边界长度，先建立可解释的基线。
    f.Add("GET", []byte{}, 0, false)
    f.Add("POST", []byte(`{"id":1}`), 128, true)
    f.Add("PATCH", []byte(`{"name":"x"}`), 1, false)

    f.Fuzz(func(t *testing.T, method string, body []byte, limit int, auth bool) {
        // 在目标内部恢复业务对象，保持 Fuzz 参数仍是受支持的基础类型。
        req := Request{Method: method, Body: body, Limit: limit, Auth: auth}
        if err := DecodeRequest(req); err != nil {
            // 解析错误是输入边界的一部分，不要让测试依赖外部服务。
            t.Skip()
        }
    })
}

这里的重点不是“种子越多越好”，而是每个种子代表一个不同的风险边界：空字节、常见方法、最小限制值、带认证标志的组合，以及字段之间可能冲突的组合。如果真正的业务对象很大，可以只拆出影响解析分支的字段，避免把无关状态也带进 fuzz target。

为每个字段安排有意义的边界

结构化语料最容易犯的错误，是只放几条正常样本，然后期待引擎替你理解业务规则。更实用的方式是给每个字段写出“为什么需要它”的边界表，再组合少量互补种子。

如果某个字段只能取有限值，仍然可以用字符串或整数表达，再在 target 里把非法值归入“拒绝”分支。不要为了让 fuzz 更快而删除这些非法种子；它们往往正是输入校验和安全边界的入口。与此同时，target 应保持快速、确定，并避免读写共享全局状态，否则同一个语料可能得到不稳定结论。

把复杂语料放进 testdata

f.Add 适合少量、能直接读懂的基线；当一条输入包含多字段，或需要把样本交给代码审查和版本控制时，可以放到 testdata/fuzz/FuzzDecodeRequest/。文件首行是语料格式版本，后面按 fuzz 参数顺序逐行写值，类型必须完全匹配。

go test fuzz v1
string("POST")
[]byte("{\"id\":1}")
int(128)
bool(true)

这类文件不是 JSON，也不是随意的键值配置，不要在文件里加入解释性注释。若 target 的参数顺序改了，文件中的值也要同步调整；否则它就不再是当前 fuzz target 的合法 seed corpus。文件名可以由工具生成的哈希组成，重点是目录名必须对应 FuzzDecodeRequest。

把失败输入变成回归样本

模糊测试发现失败输入后，最有价值的动作不是删除它，而是把它视为新的回归样本。Go fuzzing 会把失败输入写入对应的 seed corpus 目录；修复代码后，普通 go test 也会读取这些样本，因此回归测试和继续 fuzz 共用同一份输入资产。

# 先只回放某个已保存的失败语料，缩小调试范围
go test -run='FuzzDecodeRequest/'

# 修复后运行包内测试，让已有 seed corpus 继续承担回归检查
go test

# 需要继续探索时，限制一次 fuzz 的时间，避免无人值守无限运行
go test -fuzz=FuzzDecodeRequest -fuzztime=30s

回归样本至少要保留三类信息：触发了哪个 fuzz target、输入包含哪些结构化字段、修复后应该满足什么不变量。不要只断言“没有 panic”；对于解码器，还可以断言拒绝非法方法、限制 body 大小、错误返回可重复，以及合法输入经过编码再解码仍保持关键字段。

按风险检查 fuzz target

把 fuzz target 当成输入边界，而不是业务服务的缩小版。需要保护的资产通常是解析不变量、权限判断和资源上限；对应的攻击路径则是畸形字段、极端长度、未知枚举值和字段组合冲突。

• 高风险边界：会触发越界、无限分配、权限误判或 panic 的输入，应先有最小 seed，再保留每个发现的失败样本。
• 中风险边界：错误信息不一致、默认值不明确、非法字段被静默接受，需要用组合种子固定预期。
• 运行控制：不要在 target 内依赖网络、当前时间、随机全局状态或共享可变缓存；否则失败很难重放。
• 资源控制：在进入深层解析前设置合理的长度上限，避免 fuzz 为了一个无关超大输入耗尽机器资源。

结论：让语料同时服务探索和回归

结构化输入的关键是“拆开传入、在 target 内恢复”：用 f.Add 放少量可读基线，用 testdata/fuzz/FuzzXxx 保存复杂或失败样本，再让普通 go test 持续重放它们。这样种子语料不只是 fuzz 的起点，也是解析边界、权限分支和历史缺陷的长期记录。

相关问题

可以直接把自定义 struct 传给 f.Add 吗？

不能把它当作任意类型使用。应按 Go fuzz 支持的参数类型拆成字段，或者把结构编码成 []byte，再在 fuzz target 中恢复对象。

f.Add 和 testdata/fuzz 要二选一吗？

不需要。前者适合少量内联基线，后者适合需要独立文件、审查、版本控制或由 fuzz 发现的失败语料，两者会共同构成 seed corpus。

语料文件中字段顺序可以调整吗？

不能随意调整。文件中的值必须与 f.Fuzz 回调参数的类型和顺序一致；如果签名变化，应同步迁移或重新生成对应语料。