Skip to content

FUZZING.md

Latest commit

 

History

History
91 lines (65 loc) · 2.85 KB

FUZZING.md

File metadata and controls

91 lines (65 loc) · 2.85 KB

Fuzzing

Nuclei uses go-fuzz for targeted harnesses behind the gofuzz build tag.

Targets

The Makefile exposes these go-fuzz targets:

make build-fuzz GOFUZZ_PACKAGE=./pkg/operators/matchers
make fuzz GOFUZZ_PACKAGE=./pkg/operators/matchers

Required variable:

  • GOFUZZ_PACKAGE: any package path that go list can resolve from the repo root. The normal form in this repo is a relative package path such as ./pkg/operators/matchers.

build-fuzz, fuzz, and fuzz-ci derive everything else from that package path:

  • workdir: <package>/.gofuzz/
  • seed corpus: <package>/testdata/gofuzz-corpus/
  • instrumented archive: <package>/.gofuzz/<pkgname>-fuzz.zip

discover-fuzz-packages emits the GitHub Actions matrix JSON to stdout, and writes matrix=... to GITHUB_OUTPUT when that file is present.

fuzz-ci wraps make fuzz in the CI timeout.

build-fuzz and fuzz fail immediately if GOFUZZ_PACKAGE is missing, the package cannot be resolved, or the seed corpus directory is missing or empty.

Examples

Operators (matchers & extractors) harness:

make fuzz GOFUZZ_PACKAGE=./pkg/operators/matchers
make fuzz GOFUZZ_PACKAGE=./pkg/operators/extractors

Harness Coverage:

Matchers exercise Matcher.CompileMatchers() through a compact line-based grammar. Supported keys are:

  • type
  • condition
  • part
  • encoding
  • negative
  • case-insensitive
  • match-all
  • name
  • value
  • status
  • size

Extractors exercise Extractor.CompileExtractors() and the matching extraction path with fixed local corpora. Supported keys are:

  • type
  • part
  • name
  • internal
  • case-insensitive
  • group
  • attribute
  • value
  • regex
  • kval
  • json
  • xpath
  • dsl

Artifacts

Each run writes under <package>/.gofuzz/:

  • corpus/: evolving seed corpus used by go-fuzz.
  • crashers/: saved crashing inputs.
  • *-fuzz.zip: the instrumented build output created by go-fuzz-build.

Promote real crashers into ordinary regression tests in the owning package once the underlying issue is fixed.

GitHub Actions

The repository also has a dedicated GitHub Actions fuzz workflow in .github/workflows/fuzz.yaml.

  • Triggers: workflow_dispatch and a weekly schedule.
  • Scheduled runs: limited to projectdiscovery/nuclei; manual dispatch still works in forks.
  • Matrix source: any package that has committed seeds under testdata/gofuzz-corpus/ and a sibling fuzz.go harness.
  • Current package matrix: ./pkg/operators/matchers and ./pkg/operators/extractors.
  • Runtime model: discovery runs make discover-fuzz-packages, and each package runs CI=true make fuzz-ci GOFUZZ_PACKAGE=... FUZZ_DURATION=15m.
  • Artifacts: each matrix job uploads the full <package>/.gofuzz/ as the artifacts.
  • Failure policy: crashers are summarized and uploaded, but they do not fail the workflow; build/setup errors still fail the job.