Fuzzing Go Expert Agent Skill

Fuzzing Go expert

This skill provides the agent with the knowledge and tools to write, build, and

validate fuzz targets for Go projects integrated into OSS-Fuzz. Go fuzzing uses

the native Go fuzzing framework introduced in Go 1.18, which OSS-Fuzz drives

via libFuzzer under the hood using compile_native_go_fuzzer.

Fundamental Concepts

OSS-Fuzz base image

Go projects must use the Go base builder image:

FROM gcr.io/oss-fuzz-base/base-builder-go

Set language: go in project.yaml.

Harness structure

Go fuzz targets are standard Go test functions with the prefix Fuzz, placed

in _test.go files (or plain .go files that import the testing package):

package mypkg

import (
    "testing"
    _ "github.com/AdamKorcz/go-118-fuzz-build/testing" // required for OSS-Fuzz native fuzzing
)

func FuzzMyTarget(f *testing.F) {
    // Seed corpus: add representative valid inputs so the fuzzer starts
    // from a meaningful state rather than empty bytes.
    f.Add([]byte("example input"))
    f.Add([]byte("another seed"))

    f.Fuzz(func(t *testing.T, data []byte) {
        // Call into the target. Ignore expected errors; let unexpected
        // panics surface as findings.
        _, _ = ParseSomething(data)
    })
}

The inner f.Fuzz callback signature can use typed parameters instead of

[]byte when the target expects structured input:

f.Fuzz(func(t *testing.T, s string, n int, b bool) {
    _ = ProcessRecord(s, n, b)
})

Building in OSS-Fuzz

Use the compile_native_go_fuzzer helper in build.sh. It takes the package

import path, the function name, and the output binary name:

# build.sh
cp $SRC/fuzz_test.go ./          # copy harness into the module if needed
printf "package mypkg\nimport _ \"github.com/AdamKorcz/go-118-fuzz-build/testing\"\n" \
    > register.go                # required registration shim
go mod tidy
compile_native_go_fuzzer github.com/owner/repo/pkg FuzzMyTarget fuzz_my_target

For projects with multiple packages or multiple fuzz targets repeat the call:

compile_native_go_fuzzer github.com/owner/repo/pkg1 FuzzFoo fuzz_foo
compile_native_go_fuzzer github.com/owner/repo/pkg2 FuzzBar fuzz_bar

Seed corpus and dictionaries

• Seed corpus entries go in $OUT/<fuzzer_name>_seed_corpus/ as individual

files, or as a zip at $OUT/<fuzzer_name>_seed_corpus.zip.

• Dictionaries go in $OUT/<fuzzer_name>.dict as plaintext token files.
• Alternatively, add seeds directly via f.Add(...) in the harness — these

are compiled in and used as the initial corpus.

• For targets that parse a structured format, generating seeds with a script

beats hand-picking a few files — random mutation rarely passes the parser's

early checks. See the [structured seed generation

reference](../oss-fuzz-engineer/references/structured_seed_generation.md).

Characteristics of good Go fuzzing harnesses

• Targets attack surface: focus on parsers, decoders, protocol handlers,

serialisation/deserialisation, and any API that accepts untrusted bytes or

strings.

• Handles expected errors gracefully: wrap calls in error checks and ignore

expected error returns. Only genuine panics and unexpected behaviour are

findings.

• Uses typed fuzz parameters when the target is not purely byte-oriented —

Go's fuzzer can mutate string, int, bool, float64, etc. directly.

• Avoids non-determinism: do not use random sources, time, goroutines, or

global state that persists between calls.

• Keeps the callback fast: expensive setup (e.g. parsing config, opening

files) belongs outside f.Fuzz(...), not inside the inner function.

• Provides meaningful seeds: f.Add(...) entries should be valid

representative inputs so coverage grows from the start.

• Does not get stuck: avoid code paths that busy-loop or block on I/O

inside the fuzz function.

• Includes the registration shim: the `import _

"github.com/AdamKorcz/go-118-fuzz-build/testing"` blank import is required

for OSS-Fuzz to hook into native Go fuzzing — never omit it.

What Go fuzzing finds

Go is memory-safe, so the focus shifts from memory-corruption bugs to:

• Panics: index out of range, nil pointer dereference, type assertion

failures, stack overflows — any unrecovered panic is a crash.

• Logic bugs: incorrect parsing, silent data corruption, wrong output for

valid input.

• Infinite loops / hangs: code that never returns on certain inputs

(detected by OSS-Fuzz's timeout).

• Incorrect error handling: code that should return an error but panics

instead, or vice versa.

Operational guidelines

• Always validate with:

  python3 infra/helper.py build_fuzzers <project>
  python3 infra/helper.py check_build <project>
  python3 infra/helper.py run_fuzzer <project> <fuzzer_name> -- -max_total_time=30

• An instant crash almost always means the harness itself is wrong (e.g.

missing error handling, bad seed, wrong package path).

• Run go vet ./... and go build ./... inside the module before wrapping in

an OSS-Fuzz build to catch compile errors early.

• When iterating locally clone the upstream repo and switch the Dockerfile from

RUN git clone to COPY to avoid network round-trips.

• Document why each entry point was chosen and what class of bugs it may find.