From dac1eeaa46dbb3e74e3189de910eeaec16f43b1a Mon Sep 17 00:00:00 2001 From: Thomas HUET Date: Fri, 28 Aug 2015 05:42:23 +0200 Subject: [PATCH] 1.88b --- Makefile | 2 +- afl-fuzz.c | 13 ++-- docs/ChangeLog | 9 +++ docs/INSTALL | 5 +- docs/QuickStartGuide.txt | 3 +- docs/README | 132 +++++++++++++++++++------------------- docs/env_variables.txt | 4 +- docs/historical_notes.txt | 2 +- docs/notes_for_asan.txt | 4 +- 9 files changed, 93 insertions(+), 81 deletions(-) diff --git a/Makefile b/Makefile index 333a8d03..db5e4622 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ # PROGNAME = afl -VERSION = 1.87b +VERSION = 1.88b PREFIX ?= /usr/local BIN_PATH = $(PREFIX)/bin diff --git a/afl-fuzz.c b/afl-fuzz.c index ad9da19f..e52b7caf 100644 --- a/afl-fuzz.c +++ b/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); diff --git a/docs/ChangeLog b/docs/ChangeLog index 742b883b..41f9eab8 100644 --- a/docs/ChangeLog +++ b/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: -------------- diff --git a/docs/INSTALL b/docs/INSTALL index 9c420a16..06844587 100644 --- a/docs/INSTALL +++ b/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 diff --git a/docs/QuickStartGuide.txt b/docs/QuickStartGuide.txt index 4efb9595..59752e6d 100644 --- a/docs/QuickStartGuide.txt +++ b/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. diff --git a/docs/README b/docs/README index 72753389..6dd048ff 100644 --- a/docs/README +++ b/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! diff --git a/docs/env_variables.txt b/docs/env_variables.txt index edf4b972..fac42a78 100644 --- a/docs/env_variables.txt +++ b/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 diff --git a/docs/historical_notes.txt b/docs/historical_notes.txt index 64955abf..741fd925 100644 --- a/docs/historical_notes.txt +++ b/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 diff --git a/docs/notes_for_asan.txt b/docs/notes_for_asan.txt index 42d48879..1ba83e61 100644 --- a/docs/notes_for_asan.txt +++ b/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 .