FuzzGIUPluginKit

项目介绍

FuzzGIUPluginKit是一套用于辅助开发和测试FuzzGIU插件的工具链。

安装

git clone github.com/nostalgist134/FuzzGIUPluginKit.git
cd FuzzGIUPluginKit
go get
go build

或者到release中下载编译好的文件

使用方法

FuzzGIUPluginKit提供了4个子命令，分别用于开发、编译与测试插件

PS H:\tools\fuzz\FuzzGIU> .\fgpk.exe -h
Usage:
  help [flags]
  help [command]

Available Commands:
  build       # 将go项目编译为动态链接库
  completion  Generate the autocompletion script for the specified shell
  gen         # 生成开发骨架
  help        Help about any command
  info        # 获取一个插件的信息（如果有）
  test        # 测试插件的功能

gen命令

gen命令用于在目录下生成插件开发骨架，其支持的选项如下：

PS H:\tools\fuzz\FuzzGIU> .\fgpk.exe gen -h
generate plugin development go project

Usage:
  help gen [flags]

Flags:
  -d, --dir string    directory to generate project(auto mkdir)
  -h, --help          help for gen
  -n, --no-net        does not get fuzzTypes.go from net
  -t, --type string   plugin type to generate project. currently support:
                        [payloadProc reactor payloadGen requester preprocess iterator]

• -t：用于指定生成的插件骨架类型
• -d：指定生成目录（若不存在，会自动创建）
• -n：使用内嵌的fuzzTypes包。默认会从github上拉取fuzzTypes包（用于定义某些插件使用的结构体），从而保证是最新的。但工具内嵌一份包以备用，若要使用内嵌文件，则指定此选项

build命令

build命令用于将插件项目编译为动态链接库文件，其支持选项如下：

PS H:\tools\fuzz\FuzzGIU> .\fgpk.exe build -h
build plugin

Usage:
  help build [flags]

Flags:
  -g, --go-path string      go binary path
  -h, --help                help for build
  -i, --info                generate PluginInfo function for plugin
  -k, --no-clean            keep intermediate files
  -o, --out string          out file
  -p, --path string         path/file to build plugin
  -u, --usage-file string   usage file to be used for PluginInfo

• -g：指定go编译器的路径（可选），若不使用此选项，则直接执行go命令
• -i：在编译的插件内部包含一个PluginInfo函数，返回插件的元信息（若要使用fgpk的测试功能，这个选项是必须的）
• -o：编译后文件输出的路径
• -p：go项目的位置
• -k：保留编译过程中生成的中间文件，这些文件在调试过程中可能会有用
• -u：若指定了-i选项，可使用此选项在插件元信息中追加插件用法相关信息

注意：

• fgpk build要求当前的系统中必须有go编译器（指定或者从$PATH）；如果是windows上，还需要gcc编译器与cgo相关支持，否则会导致编译失败。
• linux/macOS上的插件编译时必须采用和FuzzGIU本体相同的go编译器版本（目前FuzzGIU项目中的Release均使用1.25.0版本go编译器编译），否则无法加载，windows版本则无此限制。
• iterator类型插件有一个可选的导出函数IterLen，可以自行实现也可以省略，若省略，工具会默认实现一个返回-1的IterLen。

info命令

info子命令简单地调用一个插件，获取其元信息并输出，支持如下选项

PS H:\tools\fuzz\FuzzGIU> .\fgpk.exe info -h
get plugin information

Usage:
  help info [flags]

Flags:
  -f, --format string   output format(native, json)
  -h, --help            help for info
  -p, --path string     plugin binary path

test命令

test命令用于对插件进行测试，其包含两个子命令gen和run，前者用于针对插件生成测试数据，后者则用于运行测试

PS H:\tools\fuzz\FuzzGIU> .\fgpk.exe test -h
test a plugin's functionality. this command expect plugin tested be built with PluginInfo(-i of build command)

Usage:
  help test [command]

Available Commands:
  gen         generate test data set for plugin
  run         run test

这一系列的命令要求被测插件构建时指定-i选项，否则不能正常运行。

test gen子命令

gen子命令用于生成测试数据，其参数如下

Usage:
  help test gen [flags]

Flags:
  -f, --files string    source files, each seperated with comma
  -h, --help            help for gen
  -n, --num int         number of struct to marshal (default 1)
  -o, --out string      out file (default "test.json")
  -p, --path string     path of plugin to generate test data
  -s, --struct string   marshal structs by type to a file, which can be used as data source file in the future

这一命令采用文件（-f选项）作为测试数据源，-p指定插件路径，通过读取插件的参数列表，自动生成测试数据。数据源的类型会根据插件对应参数的类型自动转换。

若待测插件的参数列表中含有结构体参数，可使用-s与-n选项生成结构体/结构体数组的json文件，作为测试数据源供未来使用。-s命令接收一个带包名的结构体名，生成值固定的结构体，-n选项用于指定生成的结构体数量。使用-o指定输出文件名。

-f选项用于指定生成测试文件的文件源，不同文件间用逗号隔开，文件数量必须和参数数量一样或多一个。文件内容的读取行为随参数类型变化，若参数类型为基本类型（数字、布尔或字符串），则按行读取，每行作为一个值；若类型为结构体，则将文件内容当成用json表示的结构体或结构体数组来读取。

工具支持将测试结果与期望值进行比较，若要指定测试的期望值，则可在-f指定和参数数量相同的文件之外再多加一个文件，最后一个文件会被作为测试期望值的文件源。

每个文件源含有的值的数量可以不同，在这种情况下，工具则会按照值最多的文件源生成测试数据，值较少的文件源，其值列表会被循环使用（类似于FuzzGIU的pitchfork-cycle模式）。生成的测试数据同样通过-o选项输出文件名。

test run子命令

test run子命令用于针对插件运行测试，其参数列表如下

Usage:
  help test run [flags]

Flags:
  -e, --expr string   run test via pseudo function calls(function name will be ignored)
  -f, --file string   run test files generated by gen command
  -h, --help          help for run
  -o, --out string    output test result to a json file
  -p, --path string   path of plugin binary file

本命令支持两种测试模式，-e和-f，但这两种模式是互斥的，一次测试中不能同时指定。使用-p指定运行测试的插件路径。

-e模式使用伪函数表达式调用插件，并输出返回结果。函数名会被忽略。若插件含有结构体参数，则会采用对应类型的空结构体。这个模式支持对插件调用多次，仅需指定多个测试函数，每个间使用逗号隔开，示例：-e test(1,2,3),test(2,3,4),...。这一模式无法指定测试期望值。

-f模式使用test gen命令生成的测试文件来运行测试，输出测试结果以及与期望值的对比结果。

-o若要将测试结果输出到文件，则指定此选项。