gofuzzheaders

README

go-fuzz-headers

This repository contains various helper functions for go fuzzing. It is mostly used in combination with 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.

Usage

Using go-fuzz-headers is easy. First create a new consumer with the bytes provided by the fuzzing engine:

import (
	fuzz "github.com/AdaLogics/go-fuzz-headers"
)
data := []byte{'R', 'a', 'n', 'd', 'o', 'm'}
f := fuzz.NewConsumer(data)

This creates a Consumer that consumes the bytes of the input as it uses them to fuzz different types.

After that, f can be used to easily create fuzzed instances of different types. Below are some examples:

Structs

One 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:

type Person struct {
    Name string
    Age  int
}
p := Person{}
// Fill p with values based on the data provided by the fuzzing engine:
err := f.GenerateStruct(&p)

This includes nested structs too. In this example, the fuzz Consumer will also insert values in p.BestFriend:

type PersonI struct {
    Name       string
    Age        int
    BestFriend PersonII
}
type PersonII struct {
    Name string
    Age  int
}
p := PersonI{}
err := f.GenerateStruct(&p)

If the consumer should insert values for unexported fields as well as exported, this can be enabled with:

f.AllowUnexportedFields()

...and disabled with:

f.DisallowUnexportedFields()

Other types:

Other useful APIs:

createdString, err := f.GetString() // Gets a string
createdInt, err := f.GetInt() // Gets an integer
createdByte, err := f.GetByte() // Gets a byte
createdBytes, err := f.GetBytes() // Gets a byte slice
createdBool, err := f.GetBool() // Gets a boolean
err := f.FuzzMap(target_map) // Fills a map
createdTarBytes, err := f.TarBytes() // Gets bytes of a valid tar archive
err := f.CreateFiles(inThisDir) // Fills inThisDir with files
createdString, err := f.GetStringFrom("anyCharInThisString", ofThisLength) // Gets a string that consists of chars from "anyCharInThisString" and has the exact length "ofThisLength"

Most APIs are added as they are needed.

Projects that use go-fuzz-headers

• runC
• Istio
• Vitess
• Containerd

Feel free to add your own project to the list, if you use go-fuzz-headers to fuzz it.

Status

The project is under development and will be updated regularly.

References

go-fuzz-headers' approach to fuzzing structs is strongly inspired by gofuzz.

Documentation

Index

• Variables
• func IsDivisibleBy(n int, divisibleby int) bool
• func SetMaxTotalLen(newLen uint32)
• type ConsumeFuzzer
  • func NewConsumer(fuzzData []byte) *ConsumeFuzzer
  • func (f *ConsumeFuzzer) AddFuncs(fuzzFuncs []interface{})
  • func (f *ConsumeFuzzer) AllowNonUTF8Strings()
  • func (f *ConsumeFuzzer) AllowUnexportedFields()
  • func (f *ConsumeFuzzer) CreateFiles(rootDir string) error
  • func (f *ConsumeFuzzer) CreateSlice(targetSlice interface{}) error
  • func (f *ConsumeFuzzer) DisallowNonUTF8Strings()
  • func (f *ConsumeFuzzer) DisallowUnexportedFields()
  • func (f *ConsumeFuzzer) FuzzMap(m interface{}) error
  • func (f *ConsumeFuzzer) GenerateStruct(targetStruct interface{}) error
  • func (f *ConsumeFuzzer) GenerateWithCustom(targetStruct interface{}) error
  • func (f *ConsumeFuzzer) GetBool() (bool, error)
  • func (f *ConsumeFuzzer) GetByte() (byte, error)
  • func (f *ConsumeFuzzer) GetBytes() ([]byte, error)
  • func (f *ConsumeFuzzer) GetFloat32() (float32, error)
  • func (f *ConsumeFuzzer) GetFloat64() (float64, error)
  • func (f *ConsumeFuzzer) GetInt() (int, error)
  • func (f *ConsumeFuzzer) GetNBytes(numberOfBytes int) ([]byte, error)
  • func (f *ConsumeFuzzer) GetRune() ([]rune, error)
  • func (f *ConsumeFuzzer) GetSQLString() (string, error)
  • func (f *ConsumeFuzzer) GetString() (string, error)
  • func (f *ConsumeFuzzer) GetStringArray() (reflect.Value, error)
  • func (f *ConsumeFuzzer) GetStringFrom(possibleChars string, length int) (string, error)
  • func (f *ConsumeFuzzer) GetUint() (uint, error)
  • func (f *ConsumeFuzzer) GetUint16() (uint16, error)
  • func (f *ConsumeFuzzer) GetUint32() (uint32, error)
  • func (f *ConsumeFuzzer) GetUint64() (uint64, error)
  • func (f *ConsumeFuzzer) Split(minCalls, maxCalls int) error
  • func (f *ConsumeFuzzer) TarBytes() ([]byte, error)
  • func (f *ConsumeFuzzer) TarFiles() ([]*TarFile, error)
• type Continue
  • func (c Continue) GenerateStruct(targetStruct interface{}) error
  • func (c Continue) GenerateStructWithCustom(targetStruct interface{}) error
• type TarFile

Variables

var (
	MaxTotalLen uint32 = 2000000
)

Functions

func IsDivisibleBy

func IsDivisibleBy(n int, divisibleby int) bool

func SetMaxTotalLen

func SetMaxTotalLen(newLen uint32)

Types

type ConsumeFuzzer

type ConsumeFuzzer struct {
	CommandPart   []byte
	RestOfArray   []byte
	NumberOfCalls int

	Funcs map[reflect.Type]reflect.Value
	// contains filtered or unexported fields
}

func NewConsumer

func NewConsumer(fuzzData []byte) *ConsumeFuzzer

func (*ConsumeFuzzer) AddFuncs

func (f *ConsumeFuzzer) AddFuncs(fuzzFuncs []interface{})

func (*ConsumeFuzzer) AllowNonUTF8Strings

func (f *ConsumeFuzzer) AllowNonUTF8Strings()

func (*ConsumeFuzzer) AllowUnexportedFields

func (f *ConsumeFuzzer) AllowUnexportedFields()

func (*ConsumeFuzzer) CreateFiles

func (f *ConsumeFuzzer) CreateFiles(rootDir string) error

CreateFiles creates pseudo-random files in rootDir. It creates subdirs and places the files there. It is the callers responsibility to ensure that rootDir exists.

func (*ConsumeFuzzer) CreateSlice

func (f *ConsumeFuzzer) CreateSlice(targetSlice interface{}) error

func (*ConsumeFuzzer) DisallowNonUTF8Strings

func (f *ConsumeFuzzer) DisallowNonUTF8Strings()

func (*ConsumeFuzzer) DisallowUnexportedFields

func (f *ConsumeFuzzer) DisallowUnexportedFields()

func (*ConsumeFuzzer) FuzzMap

func (f *ConsumeFuzzer) FuzzMap(m interface{}) error

func (*ConsumeFuzzer) GenerateStruct

func (f *ConsumeFuzzer) GenerateStruct(targetStruct interface{}) error

func (*ConsumeFuzzer) GenerateWithCustom

func (f *ConsumeFuzzer) GenerateWithCustom(targetStruct interface{}) error

func (*ConsumeFuzzer) GetBool

func (f *ConsumeFuzzer) GetBool() (bool, error)

func (*ConsumeFuzzer) GetByte

func (f *ConsumeFuzzer) GetByte() (byte, error)

func (*ConsumeFuzzer) GetBytes

func (f *ConsumeFuzzer) GetBytes() ([]byte, error)

func (*ConsumeFuzzer) GetFloat32

func (f *ConsumeFuzzer) GetFloat32() (float32, error)

func (*ConsumeFuzzer) GetFloat64

func (f *ConsumeFuzzer) GetFloat64() (float64, error)

func (*ConsumeFuzzer) GetInt

func (f *ConsumeFuzzer) GetInt() (int, error)

func (*ConsumeFuzzer) GetNBytes

func (f *ConsumeFuzzer) GetNBytes(numberOfBytes int) ([]byte, error)

func (*ConsumeFuzzer) GetRune

func (f *ConsumeFuzzer) GetRune() ([]rune, error)

func (*ConsumeFuzzer) GetSQLString

func (f *ConsumeFuzzer) GetSQLString() (string, error)

GetSQLString is the API that users interact with.

Usage:

f := NewConsumer(data)
sqlString, err := f.GetSQLString()

func (*ConsumeFuzzer) GetString

func (f *ConsumeFuzzer) GetString() (string, error)

func (*ConsumeFuzzer) GetStringArray

func (f *ConsumeFuzzer) GetStringArray() (reflect.Value, error)

func (*ConsumeFuzzer) GetStringFrom

func (f *ConsumeFuzzer) GetStringFrom(possibleChars string, length int) (string, error)

GetStringFrom returns a string that can only consist of characters included in possibleChars. It returns an error if the created string does not have the specified length.

func (*ConsumeFuzzer) GetUint

func (f *ConsumeFuzzer) GetUint() (uint, error)

func (*ConsumeFuzzer) GetUint16

func (f *ConsumeFuzzer) GetUint16() (uint16, error)

func (*ConsumeFuzzer) GetUint32

func (f *ConsumeFuzzer) GetUint32() (uint32, error)

func (*ConsumeFuzzer) GetUint64

func (f *ConsumeFuzzer) GetUint64() (uint64, error)

func (*ConsumeFuzzer) Split

func (f *ConsumeFuzzer) Split(minCalls, maxCalls int) error

func (*ConsumeFuzzer) TarBytes

func (f *ConsumeFuzzer) TarBytes() ([]byte, error)

TarBytes returns valid bytes for a tar archive

func (*ConsumeFuzzer) TarFiles

func (f *ConsumeFuzzer) TarFiles() ([]*TarFile, error)

This is similar to TarBytes, but it returns a series of files instead of raw tar bytes. The advantage of this api is that it is cheaper in terms of cpu power to modify or check the files in the fuzzer with TarFiles() because it avoids creating a tar reader.

type Continue

type Continue struct {
	F *ConsumeFuzzer
}

func (Continue) GenerateStruct

func (c Continue) GenerateStruct(targetStruct interface{}) error

func (Continue) GenerateStructWithCustom

func (c Continue) GenerateStructWithCustom(targetStruct interface{}) error

type TarFile

type TarFile struct {
	Hdr  *tar.Header
	Body []byte
}