教程：开始使用模糊测试

本教程介绍了 Go 中模糊测试的基础知识。通过模糊测试，随机数据会针对您的测试运行，以尝试查找漏洞或导致崩溃的输入。模糊测试可以发现的漏洞示例包括 SQL 注入、缓冲区溢出、拒绝服务和跨站点脚本攻击。

在本教程中，您将为一个简单函数编写模糊测试、运行 go 命令，并调试和修复代码中的问题。

有关本教程中术语的帮助，请参阅 Go 模糊测试词汇表。

您将学习以下部分

为您的代码创建一个文件夹。
添加代码进行测试。
添加单元测试。
添加模糊测试。
修复两个错误。
探索其他资源。

注意：有关其他教程，请参阅教程。

注意：Go fuzzing 目前支持Go Fuzzing 文档中列出的内置类型子集，未来将增加对更多内置类型的支持。

先决条件

安装 Go 1.18 或更高版本。有关安装说明，请参阅安装 Go。
编辑代码的工具。您拥有的任何文本编辑器都可以正常工作。
命令终端。Go 在 Linux 和 Mac 上的任何终端上都能很好地工作，在 Windows 上使用 PowerShell 或 cmd 也可以。
支持模糊测试的环境。目前，只有 AMD64 和 ARM64 架构才可以使用带有覆盖率检测的 Go fuzzing。

为您的代码创建一个文件夹

首先，为要编写的代码创建一个文件夹。

打开命令提示符并切换到您的主目录。

在 Linux 或 Mac 上
```
$ cd
```
在 Windows 上
```
C:\> cd %HOMEPATH%
```
本教程的其余部分将显示 $ 作为提示符。您使用的命令在 Windows 上也能正常工作。
在命令提示符下，为您的代码创建一个名为 fuzz 的目录。
```
$ mkdir fuzz
$ cd fuzz
```
创建一个模块来保存您的代码。

运行 go mod init 命令，并为其提供新代码的模块路径。
```
$ go mod init example/fuzz
go: creating new go.mod: module example/fuzz
```
注意：对于产品代码，您需要指定更符合您自己需求的模块路径。更多信息，请务必参阅管理依赖项。

接下来，您将添加一些简单的代码来反转字符串，我们稍后会对其进行模糊处理。

添加代码进行测试

在此步骤中，您将添加一个函数来反转字符串。

编写代码

使用您的文本编辑器，在 fuzz 目录中创建一个名为 main.go 的文件。
在 main.go 中，在文件顶部，粘贴以下包声明。
```
package main
```
一个独立程序（与库相对）始终位于包 main 中。
在包声明下方粘贴以下函数声明。
```
func Reverse(s string) string {
    b := []byte(s)
    for i, j := 0, len(b)-1; i < len(b)/2; i, j = i+1, j-1 {
        b[i], b[j] = b[j], b[i]
    }
    return string(b)
}
```
此函数将接受一个 string，一次按一个 byte 循环遍历它，并在最后返回反转后的字符串。

注意： 此代码基于 golang.org/x/example 中的 stringutil.Reverse 函数。
在 main.go 的顶部，在包声明下方，粘贴以下 main 函数以初始化一个字符串，反转它，打印输出，然后重复。
```
func main() {
    input := "The quick brown fox jumped over the lazy dog"
    rev := Reverse(input)
    doubleRev := Reverse(rev)
    fmt.Printf("original: %q\n", input)
    fmt.Printf("reversed: %q\n", rev)
    fmt.Printf("reversed again: %q\n", doubleRev)
}
```
此函数将运行一些 Reverse 操作，然后将输出打印到命令行。这有助于查看代码的实际运行情况，并可能用于调试。
main 函数使用 fmt 包，因此您需要导入它。

代码的第一行应如下所示
```
package main

import "fmt"
```

运行代码

在包含 main.go 的目录中的命令行中运行代码。

$ go run .
original: "The quick brown fox jumped over the lazy dog"
reversed: "god yzal eht revo depmuj xof nworb kciuq ehT"
reversed again: "The quick brown fox jumped over the lazy dog"

您可以看到原始字符串、反转后的结果，然后是再次反转后的结果，它等同于原始字符串。

现在代码正在运行，是时候测试它了。

添加单元测试

在此步骤中，您将为 Reverse 函数编写一个基本单元测试。

编写代码

使用文本编辑器，在 fuzz 目录中创建一个名为 reverse_test.go 的文件。

将以下代码粘贴到 reverse_test.go 中。

package main

import (
    "testing"
)

func TestReverse(t *testing.T) {
    testcases := []struct {
        in, want string
    }{
        {"Hello, world", "dlrow ,olleH"},
        {" ", " "},
        {"!12345", "54321!"},
    }
    for _, tc := range testcases {
        rev := Reverse(tc.in)
        if rev != tc.want {
                t.Errorf("Reverse: %q, want %q", rev, tc.want)
        }
    }
}

此简单测试将断言列出的输入字符串将被正确反转。

运行代码

使用 go test 运行单元测试

$ go test
PASS
ok      example/fuzz  0.013s

接下来，您将把单元测试更改为模糊测试。

添加模糊测试

单元测试有局限性，即每个输入都必须由开发人员添加到测试中。模糊测试的一个好处是，它会为您的代码提出输入，并可能识别出您提出的测试用例未涉及的边缘情况。

在本节中，您将把单元测试转换为模糊测试，以便您可以用更少的工作生成更多输入！

请注意，您可以将单元测试、基准测试和模糊测试保存在同一个 *_test.go 文件中，但对于此示例，您将把单元测试转换为模糊测试。

编写代码

在文本编辑器中，使用以下模糊测试替换 reverse_test.go 中的单元测试。

func FuzzReverse(f *testing.F) {
    testcases := []string{"Hello, world", " ", "!12345"}
    for _, tc := range testcases {
        f.Add(tc)  // Use f.Add to provide a seed corpus
    }
    f.Fuzz(func(t *testing.T, orig string) {
        rev := Reverse(orig)
        doubleRev := Reverse(rev)
        if orig != doubleRev {
            t.Errorf("Before: %q, after: %q", orig, doubleRev)
        }
        if utf8.ValidString(orig) && !utf8.ValidString(rev) {
            t.Errorf("Reverse produced invalid UTF-8 string %q", rev)
        }
    })
}

模糊测试也有一些局限性。在单元测试中，您可以预测 Reverse 函数的预期输出，并验证实际输出是否符合这些预期。

例如，在测试用例 Reverse("Hello, world") 中，单元测试指定返回结果为 "dlrow ,olleH"。

在进行模糊测试时，你无法预测预期输出，因为你无法控制输入。

然而，Reverse 函数有一些属性可以在模糊测试中进行验证。此模糊测试中检查的两个属性是

对字符串进行两次反转会保留原始值
反转后的字符串保留其作为有效 UTF-8 的状态。

注意单元测试和模糊测试之间的语法差异

函数以 FuzzXxx 开头，而不是 TestXxx，并且使用 *testing.F 而不是 *testing.T
在预期看到 t.Run 执行的位置，你反而会看到 f.Fuzz，它采用一个模糊目标函数，其参数是 *testing.T 和要模糊化的类型。单元测试中的输入使用 f.Add 作为种子语料库输入提供。

确保已导入新包 unicode/utf8。

package main

import (
    "testing"
    "unicode/utf8"
)

将单元测试转换为模糊测试后，现在可以再次运行测试。

运行代码

在不进行模糊测试的情况下运行模糊测试，以确保种子输入通过。
```
$ go test
PASS
ok      example/fuzz  0.013s
```
如果你在该文件中还有其他测试，并且只想运行模糊测试，你还可以运行 go test -run=FuzzReverse。
使用模糊测试运行 FuzzReverse，以查看是否有任何随机生成的字符串输入会导致失败。这是使用 go test 和一个新标志 -fuzz 执行的，该标志设置为参数 Fuzz。复制以下命令。
```
$ go test -fuzz=Fuzz
```
另一个有用的标志是 -fuzztime，它限制了模糊测试所需的时间。例如，在下面的测试中指定 -fuzztime 10s 意味着，只要没有更早发生失败，测试将在经过 10 秒后默认退出。请参阅 cmd/go 文档的此部分以查看其他测试标志。

现在，运行你刚刚复制的命令。
```
$ go test -fuzz=Fuzz
fuzz: elapsed: 0s, gathering baseline coverage: 0/3 completed
fuzz: elapsed: 0s, gathering baseline coverage: 3/3 completed, now fuzzing with 8 workers
fuzz: minimizing 38-byte failing input file...
--- FAIL: FuzzReverse (0.01s)
    --- FAIL: FuzzReverse (0.00s)
        reverse_test.go:20: Reverse produced invalid UTF-8 string "\x9c\xdd"

    Failing input written to testdata/fuzz/FuzzReverse/af69258a12129d6cbba438df5d5f25ba0ec050461c116f777e77ea7c9a0d217a
    To re-run:
    go test -run=FuzzReverse/af69258a12129d6cbba438df5d5f25ba0ec050461c116f777e77ea7c9a0d217a
FAIL
exit status 1
FAIL    example/fuzz  0.030s
```
在进行模糊测试时发生了一个失败，并且导致问题的输入被写入种子语料库文件，该文件将在下次调用 go test 时运行，即使没有 -fuzz 标志。要查看导致失败的输入，请在文本编辑器中打开写入 testdata/fuzz/FuzzReverse 目录的语料库文件。你的种子语料库文件可能包含不同的字符串，但格式将相同。
```
go test fuzz v1
string("泃")
```
语料库文件的第 1 行指示编码版本。每一行都表示组成语料库项的每个类型的值。由于模糊目标只接受 1 个输入，因此版本后只有一个值。

再次运行 go test，而不使用 -fuzz 标志；将使用新的失败种子语料库项

$ go test
--- FAIL: FuzzReverse (0.00s)
    --- FAIL: FuzzReverse/af69258a12129d6cbba438df5d5f25ba0ec050461c116f777e77ea7c9a0d217a (0.00s)
        reverse_test.go:20: Reverse produced invalid string
FAIL
exit status 1
FAIL    example/fuzz  0.016s

由于我们的测试失败了，现在是时候进行调试了。

修复无效字符串错误

在本节中，您将调试失败并修复错误。

在继续之前，请随意花一些时间思考这个问题并尝试自己解决问题。

诊断错误

有几种不同的方法可以调试此错误。如果您使用 VS Code 作为文本编辑器，则可以设置调试器进行调查。

在本教程中，我们将把有用的调试信息记录到您的终端。

首先，考虑utf8.ValidString的文档。

ValidString reports whether s consists entirely of valid UTF-8-encoded runes.

当前的Reverse函数逐字节地反转字符串，而这正是我们的问题所在。为了保留原始字符串的 UTF-8 编码符文，我们必须逐符文地反转字符串。

要检查输入（在本例中为中文字符泃）为何导致Reverse在反转时生成无效字符串，您可以检查反转字符串中的符文数。

编写代码

在您的文本编辑器中，用以下内容替换FuzzReverse中的模糊目标。

f.Fuzz(func(t *testing.T, orig string) {
    rev := Reverse(orig)
    doubleRev := Reverse(rev)
    t.Logf("Number of runes: orig=%d, rev=%d, doubleRev=%d", utf8.RuneCountInString(orig), utf8.RuneCountInString(rev), utf8.RuneCountInString(doubleRev))
    if orig != doubleRev {
        t.Errorf("Before: %q, after: %q", orig, doubleRev)
    }
    if utf8.ValidString(orig) && !utf8.ValidString(rev) {
        t.Errorf("Reverse produced invalid UTF-8 string %q", rev)
    }
})

如果发生错误，或者使用-v执行测试，此t.Logf行将打印到命令行，这可以帮助您调试此特定问题。

运行代码

使用 go test 运行测试

$ go test
--- FAIL: FuzzReverse (0.00s)
    --- FAIL: FuzzReverse/28f36ef487f23e6c7a81ebdaa9feffe2f2b02b4cddaa6252e87f69863046a5e0 (0.00s)
        reverse_test.go:16: Number of runes: orig=1, rev=3, doubleRev=1
        reverse_test.go:21: Reverse produced invalid UTF-8 string "\x83\xb3\xe6"
FAIL
exit status 1
FAIL    example/fuzz    0.598s

整个种子语料库都使用每个字符为一个字节的字符串。但是，诸如泃之类的字符可能需要几个字节。因此，逐字节反转字符串将使多字节字符无效。

注意：如果您好奇 Go 如何处理字符串，请阅读博客文章Go 中的字符串、字节、符文和字符以加深理解。

更好地理解错误后，请更正Reverse函数中的错误。

修复错误

要更正Reverse函数，让我们按符文而不是按字节遍历字符串。

编写代码

在您的文本编辑器中，用以下内容替换现有的 Reverse() 函数。

func Reverse(s string) string {
    r := []rune(s)
    for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
        r[i], r[j] = r[j], r[i]
    }
    return string(r)
}

关键的区别在于Reverse现在正在遍历字符串中的每个rune，而不是每个byte。

运行代码

使用go test运行测试
```
$ go test
PASS
ok      example/fuzz  0.016s
```
测试现在通过了！

再次使用go test -fuzz进行模糊测试，以查看是否有任何新错误。

$ go test -fuzz=Fuzz
fuzz: elapsed: 0s, gathering baseline coverage: 0/37 completed
fuzz: minimizing 506-byte failing input file...
fuzz: elapsed: 0s, gathering baseline coverage: 5/37 completed
--- FAIL: FuzzReverse (0.02s)
    --- FAIL: FuzzReverse (0.00s)
        reverse_test.go:33: Before: "\x91", after: "�"

    Failing input written to testdata/fuzz/FuzzReverse/1ffc28f7538e29d79fce69fef20ce5ea72648529a9ca10bea392bcff28cd015c
    To re-run:
    go test -run=FuzzReverse/1ffc28f7538e29d79fce69fef20ce5ea72648529a9ca10bea392bcff28cd015c
FAIL
exit status 1
FAIL    example/fuzz  0.032s

我们可以看到，在反转两次后，字符串与原始字符串不同。这一次，输入本身是无效的 unicode。如果我们用字符串进行模糊测试，这怎么可能？

让我们再次调试。

修复双重反转错误

在本节中，您将调试双重反转失败并修复该错误。

在继续之前，请随意花一些时间思考这个问题并尝试自己解决问题。

诊断错误

与之前一样，您可以通过多种方式调试此失败。在这种情况下，使用调试器将是一种很好的方法。

在本教程中，我们将在 Reverse 函数中记录有用的调试信息。

仔细查看反转字符串以找出错误。在 Go 中，字符串是只读字节切片，并且可以包含无效的 UTF-8 字节。原始字符串是一个包含一个字节 '\x91' 的字节切片。当输入字符串设置为 []rune 时，Go 将字节切片编码为 UTF-8，并将字节替换为 UTF-8 字符 �。当我们将替换的 UTF-8 字符与输入字节切片进行比较时，它们显然不相等。

编写代码

在文本编辑器中，将 Reverse 函数替换为以下内容。

func Reverse(s string) string {
    fmt.Printf("input: %q\n", s)
    r := []rune(s)
    fmt.Printf("runes: %q\n", r)
    for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
        r[i], r[j] = r[j], r[i]
    }
    return string(r)
}

这将帮助我们了解在将字符串转换为 rune 切片时出了什么问题。

运行代码

这次，我们只想运行失败的测试以检查日志。为此，我们将使用 go test -run。

要在 FuzzXxx/testdata 中运行特定的语料库条目，您可以向 -run 提供 {FuzzTestName}/{filename}。这在调试时会很有帮助。在这种情况下，将 -run 标志设置为失败测试的确切哈希值。从您的终端复制并粘贴唯一的哈希值；它将与以下哈希值不同。

$ go test -run=FuzzReverse/28f36ef487f23e6c7a81ebdaa9feffe2f2b02b4cddaa6252e87f69863046a5e0
input: "\x91"
runes: ['�']
input: "�"
runes: ['�']
--- FAIL: FuzzReverse (0.00s)
    --- FAIL: FuzzReverse/28f36ef487f23e6c7a81ebdaa9feffe2f2b02b4cddaa6252e87f69863046a5e0 (0.00s)
        reverse_test.go:16: Number of runes: orig=1, rev=1, doubleRev=1
        reverse_test.go:18: Before: "\x91", after: "�"
FAIL
exit status 1
FAIL    example/fuzz    0.145s

知道输入是无效的 unicode，让我们修复 Reverse 函数中的错误。

修复错误

要解决此问题，如果输入 Reverse 不是有效的 UTF-8，我们返回一个错误。

编写代码

在文本编辑器中，将现有的 Reverse 函数替换为以下内容。

func Reverse(s string) (string, error) {
    if !utf8.ValidString(s) {
        return s, errors.New("input is not valid UTF-8")
    }
    r := []rune(s)
    for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
        r[i], r[j] = r[j], r[i]
    }
    return string(r), nil
}

如果输入字符串包含无效的 UTF-8 字符，此更改将返回一个错误。

由于 Reverse 函数现在返回一个错误，因此修改 main 函数以丢弃额外的错误值。将现有的 main 函数替换为以下内容。

func main() {
    input := "The quick brown fox jumped over the lazy dog"
    rev, revErr := Reverse(input)
    doubleRev, doubleRevErr := Reverse(rev)
    fmt.Printf("original: %q\n", input)
    fmt.Printf("reversed: %q, err: %v\n", rev, revErr)
    fmt.Printf("reversed again: %q, err: %v\n", doubleRev, doubleRevErr)
}

这些对 Reverse 的调用应该返回一个 nil 错误，因为输入字符串是有效的 UTF-8。

您需要导入 errors 和 unicode/utf8 包。main.go 中的 import 语句应如下所示。
```
import (
    "errors"
    "fmt"
    "unicode/utf8"
)
```

修改 reverse_test.go 文件以检查错误，如果通过返回生成错误，则跳过测试。

func FuzzReverse(f *testing.F) {
    testcases := []string {"Hello, world", " ", "!12345"}
    for _, tc := range testcases {
        f.Add(tc)  // Use f.Add to provide a seed corpus
    }
    f.Fuzz(func(t *testing.T, orig string) {
        rev, err1 := Reverse(orig)
        if err1 != nil {
            return
        }
        doubleRev, err2 := Reverse(rev)
        if err2 != nil {
             return
        }
        if orig != doubleRev {
            t.Errorf("Before: %q, after: %q", orig, doubleRev)
        }
        if utf8.ValidString(orig) && !utf8.ValidString(rev) {
            t.Errorf("Reverse produced invalid UTF-8 string %q", rev)
        }
    })
}

除了返回，您还可以调用 t.Skip() 以停止执行该 fuzz 输入。

运行代码

使用 go test 运行测试

$ go test
PASS
ok      example/fuzz  0.019s

使用 go test -fuzz=Fuzz 对其进行模糊测试，然后在几秒钟后，使用 ctrl-C 停止模糊测试。模糊测试将运行，直到遇到失败的输入，除非你传递 -fuzztime 标志。如果没有发生失败，则默认会一直运行，并且可以使用 ctrl-C 中断进程。

$ go test -fuzz=Fuzz
fuzz: elapsed: 0s, gathering baseline coverage: 0/38 completed
fuzz: elapsed: 0s, gathering baseline coverage: 38/38 completed, now fuzzing with 4 workers
fuzz: elapsed: 3s, execs: 86342 (28778/sec), new interesting: 2 (total: 35)
fuzz: elapsed: 6s, execs: 193490 (35714/sec), new interesting: 4 (total: 37)
fuzz: elapsed: 9s, execs: 304390 (36961/sec), new interesting: 4 (total: 37)
...
fuzz: elapsed: 3m45s, execs: 7246222 (32357/sec), new interesting: 8 (total: 41)
^Cfuzz: elapsed: 3m48s, execs: 7335316 (31648/sec), new interesting: 8 (total: 41)
PASS
ok      example/fuzz  228.000s

使用 go test -fuzz=Fuzz -fuzztime 30s 对其进行模糊测试，如果未找到失败，则会在 30 秒后退出。

$ go test -fuzz=Fuzz -fuzztime 30s
fuzz: elapsed: 0s, gathering baseline coverage: 0/5 completed
fuzz: elapsed: 0s, gathering baseline coverage: 5/5 completed, now fuzzing with 4 workers
fuzz: elapsed: 3s, execs: 80290 (26763/sec), new interesting: 12 (total: 12)
fuzz: elapsed: 6s, execs: 210803 (43501/sec), new interesting: 14 (total: 14)
fuzz: elapsed: 9s, execs: 292882 (27360/sec), new interesting: 14 (total: 14)
fuzz: elapsed: 12s, execs: 371872 (26329/sec), new interesting: 14 (total: 14)
fuzz: elapsed: 15s, execs: 517169 (48433/sec), new interesting: 15 (total: 15)
fuzz: elapsed: 18s, execs: 663276 (48699/sec), new interesting: 15 (total: 15)
fuzz: elapsed: 21s, execs: 771698 (36143/sec), new interesting: 15 (total: 15)
fuzz: elapsed: 24s, execs: 924768 (50990/sec), new interesting: 16 (total: 16)
fuzz: elapsed: 27s, execs: 1082025 (52427/sec), new interesting: 17 (total: 17)
fuzz: elapsed: 30s, execs: 1172817 (30281/sec), new interesting: 17 (total: 17)
fuzz: elapsed: 31s, execs: 1172817 (0/sec), new interesting: 17 (total: 17)
PASS
ok      example/fuzz  31.025s

模糊测试通过！

除了 -fuzz 标志，还向 go test 添加了几个新标志，可以在文档中查看。

请参阅 Go 模糊测试，以获取有关模糊测试输出中使用的术语的更多信息。例如，“新的有趣”是指扩展现有模糊测试语料库的代码覆盖率的输入。随着模糊测试的开始，“新的有趣”输入的数量预计会急剧增加，随着发现新的代码路径而激增几次，然后随着时间的推移而逐渐减少。

结论

做得很好！你刚刚开始了解 Go 中的模糊测试。

下一步是在你的代码中选择一个你想要对其进行模糊测试的函数，然后试一试！如果模糊测试在你的代码中发现了错误，请考虑将其添加到战利品柜中。

如果你遇到任何问题或对某个功能有想法，提交一个问题。

对于有关该功能的讨论和一般反馈，你还可以参与 Gophers Slack 中的 #fuzzing 频道。

查看 go.dev/security/fuzz 中的文档以进一步阅读。

完成的代码

— main.go —

package main

import (
    "errors"
    "fmt"
    "unicode/utf8"
)

func main() {
    input := "The quick brown fox jumped over the lazy dog"
    rev, revErr := Reverse(input)
    doubleRev, doubleRevErr := Reverse(rev)
    fmt.Printf("original: %q\n", input)
    fmt.Printf("reversed: %q, err: %v\n", rev, revErr)
    fmt.Printf("reversed again: %q, err: %v\n", doubleRev, doubleRevErr)
}

func Reverse(s string) (string, error) {
    if !utf8.ValidString(s) {
        return s, errors.New("input is not valid UTF-8")
    }
    r := []rune(s)
    for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
        r[i], r[j] = r[j], r[i]
    }
    return string(r), nil
}

— reverse_test.go —

package main

import (
    "testing"
    "unicode/utf8"
)

func FuzzReverse(f *testing.F) {
    testcases := []string{"Hello, world", " ", "!12345"}
    for _, tc := range testcases {
        f.Add(tc) // Use f.Add to provide a seed corpus
    }
    f.Fuzz(func(t *testing.T, orig string) {
        rev, err1 := Reverse(orig)
        if err1 != nil {
            return
        }
        doubleRev, err2 := Reverse(rev)
        if err2 != nil {
            return
        }
        if orig != doubleRev {
            t.Errorf("Before: %q, after: %q", orig, doubleRev)
        }
        if utf8.ValidString(orig) && !utf8.ValidString(rev) {
            t.Errorf("Reverse produced invalid UTF-8 string %q", rev)
        }
    })
}

返回顶部