ossfuzzseeds

README

go-ossfuzz-seeds

Go fuzz tests commonly add seeds with testing.F.Add, but OSS-Fuzz's native fuzz build ignores them. The result is that an OSS-Fuzz target starts from an empty corpus.

This package bridges that gap. It wraps *testing.F and keeps normal Go fuzzing behavior unchanged, while optionally writing each Add seed in the raw corpus format consumed by OSS-Fuzz's Go fuzzing helper.

Usage

Wrap *testing.F and use the wrapper for calls to Add:

package mypackage

import (
	"testing"

	ossfuzzseeds "github.com/quic-go/go-ossfuzz-seeds"
)

func FuzzParse(f *testing.F) {
	corpus := ossfuzzseeds.New(f)

	corpus.Add(uint8(1), "GET", []byte("/index.html"))
	corpus.Add(uint8(2), "POST", []byte("/api/v1/resource"))

	f.Fuzz(func(t *testing.T, version uint8, method string, path []byte) {
		// fuzz target
	})
}

When FUZZ_CORPUS_DIR is unset, corpus.Add behaves like f.Add. When FUZZ_CORPUS_DIR is set, it also writes one OSS-Fuzz-compatible corpus file per seed.

In an OSS-Fuzz or ClusterFuzz build script, run the fuzzer once with FUZZ_CORPUS_DIR set, then package the generated files as <fuzzer>_seed_corpus.zip in $OUT:

corpus_dir="$WORK/my_fuzzer_seed_corpus"
mkdir -p "$corpus_dir"

FUZZ_CORPUS_DIR="$corpus_dir" go test ./mypackage -run '^FuzzParse$' -count=1

(cd "$corpus_dir" && zip -q -r "$OUT/my_fuzzer_seed_corpus.zip" .)
compile_native_go_fuzzer_v2 github.com/me/project/mypackage FuzzParse my_fuzzer

Testing

The compatibility tests live in testing, a nested Go module, so this module does not need to include any dependencies on go-118-fuzz-build at runtime.

The encoding is tested against github.com/AdamKorcz/go-118-fuzz-build/input.Source, which is the helper used by compile_native_go_fuzzer_v2.

Documentation

Overview

Package ossfuzzseeds writes Go native fuzz seeds as OSS-Fuzz seed corpus files.

Index

• Variables
• func CorpusEntry(args ...any) ([]byte, error)
• type Helper
  • func New(f *testing.F) *Helper
  • func (h *Helper) Add(args ...any)

Variables

var ErrUnencodableDynamicCorpusArgs = errors.New("dynamic corpus arguments can't be encoded for OSS-Fuzz")

ErrUnencodableDynamicCorpusArgs is returned when OSS-Fuzz's dynamic argument weight format can't exactly represent the requested dynamic argument lengths.

Functions

func CorpusEntry

func CorpusEntry(args ...any) ([]byte, error)

CorpusEntry encodes one set of testing.F.Add arguments as a raw OSS-Fuzz seed corpus entry.

This is the lower-level encoder used by Helper.Add when FUZZ_CORPUS_DIR is set. Most fuzz targets should use New(f).Add(...) instead.

Types

type Helper

type Helper struct {
	*testing.F
	// contains filtered or unexported fields
}

Helper wraps *testing.F. When FUZZ_CORPUS_DIR is set to a non-empty path, Add() writes corpus entries in the raw format OSS-Fuzz expects.

func New

func New(f *testing.F) *Helper

New creates a helper. If FUZZ_CORPUS_DIR is set, corpus files will be written to that directory.

func (*Helper) Add

func (h *Helper) Add(args ...any)

Add calls the real Add and, if enabled, also writes the corpus entry.