fuzz
packagestandard library
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Report a Vulnerability
Documentation¶
Overview¶
Package fuzz provides common fuzzing functionality for tests built with"go test" and for programs that use fuzzing functionality in the testingpackage.
Index¶
- func CheckCorpus(vals []any, types []reflect.Type) error
- func CoordinateFuzzing(ctx context.Context, opts CoordinateFuzzingOpts) (err error)
- func ResetCoverage()
- func RunFuzzWorker(ctx context.Context, fn func(CorpusEntry) error) error
- func SnapshotCoverage()
- type CoordinateFuzzingOpts
- type CorpusEntry
- type MalformedCorpusError
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcCheckCorpus¶
CheckCorpus verifies that the types in vals match the expected typesprovided.
funcCoordinateFuzzing¶
func CoordinateFuzzing(ctxcontext.Context, optsCoordinateFuzzingOpts) (errerror)
CoordinateFuzzing creates several worker processes and communicates withthem to test random inputs that could trigger crashes and expose bugs.The worker processes run the same binary in the same directory with thesame environment variables as the coordinator process. Workers also runwith the same arguments as the coordinator, except with the -test.fuzzworkerflag prepended to the argument list.
If a crash occurs, the function will return an error containing informationabout the crash, which can be reported to the user.
funcResetCoverage¶
func ResetCoverage()
ResetCoverage sets all of the counters for each edge of the instrumentedsource code to 0.
funcRunFuzzWorker¶
func RunFuzzWorker(ctxcontext.Context, fn func(CorpusEntry)error)error
RunFuzzWorker is called in a worker process to communicate with thecoordinator process in order to fuzz random inputs. RunFuzzWorker loopsuntil the coordinator tells it to stop.
fn is a wrapper on the fuzz function. It may return an error to indicatea given input "crashed". The coordinator will also record a crasher ifthe function times out or terminates the process.
RunFuzzWorker returns an error if it could not communicate with thecoordinator process.
funcSnapshotCoverage¶
func SnapshotCoverage()
SnapshotCoverage copies the current counter values into coverageSnapshot,preserving them for later inspection. SnapshotCoverage also rounds eachcounter down to the nearest power of two. This lets the coordinator storemultiple values for each counter by OR'ing them together.
Types¶
typeCoordinateFuzzingOpts¶
type CoordinateFuzzingOpts struct {// Log is a writer for logging progress messages and warnings.// If nil, io.Discard will be used instead.Logio.Writer// Timeout is the amount of wall clock time to spend fuzzing after the corpus// has loaded. If zero, there will be no time limit.Timeouttime.Duration// Limit is the number of random values to generate and test. If zero,// there will be no limit on the number of generated values.Limitint64// MinimizeTimeout is the amount of wall clock time to spend minimizing// after discovering a crasher. If zero, there will be no time limit. If// MinimizeTimeout and MinimizeLimit are both zero, then minimization will// be disabled.MinimizeTimeouttime.Duration// MinimizeLimit is the maximum number of calls to the fuzz function to be// made while minimizing after finding a crash. If zero, there will be no// limit. Calls to the fuzz function made when minimizing also count toward// Limit. If MinimizeTimeout and MinimizeLimit are both zero, then// minimization will be disabled.MinimizeLimitint64// parallel is the number of worker processes to run in parallel. If zero,// CoordinateFuzzing will run GOMAXPROCS workers.Parallelint// Seed is a list of seed values added by the fuzz target with testing.F.Add// and in testdata.Seed []CorpusEntry// Types is the list of types which make up a corpus entry.// Types must be set and must match values in Seed.Types []reflect.Type// CorpusDir is a directory where files containing values that crash the// code being tested may be written. CorpusDir must be set.CorpusDirstring// CacheDir is a directory containing additional "interesting" values.// The fuzzer may derive new values from these, and may write new values here.CacheDirstring}CoordinateFuzzingOpts is a set of arguments for CoordinateFuzzing.The zero value is valid for each field unless specified otherwise.
typeCorpusEntry¶
type CorpusEntry = struct {Parentstring// Path is the path of the corpus file, if the entry was loaded from disk.// For other entries, including seed values provided by f.Add, Path is the// name of the test, e.g. seed#0 or its hash.Pathstring// Data is the raw input data. Data should only be populated for seed// values. For on-disk corpus files, Data will be nil, as it will be loaded// from disk using Path.Data []byte// Values is the unmarshaled values from a corpus file.Values []anyGenerationint// IsSeed indicates whether this entry is part of the seed corpus.IsSeedbool}CorpusEntry represents an individual input for fuzzing.
We must use an equivalent type in the testing and testing/internal/testdepspackages, but testing can't import this package directly, and we don't wantto export this type from testing. Instead, we use the same struct type anduse a type alias (not a defined type) for convenience.
funcReadCorpus¶
func ReadCorpus(dirstring, types []reflect.Type) ([]CorpusEntry,error)
ReadCorpus reads the corpus from the provided dir. The returned corpusentries are guaranteed to match the given types. Any malformed files willbe saved in a MalformedCorpusError and returned, along with the most recenterror.
typeMalformedCorpusError¶
type MalformedCorpusError struct {// contains filtered or unexported fields}MalformedCorpusError is an error found while reading the corpus from thefilesystem. All of the errors are stored in the errs list. The testingframework uses this to report malformed files in testdata.
func (*MalformedCorpusError)Error¶
func (e *MalformedCorpusError) Error()string
Source Files