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
- 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.
- 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.
- 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.
- Keep the dictionary focused. Deduplicate with
sort -u. Drop full sentences and prose; keep atomic tokens. Done when: the dictionary has deduplicated atomic entries.
- 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.
- 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.
1---2name: fuzzing-dictionary3description: Use when a parser, protocol, or file format fuzzer stalls at fixed-token validation gates and needs a coverage dictionary. Not for patching the SUT: use fuzzing-obstacles.4---56# Fuzzing dictionary78## Contract910| Field | Bound contract |11|---|---|12| Trigger | User needs a focused dictionary for a parser, protocol, or file format whose coverage stalls at fixed tokens. |13| 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. |14| Side effect | Fuzzer dictionary file, campaign configuration, and transient short-campaign corpus or crash artifacts. |15| Done | The dictionary parses in the selected fuzzer and its tokens correspond to target validation or parsing gates. |1617## Not for1819- Patching the system under test to bypass obstacles: use fuzzing-obstacles.20- Coverage measurement or plateau analysis: use fuzzing-coverage-analysis.21- Remote, credential, publish, deploy, or irreversible changes.2223## Inputs2425Required: the target source, specification, header files, or binary to extract tokens from; the selected fuzzer (libFuzzer, AFL++, or cargo-fuzz).26Optional: an existing corpus, known boundary values, and the target's `-max_len` or equivalent input-length limit.2728## Procedure29301. 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.312. 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.323. 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.334. Keep the dictionary focused. Deduplicate with `sort -u`. Drop full sentences and prose; keep atomic tokens. Done when: the dictionary has deduplicated atomic entries.345. 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.356. 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.3637## Failure and recovery3839- 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.40- Tokens do not correspond to target gates: re-extract from the target source or binary rather than guessing; replace irrelevant entries.41- Oversized dictionary: an excessive number of entries slows the fuzzer and dilutes useful tokens. Prune to the most relevant entries.42- Entries ignored: a token exceeds `-max_len`. Shorten the entry or raise the limit.43- Partial result: keep only entries that load and correspond to a gate; discard the rest.44- 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.4546## Output4748A 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.
OutlineDriven