为二进制协议解析器添加种子语料与不变量断言

给二进制协议解析器做 Go 模糊测试，重点不是简单地把随机字节传给函数，而是先准备能触达关键分支的种子语料，再把“解析成功后一定成立”的性质写成不变量。下面用一个原创的四字节帧头协议完成最小实验：帧头依次包含版本、标志和两字节负载长度，后面紧跟负载。

测试策略很明确：无效输入允许返回错误；只要 ParseFrame 返回成功，长度字段、保留位、重新编码结果和负载内存所有权就必须同时正确。这样既不会把“必须接受任意输入”误当成目标，也能让模糊引擎专注寻找真正违反协议约束的样本。

前置条件与实验边界

Go 原生 fuzz test 的函数名形如 FuzzXxx，参数只能是 *testing.F，并放在 _test.go 文件中。每个 fuzz test 只有一个通过 f.Fuzz 注册的模糊目标。f.Add 的参数类型和顺序必须与模糊目标一致；本文只使用一个 []byte 参数。

示例协议采用以下约束，目的是把测试重点放在线格式和不变量，而不是模拟某个真实产品：

初始化一个最小 Go 模块

新建空目录后初始化模块。这里不依赖第三方库，解析器和测试都使用标准库。

# 初始化独立实验模块
mkdir framefuzz
cd framefuzz
go mod init example.com/framefuzz

目录中只需要 frame.go 和 frame_test.go。普通测试会先执行种子语料；显式传入 -fuzz 后，工具链才会继续生成变异输入。

先固定协议边界，再写解析器

ParseFrame 先检查最小帧头，再依次判断版本、保留位、负载上限和精确长度。成功时复制负载，避免返回值继续引用调用方可变的输入缓冲区。MarshalFrame 使用相同约束生成规范编码，后面会用于回环不变量。

package framefuzz

import (
    "encoding/binary"
    "errors"
)

const (
    headerSize       = 4
    supportedVersion = 1
    reservedFlagMask = 0xF0
    maxPayload       = 4096
)

var (
    ErrShortHeader     = errors.New("frame header is incomplete")
    ErrVersion         = errors.New("unsupported frame version")
    ErrReservedFlags   = errors.New("reserved flag bits are set")
    ErrPayloadTooLarge = errors.New("payload exceeds limit")
    ErrLength          = errors.New("declared length does not match payload")
)

type Frame struct {
    Version byte
    Flags   byte
    Payload []byte
}

func ParseFrame(data []byte) (Frame, error) {
    if len(data)  maxPayload {
        return Frame{}, ErrPayloadTooLarge
    }
    if len(data) != headerSize+payloadLen {
        return Frame{}, ErrLength
    }

    // 返回独立副本，避免调用方修改输入后污染解析结果。
    payload := append([]byte(nil), data[headerSize:]...)
    return Frame{Version: data[0], Flags: data[1], Payload: payload}, nil
}

func MarshalFrame(frame Frame) ([]byte, error) {
    if frame.Version != supportedVersion {
        return nil, ErrVersion
    }
    if frame.Flags&reservedFlagMask != 0 {
        return nil, ErrReservedFlags
    }
    if len(frame.Payload) > maxPayload {
        return nil, ErrPayloadTooLarge
    }

    // 编码器生成唯一规范格式，便于做 parse-marshal 回环比较。
    data := make([]byte, headerSize+len(frame.Payload))
    data[0] = frame.Version
    data[1] = frame.Flags
    binary.BigEndian.PutUint16(data[2:4], uint16(len(frame.Payload)))
    copy(data[headerSize:], frame.Payload)
    return data, nil
}

这段实现故意要求“实际字节数恰好等于声明长度”，因此带尾随字节的帧也会被拒绝。只有先把协议边界写清楚，后面的不变量才不会在“尾随数据是否允许”这类问题上产生歧义。

添加能触达关键分支的种子语料

种子不是越多越好，而是要有代表性。这里准备两个有效帧，以及截断帧头、长度冲突、错误版本、保留位和超限声明等输入。它们在普通 go test 中也会经过模糊目标，因此能作为稳定的基础回归样本。

package framefuzz

import (
    "bytes"
    "encoding/binary"
    "testing"
)

func FuzzParseFrame(f *testing.F) {
    seeds := [][]byte{
        {1, 0, 0, 0},                   // 有效空负载
        {1, 1, 0, 1, 0xAA},             // 有效单字节负载
        {1, 0, 0},                       // 截断帧头
        {1, 0, 0, 2, 0xAA},             // 声明长度大于实际负载
        {2, 0, 0, 0},                   // 不支持的版本
        {1, 0x80, 0, 0},                // 设置了保留位
        {1, 0, 0x10, 0x01},             // 声明 4097 字节，超过上限
    }
    for _, seed := range seeds {
        // 每条语料的参数类型与模糊目标的 []byte 完全一致。
        f.Add(seed)
    }

    f.Fuzz(func(t *testing.T, data []byte) {
        // 保留原始输入，用于回环比较和所有权断言。
        original := append([]byte(nil), data...)
        frame, err := ParseFrame(data)
        if err != nil {
            return // 无效输入返回错误是协议允许的结果
        }

        if len(original)  maxPayload {
            t.Fatalf("payload exceeds limit: %d", len(frame.Payload))
        }

        // 成功解析时，声明长度必须和返回负载长度一致。
        declared := int(binary.BigEndian.Uint16(original[2:4]))
        if declared != len(frame.Payload) {
            t.Fatalf("declared=%d payload=%d", declared, len(frame.Payload))
        }

        // 规范帧重新编码后应与原始输入逐字节相同。
        encoded, err := MarshalFrame(frame)
        if err != nil {
            t.Fatalf("marshal accepted frame failed: %v", err)
        }
        if !bytes.Equal(encoded, original) {
            t.Fatalf("round trip changed bytes: got=%x want=%x", encoded, original)
        }

        // 修改输入缓冲区不应改变 Frame 内部的负载副本。
        if len(frame.Payload) > 0 {
            data[headerSize] ^= 0xFF
            if frame.Payload[0] != original[headerSize] {
                t.Fatalf("payload aliases input memory")
            }
        }
    })
}

注意错误分支只返回，不要求固定错误文本。模糊测试真正关注的是：任何输入都不能导致未受控崩溃；一旦解析器声称成功，所有协议性质必须成立。若业务要求区分具体错误类型，可以另外用表驱动单元测试做精确断言。

把断言写成解析成功后的性质

这四类不变量分别保护不同风险：

• 长度一致：阻止越界读取、截断接受和长度字段解释错误。
• 保留位清零：保证解析成功对象没有绕过协议的字段约束。
• 编解码回环：在当前规范编码唯一的前提下，检查解析字段是否完整、编码器是否遗漏信息。
• 独立内存：确认返回负载不受调用方后续复用输入缓冲区影响。

不变量必须来自协议承诺，不能凭感觉添加。例如某些协议允许尾随扩展区，就不能要求重新编码后与完整输入逐字节相同；这时应比较规范帧部分，或把扩展区纳入返回对象。

运行普通检查与限时模糊测试

先运行普通测试，确认所有 f.Add 种子都能通过。然后用 -fuzz 选择单个模糊测试，并用 -fuzztime 给本地实验设置明确时长。

# 先把种子语料当作普通回归测试执行
go test ./...

# 再对单个模糊目标运行 30 秒覆盖引导变异
go test -fuzz=FuzzParseFrame -fuzztime=30s

Go 官方文档说明，默认 go test 会执行种子语料；启用 fuzzing 后，工具链先收集基线覆盖率，再持续生成输入。若发现失败，工具链会尝试最小化输入，并将失败样本写入对应的 testdata/fuzz/FuzzParseFrame/ 目录。修复解析器后保留该文件，它会成为后续普通测试自动执行的回归语料。

扩展到真实协议时怎么选种子

真实协议通常还有校验和、可选字段、嵌套长度和多种消息类型。扩展时优先增加“跨边界”的小语料，而不是复制大量生产报文：

• 每个合法消息类型至少一个最小有效帧。
• 长度取 0、1、上限和上限加 1。
• 可选字段分别覆盖缺失、最短值和完整值。
• 校验和同时准备正确值与单字节翻转后的错误值。
• 嵌套结构准备内层截断、外层长度正确但内层长度冲突的输入。

模糊目标应保持快速、确定，并避免依赖全局状态。不要在目标中访问网络、写共享数据库、读取会变化的系统时间，或把上一次调用的状态留给下一次。模糊引擎会并行调用目标，执行顺序也不确定；状态污染会让失败难以复现。

清理与总结

临时实验结束后，可以清理缓存中自动生成的语料；但凡是曾触发真实缺陷的失败文件，都应连同修复一起提交到 testdata/fuzz。它们会在后续 go test 中继续保护对应边界。

# 查看 Go 构建与测试缓存位置，确认清理范围
go env GOCACHE

# 仅在需要重置本机测试缓存时执行
go clean -testcache

最终可以用一句话检查设计是否正确：种子负责把引擎带到有价值的协议区域，不变量负责判断解析器是否违背承诺。对二进制解析器而言，先从长度、版本、保留位、规范回环和内存所有权开始，往往比堆更多随机样本更有效。

相关问题

是否要把每个错误码都写进 fuzz 断言？

通常不需要。模糊测试适合验证“成功结果必须满足什么”和“任意输入不能造成什么”。错误类型与错误文本的精确映射更适合表驱动单元测试，除非错误分类本身就是协议的稳定外部契约。

为什么种子既要有有效输入，也要有明显无效输入？

有效种子帮助引擎进入更深的成功路径，无效种子则快速覆盖帧头、版本和长度拒绝边界。两者组合能同时观察接受路径和拒绝路径，避免语料长期停留在最外层长度检查。

回环断言什么时候不能直接比较原字节？

当协议允许多种等价编码、字段顺序可变、存在被忽略的填充或尾随扩展时，重新编码不一定与原始输入完全一致。这时应比较解析后的语义对象，或先定义规范化结果再比较。