教程:模糊测试入门

本文翻译自《Tutorial: Getting started with fuzzing》。

本教程介绍Go中模糊测试的基本知识。通过模糊测试,随机数据会针对你的测试程序运行,试图找到程序漏洞或导致程序崩溃的输入。模糊测试可以发现的一些漏洞包括SQL注入、缓冲区溢出、拒绝服务和跨站点脚本攻击等。

有关本教程中的术语,请参阅Go Fuzzing词汇表

你将完成以下部分:

1 为代码创建一个文件夹

2 添加要测试的代码

3 添加一个单元测试

4 添加一个模糊测试

5 修复两个Bug

6 探索其他资源

注意:有关其他教程,请参见教程

注意:Go fuzzing目前支持Go fuzzing文档中列出的一个内置类型子集,并会在未来添加更多的内置类型。

先决条件

  • 安装Go 1.18或更高版本。有关安装说明,请参阅安装Go
  • 用于编辑代码的工具。你拥有的任何文本编辑器都可以正常工作。
  • 一种命令行终端。Go在Linux和Mac上使用任何终端都能很好地工作,以及Windows中的PowerShell或CMD。
  • 支持模糊测试的运行环境。带覆盖检测的Go fuzzing目前仅在AMD64和ARM64架构上可用。

为代码创建一个文件夹

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

1 打开命令提示符并转到家目录。 在Linux或Mac上:

$ cd

在Windows:

C:\> cd %HOMEPATH%

本教程的其余部分将显示一个$作为提示符。本教程使用的命令也适用于Windows。

2.在命令提示符下,为代码创建一个名为fuzz的目录。

$ mkdir fuzz
$ cd fuzz

3.创建一个模块来保存代码。

运行go mod init命令,给出代码的模块路径:

$ go mod init example/fuzz
go: creating new go.mod: module example/fuzz

注意:对于生产代码,你应该指定一个更适合你自己需求的模块路径。有关详细信息,请参阅管理依赖关系

接下来,你将添加一些简单的代码来反转字符串,稍后我们将对其进行模糊测试。

添加要测试的代码

在这一步中,你将添加一个函数来反转字符串。

编写代码

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

2.在main.go文件顶部,粘贴以下包声明:

package main

独立程序(与库相对)始终位于main包中。

3.在包声明下面,粘贴以下函数声明:

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)
}

此函数将接受一个字符串,一次循环一个字节,最后返回反转后的字符串。

:此代码基于golang.org/x/example中的stringutil.Revirse函数。

4.在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)
}

此函数将运行一些反转字符串的操作,然后将输出打印到命令行。这有助于查看运行中的代码,并可能有助于调试。

5.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函数编写一个基本的单元测试。

编写代码

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

2.将以下代码粘贴到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)  // 使用f.Add函数提供一个种子测试用例
    }
    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而不是*test.T
  • 在你期望看到t.Run的地方,你会看到f.Fuzz,它接受一个目标函数,其参数的类型是*testing.T和要模糊测试的类型。单元测试的输入使用f.Add作为一个种子语料库提供给模糊测试。

请确保已导入新的程序包unicode/utf8

package main

import (
    "testing"
    "unicode/utf8"
)

随着单元测试转换为模糊测试,是时候再次运行测试了。

运行代码

1.在不模糊的情况下运行模糊测试,以确保种子输入通过。

$ go test
PASS
ok      example/fuzz  0.013s

如果该文件中有其他测试,并且你只希望运行模糊测试,那么你可以执行go test -run=FuzzReverse

2.运行FuzzReverse函数进行模糊测试,查看任何随机生成的字符串作为输入是否会导致该函数执行失败。这也是使用go test命令执行的,使用一个新的标志-fuzz,设置它的参数值为Fuzz

$ go test -fuzz=Fuzz

另一个有用的标志是-fuzzztime,它限制模糊测试所能花费的时间。例如,在下面的测试中指定-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个值。

3.在没有使用-fuzz标志的情况下再次运行go test;将使用新的导致测试失败的种子语料库条目:

$ 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

既然我们的测试失败了,是时候调试了。

修复两个Bug

修复非法字符串Bug

在本节中,你将调试故障并修复Bug。

在继续之前,你可以花一些时间思考这个问题,并尝试自己解决这个问题。

诊断这个错误

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

在本教程中,我们将把有用的调试信息记录到终端。 首先,考虑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中的字符串、字节、rune和字符》,以获得更加深入的理解。

对上述Bug有了更好的了解后,请你更正Reverse函数中的错误。

修复Bug

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

编写代码

在文本编辑器中,将现有的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现在迭代字符串中的每个符文,而不是每个字节。

运行代码

1.使用go test运行测试

$ go test
PASS
ok      example/fuzz  0.016s

现在测试通过了!

2.用go test -fuzz再次模糊测试它,看看是否有任何新的bug

$ 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。这怎么可能发生呢?

让我们再次调试。

修复两次逆转字符串产生的Bug

在本节中,你将调试两次逆转字符串产生的Bug并修复该Bug。

在继续之前,你可以花一些时间思考这个问题,并尝试自己解决这个问题。

诊断这个错误

和以前一样,有几种方法可以调试此Bug。使用调试器(debugger)将是一种很好的方法。

在本教程中,我们将在Reverse函数中记录有用的调试信息。 仔细观察反转的字符串以发现此Bug。在Go中,一个字符串是一个只读的字节切片(a string is a read only slice of bytes),可以包含非UTF-8的字节。原始字符串是一个带有一个字节“\x91”的字节切片。当输入字符串被转换为[]rune时,Go将字节切片编码为UTF-8字符切片,并将第一个字节“\x91”替换为一个UTF-8字符。当我们将这个UTF-8字符与原始字节切片进行比较时,它们显然不相等。

编写代码

1.在文本编辑器中,将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中运行特定的语料库条目,可以提供{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函数中的Bug。

修复Bug

为了解决这个问题,如果Reverse的输入不是有效的UTF-8编码的字符串,我们就返回一个错误。

编写代码

1.在文本编辑器中,用以下内容替换现有的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字符,则返回一个错误。

2.由于Reverse函数现在返回一个错误,修改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编码。

3.将需要导入errorsunicode/utf8包。main.go中的import语句应该如下所示。

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

4.修改reverse_test.go文件以检查错误,如果Reverse函数返回了一个错误,则跳过本次测试。

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)
        }
    })
}

如果不想用直接return的话,你也可以调用t.Skip()函数来停止执行本次模糊测试。

运行代码

1.使用go test运行测试

$ go test
PASS
ok      example/fuzz  0.019s

2.用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

3.使用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模糊测试。例如,“new interesting”指的是扩展了代码覆盖率的已存在的模糊测试语料库的输入。在模糊测试的一开始,“new interesting”输入的数量会急剧增加,随着新的代码路径的发现,“new interesting”输入的数量还会激增几次,然后随着时间的推移逐渐减少。

结论

得好!你刚刚向自己介绍了Go中的模糊测试。

下一步是在代码中选择一个你想模糊测试的函数,并尝试它!如果模糊测试在你的代码中发现了一个错误,请考虑将其添加到trophy case(译者注:向别人炫耀你发现的Go标准库Bug)中。

如果你遇到任何问题或对某个功能有想法,请在此提交问题

对于有关模糊测试的功能的讨论和反馈,你也可以加入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)
        }
    })
}