diff options
author | llzmb <46303940+llzmb@users.noreply.github.com> | 2021-11-20 15:48:49 +0100 |
---|---|---|
committer | llzmb <46303940+llzmb@users.noreply.github.com> | 2021-11-20 15:48:49 +0100 |
commit | 5ec859cece70ab1b5cd9e0356c4cc3e260d2cbe0 (patch) | |
tree | 865585edd6eb6ef5390bc66fa8b1453c42e23388 | |
parent | 581cb16965a2a6aa33c052afb936e5d4a5c65ad7 (diff) | |
download | afl++-5ec859cece70ab1b5cd9e0356c4cc3e260d2cbe0.tar.gz |
Clean up docs folder
-rw-r--r-- | README.md | 98 | ||||
-rw-r--r-- | docs/best_practices.md | 4 | ||||
-rw-r--r-- | docs/branches.md | 11 | ||||
-rw-r--r-- | docs/fuzzing_in_depth.md (renamed from docs/fuzzing_expert.md) | 6 | ||||
-rw-r--r-- | docs/limitations.md (renamed from docs/known_limitations.md) | 0 | ||||
-rw-r--r-- | docs/sister_projects.md | 319 | ||||
-rw-r--r-- | docs/third_party_tools.md (renamed from docs/tools.md) | 0 |
7 files changed, 60 insertions, 378 deletions
diff --git a/README.md b/README.md index 575a6a1a..b2714787 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Release version: [3.14c](https://github.com/AFLplusplus/AFLplusplus/releases) GitHub version: 3.15a -Repository: +Repository: [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) AFL++ is maintained by: @@ -18,33 +18,33 @@ AFL++ is maintained by: Originally developed by Michał "lcamtuf" Zalewski. -AFL++ is a superior fork to Google's AFL - more speed, more and better +AFL++ is a superior fork to Google's AFL - more speed, more and better mutations, more and better instrumentation, custom module support, etc. -You are free to copy, modify, and distribute AFL++ with attribution under the +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. ## Getting started Here is some information to get you started: -* 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 +* For releases, please see the + [Releases tab](https://github.com/AFLplusplus/AFLplusplus/releases) and + [branches](#branches). Also take a look at the list of [important changes in AFL++](docs/important_changes.md). -* If you want to use AFL++ for your academic work, check the +* 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 +* 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). -* To get you started with tutorials, go to +* To get you started with tutorials, go to [docs/tutorials.md](docs/tutorials.md). ## Building and installing AFL++ -To have AFL++ easily available with everything compiled, pull the image +To have AFL++ easily available with everything compiled, pull the image directly from the Docker Hub: ```shell @@ -52,39 +52,39 @@ 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 +This image is automatically generated when a push to the stable repo happens +(see [branches](#branches)). You will find your target source code in `/src` in the container. To build AFL++ yourself, continue at [docs/INSTALL.md](docs/INSTALL.md). ## Quick start: Fuzzing with AFL++ -*NOTE: Before you start, please read about the [common sense risks of +*NOTE: Before you start, please read about the [common sense risks of fuzzing](docs/common_sense_risks.md).* -This is a quick start for fuzzing targets with the source code available. To +This is a quick start for fuzzing targets with the source code available. To read about the process in detail, see -[docs/fuzzing_expert.md](docs/fuzzing_expert.md). +[docs/fuzzing_in_depth.md](docs/fuzzing_in_depth.md). To learn about fuzzing other targets, see: -* Binary-only targets: +* Binary-only targets: [docs/fuzzing_binary-only_targets.md](docs/fuzzing_binary-only_targets.md) -* Network services: +* Network services: [docs/best_practices.md#fuzzing-a-network-service](docs/best_practices.md#fuzzing-a-network-service) -* GUI programs: +* GUI programs: [docs/best_practices.md#fuzzing-a-gui-program](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 +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 +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. 3. If the program reads from stdin, run `afl-fuzz` like so: @@ -96,51 +96,63 @@ Step-by-step quick start: 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 + 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 +4. Investigate anything shown in red in the fuzzer UI by promptly consulting [docs/status_screen.md](docs/status_screen.md). -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.: `cat output_dir/crashes/id:000000,* | - /path/to/tested/program [...program's cmdline...]` You can generate cores or +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.: `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. ## Contact Questions? Concerns? Bug reports? -* The contributors can be reached via +* 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 +* 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 +* 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. +## Branches + +The following branches exist: + +* [release](https://github.com/AFLplusplus/AFLplusplus/tree/release): the latest release +* [stable/trunk](https://github.com/AFLplusplus/AFLplusplus/): stable state of AFL++ - it is synced from dev from time to time when we are satisfied with its stability +* [dev](https://github.com/AFLplusplus/AFLplusplus/tree/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 in dev!!* +* (any other): experimental branches to work on specific features or testing new functionality or changes. + +For releases, please see the [Releases tab](https://github.com/AFLplusplus/AFLplusplus/releases). +Also take a look at the list of [important changes in AFL++](docs/important_changes.md). + ## 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 +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 +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 +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 +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 +Thank you! (For people sending pull requests - please add yourself to this list :-) <details> @@ -200,8 +212,8 @@ Thank you! (For people sending pull requests - please add yourself to this list ## Cite -If you use AFL++ in scientific work, consider citing -[our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) +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. diff --git a/docs/best_practices.md b/docs/best_practices.md index 5d07dd14..7016f08d 100644 --- a/docs/best_practices.md +++ b/docs/best_practices.md @@ -48,7 +48,7 @@ to emulate the network. This is also much faster than the real network would be. See [utils/socket_fuzzing/](../utils/socket_fuzzing/). There is an outdated AFL++ branch that implements networking if you are -desperate though: [https://github.com/AFLplusplus/AFLplusplus/tree/networking](https://github.com/AFLplusplus/AFLplusplus/tree/networking) - +desperate though: [https://github.com/AFLplusplus/AFLplusplus/tree/networking](https://github.com/AFLplusplus/AFLplusplus/tree/networking) - however a better option is AFLnet ([https://github.com/aflnet/aflnet](https://github.com/aflnet/aflnet)) which allows you to define network state with different type of data packets. @@ -62,7 +62,7 @@ which allows you to define network state with different type of data packets. 4. If you do not use shmem persistent mode, use `AFL_TMPDIR` to put the input file directory on a tempfs location, see [env_variables.md](env_variables.md). 5. Improve Linux 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 less secure). 6. Running on an `ext2` filesystem with `noatime` mount option will be a bit faster than on any other journaling filesystem. -7. Use your cores! [fuzzing_expert.md:b) Using multiple cores](fuzzing_expert.md#b-using-multiple-cores). +7. Use your cores ([fuzzing_in_depth.md:b) Using multiple cores](fuzzing_in_depth.md#b-using-multiple-cores))! ### Improving stability diff --git a/docs/branches.md b/docs/branches.md deleted file mode 100644 index ae147b08..00000000 --- a/docs/branches.md +++ /dev/null @@ -1,11 +0,0 @@ -# Branches - -The following branches exist: - -* [release](https://github.com/AFLplusplus/AFLplusplus/tree/release): the latest release -* [stable/trunk](https://github.com/AFLplusplus/AFLplusplus/): stable state of AFL++ - it is synced from dev from time to time when we are satisfied with its stability -* [dev](https://github.com/AFLplusplus/AFLplusplus/tree/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 in dev!!* -* (any other): experimental branches to work on specific features or testing new functionality or changes. - -For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab. -Also take a look at the list of [important changes in AFL++](important_changes.md). \ No newline at end of file diff --git a/docs/fuzzing_expert.md b/docs/fuzzing_in_depth.md index 876c5fbb..5306cbef 100644 --- a/docs/fuzzing_expert.md +++ b/docs/fuzzing_in_depth.md @@ -247,7 +247,7 @@ For meson you have to set the AFL++ compiler with the very first command! Sometimes cmake and configure do not pick up the AFL++ compiler, or the ranlib/ar that is needed - because this was just not foreseen by the developer -of the target. Or they have non-standard options. Figure out if there is a +of the target. Or they have non-standard options. Figure out if there is a non-standard way to set this, otherwise set up the build normally and edit the generated build environment afterwards manually to point it to the right compiler (and/or ranlib and ar). @@ -337,7 +337,7 @@ Note that this step is rather optional though. #### Done! -The INPUTS_UNIQUE/ directory from step b) - or even better the directory input/ +The INPUTS_UNIQUE/ directory from step b) - or even better the directory input/ if you minimized the corpus in step c) - is the resulting input corpus directory to be used in fuzzing! :-) @@ -627,4 +627,4 @@ This is basically all you need to know to professionally run fuzzing campaigns. If you want to know more, the tons of texts in [docs/](./) will have you covered. Note that there are also a lot of tools out there that help fuzzing with AFL++ -(some might be deprecated or unsupported), see [tools.md](tools.md). \ No newline at end of file +(some might be deprecated or unsupported), see [third_party_tools.md](third_party_tools.md). \ No newline at end of file diff --git a/docs/known_limitations.md b/docs/limitations.md index a68c0a85..a68c0a85 100644 --- a/docs/known_limitations.md +++ b/docs/limitations.md diff --git a/docs/sister_projects.md b/docs/sister_projects.md deleted file mode 100644 index 613bc778..00000000 --- a/docs/sister_projects.md +++ /dev/null @@ -1,319 +0,0 @@ -# Sister projects - -This doc lists some of the projects that are inspired by, derived from, -designed for, or meant to integrate with AFL. See README.md for the general -instruction manual. - -!!! -!!! This list is outdated and needs an update, missing: e.g. Angora, FairFuzz -!!! - -## Support for other languages / environments: - -### Python AFL (Jakub Wilk) - -Allows fuzz-testing of Python programs. Uses custom instrumentation and its -own forkserver. - -https://jwilk.net/software/python-afl - -### Go-fuzz (Dmitry Vyukov) - -AFL-inspired guided fuzzing approach for Go targets: - -https://github.com/dvyukov/go-fuzz - -### afl.rs (Keegan McAllister) - -Allows Rust features to be easily fuzzed with AFL (using the LLVM mode). - -https://github.com/kmcallister/afl.rs - -### OCaml support (KC Sivaramakrishnan) - -Adds AFL-compatible instrumentation to OCaml programs. - -https://github.com/ocamllabs/opam-repo-dev/pull/23 -https://canopy.mirage.io/Posts/Fuzzing - -### AFL for GCJ Java and other GCC frontends (-) - -GCC Java programs are actually supported out of the box - simply rename -afl-gcc to afl-gcj. Unfortunately, by default, unhandled exceptions in GCJ do -not result in abort() being called, so you will need to manually add a -top-level exception handler that exits with SIGABRT or something equivalent. - -Other GCC-supported languages should be fairly easy to get working, but may -face similar problems. See https://gcc.gnu.org/frontends.html for a list of -options. - -## AFL-style in-process fuzzer for LLVM (Kostya Serebryany) - -Provides an evolutionary instrumentation-guided fuzzing harness that allows -some programs to be fuzzed without the fork / execve overhead. (Similar -functionality is now available as the "persistent" feature described in -[the llvm_mode readme](../instrumentation/README.llvm.md)) - -https://llvm.org/docs/LibFuzzer.html - -## TriforceAFL (Tim Newsham and Jesse Hertz) - -Leverages QEMU full system emulation mode to allow AFL to target operating -systems and other alien worlds: - -https://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2016/june/project-triforce-run-afl-on-everything/ - -## WinAFL (Ivan Fratric) - -As the name implies, allows you to fuzz Windows binaries (using DynamoRio). - -https://github.com/ivanfratric/winafl - -Another Windows alternative may be: - -https://github.com/carlosgprado/BrundleFuzz/ - -## Network fuzzing - -### Preeny (Yan Shoshitaishvili) - -Provides a fairly simple way to convince dynamically linked network-centric -programs to read from a file or not fork. Not AFL-specific, but described as -useful by many users. Some assembly required. - -https://github.com/zardus/preeny - -## Distributed fuzzing and related automation - -### roving (Richo Healey) - -A client-server architecture for effortlessly orchestrating AFL runs across -a fleet of machines. You don't want to use this on systems that face the -Internet or live in other untrusted environments. - -https://github.com/richo/roving - -### Distfuzz-AFL (Martijn Bogaard) - -Simplifies the management of afl-fuzz instances on remote machines. The -author notes that the current implementation isn't secure and should not -be exposed on the Internet. - -https://github.com/MartijnB/disfuzz-afl - -### AFLDFF (quantumvm) - -A nice GUI for managing AFL jobs. - -https://github.com/quantumvm/AFLDFF - -### afl-launch (Ben Nagy) - -Batch AFL launcher utility with a simple CLI. - -https://github.com/bnagy/afl-launch - -### AFL Utils (rc0r) - -Simplifies the triage of discovered crashes, start parallel instances, etc. - -https://github.com/rc0r/afl-utils - -### AFL crash analyzer (floyd) - -Another crash triage tool: - -https://github.com/floyd-fuh/afl-crash-analyzer - -### afl-extras (fekir) - -Collect data, parallel afl-tmin, startup scripts. - -https://github.com/fekir/afl-extras - -### afl-fuzzing-scripts (Tobias Ospelt) - -Simplifies starting up multiple parallel AFL jobs. - -https://github.com/floyd-fuh/afl-fuzzing-scripts/ - -### afl-sid (Jacek Wielemborek) - -Allows users to more conveniently build and deploy AFL via Docker. - -https://github.com/d33tah/afl-sid - -Another Docker-related project: - -https://github.com/ozzyjohnson/docker-afl - -### afl-monitor (Paul S. Ziegler) - -Provides more detailed and versatile statistics about your running AFL jobs. - -https://github.com/reflare/afl-monitor - -### FEXM (Security in Telecommunications) - -Fully automated fuzzing framework, based on AFL - -https://github.com/fgsect/fexm - -## Crash triage, coverage analysis, and other companion tools: - -### afl-crash-analyzer (Tobias Ospelt) - -Makes it easier to navigate and annotate crashing test cases. - -https://github.com/floyd-fuh/afl-crash-analyzer/ - -### Crashwalk (Ben Nagy) - -AFL-aware tool to annotate and sort through crashing test cases. - -https://github.com/bnagy/crashwalk - -### afl-cov (Michael Rash) - -Produces human-readable coverage data based on the output queue of afl-fuzz. - -https://github.com/mrash/afl-cov - -### afl-sancov (Bhargava Shastry) - -Similar to afl-cov, but uses clang sanitizer instrumentation. - -https://github.com/bshastry/afl-sancov - -### RecidiVM (Jakub Wilk) - -Makes it easy to estimate memory usage limits when fuzzing with ASAN or MSAN. - -https://jwilk.net/software/recidivm - -### aflize (Jacek Wielemborek) - -Automatically build AFL-enabled versions of Debian packages. - -https://github.com/d33tah/aflize - -### afl-ddmin-mod (Markus Teufelberger) - -A variant of afl-tmin that uses a more sophisticated (but slower) -minimization algorithm. - -https://github.com/MarkusTeufelberger/afl-ddmin-mod - -### afl-kit (Kuang-che Wu) - -Replacements for afl-cmin and afl-tmin with additional features, such -as the ability to filter crashes based on stderr patterns. - -https://github.com/kcwu/afl-kit - -## Narrow-purpose or experimental: - -### Cygwin support (Ali Rizvi-Santiago) - -Pretty self-explanatory. As per the author, this "mostly" ports AFL to -Windows. Field reports welcome! - -https://github.com/arizvisa/afl-cygwin - -### Pause and resume scripts (Ben Nagy) - -Simple automation to suspend and resume groups of fuzzing jobs. - -https://github.com/bnagy/afl-trivia - -### Static binary-only instrumentation (Aleksandar Nikolich) - -Allows black-box binaries to be instrumented statically (i.e., by modifying -the binary ahead of the time, rather than translating it on the run). Author -reports better performance compared to QEMU, but occasional translation -errors with stripped binaries. - -https://github.com/vanhauser-thc/afl-dyninst - -### AFL PIN (Parker Thompson) - -Early-stage Intel PIN instrumentation support (from before we settled on -faster-running QEMU). - -https://github.com/mothran/aflpin - -### AFL-style instrumentation in llvm (Kostya Serebryany) - -Allows AFL-equivalent instrumentation to be injected at compiler level. -This is currently not supported by AFL as-is, but may be useful in other -projects. - -https://code.google.com/p/address-sanitizer/wiki/AsanCoverage#Coverage_counters - -### AFL JS (Han Choongwoo) - -One-off optimizations to speed up the fuzzing of JavaScriptCore (now likely -superseded by LLVM deferred forkserver init - see README.llvm.md). - -https://github.com/tunz/afl-fuzz-js - -### AFL harness for fwknop (Michael Rash) - -An example of a fairly involved integration with AFL. - -https://github.com/mrash/fwknop/tree/master/test/afl - -### Building harnesses for DNS servers (Jonathan Foote, Ron Bowes) - -Two articles outlining the general principles and showing some example code. - -https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop -https://goo.gl/j9EgFf - -### Fuzzer shell for SQLite (Richard Hipp) - -A simple SQL shell designed specifically for fuzzing the underlying library. - -https://www.sqlite.org/src/artifact/9e7e273da2030371 - -### Support for Python mutation modules (Christian Holler) - -now integrated in AFL++, originally from here -https://github.com/choller/afl/blob/master/docs/mozilla/python_modules.txt - -### Support for selective instrumentation (Christian Holler) - -now integrated in AFL++, originally from here -https://github.com/choller/afl/blob/master/docs/mozilla/partial_instrumentation.txt - -### Syzkaller (Dmitry Vyukov) - -A similar guided approach as applied to fuzzing syscalls: - -https://github.com/google/syzkaller/wiki/Found-Bugs -https://github.com/dvyukov/linux/commit/33787098ffaaa83b8a7ccf519913ac5fd6125931 -https://events.linuxfoundation.org/sites/events/files/slides/AFL%20filesystem%20fuzzing%2C%20Vault%202016_0.pdf - - -### Kernel Snapshot Fuzzing using Unicornafl (Security in Telecommunications) - -https://github.com/fgsect/unicorefuzz - -### Android support (ele7enxxh) - -Based on a somewhat dated version of AFL: - -https://github.com/ele7enxxh/android-afl - -### CGI wrapper (floyd) - -Facilitates the testing of CGI scripts. - -https://github.com/floyd-fuh/afl-cgi-wrapper - -### Fuzzing difficulty estimation (Marcel Boehme) - -A fork of AFL that tries to quantify the likelihood of finding additional -paths or crashes at any point in a fuzzing job. - -https://github.com/mboehme/pythia diff --git a/docs/tools.md b/docs/third_party_tools.md index ba96d0ce..ba96d0ce 100644 --- a/docs/tools.md +++ b/docs/third_party_tools.md |