Fuzzing

Why Go fuzzing

The framework is bash. Bash has no first-class fuzzing framework that OpenSSF Scorecard recognises (Scorecard scores Fuzzing 0 unless the project ships an integration with one of: OSS-Fuzz, ClusterFuzzLite, native Go fuzz, libFuzzer, Atheris). The pragmatic path is to port each user-input parsing surface into a small Go function, run the fuzzer against the Go port, and keep the Go port in lockstep with the shell original via identical regex / control-flow.

Drift between the shell and Go port IS the bug class the fuzzer is designed to surface — if the Go port accepts a string the shell rejects (or vice-versa), one of them has a hole.

Where the harnesses live

The framework ships three Go binaries as well as the shell, so harnesses live in four modules:

dot-ui and dot-ai-tui are package main in their own modules, which OSS-Fuzz's compile_native_go_fuzzer cannot import — it needs a library package. Their parsers are therefore ported into fuzz alongside the shell ports, and fuzzed in-module as well. The in-module targets are the ones that catch real bugs on every push; the ports are what runs continuously at scale. The same lockstep rule applies: drift between a port and its original is a bug in one of them.

Harnesses today

Ports (built by OSS-Fuzz / ClusterFuzzLite)

In-module (against the real implementation)

Each module's FEATURES.md maps every harness to the feature it covers, and a matrix test fails if a harness is missing from it.

Findings so far

Harness files must be self-contained

compile_native_go_fuzzer rewrites one *_test.go file into a regular .go file and builds it without the package's other test files. A harness that references a symbol declared in a sibling _test.go therefore passes go test everywhere and fails only inside the OSS-Fuzz / ClusterFuzzLite container:

./dot_ui_parsers_test.go_fuzz.go:117:21: undefined: dangerousChars
2026/09/07 01:14:42 failed to build packages:exit status 1

So a shared constant is deliberately duplicated per harness file rather than factored out. If sharing is genuinely warranted, put the symbol in a non-test .go file in the package — those the builder keeps.

tools/ci/check-fuzz-harness-self-contained.sh enforces this by type-checking each harness alone in a scratch module; it runs in the Fuzz / Harness self-containment job on every relevant PR.

Add a harness when:

• a new dot <subcommand> accepts user input via $1 / --flag,
• a new regex appears in scripts/dot/lib/utils.sh,
• a new "construct a URL / path / shell-eval string" code path lands,
• a new function in dot-ui, dot-ai-tui or dot-mcp parses or transforms stdin, an environment variable, a key stream or model output — add it in-module and port it to fuzz.

Running locally

# Ports (also what OSS-Fuzz builds)
cd fuzz
go test -run '^$' -fuzz=FuzzValidateName -fuzztime=30s ./...
go test -run '^$' -fuzz=FuzzUIEventLine  -fuzztime=30s ./...

# In-module, against the real implementation
cd defaults/dot_local/share/dot-ui
go test -run '^$' -fuzz=FuzzStepApply -fuzztime=30s ./...

cd defaults/dot_local/share/dot-ai-tui
go test -run '^$' -fuzz=FuzzHighlight -fuzztime=30s ./...

# Replay every committed corpus in a module (no fuzzing, no flakes)
go test -run '^Fuzz' -v ./...

Each module's README lists every harness with a copy-pasteable command.

Failures land in testdata/fuzz/Fuzz<Name>/ as auto-saved reproducers. Commit them — they become permanent regression guards, replayed by go test ./... and by the replay job in .github/workflows/fuzz.yml.

OSS-Fuzz integration (pending)

The fuzz/oss-fuzz/ directory contains everything OSS-Fuzz needs to onboard this project:

fuzz/oss-fuzz/
├── project.yaml      # OSS-Fuzz project metadata
├── Dockerfile        # build environment
├── build.sh          # compiles every harness in fuzz/
└── fuzz/             # the harnesses themselves
    ├── go.mod
    ├── validate_name_test.go
    ├── init_url_resolver_test.go
    ├── dot_ui_parsers_test.go       # ports of the dot-ui parsers
    └── dot_ai_tui_parsers_test.go   # ports of the dot-ai-tui parsers

To onboard:

1. Fork github.com/google/oss-fuzz.

2. Copy fuzz/oss-fuzz/ contents to projects/dotfiles/ in the fork.

3. Verify locally per https://google.github.io/oss-fuzz/getting-started/new-project-guide/#testing-locally:

   python infra/helper.py build_image dotfiles
   python infra/helper.py build_fuzzers --sanitizer address dotfiles
   python infra/helper.py check_build dotfiles
   python infra/helper.py run_fuzzer dotfiles fuzz_validate_name
   

4. Open a PR to google/oss-fuzz per https://google.github.io/oss-fuzz/getting-started/accepting-new-projects/.

5. Once merged, OSS-Fuzz schedules continuous runs on GCP; findings land as private issues in the OSS-Fuzz tracker and are mirrored to the maintainer email in project.yaml.

6. Update docs/security/SCORECARD.md — Scorecard's Fuzzing check recognises OSS-Fuzz projects automatically (0 → 10).

The upstream PR opens the door to the CIFuzz GitHub Action, which runs OSS-Fuzz-style fuzzing on every PR in this repo (separate from the local-go-fuzz CI job).

CI workflow

.github/workflows/fuzz.yml has two gates:

• replay — on every push and PR, every committed corpus (seed entries plus the minimized crashers of previously-fixed findings) is replayed in all three modules with go test -run '^Fuzz'. No fuzzing, so no flakes: a fixed crash cannot silently come back.
• fuzz — a 60-second window per harness (configurable via workflow_dispatch) on PRs touching an input-parsing surface: scripts/dot/lib/utils.sh, scripts/dot/commands/init.sh, fuzz/**, .clusterfuzzlite/** or either Go module.

This is the local equivalent of CIFuzz and catches the "shell-regex-change without Go-port update" drift class before PR merge. The per-module test workflows (dot-ui-test.yml, cockpit-test.yml) replay their own corpus too, so the guard holds even when only one module changes.

See also

• docs/security/SCORECARD.md — Fuzzing check tracking.
• Go native fuzzing tutorial.
• OSS-Fuzz new project guide.
• CIFuzz GitHub Action.