1.88b

Makefile

@@ -14,7 +14,7 @@
 #
 
 PROGNAME    = afl
-VERSION     = 1.87b
+VERSION     = 1.88b
 
 PREFIX     ?= /usr/local
 BIN_PATH    = $(PREFIX)/bin

afl-fuzz.c

@@ -3697,6 +3697,11 @@ static void show_stats(void) {
 
   }
 
+  /* Honor AFL_EXIT_WHEN_DONE. */
+
+  if (!dumb_mode && cycles_wo_finds > 20 && !pending_not_fuzzed &&
+      getenv("AFL_EXIT_WHEN_DONE")) stop_soon = 1;
+
   /* If we're not on TTY, bail out. */
 
   if (not_on_tty) return;
@@ -3769,13 +3774,7 @@ static void show_stats(void) {
     if (cycles_wo_finds < 3) strcpy(tmp, cYEL); else
 
     /* No finds for a long time and no test cases to try. */
-
-    if (cycles_wo_finds > 20 && !pending_not_fuzzed) {
-
-      strcpy(tmp, cLGN);
-      if (getenv("AFL_EXIT_WHEN_DONE")) stop_soon = 1;
-
-    }
+    if (cycles_wo_finds > 20 && !pending_not_fuzzed) strcpy(tmp, cLGN);
 
     /* Default: cautiously OK to stop? */
     else strcpy(tmp, cLBL);

docs/ChangeLog

@@ -16,6 +16,13 @@ Not sure if you should upgrade? The lowest currently recommended version
 is 1.76b. If you're stuck on an earlier release, it's strongly advisable
 to get on with the times.
 
+--------------
+Version 1.88b:
+--------------
+
+  - Made AFL_EXIT_WHEN_DONE work in non-tty mode. Issue spotted by
+    Jacek Wielemborek.
+
 --------------
 Version 1.87b:
 --------------
@@ -24,6 +31,8 @@ Version 1.87b:
 
   - Fixed several typos spotted by Dominique Pelle.
 
+  - Revamped several parts of README.
+
 --------------
 Version 1.86b:
 --------------

docs/INSTALL

@@ -156,4 +156,7 @@ VirtualBox or so to run a hardware-accelerated Linux VM; it will run around
 me know.
 
 Although Android on x86 should theoretically work, the stock kernel has SHM
-support compiled out, so you will need to address this issue first.
+support compiled out, so you will need to address this issue first. It's
+possible that all you need is this:
+
+  https://github.com/pelya/android-shmem

docs/QuickStartGuide.txt

@@ -10,7 +10,8 @@ how to hit the ground running:
 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.
+   from stdin. When fuzzing a format that uses checksums, comment out the
+   checksum verification code, too.
 
    The program must crash properly when a fault is encountered. Watch out for
    custom SIGSEGV or SIGABRT handlers and background processes.

docs/README

@@ -69,7 +69,7 @@ Simplifying a bit, the overall algorithm can be summed up as:
   6) Go to 2.
 
 The discovered test cases are also periodically culled to eliminate ones that
-have been obsoleted by newer, higher-coverage finds, and undergo several other
+have been obsoleted by newer, higher-coverage finds; and undergo several other
 instrumentation-driven effort minimization steps.
 
 As a side result of the fuzzing process, the tool creates a small,
@@ -98,35 +98,34 @@ specifics of the build process, but a nearly-universal approach would be:
 $ CC=/path/to/afl/afl-gcc ./configure
 $ make clean all
 
-For C++ programs, one would also want to set CXX=/path/to/afl/afl-g++.
+For C++ programs, you'd would also want to set CXX=/path/to/afl/afl-g++.
 
-The clang wrappers (afl-clang and afl-clang++) are used in the same way; clang
-users can also leverage a higher-performance instrumentation mode described in
-llvm_mode/README.llvm.
+The clang wrappers (afl-clang and afl-clang++) can be used in the same way;
+clang users may opt to leverage a higher-performance instrumentation mode, too.
+This is described in llvm_mode/README.llvm.
 
-When testing libraries, you need to find or write a simple program that
-reads data from stdin or from a file and passes it to the tested library.
-In such a case, it is essential to link this executable either against a 
-static version of the instrumented library, or to make sure that the correct
-.so file is loaded at runtime (usually by setting LD_LIBRARY_PATH). The
-simplest option is just a static build, e.g.:
+When testing libraries, you need to find or write a simple program that reads
+data from stdin or from a file and passes it to the tested library. In such a
+case, it is essential to link this executable against a static version of the
+instrumented library, or to make sure that the correct .so file is loaded at
+runtime (usually by setting LD_LIBRARY_PATH). The simplest option is a static
+build, usually possible via:
 
 $ CC=/path/to/afl/afl-gcc ./configure --disable-shared
 
 Setting AFL_HARDEN=1 when calling 'make' will cause the CC wrapper to
 automatically enable code hardening options that make it easier to detect
-simple memory bugs. The cost of this is a <5% performance drop.
+simple memory bugs.
 
-When compiling programs with ASAN, see the notes_for_asan.txt file for
-important caveats.
+PS. ASAN users are advised to review notes_for_asan.txt file for important
+caveats.
 
 4) Instrumenting binary-only apps
 ---------------------------------
 
-When fuzzing closed-source programs that can't be easily recompiled with
-afl-gcc, the fuzzer offers experimental support for fast, on-the-fly
-instrumentation of black-box binaries. This is accomplished with a
-version of QEMU running in the lesser-known "user space emulation" mode.
+When source code is *NOT* available, the fuzzer offers experimental support for
+fast, on-the-fly instrumentation of black-box binaries. This is accomplished
+with a version of QEMU running in the lesser-known "user space emulation" mode.
 
 QEMU is a project separate from AFL, but you can conveniently build the
 feature by doing:
@@ -136,103 +135,101 @@ $ ./build_qemu_support.sh
 
 For additional instructions and caveats, see qemu_mode/README.qemu.
 
-The mode isn't free; compared to compile-time instrumentation, the fuzzing
-process will be approximately 2-5x slower; it is also less conductive to
-parallelization on multiple cores.
+The mode is approximately 2-5x slower than compile-time instrumentation, is
+less conductive to parallelization, and may have some other quirks.
 
 5) Choosing initial test cases
 ------------------------------
 
-To operate correctly, the fuzzer requires one or more starting file containing
-the typical input normally expected by the targeted application. There are
-two basic rules:
+To operate correctly, the fuzzer requires one or more starting file that
+contains a good example of the input data normally expected by the targeted
+application. There are two basic rules:
 
   - Keep the files small. Under 1 kB is ideal, although not strictly necessary.
-    For a discussion of why size *really* matters, see perf_tips.txt.
+    For a discussion of why size matters, see perf_tips.txt.
 
-  - Use multiple test cases only if they are fundamentally different from
-    each other. There is no point in using fifty different vacation photos to
-    fuzz an image library.
+  - Use multiple test cases only if they are functionally different from
+    each other. There is no point in using fifty different vacation photos
+    to fuzz an image library.
 
-You can find quite a few good examples of starting files in the testcases/
-subdirectory that comes with this tool.
+You can find many good examples of starting files in the testcases/ subdirectory
+that comes with this tool.
 
-If a large corpus of data is available for screening, you may want to use the
-afl-cmin utility to reject redundant files - ideally, with an aggressive
-timeout (-t); afl-showmap can be used to manually examine and compare execution
-traces, too.
+PS. If a large corpus of data is available for screening, you may want to use
+the afl-cmin utility to identify a subset of functionally distinct files that
+exercise different code paths in the target binary.
 
 6) Fuzzing binaries
 -------------------
 
-The fuzzing process itself is carried out by the afl-fuzz utility. The program
+The fuzzing process itself is carried out by the afl-fuzz utility. This program
 requires a read-only directory with initial test cases, a separate place to
 store its findings, plus a path to the binary to test.
 
-For programs that accept input directly from stdin, the usual syntax may be:
+For target binaries that accept input directly from stdin, the usual syntax is:
 
 $ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program [...params...]
 
 For programs that take input from a file, use '@@' to mark the location in
-the target program's command line where the input file name should go. The
-fuzzer will substitute this for you, say:
+the target's command line where the input file name should be placed. The
+fuzzer will substitute this for you:
 
 $ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@
 
 You can also use the -f option to have the mutated data written to a specific
 file. This is useful if the program expects a particular file extension or so.
 
-Non-instrumented binaries can be fuzzed in the QEMU mode by adding -Q in the
-command line. It is also possible to use the -n flag to run afl-fuzz in plain
-old non-guided mode. This gives you a fairly traditional fuzzer with a couple
-of nice testing strategies.
+Non-instrumented binaries can be fuzzed in the QEMU mode (add -Q in the command
+line) or in a traditional, blind-fuzzer mode (specify -n).
 
 You can use -t and -m to override the default timeout and memory limit for the
-executed process; this is seldom necessary, perhaps except for video decoders
-or compilers.
+executed process; rare examples of targets that may need these settings touched
+include compilers and video decoders.
 
-Tips for optimizing the performance of the process are discussed in
-perf_tips.txt. Note that the fuzzer starts by meticulously performing an array
-of deterministic fuzzing steps, which can take several days. If you want more
-traditional behavior akin to zzuf or honggfuzz, use the -d option to get quick
-but less systematic and less in-depth results right away.
+Tips for optimizing fuzzing performance are discussed in perf_tips.txt.
+
+Note that afl-fuzz starts by performing an array of deterministic fuzzing
+steps, which can take several days. If you want quick & dirty results right
+away, akin to zzuf or honggfuzz, add the -d option to the command line.
 
 7) Interpreting output
 ----------------------
 
-The fuzzing process will continue until you press Ctrl-C. See the
-status_screen.txt file for information on how to interpret the displayed stats
-and monitor the health of the process. At the *very* minimum, you want to allow
-the fuzzer to complete one queue cycle, which may take anywhere from a couple
-of hours to a week or so.
+See the status_screen.txt 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.
+
+The fuzzing process will continue until you press Ctrl-C. At minimum, you want
+to allow the fuzzer to complete one queue cycle, which may take anywhere from a
+couple of hours to a week or so.
 
 There are three subdirectories created within the output directory and updated
 in real time:
 
   - queue/   - test cases for every distinctive execution path, plus all the
-               starting files given by the user. This is, in effect, the
-               synthesized corpus mentioned in section 2.
-
-               If desired, you can use afl-cmin to shrink the corpus to a much
-               smaller size. This works by throwing away earlier inputs that
-               used to trigger unique behaviors in the past, but have been made
-               obsolete by better finds made by afl-fuzz later on.
+               starting files given by the user. This is the synthesized corpus
+               mentioned in section 2.
 
-  - hangs/   - unique test cases that cause the tested program to time out. Note
-               that the default timeouts are fairly aggressive (set at 5x the
-               average execution time) to keep things moving fast.
+               Before using this corpus for any other purposes, you can shrink
+               it to a smaller size using the afl-cmin tool. The tool will find
+               a smaller subset of files offering equivalent edge coverage.
 
   - crashes/ - unique test cases that cause the tested program to receive a
                fatal signal (e.g., SIGSEGV, SIGILL, SIGABRT). The entries are 
                grouped by the received signal.
 
+  - hangs/   - unique test cases that cause the tested program to time out. Note
+               that when default (aggressive) timeout settings are in effect,
+               this can be slightly noisy due to latency spikes and other
+               natural phenomena.
+
 Crashes and hangs are considered "unique" if the associated execution paths
 involve any state transitions not seen in previously-recorded faults. If a
 single bug can be reached in multiple ways, there will be some count inflation
 early in the process, but this should quickly taper off.
 
-The file names for crashes and hangs should let you correlate them with the
-parent, non-faulting queue entries. This should help with debugging.
+The file names for crashes and hangs are correlated with parent, non-faulting
+queue entries. This should help with debugging.
 
 When you can't reproduce a crash found by afl-fuzz, the most likely cause is
 that you are not setting the same memory limit as used by the tool. Try:
@@ -248,7 +245,7 @@ Any existing output directory can be also used to resume aborted jobs; try:
 $ ./afl-fuzz -i- -o existing_output_dir [...etc...]
 
 If you have gnuplot installed, you can also generate some pretty graphs for any
-active fuzzing task using 'afl-plot'. For an example of how this looks like,
+active fuzzing task using afl-plot. For an example of how this looks like,
 see http://lcamtuf.coredump.cx/afl/plot/.
 
 8) Parallelized fuzzing
@@ -426,6 +423,7 @@ bug reports, or patches from:
   Richo Healey                          Martijn Bogaard
   rc0r                                  Jonathan Foote
   Christian Holler                      Dominique Pelle
+  Jacek Wielemborek
 
 Thank you!
 

docs/env_variables.txt

@@ -28,7 +28,9 @@ tools make fairly broad use of environmental variables:
     - see notes_for_asan.txt.
 
     (You can also enable MSAN via AFL_USE_MSAN; ASAN and MSAN come with the
-    same gotchas; the modes are mutually exclusive.)
+    same gotchas; the modes are mutually exclusive. UBSAN and other exotic
+    sanitizers are not officially supported yet, but are easy to get to work
+    by hand.)
 
   - Setting AFL_CC, AFL_CXX, and AFL_AS lets you use alternate downstream
     compilation tools, rather than the default 'clang', 'gcc', or 'as' binaries

docs/historical_notes.txt

@@ -37,7 +37,7 @@ it off. You can still find its original documentation at:
   https://code.google.com/p/bunny-the-fuzzer/wiki/BunnyDoc
 
 There has been a fair amount of independent work, too. Most notably, a few
-weeks  earlier that year, Jared DeMott had a Defcon presentation about a
+weeks earlier that year, Jared DeMott had a Defcon presentation about a
 coverage-driven fuzzer that relied on coverage as a fitness function.
 
 Jared's approach was by no means identical to what afl-fuzz does, but it was in

docs/notes_for_asan.txt

@@ -8,7 +8,7 @@ Notes for using ASAN with afl-fuzz
 1) Short version
 ----------------
 
-ASAN on 64-bit systems uses a lot of memory in a way that can't be easily
+ASAN on 64-bit systems requests a lot of memory in a way that can't be easily
 distinguished from a misbehaving program bent on crashing your system.
 
 Because of this, fuzzing with ASAN is recommended only in four scenarios:
@@ -18,7 +18,7 @@ Because of this, fuzzing with ASAN is recommended only in four scenarios:
 
   - On 64-bit systems only if you can do one of the following:
 
-    - Compile the binary in 32-bit mode (gcc -m32 or so),
+    - Compile the binary in 32-bit mode (gcc -m32),
 
     - Precisely gauge memory needs using http://jwilk.net/software/recidivm .