ExternalVendorCode/AFLplusplus
1
0
Fork 0
mirror of https://github.com/AFLplusplus/AFLplusplus.git synced 2025-06-10 09:11:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Edit README.md and related content

Browse Source 
Changes:
- Fix links.
- Add links.
- Restructure content.
This commit is contained in:
llzmb 2021-08-28 20:25:37 +02:00
parent 0c1dcadfb4
commit ec4cae448b
6 changed files with 144 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
README.md
View File

@ -19,129 +19,163 @@ Originally developed by Michał "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.
For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab. Also take a look at the list of [major behaviour changes in AFL++](docs/behaviour_changes.md).
If you want to use AFL++ for your academic work, check the [papers page](https://aflplus.plus/papers/) on the website.
To cite our work, look at [Cite.md](docs/cite.md).
For comparisons, use the fuzzbench `aflplusplus` setup, or use `afl-clang-fast` with `AFL_LLVM_CMPLOG=1`.
You are free to copy, modify, and distribute AFL++ with attribution under the terms of the Apache-2.0 License. See the [LICENSE](LICENSE) for details.
## Help wanted
## Getting started
We have several [to dos](TODO.md) and [ideas](docs/ideas.md) we would like to see in AFL++ to make it even better.
However, we already work on so many things that we do not have the time for all the big ideas.
Here is some information to get you started:
This can be your way to support and contribute to AFL++ - extend it to do something cool.
For everyone who wants to contribute (and send pull requests), please read our [contributing guidelines](CONTRIBUTING.md) before your submit.
Thank you to [everyone who contributed](#special-thanks).
* For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab and [branches](docs/branches.md). Also take a look at the list of [major behaviour changes in AFL++](docs/behaviour_changes.md).
* If you want to use AFL++ for your academic work, check the [papers page](https://aflplus.plus/papers/) on the website.
* To cite our work, look at the [Cite](#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](https://github.com/google/fuzzbench/tree/master/fuzzers/aflplusplus).
## Building and installing AFL++
To install AFL++ with everything compiled, use Docker:
* You can either use the [Dockerfile](Dockerfile) (which has gcc-10 and clang-11 - hence afl-clang-lto is available!)
* Or just pull directly from the Docker Hub:
To install AFL++ with everything compiled, pull the image directly from the Docker Hub:
```shell
docker pull aflplusplus/aflplusplus
docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus
```
```shell
docker pull aflplusplus/aflplusplus
docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus
```
This image is automatically generated when a push to the stable repo happens (see [docs/branches.md](docs/branches.md)).
You will find your target source code in `/src` in the container.
This image is automatically generated when a push to the stable repo happens (see [docs/branches.md](docs/branches.md)).
You will find your target source code in `/src` in the container.
To build AFL++ yourself, continue at [docs/building_installing.md](docs/building_installing.md).
## Quickstart: Fuzzing with AFL++
## Quick start: Fuzzing with AFL++
*NOTE: Before you start, please read about the [common sense risks of fuzzing](docs/common_sense_risks.md).*
This is a quickstart for fuzzing targets with the source code available.
This is a quick start for fuzzing targets with the source code available.
To read about the process in detail, see [docs/fuzzing.md](docs/fuzzing.md).
To learn about fuzzing other target, see:
To learn about fuzzing other targets, see:
* Binary-only targets: [docs/fuzzing_binary-only_targets.md](docs/fuzzing_binary-only_targets.md)
* Network services: [docs/best_practices.md#fuzzing-a-network-service](docs/best_practices.md#fuzzing-a-network-service)
* GUI programs: [docs/best_practices.md#fuzzing-a-gui-program](docs/best_practices.md#fuzzing-a-gui-program)
Step-by-step quickstart:
Step-by-step quick start:
*THIS SECTION IS WIP*
1. Compile the program or library to be fuzzed using `afl-cc`.
A common way to do this would be:
1. Instrumenting the target:
1. Selecting a compiler.
2. Instrumenting the target.
2. Preparing the fuzzing campaign.
3. Fuzzing the target:
1. Running afl-fuzz.
2. Stopping or restarting afl-fuzz or adding new seeds.
4. Monitoring.
1. Checking the status.
2. Checking the coverage.
5. Triaging crashes.
CC=/path/to/afl-cc CXX=/path/to/afl-c++ ./configure --disable-shared
make clean all
## Special thanks
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](../dictionaries/README.md), too.
Many of the improvements to the original AFL and AFL++ wouldn't be possible without feedback, bug reports, or patches from:
3. If the program reads from stdin, run `afl-fuzz` like so:
```
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
```
./afl-fuzz -i testcase_dir -o findings_dir -- \
/path/to/tested/program [...program's cmdline...]
Thank you!
(For people sending pull requests - please add yourself to this list :-)
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/status_screen.md](docs/status_screen.md).
## Contact
Questions? Concerns? Bug reports?
* The contributors can be reached via [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus).
* Take a look at our [FAQ](docs/faq.md). If you find an interesting or important question missing, submit it via
[https://github.com/AFLplusplus/AFLplusplus/discussions](https://github.com/AFLplusplus/AFLplusplus/discussions).
* There is a mailing list for the AFL/AFL++ project ([browse archive](https://groups.google.com/group/afl-users)). To compare notes with other users or to get notified about major new features, send an email to <afl-users+subscribe@googlegroups.com>.
* Or join the [Awesome Fuzzing](https://discord.gg/gCraWct) Discord server.
* Or join the [Awesome Fuzzing](https://discord.gg/gCraWct) Discord server.
## Help wanted
We have several [ideas](docs/ideas.md) we would like to see in AFL++ to make it even better.
However, we already work on so many things that we do not have the time for all the big ideas.
This can be your way to support and contribute to AFL++ - extend it to do something cool.
For everyone who wants to contribute (and send pull requests), please read our [contributing guidelines](CONTRIBUTING.md) before your 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 :-)
<details>
<summary>List of contributors</summary>
```
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
```
</details>
## Cite
If you use AFL++ in scientific work, consider citing [our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) 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.
<details>
<summary>BibTeX</summary>
```bibtex
@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,
}
```
</details>

50
docs/QuickStartGuide.md
View File

@ -1,50 +0,0 @@
# AFL quick start guide
You should read [README.md](../README.md) - it's pretty short. If you really can't, here's
how to hit the ground running:
1) Compile AFL with 'make'. If build fails, see [INSTALL.md](INSTALL.md) for tips.
2) Find or write a reasonably fast and simple program that takes data from
a file or stdin, processes it in a test-worthy way, then exits cleanly.
If testing a network service, modify it to run in the foreground and read
from stdin. When fuzzing a format that uses checksums, comment out the
checksum verification code, too.
If this is not possible (e.g. in -Q(emu) mode) then use
AFL_CUSTOM_MUTATOR_LIBRARY to calculate the values with your own library.
The program must crash properly when a fault is encountered. Watch out for
custom SIGSEGV or SIGABRT handlers and background processes. For tips on
detecting non-crashing flaws, see section 11 in [README.md](README.md) .
3) Compile the program / 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
4) 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.
5) If the program reads from stdin, run 'afl-fuzz' like so:
./afl-fuzz -i testcase_dir -o findings_dir -- \
/path/to/tested/program [...program's cmdline...]
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.
6) Investigate anything shown in red in the fuzzer UI by promptly consulting
[status_screen.md](status_screen.md).
8) There is a basic docker build with 'docker build -t aflplusplus .'
That's it. Sit back, relax, and - time permitting - try to skim through the
following files:
- README.md - A general introduction to AFL,
- docs/perf_tips.md - Simple tips on how to fuzz more quickly,
- docs/status_screen.md - An explanation of the tidbits shown in the UI,
- docs/parallel_fuzzing.md - Advice on running AFL on multiple cores.

23
docs/cite.md
View File

@ -1,23 +0,0 @@
# Cite
If you use AFLpluplus to compare to your work, please use either `afl-clang-lto`
or `afl-clang-fast` with `AFL_LLVM_CMPLOG=1` for building targets and
`afl-fuzz` with the command line option `-l 2` for fuzzing.
The most effective setup is the `aflplusplus` default configuration on Google's [fuzzbench](https://github.com/google/fuzzbench/tree/master/fuzzers/aflplusplus).
If you use AFLplusplus in scientific work, consider citing [our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) 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.
Bibtex:
```bibtex
@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,
}
```

32
docs/fuzzing.md
View File

@ -51,9 +51,9 @@ anything below 9 is not recommended.
Clickable README links for the chosen compiler:
* [LTO mode - afl-clang-lto](instrumentation/README.lto.md)
* [LLVM mode - afl-clang-fast](instrumentation/README.llvm.md)
* [GCC_PLUGIN mode - afl-gcc-fast](instrumentation/README.gcc_plugin.md)
* [LTO mode - afl-clang-lto](../instrumentation/README.lto.md)
* [LLVM mode - afl-clang-fast](../instrumentation/README.llvm.md)
* [GCC_PLUGIN mode - afl-gcc-fast](../instrumentation/README.gcc_plugin.md)
* GCC/CLANG modes (afl-gcc/afl-clang) have no README as they have no own features
You can select the mode for the afl-cc compiler by:
@ -79,7 +79,7 @@ The following options are available when you instrument with LTO mode (afl-clang
and large input corpus. This technique is called laf-intel or COMPCOV.
To use this set the following environment variable before compiling the
target: `export AFL_LLVM_LAF_ALL=1`
You can read more about this in [instrumentation/README.laf-intel.md](instrumentation/README.laf-intel.md)
You can read more about this in [instrumentation/README.laf-intel.md](../instrumentation/README.laf-intel.md)
* A different technique (and usually a better one than laf-intel) is to
instrument the target so that any compare values in the target are sent to
AFL++ which then tries to put these values into the fuzzing data at different
@ -91,7 +91,7 @@ The following options are available when you instrument with LTO mode (afl-clang
via the `-c` parameter.
Note that you can compile also just a cmplog binary and use that for both
however there will be a performance penality.
You can read more about this in [instrumentation/README.cmplog.md](instrumentation/README.cmplog.md)
You can read more about this in [instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md)
If you use LTO, LLVM or GCC_PLUGIN mode (afl-clang-fast/afl-clang-lto/afl-gcc-fast)
you have the option to selectively only instrument parts of the target that you
@ -108,16 +108,16 @@ are interested in:
default to instrument unless noted (DENYLIST) or not perform instrumentation
unless requested (ALLOWLIST).
**NOTE:** During optimization functions might be inlined and then would not match!
See [instrumentation/README.instrument_list.md](instrumentation/README.instrument_list.md)
See [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md)
There are many more options and modes available however these are most of the
time less effective. See:
* [instrumentation/README.ctx.md](instrumentation/README.ctx.md)
* [instrumentation/README.ngram.md](instrumentation/README.ngram.md)
* [instrumentation/README.ctx.md](../instrumentation/README.ctx.md)
* [instrumentation/README.ngram.md](../instrumentation/README.ngram.md)
AFL++ performs "never zero" counting in its bitmap. You can read more about this
here:
* [instrumentation/README.neverzero.md](instrumentation/README.neverzero.md)
* [instrumentation/README.neverzero.md](../instrumentation/README.neverzero.md)
#### c) Sanitizers
@ -225,7 +225,7 @@ For `configure` build systems this is usually done by:
Note that if you are using the (better) afl-clang-lto compiler you also have to
set AR to llvm-ar[-VERSION] and RANLIB to llvm-ranlib[-VERSION] - as is
described in [instrumentation/README.lto.md](instrumentation/README.lto.md).
described in [instrumentation/README.lto.md](../instrumentation/README.lto.md).
##### cmake
@ -234,7 +234,7 @@ For `cmake` build systems this is usually done by:
Note that if you are using the (better) afl-clang-lto compiler you also have to
set AR to llvm-ar[-VERSION] and RANLIB to llvm-ranlib[-VERSION] - as is
described in [instrumentation/README.lto.md](instrumentation/README.lto.md).
described in [instrumentation/README.lto.md](../instrumentation/README.lto.md).
##### meson
@ -260,7 +260,7 @@ This variant requires the usage of afl-clang-lto, afl-clang-fast or afl-gcc-fast
It is the so-called `persistent mode`, which is much, much faster but
requires that you code a source file that is specifically calling the target
functions that you want to fuzz, plus a few specific AFL++ functions around
it. See [instrumentation/README.persistent_mode.md](instrumentation/README.persistent_mode.md) for details.
it. See [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md) for details.
Basically if you do not fuzz a target in persistent mode then you are just
doing it for a hobby and not professionally :-).
@ -281,7 +281,7 @@ The generated binary is fuzzed with afl-fuzz like any other fuzz target.
Bonus: the target is already optimized for fuzzing due to persistent mode and
shared-memory testcases and hence gives you the fastest speed possible.
For more information see [utils/aflpp_driver/README.md](utils/aflpp_driver/README.md)
For more information see [utils/aflpp_driver/README.md](../utils/aflpp_driver/README.md)
### 2. Preparing the fuzzing campaign
@ -394,12 +394,12 @@ out of memory. You can decrease the memory with the `-m` option, the value is
in MB. If this is too small for the target, you can usually see this by
afl-fuzz bailing with the message that it could not connect to the forkserver.
Adding a dictionary is helpful. See the directory [dictionaries/](dictionaries/) if
Adding a dictionary is helpful. See the directory [dictionaries/](../dictionaries/) if
something is already included for your data format, and tell afl-fuzz to load
that dictionary by adding `-x dictionaries/FORMAT.dict`. With afl-clang-lto
you have an autodictionary generation for which you need to do nothing except
to use afl-clang-lto as the compiler. You also have the option to generate
a dictionary yourself, see [utils/libtokencap/README.md](utils/libtokencap/README.md).
a dictionary yourself, see [utils/libtokencap/README.md](../utils/libtokencap/README.md).
afl-fuzz has a variety of options that help to workaround target quirks like
specific locations for the input file (`-f`), performing deterministic
@ -604,7 +604,7 @@ switch or honggfuzz.
#### h) Improve the speed!
* Use [persistent mode](instrumentation/README.persistent_mode.md) (x2-x20 speed increase)
* Use [persistent mode](../instrumentation/README.persistent_mode.md) (x2-x20 speed increase)
* If you do not use shmem persistent mode, use `AFL_TMPDIR` to point the input file on a tempfs location, see [env_variables.md](env_variables.md)
* Linux: Improve kernel performance: modify `/etc/default/grub`, set `GRUB_CMDLINE_LINUX_DEFAULT="ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off spectre_v2=off stf_barrier=off"`; then `update-grub` and `reboot` (warning: makes the system more insecure) - you can also just run `sudo afl-persistent-config`
* Linux: Running on an `ext2` filesystem with `noatime` mount option will be a bit faster than on any other journaling filesystem

2
docs/links_tools.md → docs/tools.md
View File

@ -1,4 +1,4 @@
# Links: tools that help fuzzing with AFL++
# Tools that help fuzzing with AFL++
Speeding up fuzzing:
* [libfiowrapper](https://github.com/marekzmyslowski/libfiowrapper) - if the function you want to fuzz requires loading a file, this allows using the shared memory testcase feature :-) - recommended.

2
docs/links_examples_writeups.md → docs/tutorials.md
View File

@ -1,4 +1,4 @@
# Links: examples and writeups
# Tutorials
Here are some good writeups to show how to effectively use AFL++: