A distributed fuzzer which aims to pull in the best technologies, make them play nicely together, and run on multiple O/Ses.
Branch: master
Clone or download
anon8675309 Merge pull request #2 from bad2beef/feature/add_gui_process_modal_det…
…ection

Feature/add gui process modal detection
Latest commit 2b097b7 Jan 14, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
afl_progs Update AFL instrumentation and add the fork server to return_code ins… Nov 22, 2018
corpus Update AFL instrumentation and add the fork server to return_code ins… Nov 22, 2018
docs Updated the list of dependencies for Ubuntu and added the list of Fedora Dec 11, 2018
driver Fix pass of process handle Dec 22, 2018
fanart Added fanart May 4, 2018
fuzzer Add AFL style Instrumentations Nov 2, 2018
instrumentation Add wingui into build Dec 22, 2018
merger Update AFL instrumentation and add the fork server to return_code ins… Nov 22, 2018
picker Fix Linux build script Dec 11, 2018
python/manager Support linux machines as BOINC clients Nov 22, 2018
server Support linux machines as BOINC clients Nov 22, 2018
tests Update AFL instrumentation and add the fork server to return_code ins… Nov 22, 2018
tools Fix Linux build script Dec 11, 2018
tracer Update AFL instrumentation and add the fork server to return_code ins… Nov 22, 2018
winafl Made the includes more consistent with the angle-bracket vs quotes Jul 31, 2018
.gitattributes Initial source release Apr 11, 2018
.gitignore Update AFL instrumentation and add the fork server to return_code ins… Nov 22, 2018
.gitlab-ci.yml Fix Linux build script Dec 11, 2018
.gitmodules Add BOINC as a submodule Aug 2, 2018
APLv2 Initial source release Apr 11, 2018
CMakeLists.txt Fix Linux build script Dec 11, 2018
LICENSE Added name of the license to the LICENSE file to make it easier for p… Jul 19, 2018
Makefile Added Makefiles Dec 21, 2017
README.md Mac support Sep 14, 2018

README.md

Killerbeez

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

Table of Contents

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.

Windows Version 64-Bit 32-Bit
Windows 7 Not Working [1] Not Working [1]
Windows 8 Working Experimental [2]
Windows 8.1 Working Experimental [2]
Windows 10 Experimental [2] Experimental [2]

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.

[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%/build/x64/Debug/killerbeez
fuzzer.exe file debug bit_flip -n 9 ^
	-sf "%WORKDIR%/killerbeez/corpus/test/inputs/close.txt" ^
	-d "{\"path\":\"%WORKDIR%/killerbeez/corpus/test/test.exe\",\"arguments\":\"@@\"}"

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 -sf 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.

WMP Version Offset
12.0.7601 0x176D
12.0.9200 0x1BAD
12.0.9600 0x1F00
12.0.17134 0x1F20
fuzzer.exe wmp dynamorio nop -n 3 -sf "C:\Users\<user>\Desktop\test.mp4" -d "{\"timeout\":20}" -i "{\"timeout\":5000,\"coverage_modules\":[\"wmp.DLL\"],\"target_path\":\"C:\\Program Files (x86)\\Windows Media Player\\wmplayer.exe\"}"

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/
./fuzzer file return_code honggfuzz -n 20 -sf /bin/bash -d '{"path":"corpus/test-linux","arguments":"@@"}'

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 -h driver

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
./fuzzer file return_code honggfuzz -n 2000 -sf ./test1 -d '{"path":"corpus/test-linux","arguments":"@@"}'

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.