Fuzzing dictionary

Contract

Field	Bound contract
Trigger	User needs a focused dictionary for a parser, protocol, or file format whose coverage stalls at fixed tokens.
Authority	Reversible local: writes only the named local dictionary file, the fuzzer campaign configuration, and transient short-campaign corpus or crash artifacts under a single output directory; rollback is deleting the dictionary file, reverting the configuration flag, and removing the short-campaign output directory. No remote mutation.
Side effect	Fuzzer dictionary file, campaign configuration, and transient short-campaign corpus or crash artifacts.
Done	The dictionary parses in the selected fuzzer and its tokens correspond to target validation or parsing gates.

Not for

• Patching the system under test to bypass obstacles: use fuzzing-obstacles.
• Coverage measurement or plateau analysis: use fuzzing-coverage-analysis.
• Remote, credential, publish, deploy, or irreversible changes.

Inputs

Required: the target source, specification, header files, or binary to extract tokens from; the selected fuzzer (libFuzzer, AFL++, or cargo-fuzz). Optional: an existing corpus, known boundary values, and the target's -max_len or equivalent input-length limit.

Procedure

1. Bound scope: name the single dictionary file path and the single fuzzer configuration flag to set. Do not edit source, harness, or corpus files. Done when: the dictionary path and config flag are named.
2. Identify the fixed tokens the target compares against: keywords, magic bytes, protocol commands, chunk types, format delimiters, and boundary values. Read them from the target source, header files, specification, or strings of the binary. Done when: fixed tokens are extracted from the target.
3. Write the dictionary file with one entry per line. Use "token" for bare strings, kw="value" for named entries, # for comments, \\ for backslash, \" for embedded quotes, and \xXX hex escapes for non-printable bytes. Done when: the dictionary file is written with correct syntax.
4. Keep the dictionary focused. Deduplicate with sort -u. Drop full sentences and prose; keep atomic tokens. Done when: the dictionary has deduplicated atomic entries.
5. Wire the dictionary into the selected fuzzer with its flag: libFuzzer -dict=./dictionary.dict, AFL++ -x ./dictionary.dict, cargo-fuzz -- -dict=./dictionary.dict. Confirm the fuzzer loads the file without a parse error. Done when: the fuzzer loads the dictionary without error.
6. Validate effectiveness: confirm the tokens reach the target's validation or parsing gates rather than being filtered before them. Run a short campaign with and without the dictionary to observe whether the tokens reach the gates. If a token is longer than the fuzzer's max input length, shorten it or raise the limit. Done when: the dictionary parses in the selected fuzzer and its tokens correspond to target validation or parsing gates.

Failure and recovery

• Dictionary parse error: the fuzzer reports a syntax or path error. Fix unescaped quotes, invalid \xXX escapes, or the file path; re-run the load check.
• Tokens do not correspond to target gates: re-extract from the target source or binary rather than guessing; replace irrelevant entries.
• Oversized dictionary: an excessive number of entries slows the fuzzer and dilutes useful tokens. Prune to the most relevant entries.
• Entries ignored: a token exceeds -max_len. Shorten the entry or raise the limit.
• Partial result: keep only entries that load and correspond to a gate; discard the rest.
• Non-mutation rule: on any failure, delete the dictionary file and revert the configuration flag before retrying; never leave a broken dictionary wired into the campaign.

Output

A fuzzer-parseable dictionary file plus the single fuzzer configuration flag set to load it, with confirmation that the tokens correspond to target validation or parsing gates.