A Python interface to AFL, allowing for easy injection of testcases and other functionality.
Switch branches/tags
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin *snaps fingers* Sep 14, 2018
fuzzer Major py3k changes Aug 22, 2018
tests Major py3k changes Aug 22, 2018
.gitignore Add .gitignore Jan 28, 2016
.gitlab-ci.yml Trigger image builds on push Jul 9, 2016
.shellphuzz.ini Update shellphuzz letting it read the logging config Jun 15, 2017
.travis.yml travis... May 15, 2017
LICENSE Add standard BSD license Aug 20, 2016
README.md close #32 Sep 18, 2018
reqs.txt add shellphish-qemu to reqs Aug 23, 2016
setup.py add tqdm May 17, 2017
shellphuzz remove protocol_fuzz. what? closes #35 Dec 9, 2018



This module provides a Python wrapper for interacting with AFL (American Fuzzy Lop: http://lcamtuf.coredump.cx/afl/). It supports starting an AFL instance, adding slave workers, injecting and retrieving testcases, and checking various performance metrics. Shellphish used it in Mechanical Phish (our CRS for the Cyber Grand Challenge) to interact with AFL.


/!\ We recommend installing our Python packages in a Python virtual environment. That is how we do it, and you'll likely run into problems if you do it otherwise.

The fuzzer has some dependencies. First, here's a probably-incomplete list of debian packages that might be useful:

sudo apt-get install build-essential gcc-multilib libtool automake autoconf bison debootstrap debian-archive-keyring libtool-bin
sudo apt-get build-dep qemu

Then, the fuzzer also depends on shellphish-afl, which is a pip package that actually includes AFL:

pip install git+https://github.com/shellphish/shellphish-afl

That'll pull a ton of other stuff, compile qemu about 4 times, and set everything up. Then, install this fuzzer wrapper:

pip install git+https://github.com/shellphish/fuzzer


There are two ways of using this package. The easy way is to use the shellphuzz script, which allows you to specify various options, enable driller, etc. The script has explanations about its usage with --help.

A quick example:

# fuzz with 4 AFL cores
shellphuzz -i -c 4 /path/to/binary

# perform symbolic-assisted fuzzing with 4 AFL cores and 2 symbolic tracing (drilling) cores.
shellphuzz -i -c 4 -d 2 /path/to/binary

You can also use it programmatically, but we have no documentation for that. For now, import fuzzer or look at the shellphuz script and figure it out ;-)