From b4cd555991637a9b55e401f7bbcc751c68d6f2bf Mon Sep 17 00:00:00 2001 From: Thomas HUET Date: Wed, 26 Aug 2015 05:42:19 +0200 Subject: [PATCH] 1.87b --- Makefile | 3 +- QuickStartGuide.txt | 1 + afl-cmin | 6 +-- docs/ChangeLog | 8 ++++ docs/INSTALL | 4 +- docs/QuickStartGuide.txt | 47 +++++++++++++++++++++++ docs/README | 80 ++++++++++++++++++++-------------------- docs/sister_projects.txt | 1 - docs/status_screen.txt | 8 ++-- 9 files changed, 106 insertions(+), 52 deletions(-) create mode 120000 QuickStartGuide.txt create mode 100644 docs/QuickStartGuide.txt diff --git a/Makefile b/Makefile index 7d5a29ff..333a8d03 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ # PROGNAME = afl -VERSION = 1.86b +VERSION = 1.87b PREFIX ?= /usr/local BIN_PATH = $(PREFIX)/bin @@ -132,4 +132,5 @@ publish: clean cat docs/historical_notes.txt >~/www/afl/historical_notes.txt cat docs/technical_details.txt >~/www/afl/technical_details.txt cat docs/ChangeLog >~/www/afl/ChangeLog.txt + cat docs/QuickStartGuide.txt >~/www/afl/QuickStartGuide.txt echo -n "$(VERSION)" >~/www/afl/version.txt diff --git a/QuickStartGuide.txt b/QuickStartGuide.txt new file mode 120000 index 00000000..e1687eb5 --- /dev/null +++ b/QuickStartGuide.txt @@ -0,0 +1 @@ +docs/QuickStartGuide.txt \ No newline at end of file diff --git a/afl-cmin b/afl-cmin index 0faa102e..16e98a6c 100755 --- a/afl-cmin +++ b/afl-cmin @@ -18,11 +18,11 @@ # the starting corpus. This has two uses: # # - Screening large corpora of input files before using them as a seed for -# seed for afl-fuzz. The tool effectively reject functionally redundant -# files and likely leave you with a much smaller set. +# seed for afl-fuzz. The tool will remove functionally redundant files and +# likely leave you with a much smaller set. # # (In this case, you probably also want to consider running afl-tmin on -# the individual files to reduce their size.) +# the individual files later on to reduce their size.) # # - Minimizing the corpus generated organically by afl-fuzz, perhaps when # planning to feed it to more resource-intensive tools. The tool achieves diff --git a/docs/ChangeLog b/docs/ChangeLog index e56e8602..742b883b 100644 --- a/docs/ChangeLog +++ b/docs/ChangeLog @@ -16,6 +16,14 @@ 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.87b: +-------------- + + - Added QuickStartGuide.txt, a one-page quick start doc. + + - Fixed several typos spotted by Dominique Pelle. + -------------- Version 1.86b: -------------- diff --git a/docs/INSTALL b/docs/INSTALL index 90ce4e8e..9c420a16 100644 --- a/docs/INSTALL +++ b/docs/INSTALL @@ -13,8 +13,8 @@ This platform is expected to work well. Compile the program with: $ make -You can starting using the fuzzer without installation, but it is also possible -to install it with: +You can start using the fuzzer without installation, but it is also possible to +install it with: # make install diff --git a/docs/QuickStartGuide.txt b/docs/QuickStartGuide.txt new file mode 100644 index 00000000..4efb9595 --- /dev/null +++ b/docs/QuickStartGuide.txt @@ -0,0 +1,47 @@ +===================== +AFL quick start guide +===================== + +You should read docs/README. It's pretty short. If you really can't, here's +how to hit the ground running: + +1) Compile AFL with 'make'. If build fails, see docs/INSTALL for tips. + +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. + + The program must crash properly when a fault is encountered. Watch out for + custom SIGSEGV or SIGABRT handlers and background processes. + +3) Compile the program / library to be fuzzed using afl-gcc. A common way to + do this would be: + + CC=/path/to/afl-gcc CXX=/path/to/afl-g++ ./configure --disable-shared + make clean all + + If program build fails, ping . + +4) 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 + testcases/README.testcases, too. + +5) If the program reads from stdin, run 'afl-fuzz' like so: + + ./afl-fuzz -i testcase_dir -o findings_dir -- \ + /path/to/tested/program [...program's cmdline...] + + 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. + +6) Investigate anything shown in red in the fuzzer UI by promptly consulting + docs/status_screen.txt. + +That's it. Sit back, relax, and - time permitting - try to skim through the +following files: + + - docs/README - A general introduction to AFL, + - docs/perf_tips.txt - Simple tips on how to fuzz more quickly, + - docs/status_screen.txt - An explanation of the tidbits shown in the UI, + - docs/parallel_fuzzing.txt - Advice on running AFL on multiple cores. diff --git a/docs/README b/docs/README index f0a5ae04..72753389 100644 --- a/docs/README +++ b/docs/README @@ -13,6 +13,8 @@ american fuzzy lop To compare notes with other users or get notified about major new features, send a mail to . + ** See QuickStartGuide.txt if you don't have time to read this file. ** + 1) Challenges of guided fuzzing ------------------------------- @@ -21,34 +23,32 @@ security issues in real-world software; it is responsible for the vast majority of remote code execution and privilege escalation bugs found to date in security-critical software. -Unfortunately, fuzzing also offers fairly shallow coverage, because many of the -mutations needed to reach new code paths are exceedingly unlikely to be hit -purely by chance. - -There have been numerous attempts to solve this problem by augmenting the -process with additional information about the behavior of the tested code, -ranging from simple corpus distillation, to flow analysis (aka "concolic" -execution), to pure symbolic execution, to static analysis. - -The first method on that list has been demonstrated to work well, but depends -on the availability of a massive, high-quality corpus of valid input data. On -top of this, coverage measurements provide only a fairly simplistic view of -program state, making them less suited for guiding the fuzzing process later on. - -The remaining techniques are extremely promising in experimental settings, but -frequently suffer from reliability problems or irreducible complexity. Most of -the high-value targets have enough internal states and possible execution paths -to make such tools fall apart and perform strictly worse than their traditional -counterparts, at least until fine-tuned with utmost care. +Unfortunately, fuzzing is also relatively shallow; blind, random mutations +make it very unlikely to reach certain code paths in the tested code, leaving +some vulnerabilities firmly outside the reach of this technique. + +There have been numerous attempts to solve this problem. One of the early +approaches - pioneered by Tavis Ormandy - is corpus distillation. The method +relies on coverage signals to select a subset of interesting seeds from a +massive, high-quality corpus of candidate files, and then fuzz them by +traditional means. The approach works exceptionally well, but requires such +a corpus to be readily available. In addition, block coverage measurements +provide only a very simplistic understanding of program state, and are less +useful for guiding the fuzzing effort in the long haul. + +Other, more sophisticated research has focused on techniques such as program +flow analysis ("concolic execution"), symbolic execution, or static analysis. +All these methods are extremely promising in experimental settings, but tend +to suffer from reliability and performance problems in practical uses - and +currently do not offer a viable alternative to "dumb" fuzzing techniques. 2) The afl-fuzz approach ------------------------ American Fuzzy Lop is a brute-force fuzzer coupled with an exceedingly simple -but rock-solid instrumentation-guided genetic algorithm. It uses an enhanced -form of edge coverage to easily detect subtle, local-scale changes to program -control flow, without being bogged down by complex comparisons between multiple -long-winded execution paths. +but rock-solid instrumentation-guided genetic algorithm. It uses a modified +form of edge coverage to effortlessly pick up subtle, local-scale changes to +program control flow. Simplifying a bit, the overall algorithm can be summed up as: @@ -72,19 +72,14 @@ The discovered test cases are also periodically culled to eliminate ones that have been obsoleted by newer, higher-coverage finds, and undergo several other instrumentation-driven effort minimization steps. -The strategies mentioned in step 4 are fairly straightforward, but go well -beyond the functionality of tools such as zzuf and honggfuzz and lead to -additional finds; this is discussed in more detail in technical_notes.txt. - As a side result of the fuzzing process, the tool creates a small, self-contained corpus of interesting test cases. These are extremely useful for seeding other, labor- or resource-intensive testing regimes - for example, for stress-testing browsers, office applications, graphics suites, or closed-source tools. -The fuzzer is thoroughly tested to deliver coverage far superior to blind -fuzzing or coverage-only tools without the need to dial in any settings or -adjust any knobs. +The fuzzer is thoroughly tested to deliver out-of-the-box performance far +superior to blind fuzzing or coverage-only tools. 3) Instrumenting programs for use with AFL ------------------------------------------ @@ -103,17 +98,18 @@ 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, you will want: - -$ CXX=/path/to/afl/afl-g++ ./configure +For C++ programs, one 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. -When testing libraries, it is essential to either link the tested executable -against a static version of the instrumented library, or to set the right -LD_LIBRARY_PATH. Usually, the simplest option is just: +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.: $ CC=/path/to/afl/afl-gcc ./configure --disable-shared @@ -121,7 +117,8 @@ 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. -Oh: when using ASAN, see the notes_for_asan.txt file for important caveats. +When compiling programs with ASAN, see the notes_for_asan.txt file for +important caveats. 4) Instrumenting binary-only apps --------------------------------- @@ -176,10 +173,11 @@ For programs that accept input directly from stdin, the usual syntax may be: $ ./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 where -the input file name should go. The fuzzer will substitute this for you: +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: -$ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program -r @@ +$ ./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. @@ -427,7 +425,7 @@ bug reports, or patches from: Keegan McAllister Kostya Serebryany Richo Healey Martijn Bogaard rc0r Jonathan Foote - Christian Holler + Christian Holler Dominique Pelle Thank you! diff --git a/docs/sister_projects.txt b/docs/sister_projects.txt index aa38ed38..f50509b1 100644 --- a/docs/sister_projects.txt +++ b/docs/sister_projects.txt @@ -211,7 +211,6 @@ Building harnesses for DNS servers (Jonathan Foote, Ron Bowes) https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop https://goo.gl/j9EgFf - Fuzzer shell for SQLite (Richard Hipp) -------------------------------------- diff --git a/docs/status_screen.txt b/docs/status_screen.txt index 290491e9..3a764d4e 100644 --- a/docs/status_screen.txt +++ b/docs/status_screen.txt @@ -190,7 +190,7 @@ now. It tells you about the current stage, which can be any of: "interesting" 8-, 16-, and 32-bit values to try. The stepover is 8 bits. - extras - deterministic injection of dictionary terms. This can be shown as - "user" or "auto", depending on whether the fuzzer is using an user-supplied + "user" or "auto", depending on whether the fuzzer is using a user-supplied dictionary (-x) or an auto-created one. You will also see "over" or "insert", depending on whether the dictionary words overwrite existing data or are inserted by offsetting the remaining data to accommodate their length. @@ -320,9 +320,9 @@ explanations for variable behavior of the tested program: Less likely causes may include running out of disk space, SHM handles, or other globally limited resources. -The paths where variable behavior is detected are marked with with a matching -entry in the /queue/.state/variable_behavior/ directory, so you can -look them up easily. +The paths where variable behavior is detected are marked with a matching entry +in the /queue/.state/variable_behavior/ directory, so you can look +them up easily. If you can't suppress variable behavior and don't want to see these warnings, simply set AFL_NO_VAR_CHECK=1 in the environment before running afl-fuzz. This