Hello community,
here is the log from the commit of package afl for openSUSE:Factory checked in
at 2015-09-08 17:45:03
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Comparing /work/SRC/openSUSE:Factory/afl (Old)
and /work/SRC/openSUSE:Factory/.afl.new (New)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "afl"
Changes:
--------
--- /work/SRC/openSUSE:Factory/afl/afl.changes 2015-08-12 15:13:00.000000000
+0200
+++ /work/SRC/openSUSE:Factory/.afl.new/afl.changes 2015-09-08
18:06:42.000000000 +0200
@@ -1,0 +2,37 @@
+Mon Sep 7 13:22:07 UTC 2015 - astie...@suse.com
+
+- afl 1.92b:
+ * C++ fix (namespaces)
+
+-------------------------------------------------------------------
+Thu Sep 3 14:32:09 UTC 2015 - astie...@suse.com
+
+- afl 1.91b:
+ * C++ instrumentation fixes
+- includes changes from 1.90b:
+ * documentation updates
+ * Fixed a potential problem with deferred mode signatures getting
+ optimized out by the linker (with --gc-sections).
+
+-------------------------------------------------------------------
+Wed Sep 2 07:57:31 UTC 2015 - astie...@suse.com
+
+- afl 1.89b:
+ * Revamped the support for persistent and deferred forkserver
+ modes. Both now feature simpler syntax and do not require
+ companion env variables.
+ * Added a bit more info about afl-showmap.
+
+-------------------------------------------------------------------
+Sun Aug 30 23:40:19 UTC 2015 - astie...@suse.com
+
+- afl 1.88b:
+ * Make AFL_EXIT_WHEN_DONE work in non-tty mode.
+
+-------------------------------------------------------------------
+Thu Aug 27 14:32:46 UTC 2015 - astie...@suse.com
+
+- afl 1.87b:
+ * Add QuickStartGuide.txt and other documentation updates
+
+-------------------------------------------------------------------
Old:
----
afl-1.86b.tgz
New:
----
afl-1.92b.tgz
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Other differences:
------------------
++++++ afl.spec ++++++
--- /var/tmp/diff_new_pack.ukTcEm/_old 2015-09-08 18:06:45.000000000 +0200
+++ /var/tmp/diff_new_pack.ukTcEm/_new 2015-09-08 18:06:45.000000000 +0200
@@ -17,7 +17,7 @@
Name: afl
-Version: 1.86b
+Version: 1.92b
Release: 0
Summary: American fuzzy lop is a security-oriented fuzzer
License: Apache-2.0
++++++ afl-1.86b.tgz -> afl-1.92b.tgz ++++++
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/Makefile new/afl-1.92b/Makefile
--- old/afl-1.86b/Makefile 2015-08-09 06:26:31.000000000 +0200
+++ new/afl-1.92b/Makefile 2015-09-03 19:54:32.000000000 +0200
@@ -14,7 +14,7 @@
#
PROGNAME = afl
-VERSION = 1.86b
+VERSION = 1.92b
PREFIX ?= /usr/local
BIN_PATH = $(PREFIX)/bin
@@ -132,4 +132,5 @@
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 -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/QuickStartGuide.txt
new/afl-1.92b/QuickStartGuide.txt
--- old/afl-1.86b/QuickStartGuide.txt 1970-01-01 01:00:00.000000000 +0100
+++ new/afl-1.92b/QuickStartGuide.txt 2015-09-08 18:06:45.000000000 +0200
@@ -0,0 +1 @@
+symbolic link to docs/QuickStartGuide.txt
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/afl-cmin new/afl-1.92b/afl-cmin
--- old/afl-1.86b/afl-cmin 2015-08-01 04:43:30.000000000 +0200
+++ new/afl-1.92b/afl-cmin 2015-08-09 07:58:08.000000000 +0200
@@ -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 -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/afl-fuzz.c new/afl-1.92b/afl-fuzz.c
--- old/afl-1.86b/afl-fuzz.c 2015-08-09 06:34:48.000000000 +0200
+++ new/afl-1.92b/afl-fuzz.c 2015-09-03 07:12:32.000000000 +0200
@@ -2072,9 +2072,9 @@
" - Less likely, there is a horrible bug in the fuzzer. If other
options\n"
" fail, poke <lcam...@coredump.cx> for troubleshooting tips.\n",
- getenv("AFL_DEFER_FORKSRV") ? "three" : "two",
- getenv("AFL_DEFER_FORKSRV") ?
- " - You are using AFL_DEFER_FORKSRV, but __afl_manual_init() is
never\n"
+ getenv(DEFER_ENV_VAR) ? "three" : "two",
+ getenv(DEFER_ENV_VAR) ?
+ " - You are using deferred forkserver, but __AFL_INIT() is never\n"
" reached before the program terminates.\n\n" : "",
DMS(mem_limit << 20), mem_limit - 1);
@@ -3697,6 +3697,11 @@
}
+ /* 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 @@
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);
@@ -6606,6 +6605,23 @@
if (memmem(f_data, f_len, "libasan.so", 10) ||
memmem(f_data, f_len, "__msan_init", 11)) uses_asan = 1;
+ /* Detect persistent & deferred init signatures in the binary. */
+
+ if (memmem(f_data, f_len, PERSIST_SIG, strlen(PERSIST_SIG) + 1)) {
+
+ OKF(cPIN "Persistent mode binary detected.");
+ setenv(PERSIST_ENV_VAR, "1", 1);
+ no_var_check = 1;
+
+ }
+
+ if (memmem(f_data, f_len, DEFER_SIG, strlen(DEFER_SIG) + 1)) {
+
+ OKF(cPIN "Deferred forkserver binary detected.");
+ setenv(DEFER_ENV_VAR, "1", 1);
+
+ }
+
if (munmap(f_data, f_len)) PFATAL("unmap() failed");
}
@@ -6878,7 +6894,8 @@
" launchctl unload -w ${SL}/LaunchAgents/${PL}.plist\n"
" sudo launchctl unload -w ${SL}/LaunchDaemons/${PL}.Root.plist\n");
- FATAL("Crash reporter detected");
+ if (!getenv("AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES"))
+ FATAL("Crash reporter detected");
#else
@@ -6905,7 +6922,8 @@
" echo core >/proc/sys/kernel/core_pattern\n");
- FATAL("Pipe at the beginning of 'core_pattern'");
+ if (!getenv("AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES"))
+ FATAL("Pipe at the beginning of 'core_pattern'");
}
@@ -7492,11 +7510,9 @@
}
- if (getenv("AFL_NO_FORKSRV")) no_forkserver = 1;
- if (getenv("AFL_NO_CPU_RED")) no_cpu_meter_red = 1;
-
- if (getenv("AFL_NO_VAR_CHECK") || getenv("AFL_PERSISTENT"))
- no_var_check = 1;
+ if (getenv("AFL_NO_FORKSRV")) no_forkserver = 1;
+ if (getenv("AFL_NO_CPU_RED")) no_cpu_meter_red = 1;
+ if (getenv("AFL_NO_VAR_CHECK")) no_var_check = 1;
if (dumb_mode == 2 && no_forkserver)
FATAL("AFL_DUMB_FORKSRV and AFL_NO_FORKSRV are mutually exclusive");
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/afl-showmap.c new/afl-1.92b/afl-showmap.c
--- old/afl-1.86b/afl-showmap.c 2015-07-04 21:37:43.000000000 +0200
+++ new/afl-1.92b/afl-showmap.c 2015-09-01 00:58:00.000000000 +0200
@@ -337,8 +337,6 @@
setenv("MSAN_OPTIONS", "exit_code=" STRINGIFY(MSAN_ERROR) ":"
"msan_track_origins=0", 0);
- unsetenv("AFL_PERSISTENT");
-
}
@@ -444,7 +442,8 @@
" -q - sink program's output and don't show messages\n"
" -e - show edge coverage only, ignore hit counts\n\n"
- "For additional tips, please consult %s/README.\n\n",
+ "This tool displays raw tuple data captured by AFL instrumentation.\n"
+ "For additional help, consult %s/README.\n\n",
argv0, MEM_LIMIT, doc_path);
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/afl-tmin.c new/afl-1.92b/afl-tmin.c
--- old/afl-1.86b/afl-tmin.c 2015-07-04 21:38:54.000000000 +0200
+++ new/afl-1.92b/afl-tmin.c 2015-09-01 00:58:05.000000000 +0200
@@ -684,8 +684,6 @@
setenv("MSAN_OPTIONS", "exit_code=" STRINGIFY(MSAN_ERROR) ":"
"msan_track_origins=0", 0);
- unsetenv("AFL_PERSISTENT");
-
}
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/config.h new/afl-1.92b/config.h
--- old/afl-1.86b/config.h 2015-05-06 01:47:32.000000000 +0200
+++ new/afl-1.92b/config.h 2015-09-01 00:59:35.000000000 +0200
@@ -263,6 +263,13 @@
#define CLANG_ENV_VAR "__AFL_CLANG_MODE"
#define AS_LOOP_ENV_VAR "__AFL_AS_LOOPCHECK"
+#define PERSIST_ENV_VAR "__AFL_PERSISTENT"
+#define DEFER_ENV_VAR "__AFL_DEFER_FORKSRV"
+
+/* In-code signatures for deferred and persistent mode. */
+
+#define PERSIST_SIG "##SIG_AFL_PERSISTENT##"
+#define DEFER_SIG "##SIG_AFL_DEFER_FORKSRV##"
/* Distinctive bitmap signature used to indicate failed execution: */
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/ChangeLog new/afl-1.92b/docs/ChangeLog
--- old/afl-1.86b/docs/ChangeLog 2015-08-09 06:24:23.000000000 +0200
+++ new/afl-1.92b/docs/ChangeLog 2015-09-03 19:55:03.000000000 +0200
@@ -13,10 +13,62 @@
sending a mail to <afl-users+subscr...@googlegroups.com>.
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
+is 1.92b. If you're stuck on an earlier release, it's strongly advisable
to get on with the times.
--------------
+Version 1.91b:
+--------------
+
+ - Yet another C++ fix (namespaces). Reported by Daniel Lockyer.
+
+--------------
+Version 1.91b:
+--------------
+
+ - Another fix to make 1.90b actually work properly with C++ (d'oh).
+ Problem spotted by Daniel Lockyer.
+
+--------------
+Version 1.90b:
+--------------
+
+ - Fixed a minor typo spotted by Kai Zhao; and made several other minor
updates
+ to docs.
+
+ - Updated the project URL for python-afl. Requested by Jakub Wilk.
+
+ - Fixed a potential problem with deferred mode signatures getting optimized
+ out by the linker (with --gc-sections).
+
+--------------
+Version 1.89b:
+--------------
+
+ - Revamped the support for persistent and deferred forkserver modes.
+ Both now feature simpler syntax and do not require companion env
+ variables. Suggested by Jakub Wilk.
+
+ - Added a bit more info about afl-showmap. Suggested by Jacek Wielemborek.
+
+--------------
+Version 1.88b:
+--------------
+
+ - Made AFL_EXIT_WHEN_DONE work in non-tty mode. Issue spotted by
+ Jacek Wielemborek.
+
+--------------
+Version 1.87b:
+--------------
+
+ - Added QuickStartGuide.txt, a one-page quick start doc.
+
+ - Fixed several typos spotted by Dominique Pelle.
+
+ - Revamped several parts of README.
+
+--------------
Version 1.86b:
--------------
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/INSTALL new/afl-1.92b/docs/INSTALL
--- old/afl-1.86b/docs/INSTALL 2015-06-27 21:41:01.000000000 +0200
+++ new/afl-1.92b/docs/INSTALL 2015-08-26 06:09:23.000000000 +0200
@@ -13,8 +13,8 @@
$ 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
@@ -156,4 +156,7 @@
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 -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/QuickStartGuide.txt
new/afl-1.92b/docs/QuickStartGuide.txt
--- old/afl-1.86b/docs/QuickStartGuide.txt 1970-01-01 01:00:00.000000000
+0100
+++ new/afl-1.92b/docs/QuickStartGuide.txt 2015-08-26 06:04:19.000000000
+0200
@@ -0,0 +1,48 @@
+=====================
+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. 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.
+
+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 <afl-us...@googlegroups.com>.
+
+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 -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/README new/afl-1.92b/docs/README
--- old/afl-1.86b/docs/README 2015-08-09 06:09:32.000000000 +0200
+++ new/afl-1.92b/docs/README 2015-09-01 09:44:13.000000000 +0200
@@ -13,6 +13,8 @@
To compare notes with other users or get notified about major new features,
send a mail to <afl-users+subscr...@googlegroups.com>.
+ ** See QuickStartGuide.txt if you don't have time to read this file. **
+
1) Challenges of guided fuzzing
-------------------------------
@@ -21,34 +23,32 @@
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:
@@ -69,22 +69,17 @@
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.
-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,33 +98,34 @@
$ 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, 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.
-
-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:
+The clang wrappers (afl-clang and afl-clang++) can be used in the same way;
+clang users may also opt to leverage a higher-performance instrumentation mode,
+as 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 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.
-Oh: when using 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:
@@ -139,102 +135,101 @@
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.
-
-You can find quite a few 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.
+ - 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 many good examples of starting files in the testcases/
subdirectory
+that comes with this tool.
+
+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 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'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 -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.
-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 fuzzing performance are discussed in perf_tips.txt.
-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.
+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.
+ starting files given by the user. This is 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.
-
- - 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:
@@ -250,7 +245,7 @@
$ ./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
@@ -427,7 +422,8 @@
Keegan McAllister Kostya Serebryany
Richo Healey Martijn Bogaard
rc0r Jonathan Foote
- Christian Holler
+ Christian Holler Dominique Pelle
+ Jacek Wielemborek
Thank you!
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/env_variables.txt
new/afl-1.92b/docs/env_variables.txt
--- old/afl-1.86b/docs/env_variables.txt 2015-08-09 06:26:17.000000000
+0200
+++ new/afl-1.92b/docs/env_variables.txt 2015-09-01 01:36:18.000000000
+0200
@@ -28,7 +28,9 @@
- 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
@@ -120,14 +122,8 @@
- When running in the -M or -S mode, setting AFL_IMPORT_FIRST causes the
fuzzer to import test cases from other instances before doing anything
- else. This is in contrast with the default mode, where the instances are
- allowed to run on their own for a while before syncing, so that they
- acquire some initial variability in their respective input sets.
-
- The benefit of AFL_IMPORT_FIRST is that it makes the "own finds" counter
- in the UI more accurately reflect the number of findings made by the
- instance (that the remaining instances did not already have). Beyond
- counter aesthetics, not much else should change.
+ else. This makes the "own finds" counter in the UI more accurate
+ Beyond counter aesthetics, not much else should change.
- Setting AFL_POST_LIBRARY allows you to configure a postprocessor for
mutated files - say, to fix up checksums. See experimental/post_library/
@@ -137,18 +133,11 @@
may complain of high load prematurely, especially on systems with low core
counts. To avoid the alarming red color, you can set AFL_NO_CPU_RED.
- - In LLVM mode, AFL_DEFER_FORKSRV can be set to require the forkserver to
- be initialized manually (see llvm_mode/README.llvm). This setting has no
- effect for programs not compiled with afl-clang-fast.
-
- (Technically speaking, the setting is passed down to the binary itself,
- and not handled in any special way by afl-fuzz.)
-
- - In LLVM mode, AFL_PERSISTENT can be set to fuzz in persistent mode. See
- llvm_mode/README.llvm for additional information on what this means.
-
- In QEMU mode (-Q), AFL_PATH will be searched for afl-qemu-trace.
+ - If you are Jakub, you may need AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES.
+ Others need not apply.
+
4) Settings for afl-qemu-trace
------------------------------
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/historical_notes.txt
new/afl-1.92b/docs/historical_notes.txt
--- old/afl-1.86b/docs/historical_notes.txt 2015-04-20 05:37:07.000000000
+0200
+++ new/afl-1.92b/docs/historical_notes.txt 2015-08-26 06:18:00.000000000
+0200
@@ -37,7 +37,7 @@
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 -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/notes_for_asan.txt
new/afl-1.92b/docs/notes_for_asan.txt
--- old/afl-1.86b/docs/notes_for_asan.txt 2015-08-07 17:16:17.000000000
+0200
+++ new/afl-1.92b/docs/notes_for_asan.txt 2015-08-26 06:20:38.000000000
+0200
@@ -8,7 +8,7 @@
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 @@
- 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 .
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/perf_tips.txt
new/afl-1.92b/docs/perf_tips.txt
--- old/afl-1.86b/docs/perf_tips.txt 2015-06-11 08:47:54.000000000 +0200
+++ new/afl-1.92b/docs/perf_tips.txt 2015-09-01 09:55:22.000000000 +0200
@@ -14,10 +14,10 @@
ways.
To illustrate, let's say that you're randomly flipping bits in a file, one bit
-at a time. If you flip bit #47, you will hit a security bug; flipping any
-other bit just results in an invalid document.
+at a time. Let's assume that if you flip bit #47, you will hit a security bug;
+flipping any other bit just results in an invalid document.
-If your starting test case is 100 bytes long, you will have a 71% chance of
+Now, if your starting test case is 100 bytes long, you will have a 71% chance
of
triggering the bug within the first 1,000 execs - not bad! But if the test case
is 1 kB long, the probability that we will randomly hit the right pattern in
the same timeframe goes down to 11%. And if it has 10 kB of non-essential
@@ -59,10 +59,13 @@
The LLVM mode also offers a "persistent", in-process fuzzing mode that can
work well for certain types of self-contained libraries, and for fast targets,
-can offer performance gains up to 5-10x.
+can offer performance gains up to 5-10x; and a "deferred fork server" mode
+that can offer huge benefits for programs with high startup overhead. Both
+modes require you to edit the source code of the fuzzed program, but the
+changes often amount to just strategically placing a single line or two.
-4) Have a closer look at the binary
------------------------------------
+4) Profile and optimize the binary
+----------------------------------
Check for any parameters or settings that obviously improve performance. For
example, the djpeg utility that comes with IJG jpeg and libjpeg-turbo can be
@@ -81,19 +84,21 @@
first error) may result in smaller files and improved run time without
sacrificing coverage; for example, for sqlite, you may want to specify -bail.
-If you are still stumped, you can use strace -tt or an equivalent profiling
-tool to see if the targeted binary is doing anything unnecessarily slow.
+If the program is still too slow, you can use strace -tt or an equivalent
+profiling tool to see if the targeted binary is doing anything silly.
Sometimes, you can speed things up simply by specifying /dev/null as the
config file, or disabling some compile-time features that aren't really needed
for the job (try ./configure --help). One of the notoriously resource-consuming
things would be calling other utilities via exec*(), popen(), system(), or
-equivalent calls; for example, tar can invoke external decompression tools.
+equivalent calls; for example, tar can invoke external decompression tools
+when it decides that the input file is a compressed archive.
+
Some programs may also intentionally call sleep(), usleep(), or nanosleep();
vim is a good example of that.
In programs that are slow due to unavoidable initialization overhead, you may
want to try the LLVM deferred forkserver mode (see llvm_mode/README.llvm),
-which can give you speed gains up to 10x, but needs to be used with care.
+which can give you speed gains up to 10x, as mentioned above.
Last but not least, if you are using ASAN and the performance is unacceptable,
consider turning it off for now, and manually examining the generated corpus
@@ -103,8 +108,10 @@
--------------------------------
Instrument just the libraries you actually want to stress-test right now, one
-at a time. Trying to simultaneously instrument glibc, zlib, gmp, OpenSSL,
-and libxml2 to test a single program is an overkill.
+at a time. Let the program use system-wide, non-instrumented libraries for
+any functionality you don't actually want to fuzz. For example, in most
+cases, it doesn't make to instrument libgmp just because you're testing a
+crypto app that relies on it for bignum math.
Beware of programs that come with oddball third-party libraries bundled with
their source code (Spidermonkey is a good example of this). Check ./configure
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/sister_projects.txt
new/afl-1.92b/docs/sister_projects.txt
--- old/afl-1.86b/docs/sister_projects.txt 2015-08-06 19:35:02.000000000
+0200
+++ new/afl-1.92b/docs/sister_projects.txt 2015-09-02 07:05:13.000000000
+0200
@@ -16,7 +16,7 @@
Allows fuzz-testing of Python programs. Uses custom instrumentation and its
own forkserver.
- https://bitbucket.org/jwilk/python-afl
+ http://jwilk.net/software/python-afl
Go-fuzz (Dmitry Vyukov)
-----------------------
@@ -211,7 +211,6 @@
https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop
https://goo.gl/j9EgFf
-
Fuzzer shell for SQLite (Richard Hipp)
--------------------------------------
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/docs/status_screen.txt
new/afl-1.92b/docs/status_screen.txt
--- old/afl-1.86b/docs/status_screen.txt 2015-06-16 04:17:59.000000000
+0200
+++ new/afl-1.92b/docs/status_screen.txt 2015-08-26 02:34:18.000000000
+0200
@@ -190,7 +190,7 @@
"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 @@
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 <out_dir>/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 <out_dir>/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
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/afl-1.86b/experimental/persistent_demo/persistent_demo.c
new/afl-1.92b/experimental/persistent_demo/persistent_demo.c
--- old/afl-1.86b/experimental/persistent_demo/persistent_demo.c
2015-06-12 08:29:11.000000000 +0200
+++ new/afl-1.92b/experimental/persistent_demo/persistent_demo.c
2015-09-01 01:09:29.000000000 +0200
@@ -18,8 +18,7 @@
across runs.
To make this work, the library and this shim need to be compiled in LLVM
- mode using afl-clang-fast (other compiler wrappers will *not* work); and
- afl-fuzz must be called with AFL_PERSISTENT set.
+ mode using afl-clang-fast (other compiler wrappers will *not* work).
*/
@@ -29,14 +28,6 @@
#include <signal.h>
#include <string.h>
-/* This constant specifies the number of inputs to process before restarting.
- This is optional, but helps limit the impact of memory leaks and similar
- hiccups. */
-
-#define PERSIST_MAX 1000
-
-unsigned int persist_cnt;
-
/* Main entry point. */
@@ -45,57 +36,52 @@
char buf[100]; /* Example-only buffer, you'd replace it with other global or
local variables appropriate for your use case. */
-try_again:
-
- /*** PLACEHOLDER CODE ***/
-
- /* STEP 1: Fully re-initialize all critical variables. In our example, this
- involves zeroing buf[], our input buffer. */
-
- memset(buf, 0, 100);
-
- /* STEP 2: Read input data. When reading from stdin, no special preparation
- is required. When reading from a named file, you need to close the
- old descriptor and reopen the file first!
-
- Beware of reading from buffered FILE* objects such as stdin. Use
- raw file descriptors or call fopen() / fdopen() in every pass. */
-
- read(0, buf, 100);
-
- /* STEP 3: This is where we'd call the tested library on the read data. Here,
- we just have some trivial inline code that faults on 'foo!'. */
-
- if (buf[0] == 'f') {
- printf("one\n");
- if (buf[1] == 'o') {
- printf("two\n");
- if (buf[2] == 'o') {
- printf("three\n");
- if (buf[3] == '!') {
- printf("four\n");
- abort();
+ /* The number passed to __AFL_LOOP() controls the maximum number of
+ iterations before the loop exits and the program is allowed to
+ terminate normally. This limits the impact of accidental memory leaks
+ and similar hiccups. */
+
+ while (__AFL_LOOP(1000)) {
+
+ /*** PLACEHOLDER CODE ***/
+
+ /* STEP 1: Fully re-initialize all critical variables. In our example, this
+ involves zeroing buf[], our input buffer. */
+
+ memset(buf, 0, 100);
+
+ /* STEP 2: Read input data. When reading from stdin, no special preparation
+ is required. When reading from a named file, you need to close
+ the old descriptor and reopen the file first!
+
+ Beware of reading from buffered FILE* objects such as stdin. Use
+ raw file descriptors or call fopen() / fdopen() in every pass.
*/
+
+ read(0, buf, 100);
+
+ /* STEP 3: This is where we'd call the tested library on the read data.
+ We just have some trivial inline code that faults on 'foo!'. */
+
+ if (buf[0] == 'f') {
+ printf("one\n");
+ if (buf[1] == 'o') {
+ printf("two\n");
+ if (buf[2] == 'o') {
+ printf("three\n");
+ if (buf[3] == '!') {
+ printf("four\n");
+ abort();
+ }
}
}
}
- }
-
- /*** END PLACEHOLDER CODE ***/
-
- /* STEP 4: To signal successful completion of a run, we need to deliver
- SIGSTOP to our own process, then loop to the very beginning
- once we're resumed by the supervisor process. We do this only
- if AFL_PERSISTENT is set to retain normal behavior when the
- program is executed directly; and take note of PERSIST_MAX. */
-
- if (getenv("AFL_PERSISTENT") && persist_cnt++ < PERSIST_MAX) {
- raise(SIGSTOP);
- goto try_again;
+ /*** END PLACEHOLDER CODE ***/
}
- /* If AFL_PERSISTENT not set or PERSIST_MAX exceeded, exit normally. */
+ /* Once the loop is exited, terminate normally - AFL will restat the process
+ from scratch. */
return 0;
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/llvm_mode/Makefile
new/afl-1.92b/llvm_mode/Makefile
--- old/afl-1.86b/llvm_mode/Makefile 2015-06-11 09:25:52.000000000 +0200
+++ new/afl-1.92b/llvm_mode/Makefile 2015-09-01 00:59:44.000000000 +0200
@@ -80,7 +80,7 @@
test_build: $(PROGS)
@echo "[*] Testing the CC wrapper and instrumentation output..."
- unset AFL_USE_ASAN AFL_USE_MSAN AFL_DEFER_FORKSRV; AFL_QUIET=1
AFL_INST_RATIO=100 AFL_PATH=. AFL_CC=$(CC) ../afl-clang-fast $(CFLAGS)
../test-instr.c -o test-instr $(LDFLAGS)
+ unset AFL_USE_ASAN AFL_USE_MSAN; AFL_QUIET=1 AFL_INST_RATIO=100
AFL_PATH=. AFL_CC=$(CC) ../afl-clang-fast $(CFLAGS) ../test-instr.c -o
test-instr $(LDFLAGS)
echo 0 | ../afl-showmap -m none -q -o .test-instr0 ./test-instr
echo 1 | ../afl-showmap -m none -q -o .test-instr1 ./test-instr
@rm -f test-instr
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/llvm_mode/README.llvm
new/afl-1.92b/llvm_mode/README.llvm
--- old/afl-1.86b/llvm_mode/README.llvm 2015-06-12 09:15:10.000000000 +0200
+++ new/afl-1.92b/llvm_mode/README.llvm 2015-09-03 16:52:18.000000000 +0200
@@ -61,10 +61,7 @@
CC=/path/to/afl/afl-clang-fast ./configure [...options...]
make
-...or:
-
- CXX=/path/to/afl/afl-clang-fast++ ./configure [...options...]
- make
+Be sure to also include CXX set to afl-clang-fast++ for C++ code.
The tool honors roughly the same environmental variables as afl-gcc (see
../docs/env_variables.txt). This includes AFL_INST_RATIO, AFL_USE_ASAN,
@@ -89,51 +86,43 @@
Although this approach eliminates much of the OS-, linker- and libc-level
costs of executing the program, it does not always help with binaries that
-perform other time-consuming initialization steps before getting to the input
-file.
-
-In such cases, it would be beneficial to initialize the forkserver a bit later,
-once most of the initialization work is already done, but before the binary
-attempts to read the fuzzed input and parse it. You can do this in LLVM mode in
-a fairly simple way:
+perform other time-consuming initialization steps - say, parsing a large config
+file before getting to the fuzzed data.
-1. First, locate a suitable location in the code for the deferred
initialization
- to take place. This needs to be done with *extreme* care to avoid breaking
- the binary. In particular, the program will probably malfunction if the
- initialization happens after:
+In such cases, it's beneficial to initialize the forkserver a bit later, once
+most of the initialization work is already done, but before the binary attempts
+to read the fuzzed input and parse it; in some cases, this can offer a 10x+
+performance gain. You can implement delayed initialization in LLVM mode in a
+fairly simple way.
- - The creation of any vital threads or child processes - since the
forkserver
- can't clone them easily.
+First, locate a suitable location in the code where the delayed cloning can
+take place. This needs to be done with *extreme* care to avoid breaking the
+binary. In particular, the program will probably malfunction if you select
+a location after:
- - The creation of temporary files, network sockets, offset-sensitive file
- descriptors, and similar shared-state resources - but only provided that
- their state meaningfully influences the behavior of the program later on.
+ - The creation of any vital threads or child processes - since the forkserver
+ can't clone them easily.
- - Any access to the fuzzed input, including reading the metadata about its
- size.
+ - The initialization of timers via setitimer() or equivalent calls.
- Of course, things will also not work if the forkserver is never initialized
- at all and the program is allowed to exit before that; in this case,
afl-fuzz
- will complain about failed handshake and bail out.
+ - The creation of temporary files, network sockets, offset-sensitive file
+ descriptors, and similar shared-state resources - but only provided that
+ their state meaningfully influences the behavior of the program later on.
-2. Next, insert the following global function declaration somewhere in the
- source file:
+ - Any access to the fuzzed input, including reading the metadata about its
+ size.
- void __afl_manual_init(void);
+With the location selected, add this code in the appropriate spot:
- ...and add a call to this function in the desired location before
recompiling
- the project with afl-clang-fast (afl-gcc and afl-clang will *not* work). You
- can put this in between #ifdef __AFL_HAVE_MANUAL_INIT to allow the code to
- build correctly without afl-clang-fast.
+#ifdef __AFL_HAVE_MANUAL_CONTROL
+ __AFL_INIT();
+#endif
-3. Finally, be sure to set AFL_DEFER_FORKSRV=1 before invoking afl-fuzz.
+You don't need the #ifdef guards, but they will make the program still work as
+usual when compiled with a tool other than afl-clang-fast.
-Again, this feature is easy to misuse; be careful and double-test that the
-coverage and the number of discovered paths is comparable between normal and
-deferred runs. That said, when you do it well, you can see gains up to 10x or
-so:
-
- https://groups.google.com/forum/#!topic/afl-users/fNMJHl7Fhzs
+Finally, recompile the pogram with afl-clang-fast (afl-gcc or afl-clang will
+*not* generate a deferred-initialization binary) - and you should be all set!
5) Bonus feature #2: persistent mode
------------------------------------
@@ -141,27 +130,36 @@
Some libraries provide APIs that are stateless, or whose state can be reset in
between processing different input files. When such a reset is performed, a
single long-lived process can be reused to try out multiple test cases,
-eliminating the need for repeated fork() calls and the associated OS overhead:
+eliminating the need for repeated fork() calls and the associated OS overhead.
+
+The basic structure of the program that does this would be:
+
+ while (__AFL_LOOP(1000)) {
+
+ /* Read input data. */
+ /* Call library code to be fuzzed. */
+ /* Reset state. */
+
+ }
+
+ /* Exit normally */
- http://lcamtuf.blogspot.com/2015/06/new-in-afl-persistent-mode.html
+The numerical value specified within the loop controls the maximum number
+of iterations before AFL will restart the process from scratch. This minimizes
+the impact of memory leaks and similar glitches; 1000 is a good starting point.
-With certain fast targets, such an approach can offer dramatic (5x+)
-performance gains. The LLVM mode allows you to build such persistent targets
-using the template provided in ../experimental/persistent_demo/.
-
-To leverage this functionality, you need to set AFL_PERSISTENT before
-invoking afl-fuzz, and the target binary needs to incorporate a simple pattern
-documented in the aforementioned example file. It also needs to be compiled
with
-afl-clang-fast; other compiler wrappers will not work.
+A more detailed template is shown in ../experimental/persistent_demo/.
+Similarly to the previous mode, the feature works only with afl-clang-fast;
+#ifdef guards can be used to suppress it when using other compilers.
Note that as with the previous mode, the feature is easy to misuse; if you
do not reset the critical state fully, you may end up with false positives or
waste a whole lot of CPU power doing nothing useful at all. Be particularly
-wary of memory leaks.
+wary of memory leaks and the state of file descriptors.
When running in this mode, the execution paths will inherently vary a bit
depending on whether the input loop is being entered for the first time or
-executed again. To avoid spurious warnings, AFL_PERSISTENT implies
+executed again. To avoid spurious warnings, the feature implies
AFL_NO_VAR_CHECK and hides the "variable path" warnings in the UI.
PS. Because there are task switches still involved, the mode isn't as fast as
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/llvm_mode/afl-clang-fast.c
new/afl-1.92b/llvm_mode/afl-clang-fast.c
--- old/afl-1.86b/llvm_mode/afl-clang-fast.c 2015-05-03 00:20:31.000000000
+0200
+++ new/afl-1.92b/llvm_mode/afl-clang-fast.c 2015-09-03 19:53:58.000000000
+0200
@@ -99,7 +99,7 @@
u8 fortify_set = 0, asan_set = 0, x_set = 0, maybe_linking = 1;
u8 *name;
- cc_params = ck_alloc((argc + 32) * sizeof(u8*));
+ cc_params = ck_alloc((argc + 64) * sizeof(u8*));
name = strrchr(argv[0], '/');
if (!name) name = argv[0]; else name++;
@@ -176,7 +176,19 @@
}
- cc_params[cc_par_cnt++] = "-D__AFL_HAVE_MANUAL_INIT=1";
+ cc_params[cc_par_cnt++] = "-D__AFL_HAVE_MANUAL_CONTROL=1";
+
+ cc_params[cc_par_cnt++] = "-D__AFL_LOOP(_A)="
+ "({ static volatile char *_B __attribute__((used)); "
+ " _B = (char*)\"" PERSIST_SIG "\"; "
+ "int _L(unsigned int) __asm__(\"__afl_persistent_loop\"); "
+ "_L(_A); })";
+
+ cc_params[cc_par_cnt++] = "-D__AFL_INIT()="
+ "do { static volatile char *_A __attribute__((used)); "
+ " _A = (char*)\"" DEFER_SIG "\"; "
+ "void _I(void) __asm__(\"__afl_manual_init\"); "
+ "_I(); } while (0)";
if (maybe_linking) {
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/llvm_mode/afl-llvm-pass.so.cc
new/afl-1.92b/llvm_mode/afl-llvm-pass.so.cc
--- old/afl-1.86b/llvm_mode/afl-llvm-pass.so.cc 2015-04-30 07:48:40.000000000
+0200
+++ new/afl-1.92b/llvm_mode/afl-llvm-pass.so.cc 2015-09-03 16:50:08.000000000
+0200
@@ -82,7 +82,7 @@
/* Decide instrumentation ratio */
char* inst_ratio_str = getenv("AFL_INST_RATIO");
- int inst_ratio = 100;
+ unsigned int inst_ratio = 100;
if (inst_ratio_str) {
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/afl-1.86b/llvm_mode/afl-llvm-rt.o.c
new/afl-1.92b/llvm_mode/afl-llvm-rt.o.c
--- old/afl-1.86b/llvm_mode/afl-llvm-rt.o.c 2015-06-12 10:25:16.000000000
+0200
+++ new/afl-1.92b/llvm_mode/afl-llvm-rt.o.c 2015-09-03 08:04:27.000000000
+0200
@@ -42,6 +42,11 @@
u16 __afl_prev_loc;
+/* Running in persistent mode? */
+
+static u8 is_persistent;
+
+
/* SHM setup. */
static void __afl_map_shm(void) {
@@ -80,7 +85,6 @@
s32 child_pid;
u8 child_stopped = 0;
- u8 use_persistent = !!getenv("AFL_PERSISTENT");
/* Phone home and tell the parent that we're OK. If parent isn't there,
assume we're not running in forkserver mode and just execute program. */
@@ -136,7 +140,7 @@
if (write(FORKSRV_FD + 1, &child_pid, 4) != 4) exit(1);
- if (waitpid(child_pid, &status, use_persistent ? WUNTRACED : 0) < 0)
+ if (waitpid(child_pid, &status, is_persistent ? WUNTRACED : 0) < 0)
exit(1);
/* In persistent mode, the child stops itself with SIGSTOP to indicate
@@ -154,7 +158,33 @@
}
-/* This one can be called from user code when AFL_DEFER_FORKSRV is set. */
+/* A simplified persistent mode handler, used as explained in README.llvm. */
+
+int __afl_persistent_loop(unsigned int max_cnt) {
+
+ static u8 first_pass = 1;
+ static u32 cycle_cnt;
+
+ if (first_pass) {
+
+ cycle_cnt = max_cnt;
+ first_pass = 0;
+ return 1;
+
+ }
+
+ if (is_persistent && --cycle_cnt) {
+
+ raise(SIGSTOP);
+ return 1;
+
+ } else return 0;
+
+}
+
+
+/* This one can be called from user code when deferred forkserver mode
+ is enabled. */
void __afl_manual_init(void) {
@@ -175,7 +205,10 @@
__attribute__((constructor(0))) void __afl_auto_init(void) {
- if (getenv("AFL_DEFER_FORKSRV")) return;
+ is_persistent = !!getenv(PERSIST_ENV_VAR);
+
+ if (getenv(DEFER_ENV_VAR)) return;
+
__afl_manual_init();
}
