1# AFL++ dictionaries 2 3For the general instruction manual, see [docs/README.md](../docs/README.md). 4 5This subdirectory contains a set of dictionaries that can be used in conjunction 6with the -x option to allow the fuzzer to effortlessly explore the grammar of 7some of the more verbose data formats or languages. 8 9These sets were done by Michal Zalewski, various contributors, and imported from 10oss-fuzz, go-fuzz and libfuzzer. 11 12Custom dictionaries can be added at will. They should consist of a 13reasonably-sized set of rudimentary syntax units that the fuzzer will then try 14to clobber together in various ways. Snippets between 2 and 16 bytes are usually 15the sweet spot. 16 17Custom dictionaries can be created in two ways: 18 19 - By creating a new directory and placing each token in a separate file, in 20 which case, there is no need to escape or otherwise format the data. 21 22 - By creating a flat text file where tokens are listed one per line in the 23 format of name="value". The alphanumeric name is ignored and can be omitted, 24 although it is a convenient way to document the meaning of a particular 25 token. The value must appear in quotes, with hex escaping (\xNN) applied to 26 all non-printable, high-bit, or otherwise problematic characters (\\ and \" 27 shorthands are recognized, too). 28 29The fuzzer auto-selects the appropriate mode depending on whether the -x 30parameter is a file or a directory. 31 32In the file mode, every name field can be optionally followed by @<num>, e.g.: 33 34 `keyword_foo@1 = "foo"` 35 36Such entries will be loaded only if the requested dictionary level is equal or 37higher than this number. The default level is zero; a higher value can be set by 38appending @<num> to the dictionary file name, like so: 39 40 `-x path/to/dictionary.dct@2` 41 42Good examples of dictionaries can be found in xml.dict and png.dict.