about summary refs log tree commit diff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--GNUmakefile6
-rw-r--r--README.md15
-rw-r--r--docs/INSTALL.md37
-rw-r--r--docs/fuzzing_binary-only_targets.md13
-rw-r--r--docs/fuzzing_in_depth.md24
-rw-r--r--docs/important_changes.md15
-rw-r--r--docs/resources/screenshot.pngbin117199 -> 144422 bytes
-rw-r--r--docs/tutorials.md4
8 files changed, 64 insertions, 50 deletions
diff --git a/GNUmakefile b/GNUmakefile
index 673d2bf8..a2c80261 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -345,9 +345,9 @@ performance-test:	source-only
 help:
 	@echo "HELP --- the following make targets exist:"
 	@echo "=========================================="
-	@echo "all: just the main afl++ binaries"
-	@echo "binary-only: everything for binary-only fuzzing: qemu_mode, frida_mode, unicorn_mode, coresight_mode, libdislocator, libtokencap"
-	@echo "source-only: everything for source code fuzzing: gcc_plugin, libdislocator, libtokencap"
+	@echo "all: the main afl++ binaries and llvm/gcc instrumentation"
+	@echo "binary-only: everything for binary-only fuzzing: frida_mode, qemu_mode, frida_mode, unicorn_mode, coresight_mode, libdislocator, libtokencap"
+	@echo "source-only: everything for source code fuzzing: libdislocator, libtokencap"
 	@echo "distrib: everything (for both binary-only and source code fuzzing)"
 	@echo "man: creates simple man pages from the help option of the programs"
 	@echo "install: installs everything you have compiled with the build option above"
diff --git a/README.md b/README.md
index 21724696..b01f6b86 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,8 @@ Here is some information to get you started:
 
 * For releases, see the
   [Releases tab](https://github.com/AFLplusplus/AFLplusplus/releases) and
-  [branches](#branches). Also take a look at the list of
+  [branches](#branches). The best branches to use are however `stable` or
+  `dev` - depending on your risk appetite. Also take a look at the list of
   [important changes in AFL++](docs/important_changes.md) and the list of
   [features](docs/features.md).
 * If you want to use AFL++ for your academic work, check the
@@ -115,11 +116,14 @@ Step-by-step quick start:
 
    You can generate cores or use gdb directly to follow up the crashes.
 
+6. We cannot stress this enough - if you want to fuzz effectively, read the
+   [docs/fuzzing_in_depth.md](docs/fuzzing_in_depth.md) document!
+
 ## Contact
 
 Questions? Concerns? Bug reports?
 
-* The contributors can be reached via
+* The contributors can be reached via (e.g. by creating an issue):
   [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
@@ -127,8 +131,9 @@ Questions? Concerns? Bug reports?
 * 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.
+  email to <afl-users+subscribe@googlegroups.com>, but note that this is not
+  managed by us.
+* Best: join the [Awesome Fuzzing](https://discord.gg/gCraWct) Discord server.
 
 ## Branches
 
@@ -141,7 +146,7 @@ The following branches exist:
   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!!*
+  or has a bug. **We only accept PRs to dev!**
 * (any other): experimental branches to work on specific features or testing new
   functionality or changes.
 
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 7f0d3df1..9d7a1c5b 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -33,10 +33,10 @@ sudo make install
 It is recommended to install the newest available gcc, clang and llvm-dev
 possible in your distribution!
 
-Note that "make distrib" also builds instrumentation, QEMU mode, unicorn_mode
-and more. If you just want plain AFL++, then do "make all". However, compiling
-and using at least instrumentation is highly recommended for much better results
-- hence in this case choose:
+Note that "make distrib" also builds FRIDA mode, QEMU mode, unicorn_mode
+and more. If you just want plain AFL++, then do "make all". If you want
+some assisting tooling compiled but are not interested in binary-only targets
+then instead choose:
 
 ```shell
 make source-only
@@ -44,11 +44,10 @@ make source-only
 
 These build targets exist:
 
-* all: just the main AFL++ binaries
-* binary-only: everything for binary-only fuzzing: qemu_mode, unicorn_mode,
-  libdislocator, libtokencap
-* source-only: everything for source code fuzzing: instrumentation,
-  libdislocator, libtokencap
+* all: the main afl++ binaries and llvm/gcc instrumentation
+* binary-only: everything for binary-only fuzzing: frida_mode, qemu_mode,
+  unicorn_mode, libdislocator, libtokencap
+* source-only: everything for source code fuzzing: libdislocator, libtokencap
 * distrib: everything (for both binary-only and source code fuzzing)
 * man: creates simple man pages from the help option of the programs
 * install: installs everything you have compiled with the build options above
@@ -86,19 +85,19 @@ e.g.: `make ASAN_BUILD=1`
 
 ## MacOS X on x86 and arm64 (M1)
 
-MacOS X should work, but there are some gotchas due to the idiosyncrasies of the
-platform. On top of this, we have limited release testing capabilities and
-depend mostly on user feedback.
+MacOS has some gotchas due to the idiosyncrasies of the platform.
 
 To build AFL, install llvm (and perhaps gcc) from brew and follow the general
 instructions for Linux. If possible, avoid Xcode at all cost.
 
-`brew install wget git make cmake llvm gdb coreutils`
+```shell
+brew install wget git make cmake llvm gdb coreutils
+```
 
 Be sure to setup `PATH` to point to the correct clang binaries and use the
 freshly installed clang, clang++, gmake and coreutils, e.g.:
 
-```
+```shell
 export
 PATH="/usr/local/Cellar/llvm/13.0.0_2/bin/:/usr/local/opt/coreutils/libexec/gnubin:/usr/local/bin:$PATH"
 export CC=clang
@@ -111,8 +110,10 @@ sudo gmake install
 ```
 
 `afl-gcc` will fail unless you have GCC installed, but that is using outdated
-instrumentation anyway. You don't want that. Note that `afl-clang-lto`,
-`afl-gcc-fast` and `qemu_mode` are not working on MacOS.
+instrumentation anyway. `afl-clang` might fail too depending on your PATH
+setup. But you don't want neither, you want `afl-clang-fast` anyway :)
+Note that `afl-clang-lto`, `afl-gcc-fast` and `qemu_mode` are not working on
+MacOS.
 
 The crash reporting daemon that comes by default with MacOS X will cause
 problems with fuzzing. You need to turn it off:
@@ -134,7 +135,7 @@ and definitely don't look POSIX-compliant. This means two things:
 
 User emulation mode of QEMU does not appear to be supported on MacOS X, so
 black-box instrumentation mode (`-Q`) will not work. However, Frida mode (`-O`)
-should work on x86 and arm64 MacOS boxes.
+works on both x86 and arm64 MacOS boxes.
 
 MacOS X supports SYSV shared memory used by AFL's instrumentation, but the
 default settings aren't usable with AFL++. The default settings on 10.14 seem to
@@ -170,4 +171,4 @@ sysctl kern.sysv.shmall=98304
 
 See
 [http://www.spy-hill.com/help/apple/SharedMemory.html](http://www.spy-hill.com/help/apple/SharedMemory.html)
-for documentation for these settings and how to make them permanent.
\ No newline at end of file
+for documentation for these settings and how to make them permanent.
diff --git a/docs/fuzzing_binary-only_targets.md b/docs/fuzzing_binary-only_targets.md
index 5434a22c..0f2f84f6 100644
--- a/docs/fuzzing_binary-only_targets.md
+++ b/docs/fuzzing_binary-only_targets.md
@@ -12,11 +12,10 @@ fuzzed with AFL++.
 
 ## TL;DR:
 
-QEMU mode in persistent mode is the fastest - if the stability is high enough.
-Otherwise, try RetroWrite, Dyninst, and if these fail, too, then try standard
-QEMU mode with `AFL_ENTRYPOINT` to where you need it.
-
-If your target is a library, then use FRIDA mode.
+FRIDA mode and QEMU mode in persistent mode are the fastest - if persistent mode
+is possible and the stability is high enough.
+Otherwise, try Zafl, RetroWrite, Dyninst, and if these fail, too, then try
+standard FRIDA/QEMU mode with `AFL_ENTRYPOINT` to where you need it.
 
 If your target is non-linux, then use unicorn_mode.
 
@@ -92,7 +91,7 @@ For more information, see
 ### FRIDA mode
 
 In FRIDA mode, you can fuzz binary-only targets as easily as with QEMU mode.
-FRIDA mode is sometimes faster and sometimes slower than QEMU mode. It is also
+FRIDA mode is most of the times slightly faster than QEMU mode. It is also
 newer, lacks COMPCOV, and has the advantage that it works on MacOS (both intel
 and M1).
 
@@ -100,7 +99,7 @@ To build FRIDA mode:
 
 ```shell
 cd frida_mode
-make
+gmake
 ```
 
 For additional instructions and caveats, see
diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md
index b280ca0a..2db6cfda 100644
--- a/docs/fuzzing_in_depth.md
+++ b/docs/fuzzing_in_depth.md
@@ -334,7 +334,7 @@ afl-clang-fast++ -fsanitize=fuzzer -o harness harness.cpp targetlib.a
 ```
 
 You can even use advanced libfuzzer features like `FuzzedDataProvider`,
-`LLVMFuzzerMutate()` etc. and they will work!
+`LLVMFuzzerInitialize()` etc. and they will work!
 
 The generated binary is fuzzed with afl-fuzz like any other fuzz target.
 
@@ -373,19 +373,19 @@ produce a new path/coverage in the target:
 
 1. Put all files from [step a](#a-collecting-inputs) into one directory, e.g., INPUTS.
 2. Run afl-cmin:
-   * If the target program is to be called by fuzzing as `bin/target -d
+   * If the target program is to be called by fuzzing as `bin/target
      INPUTFILE`, set the INPUTFILE argument that the target program would read
      from as `@@`:
 
      ```
-     afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -d @@
+     afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -someopt @@
      ```
 
    * If the target reads from stdin instead, just omit the `@@` as this is the
      default:
 
      ```
-     afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -d
+     afl-cmin -i INPUTS -o INPUTS_UNIQUE -- bin/target -someopt
      ```
 
 This step is highly recommended!
@@ -400,7 +400,7 @@ however, it is a long process as this has to be done for every file:
 mkdir input
 cd INPUTS_UNIQUE
 for i in *; do
-  afl-tmin -i "$i" -o "../input/$i" -- bin/target -d @@
+  afl-tmin -i "$i" -o "../input/$i" -- bin/target -someopt @@
 done
 ```
 
@@ -449,7 +449,7 @@ hence all you need is to specify the seed input directory with the result of
 step [2a) Collecting inputs](#a-collecting-inputs):
 
 ```
-afl-fuzz -i input -o output -- bin/target -d @@
+afl-fuzz -i input -o output -- bin/target -someopt @@
 ```
 
 Note that the directory specified with `-o` will be created if it does not
@@ -469,15 +469,19 @@ If you need to stop and re-start the fuzzing, use the same command line options
 mode!) and switch the input directory with a dash (`-`):
 
 ```
-afl-fuzz -i - -o output -- bin/target -d @@
+afl-fuzz -i - -o output -- bin/target -someopt @@
 ```
 
 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
+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.
+With `afl-clang-fast` you can set
+`AFL_LLVM_DICT2FILE=/full/path/to/new/file.dic` to automatically generate a
+dictionary during target compilation.
+You also have the option to generate 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
diff --git a/docs/important_changes.md b/docs/important_changes.md
index d5e67f75..facaf3c1 100644
--- a/docs/important_changes.md
+++ b/docs/important_changes.md
@@ -6,11 +6,16 @@ changes.
 ## From version 3.00 onwards
 
 With AFL++ 3.13-3.20, we introduce FRIDA mode (`-O`) to have an alternative for
-binary-only fuzzing. It is slower than QEMU mode but works on MacOS, Android,
-iOS etc.
+binary-only fuzzing. It is a bit faster than QEMU mode and works on MacOS,
+Android, iOS etc.
+
+With AFL++ 4.00, we introduced the following changes from previous behaviors:
+  * the complete documenation was overhauled and restructured thanks to @llzmb!
+  * a new CMPLOG target format requires recompiling CMPLOG targets for use
+    with afl++ 4.0 onwards
+  * better naming for several fields in the UI
 
 With AFL++ 3.15, we introduced the following changes from previous behaviors:
-  * Also -M main mode does not do deterministic fuzzing by default anymore
   * afl-cmin and afl-showmap -Ci now descent into subdirectories like afl-fuzz
     -i does (but note that afl-cmin.bash does not)
 
@@ -20,7 +25,7 @@ With AFL++ 3.14, we introduced the following changes from previous behaviors:
     however, does not)
 
 With AFL++ 3.10, we introduced the following changes from previous behaviors:
-  * The '+' feature of the '-t' option now means to  auto-calculate the timeout
+  * The '+' feature of the '-t' option now means to auto-calculate the timeout
     with the value given being the maximum timeout. The original meaning of
     "skipping timeouts instead of abort" is now inherent to the -t option.
 
@@ -55,4 +60,4 @@ behaviors and defaults:
     * -M mains do not perform trimming
   * examples/ got renamed to utils/
   * libtokencap/ libdislocator/ and qdbi_mode/ were moved to utils/
-  * afl-cmin/afl-cmin.bash now search first in PATH and last in AFL_PATH
\ No newline at end of file
+  * afl-cmin/afl-cmin.bash now search first in PATH and last in AFL_PATH
diff --git a/docs/resources/screenshot.png b/docs/resources/screenshot.png
index 7b4dd7e4..75b88287 100644
--- a/docs/resources/screenshot.png
+++ b/docs/resources/screenshot.png
Binary files differdiff --git a/docs/tutorials.md b/docs/tutorials.md
index ed8a7eec..4f6d913d 100644
--- a/docs/tutorials.md
+++ b/docs/tutorials.md
@@ -18,13 +18,13 @@ training, then we can highly recommend the following:
 If you are interested in fuzzing structured data (where you define what the
 structure is), these links have you covered:
 
-* Superion for AFL++:
-  [https://github.com/adrian-rt/superion-mutator](https://github.com/adrian-rt/superion-mutator)
 * libprotobuf for AFL++:
   [https://github.com/P1umer/AFLplusplus-protobuf-mutator](https://github.com/P1umer/AFLplusplus-protobuf-mutator)
 * libprotobuf raw:
   [https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator](https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator)
 * libprotobuf for old AFL++ API:
   [https://github.com/thebabush/afl-libprotobuf-mutator](https://github.com/thebabush/afl-libprotobuf-mutator)
+* Superion for AFL++:
+  [https://github.com/adrian-rt/superion-mutator](https://github.com/adrian-rt/superion-mutator)
 
 If you find other good ones, please send them to us :-)
\ No newline at end of file
generated by cgit-pink 1.4.1 (git 2.36.1) at 2025-06-05 05:01:41 +0000