diff options
| -rw-r--r-- | README.md | 218 | ||||
| -rw-r--r-- | docs/QuickStartGuide.md | 50 | ||||
| -rw-r--r-- | docs/cite.md | 23 | ||||
| -rw-r--r-- | docs/fuzzing.md | 32 | ||||
| -rw-r--r-- | docs/tools.md (renamed from docs/links_tools.md) | 2 | ||||
| -rw-r--r-- | docs/tutorials.md (renamed from docs/links_examples_writeups.md) | 2 |
6 files changed, 144 insertions, 183 deletions
diff --git a/README.md b/README.md index 7fb88740..f855c5b2 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file +* 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> \ No newline at end of file diff --git a/docs/QuickStartGuide.md b/docs/QuickStartGuide.md deleted file mode 100644 index 2d056ecf..00000000 --- a/docs/QuickStartGuide.md +++ /dev/null @@ -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. diff --git a/docs/cite.md b/docs/cite.md deleted file mode 100644 index 603616e5..00000000 --- a/docs/cite.md +++ /dev/null @@ -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, -} -``` \ No newline at end of file diff --git a/docs/fuzzing.md b/docs/fuzzing.md index b173847a..23b24ad0 100644 --- a/docs/fuzzing.md +++ b/docs/fuzzing.md @@ -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 diff --git a/docs/links_tools.md b/docs/tools.md index c544e18f..ba96d0ce 100644 --- a/docs/links_tools.md +++ b/docs/tools.md @@ -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. diff --git a/docs/links_examples_writeups.md b/docs/tutorials.md index 8f70045c..cc7ed130 100644 --- a/docs/links_examples_writeups.md +++ b/docs/tutorials.md @@ -1,4 +1,4 @@ -# Links: examples and writeups +# Tutorials Here are some good writeups to show how to effectively use AFL++: |