Fuzzing with Fandango

Creating a Name Database

Let us now come up with an input that is slightly more complex. We want to create a set of inputs with names of persons and their respective age. These two values would be comma-separated, such that typical inputs would look like this:

Alice Doe,27
John Smith,45
...

This makes the overall format of our input look like this:

<start> ::= <person_name> "," <age>

with <age> again being a sequence of digits, and a <person>’s name being defined as

<person_name> ::= <first_name> " " <last_name>

where both first and last name would be a sequence of letters - first, an uppercase letter, and then a sequence of lowercase letters. The full definition looks like this:

In Fandango specs, symbol names are formed as identifiers in Python - that is, they consist of letters, underscores, and digits.

Future Fandango versions will have shortcuts for specifying character ranges.

<start> ::= <person_name> "," <age>
<person_name> ::= <first_name> " " <last_name>
<first_name> ::= <name>
<last_name> ::= <name>
<name> ::= <ascii_uppercase_letter><ascii_lowercase_letter>+
<age> ::= <digit>+

The symbols <ascii_uppercase_letter>, <ascii_lowercase_letter>, and <digits> are predefined in the Fandango Standard Library; they are defined exactly as would be expected.

Create or download a file persons.fan and run Fandango on it:

$ fandango fuzz -f persons.fan -n 10

Your output will look like this:

Nva Olqueq,32
Dlmqu Hplwsq,84
Zhlvfz Prgf,570
Gbobw Xj,29563
Cevuip Szrun,18
Eqrxw Vdk,15768
Ck Znmgz,8
Kxg Uyiww,2053
Bnvts Uhne,8876
Ld Fhd,28

Such random names are a typical result of fuzzing – that is, testing with randomly generated values. How do we get these into a program under test?

Feeding Inputs Into Programs

So far, we have had Fandango simply output the strings it generates. This is nice for understanding and debugging, but not necessarily useful for processing these inputs further. Fandango provides a number of means to help you process its output.

Feed Inputs into a Single file

Fandango has a -o option that directs its output into a single file. To store the generated strings in a file named persons.txt, use -o persons.txt:

$ fandango fuzz -f persons.fan -n 10 -o persons.txt

By default, the generated strings are separated by newlines. With the -s option, you can define an alternate separator. To have the outputs generated separated by :, for instance, use

$ fandango fuzz -f persons.fan -n 10 -o persons.txt -s ':'

Feed Inputs into Individual Files

With the -d option, Fandango can store its strings into individual files in the directory given after -d. They can then be picked up for post-processing. To store all outputs in a directory named persons, for instance, use -d persons:

$ fandango fuzz -f persons.fan -n 10 -d persons

Fandango will create the directory and store the inputs as Fandango-0001.txt, Fandango-0002.txt, etc.

Note

If the directory is already present, Fandango will use that directory.

Warning

Fandango will overwrite files Fandango-0001.txt, Fandango-0002.txt, etc., but leave other files in the directory unchanged.

If you want a different file extension (for instance, because .txt is not suitable), Fandango provides a --filename-extension option to set a different one.

Invoking Programs Directly

You can have Fandango invoke programs directly, and have Fandango feed them the generated inputs. The programs are specified as arguments on the command line.

There are two ways to pass the input into programs, on the command line and via standard input.

Passing Inputs on the Command Line

When Fandango invokes programs, you can pass input as a file name as last argument on the program’s command line. This is the default, and can also be obtained with the --input-method=filename option.

For instance, to test the wc program with its own -c option and the inputs Fandango generates, use

$ fandango fuzz -f persons.fan -n 10 wc -c

The wc program is then invoked as wc -c FILE_1, wc -c FILE_2, etc., where each FILE contains an individual input from Fandango.

Passing Inputs via Standard Input

As an alternative, Fandango can pass inputs via standard input. For this, use the --input-method=stdin option.

For instance, to test the cat program with its own -n option and the inputs Fandango generates, use

$ fandango fuzz -f persons.fan -n 10 --input-method=stdin cat -n

The cat program is then invoked repeatedly, each time passing a new Fandango-generated input as its standard input.

Executable .fan files

On a Unix system, you can turn a .fan file into an executable file by placing a line

#!/usr/bin/env fandango fuzz -f

at the top. If you set its “executable” flag with chmod +x FILE, you can then directly execute the .fan file as a command as if it were prefixed by fandango fuzz -f.

As an example, let us create a file fuzz-persons.fan:

$ (echo '#!/usr/bin/env fandango fuzz -f'; cat persons.fan) > fuzz-persons.fan
$ chmod +x fuzz-persons.fan

You can now invoke the file, even with extra arguments:

$ ./fuzz-persons.fan -n 1

/usr/bin/env: ‘fandango fuzz -f’: No such file or directory
/usr/bin/env: use -[v]S to pass options in shebang lines