From bd4ecd83b1e4126300475d5beb09b4a8327b045a Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Fri, 10 Sep 2021 15:35:29 +0200 Subject: Update README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index db6a70b5..eb99d9bd 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ You are free to copy, modify, and distribute AFL++ with attribution under the te 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 [major behaviour changes in AFL++](docs/behaviour_changes.md). +* 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 [important behaviour changes in AFL++](docs/important_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). @@ -66,7 +66,7 @@ A common way to do this would be: 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](../dictionaries/README.md), too. +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: @@ -82,7 +82,7 @@ When fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described i 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 +* 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 . * Or join the [Awesome Fuzzing](https://discord.gg/gCraWct) Discord server. -- cgit 1.4.1 From 82ef4a90b0ff12a297e1bc3f1c8256ae9ace4f25 Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Fri, 10 Sep 2021 21:37:55 +0200 Subject: Fix links --- README.md | 2 +- docs/best_practices.md | 2 +- docs/branches.md | 2 +- docs/fuzzing_expert.md | 2 +- docs/interpreting_output.md | 2 +- docs/known_limitations.md | 2 +- docs/life_pro_tips.md | 20 ++++++++++---------- docs/rpc_statsd.md | 2 +- docs/triaging_crashes.md | 2 +- 9 files changed, 18 insertions(+), 18 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index eb99d9bd..25e47ef2 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ You are free to copy, modify, and distribute AFL++ with attribution under the te 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 [important behaviour changes in AFL++](docs/important_changes.md). +* 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 [important changes in AFL++](docs/important_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). diff --git a/docs/best_practices.md b/docs/best_practices.md index 23fa237d..1521748a 100644 --- a/docs/best_practices.md +++ b/docs/best_practices.md @@ -59,7 +59,7 @@ which allows you to define network state with different type of data packets. 1. Use [llvm_mode](../instrumentation/README.llvm.md): afl-clang-lto (llvm >= 11) or afl-clang-fast (llvm >= 9 recommended). 2. Use [persistent mode](../instrumentation/README.persistent_mode.md) (x2-x20 speed increase). 3. Use the [AFL++ snapshot module](https://github.com/AFLplusplus/AFL-Snapshot-LKM) (x2 speed increase). -4. If you do not use shmem persistent mode, use `AFL_TMPDIR` to put the input file directory on a tempfs location, see [docs/env_variables.md](docs/env_variables.md). +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! [README.md:3.b) Using multiple cores/threads](../README.md#b-using-multiple-coresthreads). diff --git a/docs/branches.md b/docs/branches.md index 1e4ebbb2..81c73a0f 100644 --- a/docs/branches.md +++ b/docs/branches.md @@ -7,4 +7,4 @@ The following branches exist: * [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 [major behaviour changes in AFL++](behaviour_changes.md). \ No newline at end of file +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_expert.md index 23b24ad0..37ab8e2f 100644 --- a/docs/fuzzing_expert.md +++ b/docs/fuzzing_expert.md @@ -620,4 +620,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 [links_tools.md](links_tools.md). \ No newline at end of file +(some might be deprecated or unsupported), see [tools.md](tools.md). \ No newline at end of file diff --git a/docs/interpreting_output.md b/docs/interpreting_output.md index 54ad76df..364d2cf4 100644 --- a/docs/interpreting_output.md +++ b/docs/interpreting_output.md @@ -1,6 +1,6 @@ # Interpreting output -See the [docs/status_screen.md](docs/status_screen.md) file for information on +See the [status_screen.md](status_screen.md) file for information on how to interpret the displayed stats and monitor the health of the process. Be sure to consult this file especially if any UI elements are highlighted in red. diff --git a/docs/known_limitations.md b/docs/known_limitations.md index deb539e2..b5fc8446 100644 --- a/docs/known_limitations.md +++ b/docs/known_limitations.md @@ -15,7 +15,7 @@ Here are some of the most important caveats for AFL: To work around this, you can comment out the relevant checks (see utils/libpng_no_checksum/ for inspiration); if this is not possible, you can also write a postprocessor, one of the hooks of custom mutators. - See [docs/custom_mutators.md](docs/custom_mutators.md) on how to use + See [custom_mutators.md](custom_mutators.md) on how to use `AFL_CUSTOM_MUTATOR_LIBRARY` - There are some unfortunate trade-offs with ASAN and 64-bit binaries. This diff --git a/docs/life_pro_tips.md b/docs/life_pro_tips.md index 13ffcea0..e79bcafa 100644 --- a/docs/life_pro_tips.md +++ b/docs/life_pro_tips.md @@ -27,16 +27,16 @@ Run the bundled `afl-plot` utility to generate browser-friendly graphs. Check out the `fuzzer_stats` file in the AFL output dir or try `afl-whatsup`. ## Puzzled by something showing up in red or purple in the AFL UI? -It could be important - consult docs/status_screen.md right away! +It could be important - consult [status_screen.md](status_screen.md) right away! ## Know your target? Convert it to persistent mode for a huge performance gain! -Consult section #5 in README.llvm.md for tips. +Consult section #5 in [instrumentation/README.llvm.md](../instrumentation/README.llvm.md) for tips. ## Using clang? -Check out instrumentation/ for a faster alternative to afl-gcc! +Check out [instrumentation/](../instrumentation/) for a faster alternative to afl-gcc! ## Did you know that AFL can fuzz closed-source or cross-platform binaries? -Check out qemu_mode/README.md and unicorn_mode/README.md for more. +Check out [qemu_mode/README.md](../qemu_mode/README.md) and [unicorn_mode/README.md](../unicorn_mode/README.md) for more. ## Did you know that afl-fuzz can minimize any test case for you? Try the bundled `afl-tmin` tool - and get small repro files fast! @@ -46,7 +46,7 @@ Try the bundled `afl-tmin` tool - and get small repro files fast! ## Trouble dealing with a machine uprising? Relax, we've all been there. -Find essential survival tips at http://lcamtuf.coredump.cx/prep/. +Find essential survival tips at [http://lcamtuf.coredump.cx/prep/](http://lcamtuf.coredump.cx/prep/). ## Want to automatically spot non-crashing memory handling bugs? @@ -54,7 +54,7 @@ Try running an AFL-generated corpus through ASAN, MSAN, or Valgrind. ## Good selection of input files is critical to a successful fuzzing job. -See docs/perf_tips.md for pro tips. +See [perf_tips.md](perf_tips.md) for pro tips. ## You can improve the odds of automatically spotting stack corruption issues. @@ -70,18 +70,18 @@ sanity-checking `assert()` / `abort()` statements to effortlessly catch logic bu ## Hey kid... pssst... want to figure out how AFL really works? -Check out docs/technical_details.md for all the gory details in one place! +Check out [technical_details.md](technical_details.md) for all the gory details in one place! ## There's a ton of third-party helper tools designed to work with AFL! -Be sure to check out docs/sister_projects.md before writing your own. +Be sure to check out [sister_projects.md](sister_projects.md) before writing your own. ## Need to fuzz the command-line arguments of a particular program? -You can find a simple solution in utils/argv_fuzzing. +You can find a simple solution in [utils/argv_fuzzing](../utils/argv_fuzzing/). ## Attacking a format that uses checksums? Remove the checksum-checking code or use a postprocessor! -See `afl_custom_post_process` in custom_mutators/examples/example.c for more. +See `afl_custom_post_process` in [custom_mutators/examples/example.c](../custom_mutators/examples/example.c) for more. diff --git a/docs/rpc_statsd.md b/docs/rpc_statsd.md index 898ad099..efbd550b 100644 --- a/docs/rpc_statsd.md +++ b/docs/rpc_statsd.md @@ -41,7 +41,7 @@ To enable the StatsD reporting on your fuzzer instances, you need to set the env Setting `AFL_STATSD_TAGS_FLAVOR` to the provider of your choice will assign tags / labels to each metric based on their format. The possible values are `dogstatsd`, `librato`, `signalfx` or `influxdb`. -For more information on these env vars, check out `docs/env_variables.md`. +For more information on these env vars, check out [env_variables.md](env_variables.md). The simplest way of using this feature is to use any metric provider and change the host/port of your StatsD daemon, with `AFL_STATSD_HOST` and `AFL_STATSD_PORT`, if required (defaults are `localhost` and port `8125`). diff --git a/docs/triaging_crashes.md b/docs/triaging_crashes.md index 1857c4b1..21ccecaa 100644 --- a/docs/triaging_crashes.md +++ b/docs/triaging_crashes.md @@ -43,4 +43,4 @@ file, attempts to sequentially flip bytes, and observes the behavior of the tested program. It then color-codes the input based on which sections appear to be critical, and which are not; while not bulletproof, it can often offer quick insights into complex file formats. More info about its operation can be found -near the end of [docs/technical_details.md](docs/technical_details.md). \ No newline at end of file +near the end of [technical_details.md](technical_details.md). \ No newline at end of file -- cgit 1.4.1 From 65c94d914db9930eaae50c6d36bdcb4ed16ea908 Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Sun, 17 Oct 2021 20:29:24 +0200 Subject: Change line length to max. 80 characters --- README.md | 109 ++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 70 insertions(+), 39 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 9fe1da7e..575a6a1a 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,8 @@ Release version: [3.14c](https://github.com/AFLplusplus/AFLplusplus/releases) GitHub version: 3.15a -Repository: [https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) +Repository: +[https://github.com/AFLplusplus/AFLplusplus](https://github.com/AFLplusplus/AFLplusplus) AFL++ is maintained by: @@ -17,56 +18,74 @@ AFL++ is maintained by: 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. +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 terms of the Apache-2.0 License. See the [LICENSE](LICENSE) for details. +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 [important changes in AFL++](docs/important_changes.md). -* If you want to use AFL++ for your academic work, check the [papers page](https://aflplus.plus/papers/) on the website. +* 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 + [important changes in AFL++](docs/important_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). -* To get you started with tutorials, go to [docs/tutorials.md](docs/tutorials.md). +* 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 + [docs/tutorials.md](docs/tutorials.md). ## Building and installing AFL++ -To have AFL++ easily available with everything compiled, pull the image directly from the Docker Hub: +To have AFL++ easily available 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 ``` -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/INSTALL.md](docs/INSTALL.md). ## Quick start: Fuzzing with AFL++ -*NOTE: Before you start, please read about the [common sense risks of fuzzing](docs/common_sense_risks.md).* +*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 read about the process in detail, see [docs/fuzzing_expert.md](docs/fuzzing_expert.md). +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). 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) +* 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 quick start: -1. Compile the program or library to be fuzzed using `afl-cc`. -A common way to do this would be: +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](dictionaries/README.md), too. +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: @@ -77,42 +96,52 @@ When fuzzing verbose syntax (SQL, HTTP, etc), create a dictionary as described i 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 [docs/status_screen.md](docs/status_screen.md). +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 use gdb directly to follow up the crashes. +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 [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 . +* 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 . * 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. +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. +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. +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. +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 +:-)
@@ -171,7 +200,9 @@ Thank you! ## Cite -If you use AFL++ in scientific work, consider citing [our paper](https://www.usenix.org/conference/woot20/presentation/fioraldi) presented at WOOT'20: +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. -- cgit 1.4.1