go-fuzz-patterns
Use this when adding fuzz tests for input parsers (JSON, query params, headers), validating that handlers never panic on malformed input, or testing query builders for injection vulnerabilities. Cover
SKILL.mdskills/go-fuzz-patterns/SKILL.md
GitHubFuzz Patterns
Standardizes fuzz testing across all microservices. Fuzzing finds edge cases, panics, and security vulnerabilities by feeding random inputs to parsers, handlers, and validators. Uses Go's native fuzzing (Go 1.18+).
When to Activate
- When testing input parsing (JSON, query params, headers)
- When validating that handlers never panic on malformed input
- When testing query builders for injection vulnerabilities
- Used by: test-generator, simulated-security-reviewer, simulated-qa-engineer
Go Native Fuzzing (Go 1.18+)
Basic Fuzz Function
func FuzzParseRequest(f *testing.F) {
// Seed corpus with known inputs
f.Add([]byte(`{"email":"user@example.com","name":"Test"}`))
f.Add([]byte(`{}`))
f.Add([]byte(`{"email":""}`))
f.Add([]byte(`null`))
f.Add([]byte{}) // empty
f.Fuzz(func(t *testing.T, data []byte) {
req, err := ParseCreateUserRequest(data)
if err != nil {
// Errors are expected for invalid input — not a bug
return
}
// If parsing succeeded, validate invariants
if req.Email == "" {
t.Error("parsed request has empty email")
}
})
}
Multi-Parameter Fuzzing
func FuzzAuthenticate(f *testing.F) {
f.Add("user@example.com", "password123")
f.Add("", "")
f.Add("admin@test.com", strings.Repeat("a", 10000))
f.Fuzz(func(t *testing.T, email, password string) {
// Must not panic regardless of input
_, err := svc.Authenticate(ctx, email, password)
if err == nil && email == "" {
t.Error("authenticated with empty email")
}
})
}
Corpus Management
testdata/
fuzz/
FuzzParseRequest/
corpus/
seed1 # Auto-generated corpus entries
seed2
crash-abc123 # Crash-causing inputs (bugs to fix)
- Corpus files are stored in
testdata/fuzz/<FuncName>/ f.Add()seeds are compiled into the binary- The fuzzer discovers new inputs and saves interesting ones to corpus
- Crash inputs are saved with
crash-prefix
Running Fuzz Tests
# Run for 60 seconds
go test -fuzz=FuzzParseRequest -fuzztime=60s ./...
# Run until a crash is found
go test -fuzz=FuzzParseRequest ./...
# Run specific fuzz target
go test -fuzz=^FuzzAuthenticate$ -fuzztime=30s ./pkg/auth/
# Run all fuzz targets in a package
go test -fuzz=. -fuzztime=10s ./pkg/handlers/
Crash Triage
When a fuzz crash is found:
- Reproduce:
go test -run=FuzzParseRequest/crash-abc123 ./... - Analyze: Read the crash input file — is it a realistic attack vector?
- Classify:
- Panic in production code = BUG (fix immediately)
- Index out of bounds = BUG
- Nil pointer dereference = BUG
- Unhandled error = BUG (add validation)
- Expected error not returned = BUG
- Fix: Add input validation, then verify the crash input no longer causes failure
- Keep: The crash file stays in corpus as a regression test
Common Fuzz Targets
| Target | What to Fuzz | What to Assert |
|---|---|---|
| JSON handlers | Random bytes as request body | No panic, valid error on invalid input |
| Query params | Random strings for filter/sort/page | No SQL injection, no panic |
| Path params | Random UUIDs, empty, special chars | 400 on invalid, no panic |
| Template renderer | Random merge field values | No SSTI, no panic |
| Auth tokens | Malformed JWTs, truncated tokens | Proper rejection, no panic |
Integration with CI
# In CI, run fuzz tests for limited time (not indefinitely)
go test -fuzz=. -fuzztime=60s ./...
# Exit code 0 = no crashes found in time window
# Exit code 1 = crash found (investigate)
Anti-Patterns
- Do NOT fuzz pure functions with bounded inputs (enums, booleans)
- Do NOT ignore panics — every panic in production code is a bug
- Do NOT run fuzz tests with
-racein CI (too slow) — run separately - Do NOT commit crash files without fixing the underlying bug first