American Fuzzy Lop plus plus (AFL++)

Release version: 5.03c

GitHub version: 5.03c

Repository: https://github.com/AFLplusplus/AFLplusplus

AFL++ is maintained by:

Marc "van Hauser" Heuse [email protected]
Dominik Maier [email protected]
Andrea Fioraldi [email protected]
Heiko "hexcoder-" Eissfeldt [email protected]
frida_mode is maintained by @Worksbutnottested

Originally developed by Michal "lcamtuf" Zalewski.

AFL++ is a superior fork to Google's AFL - more speed, more and better mutations, more and better instrumentation, custom module support, etc.

AFL++ is licensed under the AGPL-3.0-or-later, and it also contains files under the Apache-2.0 License. Everything compiled into a fuzzing harness is and will stay Apache 2.0 licensed. Each file states its own license in its SPDX-License-Identifier header — that is the license you must follow for that file. An optional commercial license is available for organizations that cannot use the AGPL (obtained by donating to a good cause — the project and its maintainers receive no money). See LICENSING.md for a plain-language overview and the License section below for details.

Getting started

Here is some information to get you started:

For an overview of the AFL++ documentation and a very helpful graphical guide, please visit docs/README.md.
To get you started with tutorials, go to docs/tutorials.md.
For releases, see the Releases tab and branches. The best branches to use are, however, stable or dev - depending on your risk appetite. Also take a look at the list of important changes in AFL++ and the list of features.
If you want to use AFL++ for your academic work, check the papers page on the website.
To cite our work, look at the Cite section.
For comparisons, use the fuzzbench aflplusplus setup, or use afl-clang-fast with AFL_LLVM_CMPLOG=1. You can find the aflplusplus default configuration on Google's fuzzbench.

Building and installing AFL++

To have AFL++ easily available with everything compiled, pull the image directly from the Docker Hub (available for both x86_64 and arm64):

docker pull aflplusplus/aflplusplus
docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus

This image is automatically published when a push to the stable branch happens (see branches). If you use the command above, you will find your target source code in /src in the container.

Note: you can also pull aflplusplus/aflplusplus:dev which is the most current development state of AFL++.

To build AFL++ yourself - which we recommend - continue at docs/INSTALL.md.

Quick start: Fuzzing with AFL++

NOTE: Before you start, please read about the common sense risks of fuzzing.

This is a quick start for fuzzing targets with the source code available. To read about the process in detail, see docs/fuzzing_in_depth.md.

To learn about fuzzing other targets, see:

Binary-only targets: docs/fuzzing_binary-only_targets.md
Network services: docs/best_practices.md#fuzzing-a-network-service
GUI programs: docs/best_practices.md#fuzzing-a-gui-program

Step-by-step quick start:

Compile the program or library to be fuzzed using afl-cc. A common way to do this would be:
```
CC=/path/to/afl-cc CXX=/path/to/afl-c++ ./configure --disable-shared
make clean all
```
Get a small but valid input file that makes sense to the program. When fuzzing verbose syntax (SQL, HTTP, etc.), create a dictionary as described in dictionaries/README.md, too.
If the program reads from stdin, run afl-fuzz like so:
```
./afl-fuzz -i seeds_dir -o output_dir -- \
/path/to/tested/program [...program's cmdline...]
```
To add a dictionary, add -x /path/to/dictionary.txt to afl-fuzz.

If the program takes input from a file, you can put @@ in the program's command line; AFL++ will put an auto-generated file name in there for you.
Investigate anything shown in red in the fuzzer UI by promptly consulting docs/afl-fuzz_approach.md#understanding-the-status-screen.
You will find found crashes and hangs in the subdirectories crashes/ and hangs/ in the -o output_dir directory. You can replay the crashes by feeding them to the target, e.g. if your target is using stdin:
```
cat output_dir/crashes/id:000000,* | /path/to/tested/program [...program's cmdline...]
```
You can generate cores or use gdb directly to follow up the crashes.
For coverage analysis of your fuzzing we recommend our partner tools cov-analysis (source-based coverage reports from a fuzzing corpus) and fuzz-reachability (static analysis of which functions a harness can reach, to tell actionable coverage gaps apart from dead code and to generate instrumentation allowlists)
We cannot stress this enough - if you want to fuzz effectively, read the docs/fuzzing_in_depth.md document!

Contact

Questions? Concerns? Bug reports?

The contributors can be reached via (e.g., by creating an issue - but only for AFL++ defects!): https://github.com/AFLplusplus/AFLplusplus.
Take a look at our FAQ and Best Practices.
Best: join the Fuzzing Zulip server!

Branches

The following branches exist:

release: the latest release
stable: stable state of AFL++ - it is synced from dev from time to time when we are satisfied with its stability. This is the default branch.
dev: development state of AFL++ - bleeding edge and you might catch a checkout which does not compile or has a bug. We only accept PRs (pull requests) for the 'dev' branch!
(any other): experimental branches to work on specific features or testing new functionality or changes.

AFLplusplus v5.03c