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