fuzzing-obstacles

Fuzzing obstacles

Contract

Field	Bound contract
Trigger	User needs to identify and safely bypass checksums, nondeterminism, or validation barriers that block fuzzing coverage.
Authority	Reversible local: writes only the System Under Test source behind an explicit fuzzing build flag so production behavior is unchanged; rollback is deleting the conditional block or the fuzz build configuration. No remote mutation. Production code path is never altered.
Side effect	Fuzz-only target behavior behind explicit build controls. No production binary, credential, remote, or published artifact is touched.
Done	The specific obstacle is bypassed only in fuzz builds, coverage improves over the unpatched baseline, and false-positive risk is assessed.

Not for

• Dictionary creation for fixed-token gates: use fuzzing-dictionary.
• Coverage measurement or plateau analysis: use fuzzing-coverage-analysis.
• Remote, credential, publish, deploy, or irreversible changes.

Inputs

Required:

• The System Under Test source tree and its build system.
• A fuzzer harness and coverage tooling already producing a baseline coverage report.

Optional:

• A seed corpus or dictionary (use these first; only patch when they cannot overcome the obstacle).

Procedure

1. Identify the obstacle. Run the fuzzer and inspect coverage to locate unreachable code. Look for: checksum or hash verification before deeper processing; calls to rand(), time(), or srand() with system seeds; validation functions that reject most inputs; global-state initialization that differs across runs. Confirm the obstacle cannot be cleared with a better seed corpus or dictionary before patching. Done when: the obstacle is identified and confirmed unclearable by seeds or dictionary.
2. Add conditional compilation gated on the fuzzing build flag. Wrap the obstacle so it is enforced in production and bypassed only under the fuzzing build mode. See references/patch-patterns.md for C/C++ and Rust bypass patterns. Done when: the obstacle is wrapped behind the fuzzing build flag.
3. Patch incrementally. Bypass one obstacle at a time. Keep cheap validation (magic bytes, size checks) that guides the fuzzer at low cost; skip only the specific check that blocks coverage. Done when: one obstacle is bypassed and cheap validation is retained.
4. Provide safe defaults when downstream code assumes validated state. If code after the skipped check depends on a validated property (e.g., a divisor is nonzero), supply a safe fallback value under the fuzzing branch instead of skipping wholesale. See references/patch-patterns.md for the safe-default pattern. Done when: downstream assumptions are satisfied under the fuzzing branch.
5. Verify coverage improvement. Rebuild with fuzzing instrumentation, run the fuzzer for a short time, and compare line/basic-block/function coverage and corpus diversity against the unpatched baseline. Confirm new code paths are reachable. Done when: coverage improves over the unpatched baseline.
6. Assess false-positive risk. For each patch, determine whether skipping the check introduces program states impossible in production: does downstream code assume validated properties; could skipping cause crashes that cannot occur in production; is there implicit state dependency. Classify risk (LOW / MEDIUM / MITIGATED) and record it. If risk is high, narrow the patch or restore validation with safe defaults rather than skipping. Done when: each patch has a risk classification with rationale.
7. Document each patch so the fuzzing-vs-production divergence is visible to future maintainers. Done when: every patch is documented.