1# go-fuzz-headers
2This repository contains various helper functions for go fuzzing. It is mostly used in combination with [go-fuzz](https://github.com/dvyukov/go-fuzz), but compatibility with fuzzing in the standard library will also be supported. Any coverage guided fuzzing engine that provides an array or slice of bytes can be used with go-fuzz-headers.
3
4
5## Usage
6Using go-fuzz-headers is easy. First create a new consumer with the bytes provided by the fuzzing engine:
7
8```go
9import (
10 fuzz "github.com/AdaLogics/go-fuzz-headers"
11)
12data := []byte{'R', 'a', 'n', 'd', 'o', 'm'}
13f := fuzz.NewConsumer(data)
14
15```
16
17This creates a `Consumer` that consumes the bytes of the input as it uses them to fuzz different types.
18
19After that, `f` can be used to easily create fuzzed instances of different types. Below are some examples:
20
21### Structs
22One of the most useful features of go-fuzz-headers is its ability to fill structs with the data provided by the fuzzing engine. This is done with a single line:
23```go
24type Person struct {
25 Name string
26 Age int
27}
28p := Person{}
29// Fill p with values based on the data provided by the fuzzing engine:
30err := f.GenerateStruct(&p)
31```
32
33This includes nested structs too. In this example, the fuzz Consumer will also insert values in `p.BestFriend`:
34```go
35type PersonI struct {
36 Name string
37 Age int
38 BestFriend PersonII
39}
40type PersonII struct {
41 Name string
42 Age int
43}
44p := PersonI{}
45err := f.GenerateStruct(&p)
46```
47
48If the consumer should insert values for unexported fields as well as exported, this can be enabled with:
49
50```go
51f.AllowUnexportedFields()
52```
53
54...and disabled with:
55
56```go
57f.DisallowUnexportedFields()
58```
59
60### Other types:
61
62Other useful APIs:
63
64```go
65createdString, err := f.GetString() // Gets a string
66createdInt, err := f.GetInt() // Gets an integer
67createdByte, err := f.GetByte() // Gets a byte
68createdBytes, err := f.GetBytes() // Gets a byte slice
69createdBool, err := f.GetBool() // Gets a boolean
70err := f.FuzzMap(target_map) // Fills a map
71createdTarBytes, err := f.TarBytes() // Gets bytes of a valid tar archive
72err := f.CreateFiles(inThisDir) // Fills inThisDir with files
73createdString, err := f.GetStringFrom("anyCharInThisString", ofThisLength) // Gets a string that consists of chars from "anyCharInThisString" and has the exact length "ofThisLength"
74```
75
76Most APIs are added as they are needed.
77
78## Projects that use go-fuzz-headers
79- [runC](https://github.com/opencontainers/runc)
80- [Istio](https://github.com/istio/istio)
81- [Vitess](https://github.com/vitessio/vitess)
82- [Containerd](https://github.com/containerd/containerd)
83
84Feel free to add your own project to the list, if you use go-fuzz-headers to fuzz it.
85
86
87
88
89## Status
90The project is under development and will be updated regularly.
91
92## References
93go-fuzz-headers' approach to fuzzing structs is strongly inspired by [gofuzz](https://github.com/google/gofuzz).View as plain text