fuzzing-dictionary skill
✓ OfficialBuilds and applies domain-specific token dictionaries to guide fuzzers toward deeper code paths in parsers, protocols, and file formats.
- GitHub stars
- 8,136
- Files
- 3
- Last commit
- Nov 11, 2026
- License
- CC-BY-SA-4.0
- Allowed tools
- —
What does the fuzzing-dictionary skill do?
fuzzing-dictionary builds and applies domain-specific token dictionaries to guide fuzzers toward deeper code paths in parsers, protocols, and file formats.
Summary generated from the skill's SKILL.md.
About the fuzzing-dictionary skill
Guiding fuzzers toward deeper code paths in parsers, protocols, and file formats is what this technique enables. By providing domain-specific tokens like magic bytes, keywords, and protocol commands, you help a fuzzer bypass early validation checks that often stall coverage during blind mutation. This is particularly useful when a target compares input against fixed strings or when coverage plateaus at initial input validation stages.
Developers can generate these dictionaries by extracting strings from header files, binaries, or man pages, or by using an LLM to identify relevant tokens. The resulting text files contain quoted strings or key-value pairs and can include hex escapes for non-printable characters. Once created, these files are integrated into existing fuzzing workflows using specific flags for tools like libFuzzer, AFL++, and cargo-fuzz. This approach ensures that the fuzzer incorporates meaningful structure into its generated inputs rather than relying on purely random mutations.
What an agent can do with it
- 1Bypass early parser validationUse dictionaries to help a fuzzer reach deeper logic in JSON, XML, or configuration file parsers.
- 2Fuzz network protocol implementationsProvide a fuzzer with HTTP methods and headers to test protocol handlers.
- 3Test media codec handlersInject magic bytes and chunk types to guide fuzzing of image or video formats.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the fuzzing-dictionary skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the fuzzing-dictionary skill in Plugin
/plugin marketplace add trailofbits/skills /plugin install testing-handbook-skills@trailofbits
Install the fuzzing-dictionary skill in Claude Code
~/.claude/skills/fuzzing-dictionary/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/fuzzing-dictionary ~/.claude/skills/fuzzing-dictionaryInstall the fuzzing-dictionary skill in Claude Code (project)
.claude/skills/fuzzing-dictionary/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/fuzzing-dictionary .claude/skills/fuzzing-dictionaryInstall the fuzzing-dictionary skill in Codex
~/.agents/skills/fuzzing-dictionary/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/fuzzing-dictionary ~/.agents/skills/fuzzing-dictionaryInstall the fuzzing-dictionary skill in Gemini CLI
~/.gemini/skills/fuzzing-dictionary/SKILL.md
$ npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/fuzzing-dictionary ~/.gemini/skills/fuzzing-dictionaryInstall the fuzzing-dictionary skill in Claude.ai
npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/fuzzing-dictionary fuzzing-dictionary && zip -r fuzzing-dictionary.zip fuzzing-dictionary # claude.ai → Customize → Skills → + → Create skill → Upload a skill → fuzzing-dictionary.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletrailofbits/skills/plugins/testing-handbook-skills/skills/fuzzing-dictionary is public and reachablegithub.com/trailofbits/skills/tree/HEAD/plugins/testing-hand ↗Pass
- Open source license (OSI)CC-BY-SA-4.0 is not OSI-approvedspdx.org/licenses/CC-BY-SA-4.0.html ↗Finding
- Commit or release in the last yearLast commit 2026-11-11github.com/trailofbits/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/trailofbits/skills/blob/HEAD/plugins/testing-hand ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/trailofbits/skills/blob/HEAD/plugins/testing-hand ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 296 linesgithub.com/trailofbits/skills/blob/HEAD/plugins/testing-hand ↗Pass
SKILL.md
View on GitHubFuzzing Dictionary
A fuzzing dictionary provides domain-specific tokens to guide the fuzzer toward interesting inputs. Instead of purely random mutations, the fuzzer incorporates known keywords, magic numbers, protocol commands, and format-specific strings that are more likely to reach deeper code paths in parsers, protocol handlers, and file format processors.
Overview
Dictionaries are text files containing quoted strings that represent meaningful tokens for your target. They help fuzzers bypass early validation checks and explore code paths that would be difficult to reach through blind mutation alone.
Key Concepts
| Concept | Description |
|---|---|
| Dictionary Entry | A quoted string (e.g., "keyword") or key-value pair (e.g., kw="value") |
| Hex Escapes | Byte sequences like "\xF7\xF8" for non-printable characters |
| Token Injection | Fuzzer inserts dictionary entries into generated inputs |
| Cross-Fuzzer Format | Dictionary files work with libFuzzer, AFL++, and cargo-fuzz |
When to Apply
Apply this technique when:
- Fuzzing parsers (JSON, XML, config files)
- Fuzzing protocol implementations (HTTP, DNS, custom protocols)
- Fuzzing file format handlers (PNG, PDF, media codecs)
- Coverage plateaus early without reaching deeper logic
- Target code checks for specific keywords or magic values
Skip this technique when:
- Fuzzing pure algorithms without format expectations
- Target has no keyword-based parsing
- Corpus already achieves high coverage
Quick Reference
| Task | Command/Pattern |
|---|---|
| Use with libFuzzer | ./fuzz -dict=./dictionary.dict ... |
| Use with AFL++ | afl-fuzz -x ./dictionary.dict ... |
| Use with cargo-fuzz | cargo fuzz run fuzz_target -- -dict=./dictionary.dict |
| Extract from header | grep -o '".*"' header.h > header.dict |
| Generate from binary | strings ./binary | sed 's/^/"&/; s/$/&"/' > strings.dict |
Step-by-Step
Step 1: Create Dictionary File
Create a text file with quoted strings on each line. Use comments (#) for documentation.
Example dictionary format:
# Lines starting with '#' and empty lines are ignored.
# Adds "blah" (w/o quotes) to the dictionary.
kw1="blah"
# Use \\ for backslash and \" for quotes.
kw2="\"ac\\dc\""
# Use \xAB for hex values
kw3="\xF7\xF8"
# the name of the keyword followed by '=' may be omitted:
"foo\x0Abar"
Step 2: Generate Dictionary Content
Choose a generation method based on what's available:
From LLM: Prompt ChatGPT or Claude with:
A dictionary can be used to guide the fuzzer. Write me a dictionary file for fuzzing a <PNG parser>. Each line should be a quoted string or key-value pair like kw="value". Include magic bytes, chunk types, and common header values. Use hex escapes like "\xF7\xF8" for binary values.
From header files:
grep -o '".*"' header.h > header.dict
From man pages (for CLI tools):
man curl | grep -oP '^\s*(--|-)\K\S+' | sed 's/[,.]$//' | sed 's/^/"&/; s/$/&"/' | sort -u > man.dict
From binary strings:
strings ./binary | sed 's/^/"&/; s/$/&"/' > strings.dict
Step 3: Pass Dictionary to Fuzzer
Use the appropriate flag for your fuzzer (see Quick Reference above).
Common Patterns
Pattern: Protocol Keywords
Use Case: Fuzzing HTTP or custom protocol handlers
Dictionary content:
# HTTP methods
"GET"
"POST"
"PUT"
"DELETE"
"HEAD"
# Headers
"Content-Type"
"Authorization"
"Host"
# Protocol markers
"HTTP/1.1"
"HTTP/2.0"
Pattern: Magic Bytes and File Format Headers
Use Case: Fuzzing image parsers, media decoders, archive handlers
Dictionary content:
# PNG magic bytes and chunks
png_magic="\x89PNG\r\n\x1a\n"
ihdr="IHDR"
plte="PLTE"
idat="IDAT"
iend="IEND"
# JPEG markers
jpeg_soi="\xFF\xD8"
jpeg_eoi="\xFF\xD9"
Pattern: Configuration File Keywords
Use Case: Fuzzing config file parsers (YAML, TOML, INI)
Dictionary content:
# Common config keywords
"true"
"false"
"null"
"version"
"enabled"
"disabled"
# Section headers
"[general]"
"[network]"
"[security]"
Advanced Usage
Tips and Tricks
| Tip | Why It Helps |
|---|---|
| Combine multiple generation methods | LLM-generated keywords + strings from binary covers broad surface |
| Include boundary values | "0", "-1", "2147483647" trigger edge cases |
| Add format delimiters | :, =, {, } help fuzzer construct valid structures |
| Keep dictionaries focused | 50-200 entries perform better than thousands |
| Test dictionary effectiveness | Run with and without dict, compare coverage |
Auto-Generated Dictionaries (AFL++)
When using afl-clang-lto compiler, AFL++ automatically extracts dictionary entries from string comparisons in the binary. This happens at compile time via the AUTODICTIONARY feature.
Enable auto-dictionary:
export AFL_LLVM_DICT2FILE=auto.dict
afl-clang-lto++ target.cc -o target
# Dictionary saved to auto.dict
afl-fuzz -x auto.dict -i in -o out -- ./target
Combining Multiple Dictionaries
Some fuzzers support multiple dictionary files:
# AFL++ with multiple dictionaries
afl-fuzz -x keywords.dict -x formats.dict -i in -o out -- ./target
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| Including full sentences | Fuzzer needs atomic tokens, not prose | Break into individual keywords |
| Duplicating entries | Wastes mutation budget | Use sort -u to deduplicate |
| Over-sized dictionaries | Slows fuzzer, dilutes useful tokens | Keep focused: 50-200 most relevant entries |
| Missing hex escapes | Non-printable bytes become mangled | Use \xXX for binary values |
| No comments | Hard to maintain and audit | Document sections with # comments |
Tool-Specific Guidance
libFuzzer
clang++ -fsanitize=fuzzer,address harness.cc -o fuzz
./fuzz -dict=./dictionary.dict corpus/
Integration tips:
- Dictionary tokens are inserted/replaced during mutations
- Combine with
-max_lento control input size - Use
-print_final_stats=1to see dictionary effectiveness metrics - Dictionary entries longer than
-max_lenare ignored
AFL++
afl-fuzz -x ./dictionary.dict -i input/ -o output/ -- ./target @@
Integration tips:
- AFL++ supports multiple
-xflags for multiple dictionaries - Use
AFL_LLVM_DICT2FILEwithafl-clang-ltofor auto-generated dictionaries - Dictionary effectiveness shown in fuzzer stats UI
- Tokens are used during deterministic and havoc stages
cargo-fuzz (Rust)
cargo fuzz run fuzz_target -- -dict=./dictionary.dict
Integration tips:
- cargo-fuzz uses libFuzzer backend, so all libFuzzer dict flags work
- Place dictionary file in
fuzz/directory alongside harness - Reference from harness directory:
cargo fuzz run target -- -dict=../dictionary.dict
go-fuzz (Go)
go-fuzz does not have built-in dictionary support, but you can manually seed the corpus with dictionary entries:
# Convert dictionary to corpus files
grep -o '".*"' dict.txt | while read line; do
echo -n "$line" | base64 > corpus/$(echo "$line" | md5sum | cut -d' ' -f1)
done
go-fuzz -bin=./target-fuzz.zip -workdir=.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Dictionary file not loaded | Wrong path or format error | Check fuzzer output for dict parsing errors; verify file format |
| No coverage improvement | Dictionary tokens not relevant | Analyze target code for actual keywords; try different generation method |
| Syntax errors in dict file | Unescaped quotes or invalid escapes | Use \\ for backslash, \" for quotes; validate with test run |
| Fuzzer ignores long entries | Entries exceed -max_len |
Keep entries under max input length, or increase -max_len |
| Too many entries slow fuzzer | Dictionary too large | Prune to 50-200 most relevant entries |
Related Skills
Tools That Use This Technique
| Skill | How It Applies |
|---|---|
| libfuzzer | Native dictionary support via -dict= flag |
| aflpp | Native dictionary support via -x flag; auto-generation with AUTODICTIONARIES |
| cargo-fuzz | Uses libFuzzer backend, inherits -dict= support |
Related Techniques
| Skill | Relationship |
|---|---|
| fuzzing-corpus | Dictionaries complement corpus: corpus provides structure, dictionary provides keywords |
| coverage-analysis | Use coverage data to validate dictionary effectiveness |
| harness-writing | Harness structure determines which dictionary tokens are useful |
Resources
Key External Resources
AFL++ Dictionaries Pre-built dictionaries for common formats (HTML, XML, JSON, SQL, etc.). Good starting point for format-specific fuzzing.
libFuzzer Dictionary Documentation Official libFuzzer documentation on dictionary format and usage. Explains token insertion strategy and performance implications.
Additional Examples
OSS-Fuzz Dictionaries
Real-world dictionaries from Google's continuous fuzzing service. Search project directories for *.dict files to see production examples.
Files in this skill
3fuzzing-dictionary skill questions
How do I install the fuzzing-dictionary skill in Claude Code?
Run npx degit trailofbits/skills/plugins/testing-handbook-skills/skills/fuzzing-dictionary ~/.claude/skills/fuzzing-dictionary. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the fuzzing-dictionary skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
When should I use a fuzzing dictionary?
Use this technique when fuzzing parsers, protocol implementations, or file format handlers, especially if coverage plateaus or the target checks for specific keywords.
How do I use a dictionary with AFL++?
You can pass a dictionary to AFL++ using the -x flag: afl-fuzz -x ./dictionary.dict ....
Can AFL++ automatically generate dictionaries?
Yes, when using the afl-clang-lto compiler, AFL++ can automatically extract dictionary entries from string comparisons in the binary using the AUTODICTIONARY feature.
What is the recommended size for a fuzzing dictionary?
It is best to keep dictionaries focused, ideally between 50 and 200 entries, to avoid slowing down the fuzzer.