Awesome

Killerbeez

Killerbeez is a modular fuzzing framework that aims to bring awesome tools together into a standard format.

Table of Contents

• Motivation
• Getting Started
• Windows
• Linux and Mac
• Documentation
• Troubleshooting

Motivation

Many fuzzing tools are "research-quality" code, which means they're difficult to incorporate with each other or make changes to short of forking. Killerbeez seeks to reduce the engineering effort required to bring these tools together. By writing things to a common API, we hope to encourage clean interfaces, which should discourage spaghetti code and make writing cross-platform tools easier.

Getting Started

We provide build instructions for Windows and Linux, and binaries for Windows. For instructions building Killerbeez from source, see the BUILD instructions. Currently only the standalone client is available, server coming soon!

Windows

Binary Releases

If you don't want to build the project from source, you can try the binary releases (though be warned they are likely out of date). They have been tested on the following operating systems.

You will also need to install the 2017 Microsoft Visual C++ Redistributable. Please note that if you are running Killerbeez on a 64-bit host, you will need to install both the 64-bit and the 32-bit versions of the redistributable.

• 64-Bit Redistributable Download
• 32-Bit Redistributable Download

[1] This is due to a compatibility problem with Windows 7 and DynamoRIO see this issue for more info.
[2] Experimental status means that most of the features are working as expected, and a few are not.

Quickstart and Examples

Fuzzing a simple test program:

REM Paste this into cmd.exe.
REM Assuming you: set WORKDIR=C:/killerbeez
REM Note: if using backslashes, they need to be escaped to be proper JSON.

cd %WORKDIR%/killerbeez/build/x64/Debug/killerbeez
echo {"path":"%WORKDIR%/killerbeez/corpus/test/test.exe","arguments":"@@"} > driver.json
fuzzer.exe -n 9 -s "%WORKDIR%/killerbeez/corpus/test/inputs/close.txt" ^
	-d driver.json file debug bit_flip

Successful output should look like

Wed Aug  8 18:27:08 2018 - INFO     - Logging Started
Wed Aug  8 18:27:09 2018 - CRITICAL - Found crashes
Wed Aug  8 18:27:09 2018 - INFO     - Ran 9 iterations in 1 seconds

Fuzzing Windows Media Player

Download a small video file you would like to use as a seed file (e.g. youtube-dl --format mp4 --output test.mp4 your-favorite-video). Be sure to replace the seed file argument -s with the path to the video file you just downloaded.

Note that because wmplayer.exe is a 32-bit executable you'll either need to use the 32-bit fuzzer.exe, or manually specify the path to the 32-bit winafl.dll with the instrumentation's winafl_dir option. Additionally, the -target_offset argument that is passed to the instrumentation will need to be updated depending on your Windows version. In this case we are just using the entry point of wmplayer.exe, below there is a table to use as reference but it is best to verify the entry point of your binary.

echo {"timeout":20} > driver.json
echo {"timeout":5000,"coverage_modules":["wmp.DLL"],"target_path":"C:\\Program Files (x86)\\Windows Media Player\\wmplayer.exe"} > instrumentation.json
fuzzer.exe -n 3 -s "C:\Users\user\Desktop\test.mp4" -d driver.json -i instrumentation.json wmp dynamorio nop

You may need to modify these parameters to match your environment. In order to speed up fuzzing, it may be useful to enable persistence mode. See PersistenceMode.md for instructions.

Linux and Mac

Once you've built Killerbeez following the BUILD instructions, you should be ready to change into the right directory and run the fuzzer. Here's an example of running it on a test program from our corpus.

# assuming that you're in $WORKDIR/build/killerbeez
cd ../build/killerbeez/
echo '{"path":"corpus/test-linux","arguments":"@@"}' > driver.json
./fuzzer -n 20 -s /bin/bash -d driver.json file return_code honggfuzz

If it ran correctly, you should see something like this:

Thu Jul 19 09:40:46 2018 - INFO     - Logging Started
Thu Jul 19 09:40:46 2018 - INFO     - Ran 20 iterations in 0 seconds

In the example above, we're using the file driver, the return_code instrumentation, and the honggfuzz mutator module. We are only going to do 20 executions and our seed file is /bin/bash, because why not?

The -d option are for the driver. We need to give it the path to our executable and the command line arguments, which in our case is just the filename, represented by "@@" here.

We don't need to specify any options for the mutator or the instrumentation, so we'll rely on default values instead. To see the options available, you can use the -h help flag. Some examples:

./fuzzer -h
./fuzzer -hd
./fuzzer -hi

Looking at the results in the "output" directory, we see that it didn't find any crashes, hangs or new paths. At first glance, it might seem like it didn't work. However, we were using the return_code instrumentation, which does not actually track code coverage, so it can not determine the execution path, thus it can't determine if a new path was hit. Instead, it just looks at the return code to determine if the process crashed or not. It's very efficient, however this is effectively dumb fuzzing. In order to track coverage on Linux, Killerbeez has support for Intel Processor Trace. See IPT.md for more details.

To see a crash, we can just change our seed file to be close to the file which will cause a crash. It's cheating, but it works well to demonstrate the importance of seed files as well as illustrating what the output of finding a crash looks like. The following commands assume you are still in the directory containing ./fuzzer.

# assuming that you're in $WORKDIR/build/killerbeez
echo "ABC@" > test1  # ABC@ is one bit different than ABCD, the crashing input
echo '{"path":"corpus/test-linux","arguments":"@@"}' > driver.json
./fuzzer -n 2000 -s ./test1 -d driver.json file return_code honggfuzz

Which should yield output similar to this:

Thu Jul 19 12:03:11 2018 - INFO     - Logging Started
Thu Jul 19 12:03:13 2018 - CRITICAL - Found crashes
Thu Jul 19 12:03:13 2018 - CRITICAL - Found crashes
Thu Jul 19 12:03:19 2018 - CRITICAL - Found crashes
Thu Jul 19 12:03:22 2018 - CRITICAL - Found crashes
Thu Jul 19 12:03:22 2018 - INFO     - Ran 2000 iterations in 11 seconds

Looking in the output/crashes folder, we can see the inputs which were found to crash this target and reproduce the crash manually.

$ ls output/crashes/
2B81D0C867F76051FD33D8690AA2AC68  5220E572A6F9DAAF522EF5C5698EAF4C  59F885D0289BE9A83E711C5E7CFCBE4D  ED5D34C74E59D16BD6D5B3683DB655C3
$ cat output/crashes/59F885D0289BE9A83E711C5E7CFCBE4D ; echo
ABCD
$ corpus/test-linux output/crashes/59F885D0289BE9A83E711C5E7CFCBE4D
Segmentation fault (core dumped)

Documentation

Documentation of the API can be found in the docs folder. It's written in LaTeX which can be used to generate a PDF, HTML, or various other formats. PDFs are also included so the documentation is easy to read for those who do not have a LaTeX typesetting environment set up.

Troubleshooting

Q: The target program doesn't start
A: Windows Media Player won't automatically play media the first time is run. There's a pop-up which requires you to configure some settings. Just run it manually once and you should be good to go after that.

Q: I'm getting an error about a pipe timing out
A: This is related to the instrumentation and the target taking too long to start up. If running it again doesn't work, try increasing the "timeout" on the -i argument and that should take care of it.

Still Having a Problem?

Please create an issue on GitHub and we will address it as soon as possible.

Have questions? Wanna chat?

Feel free to join the mailing list! Send a request to join to killerbeez-join@lists.grimm-co.com then post your questions to killerbeez@lists.grimm-co.com! We've also got #killerbeez on freenode, but it's pretty quiet.

License

This project is licensed under the UIUC License - see the LICENSE file for details. Some parts of this project have been included from other software and will be under different licenses, where marked.