American Fuzzy Lop plus plus (AFL++)

Release version: 5.00c

GitHub version: 5.01a

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

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

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

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

4. Investigate anything shown in red in the fuzzer UI by promptly consulting docs/afl-fuzz_approach.md#understanding-the-status-screen.

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

6. For coverage analysis of your fuzzing we recommend our partner tools cov-analysis

7. 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): https://github.com/AFLplusplus/AFLplusplus.
• Take a look at our FAQ. If you find an interesting or important question missing, submit it via https://github.com/AFLplusplus/AFLplusplus/discussions.
• Best: join the Fuzzing Zulip server.
• There is a (not really used) mailing list for the AFL/AFL++ project (browse archive). To compare notes with other users or to get notified about major new features, send an email to [email protected], but note that this is not managed by us.

Branches

The following branches exist:

• release: the latest release
• stable/trunk: stable state of AFL++ - it is synced from dev from time to time when we are satisfied with its stability
• 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.

Help wanted

Check out our issues list with the "help wanted" tag]. This can be your way to support and contribute to AFL++ - extend it to do something cool. If you have other ideas - just create an issue and propose it!

For everyone who wants to contribute (and send pull requests), please read our contributing guidelines before you submit.

Special thanks

Many of the improvements to the original AFL and AFL++ wouldn't be possible without feedback, bug reports, or patches from our contributors.

Thank you! (For people sending pull requests - please add yourself to this list :-)

    Jann Horn                             Hanno Boeck
    Felix Groebert                        Jakub Wilk
    Richard W. M. Jones                   Alexander Cherepanov
    Tom Ritter                            Hovik Manucharyan
    Sebastian Roschke                     Eberhard Mattes
    Padraig Brady                         Ben Laurie
    @dronesec                             Luca Barbato
    Tobias Ospelt                         Thomas Jarosch
    Martin Carpenter                      Mudge Zatko
    Joe Zbiciak                           Ryan Govostes
    Michael Rash                          William Robinet
    Jonathan Gray                         Filipe Cabecinhas
    Nico Weber                            Jodie Cunningham
    Andrew Griffiths                      Parker Thompson
    Jonathan Neuschaefer                  Tyler Nighswander
    Ben Nagy                              Samir Aguiar
    Aidan Thornton                        Aleksandar Nikolich
    Sam Hakim                             Laszlo Szekeres
    David A. Wheeler                      Turo Lamminen
    Andreas Stieger                       Richard Godbee
    Louis Dassy                           teor2345
    Alex Moneger                          Dmitry Vyukov
    Keegan McAllister                     Kostya Serebryany
    Richo Healey                          Martijn Bogaard
    rc0r                                  Jonathan Foote
    Christian Holler                      Dominique Pelle
    Jacek Wielemborek                     Leo Barnes
    Jeremy Barnes                         Jeff Trull
    Guillaume Endignoux                   ilovezfs
    Daniel Godas-Lopez                    Franjo Ivancic
    Austin Seipp                          Daniel Komaromy
    Daniel Binderman                      Jonathan Metzman
    Vegard Nossum                         Jan Kneschke
    Kurt Roeckx                           Marcel Boehme
    Van-Thuan Pham                        Abhik Roychoudhury
    Joshua J. Drake                       Toby Hutton
    Rene Freingruber                      Sergey Davidoff
    Sami Liedes                           Craig Young
    Andrzej Jackowski                     Daniel Hodson
    Nathan Voss                           Dominik Maier
    Andrea Biondo                         Vincent Le Garrec
    Khaled Yakdan                         Kuang-che Wu
    Josephine Calliotte                   Konrad Welc
    Thomas Rooijakkers                    David Carlier
    Ruben ten Hove                        Joey Jiao
    fuzzah                                @intrigus-lgtm
    Yaakov Saxon                          Sergej Schumilo
    Ziqiao Kong                           Ryan Berger
    Sangjun Park                          Scott Guest
    Fabian Keil

Cite

If you use AFL++ in scientific work, consider citing our paper presented at WOOT'20:

Andrea Fioraldi, Dominik Maier, Heiko Eißfeldt, and Marc Heuse. “AFL++: Combining incremental steps of fuzzing research”. In 14th USENIX Workshop on Offensive Technologies (WOOT 20). USENIX Association, Aug. 2020.

  @inproceedings {AFLplusplus-Woot20,
  author = {Andrea Fioraldi and Dominik Maier and Heiko Ei{\ss}feldt and Marc Heuse},
  title = {{AFL++}: Combining Incremental Steps of Fuzzing Research},
  booktitle = {14th {USENIX} Workshop on Offensive Technologies ({WOOT} 20)},
  year = {2020},
  publisher = {{USENIX} Association},
  month = aug,
  }

License

AFL++ is licensed under the GNU AGPL-3.0-or-later. In short, you can use AFL++ three ways:

1. Free, under the AGPL-3.0-or-later — the default. Use, modify, and share AFL++; if you run a modified version as a network service, the AGPL requires you to offer your users the corresponding source. Full text: LICENSE.

2. Per file, under the license in its header — the project contains files under both SPDX-License-Identifier: AGPL-3.0-or-later and SPDX-License-Identifier: Apache-2.0. Always check the header of the file you use and adhere to the license stated there; files marked Apache-2.0 may be reused individually under the Apache-2.0 License. (A few bundled third-party files carry other licenses, e.g. the GCC plugin under GPL-3.0-or-later and the LLVM SanitizerCoverage passes under Apache-2.0-WITH-LLVM-exception — each marked by its own SPDX identifier.) Note that the combined afl-fuzz binary includes AGPL files, so the program as a whole is AGPL.

3. Commercial license — optional, for organizations that cannot or do not want to comply with the AGPL. The project receives no money. Instead you donate EUR 20,000 (€20,000) to either the EFF or the CCC and email proof to [email protected]; your license is then effective from the donation date for one year (renewable by donating again). Full terms: LICENSE.COMMERCIAL.

Bundled third-party components (e.g. xxHash, t1ha, libFuzzer, submodules) keep their own licenses. For the complete plain-language overview, see LICENSING.md.