Giter Site home page Giter Site logo

go-fuzz's Introduction

go-fuzz: randomized testing for Go

Go-fuzz is a coverage-guided fuzzing solution for testing of Go packages. Fuzzing is mainly applicable to packages that parse complex inputs (both text and binary), and is especially useful for hardening of systems that parse inputs from potentially malicious users (e.g. anything accepted over a network).

Usage

First, you need to write a test function of the form:

func Fuzz(data []byte) int

Data is a random input generated by go-fuzz, note that in most cases it is invalid. The function must return 1 if the fuzzer should increase priority of the given input during subsequent fuzzing (for example, the input is lexically correct and was parsed successfully); -1 if the input must not be added to corpus even if gives new coverage; and 0 otherwise; other values are reserved for future use.

The Fuzz function must be in a package that go-fuzz can import. This means the code you want to test can't be in package main. Fuzzing internal packages is supported, however.

In its basic form the Fuzz function just parses the input, and go-fuzz ensures that it does not panic, crash the program, allocate insane amount of memory nor hang. Fuzz function can also do application-level checks, which will make testing more efficient (discover more bugs). For example, Fuzz function can serialize all inputs that were successfully deserialized, thus ensuring that serialization can handle everything deserialization can produce. Or, Fuzz function can deserialize-serialize-deserialize-serialize and check that results of first and second serialization are equal. Or, Fuzz function can feed the input into two different implementations (e.g. dumb and optimized) and check that the output is equal. To communicate application-level bugs Fuzz function should panic (os.Exit(1) will work too, but panic message contains more info). Note that Fuzz function should not output to stdout/stderr, it will slow down fuzzing and nobody will see the output anyway. The exception is printing info about a bug just before panicking.

Here is an example of a simple Fuzz function for image/png package:

package png

import (
	"bytes"
	"image/png"
)

func Fuzz(data []byte) int {
	png.Decode(bytes.NewReader(data))
	return 0
}

A more useful Fuzz function would look like:

func Fuzz(data []byte) int {
	img, err := png.Decode(bytes.NewReader(data))
	if err != nil {
		if img != nil {
			panic("img != nil on error")
		}
		return 0
	}
	var w bytes.Buffer
	err = png.Encode(&w, img)
	if err != nil {
		panic(err)
	}
	return 1
}

The second step is collection of initial input corpus. Ideally, files in the corpus are as small as possible and as diverse as possible. You can use inputs used by unit tests and/or generate them. For example, for an image decoding package you can encode several small bitmaps (black, random noise, white with few non-white pixels) with different levels of compressions and use that as the initial corpus. Go-fuzz will deduplicate and minimize the inputs. So throwing in a thousand of inputs is fine, diversity is more important.

Put the initial corpus into the workdir/corpus directory (in our case examples/png/corpus). Go-fuzz will add own inputs to the corpus directory. Consider committing the generated inputs to your source control system, this will allow you to restart go-fuzz without losing previous work.

Examples directory contains a bunch of examples of test functions and initial input corpuses for various packages.

The next step is to get go-fuzz:

$ go get github.com/dvyukov/go-fuzz/go-fuzz
$ go get github.com/dvyukov/go-fuzz/go-fuzz-build

Then, build the test program with necessary instrumentation:

$ go-fuzz-build github.com/dvyukov/go-fuzz/examples/png

This will produce png-fuzz.zip archive.

Now we are ready to go:

$ go-fuzz -bin=./png-fuzz.zip -workdir=examples/png

Go-fuzz will generate and test various inputs in an infinite loop. Workdir is used to store persistent data like current corpus and crashers, it allows fuzzer to continue after restart. Discovered bad inputs are stored in workdir/crashers dir; where file without a suffix contains binary input, file with .quoted suffix contains quoted input that can be directly copied into a reproducer program or a test, file with .output suffix contains output of the test on this input. Every few seconds go-fuzz prints logs of the form:

2015/04/25 12:39:53 slaves: 500, corpus: 186 (42s ago), crashers: 3,
     restarts: 1/8027, execs: 12009519 (121224/sec), cover: 2746, uptime: 1m39s

Where slaves means number of tests running in parallel (set with -procs flag). corpus is current number of interesting inputs the fuzzer has discovered, time in brackets says when the last interesting input was discovered. crashers is number of discovered bugs (check out workdir/crashers dir). restarts is the rate with which the fuzzer restarts test processes. The rate should be close to 1/10000 (which is the planned restart rate); if it is considerably higher than 1/10000, consider fixing already discovered bugs which lead to frequent restarts. execs is total number of test executions, and the number in brackets is the average speed of test executions. cover is number of bits set in a hashed coverage bitmap, if this number grows fuzzer uncovers new lines of code; size of the bitmap is 64K; ideally cover value should be less than ~5000, otherwise fuzzer can miss new interesting inputs due to hash collisions. And finally uptime is uptime of the process. This same information is also served via http (see the -http flag).

Random Notes

go-fuzz-build builds the program with gofuzz build tag, this allows to put the Fuzz function implementation directly into the tested package, but exclude it from normal builds with // +build gofuzz directive.

If your inputs contain a checksum, it can make sense to append/update the checksum in the Fuzz function. The chances that go-fuzz will generate the correct checksum are very low, so most work will be in vain otherwise.

Go-fuzz can utilize several machines. To do this, start master process separately:

$ go-fuzz -workdir=examples/png -master=127.0.0.1:8745

It will manage persistent corpus and crashers and coordinate work of slave processes. Then run one or more slave processes as:

$ go-fuzz -bin=./png-fuzz.zip -slave=127.0.0.1:8745 -procs=10

External Articles

Credits and technical details

Go-fuzz fuzzing logic is heavily based on american fuzzy lop, so refer to AFL readme if you are interested in technical details. AFL is written and maintained by Michal Zalewski. Some of the mutations employed by go-fuzz are inspired by work done by Mateusz Jurczyk, Gynvael Coldwind and Felix Gröbert.

Trophies

If you find some bugs with go-fuzz and are comfortable with sharing them, I would like to add them to this list. Please either send a pull request for README.md (preferable) or file an issue. If the source code is closed, you can say just "found N bugs in project X". Thank you.

go-fuzz's People

Contributors

dvyukov avatar stephens2424 avatar dgryski avatar rlmcpherson avatar thomasdezeeuw avatar tbg avatar mdlayher avatar joeshaw avatar bep avatar tdewolff avatar pmezard avatar breml avatar cryptix avatar gregory-m avatar marete avatar btracey avatar andybalholm avatar titanous avatar josharian avatar judwhite avatar mkevac avatar ebfe avatar cixtor avatar nikai3d avatar hydroflame avatar pcasaretto avatar ryancox avatar tgulacsi avatar tv42 avatar tw4452852 avatar

Watchers

xiazemin avatar avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.