diff options
| -rw-r--r-- | Makefile | 48 | ||||
| l--------- | QuickStartGuide.md | 1 | ||||
| l--------- | QuickStartGuide.txt | 1 | ||||
| -rw-r--r-- | README.md | 24 | ||||
| -rwxr-xr-x | afl-whatsup | 2 | ||||
| -rw-r--r-- | custom_mutators/README | 2 | ||||
| -rw-r--r-- | docs/ChangeLog | 41 | ||||
| -rw-r--r-- | docs/INSTALL.md (renamed from docs/INSTALL) | 97 | ||||
| -rw-r--r-- | docs/PATCHES.md (renamed from docs/PATCHES) | 13 | ||||
| -rw-r--r-- | docs/QuickStartGuide.md (renamed from docs/QuickStartGuide.txt) | 20 | ||||
| -rw-r--r-- | docs/README.MOpt.md (renamed from docs/README.MOpt) | 0 | ||||
| -rw-r--r--[l---------] | docs/README.md | 683 | ||||
| -rw-r--r--[l---------] | docs/README.radamsa.md | 10 | ||||
| -rw-r--r-- | docs/binaryonly_fuzzing.md | 2 | ||||
| -rw-r--r-- | docs/custom_mutator.md (renamed from docs/custom_mutator.txt) | 15 | ||||
| -rw-r--r-- | docs/env_variables.md (renamed from docs/env_variables.txt) | 92 | ||||
| -rw-r--r-- | docs/historical_notes.md (renamed from docs/historical_notes.txt) | 28 | ||||
| -rw-r--r-- | docs/life_pro_tips.md | 90 | ||||
| -rw-r--r-- | docs/life_pro_tips.txt | 128 | ||||
| -rw-r--r-- | docs/notes_for_asan.md (renamed from docs/notes_for_asan.txt) | 46 | ||||
| -rw-r--r-- | docs/parallel_fuzzing.md (renamed from docs/parallel_fuzzing.txt) | 35 | ||||
| -rw-r--r-- | docs/perf_tips.md (renamed from docs/perf_tips.txt) | 129 | ||||
| -rw-r--r-- | docs/power_schedules.md (renamed from docs/power_schedules.txt) | 7 | ||||
| -rw-r--r-- | docs/python_mutators.md (renamed from docs/python_mutators.txt) | 24 | ||||
| -rw-r--r-- | docs/sister_projects.md | 318 | ||||
| -rw-r--r-- | docs/sister_projects.txt | 360 | ||||
| -rw-r--r-- | docs/status_screen.md (renamed from docs/status_screen.txt) | 184 | ||||
| -rw-r--r-- | docs/technical_details.md (renamed from docs/technical_details.txt) | 150 | ||||
| -rw-r--r-- | examples/README.md (renamed from experimental/README.experiments) | 10 | ||||
| -rw-r--r-- | examples/argv_fuzzing/Makefile (renamed from experimental/argv_fuzzing/Makefile) | 0 | ||||
| -rw-r--r-- | examples/argv_fuzzing/README.md (renamed from experimental/argv_fuzzing/README.md) | 0 | ||||
| -rw-r--r-- | examples/argv_fuzzing/argv-fuzz-inl.h (renamed from experimental/argv_fuzzing/argv-fuzz-inl.h) | 0 | ||||
| -rw-r--r-- | examples/argv_fuzzing/argvfuzz.c (renamed from experimental/argv_fuzzing/argvfuzz.c) | 0 | ||||
| -rwxr-xr-x | examples/asan_cgroups/limit_memory.sh (renamed from experimental/asan_cgroups/limit_memory.sh) | 2 | ||||
| -rw-r--r-- | examples/bash_shellshock/shellshock-fuzz.diff (renamed from experimental/bash_shellshock/shellshock-fuzz.diff) | 0 | ||||
| -rw-r--r-- | examples/canvas_harness/canvas_harness.html (renamed from experimental/canvas_harness/canvas_harness.html) | 0 | ||||
| -rwxr-xr-x | examples/clang_asm_normalize/as (renamed from experimental/clang_asm_normalize/as) | 0 | ||||
| -rwxr-xr-x | examples/crash_triage/triage_crashes.sh (renamed from experimental/crash_triage/triage_crashes.sh) | 0 | ||||
| -rw-r--r-- | examples/custom_mutators/README | 2 | ||||
| -rw-r--r-- | examples/custom_mutators/simple_mutator.c (renamed from custom_mutators/simple_mutator.c) | 0 | ||||
| -rwxr-xr-x | examples/distributed_fuzzing/sync_script.sh (renamed from experimental/distributed_fuzzing/sync_script.sh) | 0 | ||||
| -rw-r--r-- | examples/libpng_no_checksum/libpng-nocrc.patch (renamed from experimental/libpng_no_checksum/libpng-nocrc.patch) | 0 | ||||
| -rw-r--r-- | examples/persistent_demo/persistent_demo.c (renamed from experimental/persistent_demo/persistent_demo.c) | 0 | ||||
| -rw-r--r-- | examples/post_library/post_library.so.c (renamed from experimental/post_library/post_library.so.c) | 0 | ||||
| -rw-r--r-- | examples/post_library/post_library_png.so.c (renamed from experimental/post_library/post_library_png.so.c) | 0 | ||||
| -rw-r--r-- | examples/python_mutators/README (renamed from python_mutators/README) | 2 | ||||
| -rw-r--r-- | examples/python_mutators/XmlMutatorMin.py (renamed from python_mutators/XmlMutatorMin.py) | 0 | ||||
| -rw-r--r-- | examples/python_mutators/common.py (renamed from python_mutators/common.py) | 0 | ||||
| -rw-r--r-- | examples/python_mutators/example.py (renamed from python_mutators/example.py) | 0 | ||||
| -rw-r--r-- | examples/python_mutators/simple-chunk-replace.py (renamed from python_mutators/simple-chunk-replace.py) | 0 | ||||
| -rw-r--r-- | examples/python_mutators/wrapper_afl_min.py (renamed from python_mutators/wrapper_afl_min.py) | 0 | ||||
| -rw-r--r-- | examples/socket_fuzzing/Makefile (renamed from experimental/socket_fuzzing/Makefile) | 0 | ||||
| -rw-r--r-- | examples/socket_fuzzing/README.md (renamed from experimental/socket_fuzzing/README.md) | 0 | ||||
| -rw-r--r-- | examples/socket_fuzzing/socketfuzz.c (renamed from experimental/socket_fuzzing/socketfuzz.c) | 0 | ||||
| -rw-r--r-- | gcc_plugin/README.md | 4 | ||||
| -rw-r--r-- | llvm_mode/README.md | 4 | ||||
| -rw-r--r-- | qemu_mode/README.md | 2 | ||||
| -rw-r--r-- | src/afl-as.c | 2 | ||||
| -rw-r--r-- | src/afl-forkserver.c | 4 | ||||
| -rw-r--r-- | src/afl-fuzz-cmplog.c | 4 | ||||
| -rw-r--r-- | src/afl-fuzz-init.c | 4 | ||||
| -rw-r--r-- | src/afl-fuzz-stats.c | 6 | ||||
| -rw-r--r-- | src/afl-fuzz.c | 6 | ||||
| -rw-r--r-- | src/afl-gotcpu.c | 2 | ||||
| -rw-r--r-- | src/afl-showmap.c | 257 | ||||
| -rw-r--r-- | src/afl-tmin.c | 12 | ||||
| -rwxr-xr-x | test/test.sh | 4 |
67 files changed, 1847 insertions, 1030 deletions
diff --git a/Makefile b/Makefile index dd6c19aa..da3d0766 100644 --- a/Makefile +++ b/Makefile @@ -63,6 +63,14 @@ CFLAGS += -Wall -g -Wno-pointer-sign -I include/ \ AFL_FUZZ_FILES = $(wildcard src/afl-fuzz*.c) +ifneq "$(shell which python3m)" "" + ifneq "$(shell which python3m-config)" "" + PYTHON_INCLUDE ?= $(shell python3m-config --includes) + PYTHON_LIB ?= $(shell python3m-config --ldflags) + PYTHON_VERSION ?= $(strip $(shell python3m --version 2>&1)) + endif +endif + ifneq "$(shell which python3)" "" ifneq "$(shell which python3-config)" "" PYTHON_INCLUDE ?= $(shell python3-config --includes) @@ -249,7 +257,7 @@ afl-fuzz: include/afl-fuzz.h $(AFL_FUZZ_FILES) src/afl-common.o src/afl-sharedme $(CC) $(CFLAGS) $(CFLAGS_FLTO) $(AFL_FUZZ_FILES) src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o -o $@ $(PYFLAGS) $(LDFLAGS) afl-showmap: src/afl-showmap.c src/afl-common.o src/afl-sharedmem.o $(COMM_HDR) | test_x86 - $(CC) $(CFLAGS) $(CFLAGS_FLTO) src/$@.c src/afl-common.o src/afl-sharedmem.o -o $@ $(LDFLAGS) + $(CC) $(CFLAGS) $(CFLAGS_FLTO) src/$@.c src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o -o $@ $(LDFLAGS) afl-tmin: src/afl-tmin.c src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o $(COMM_HDR) | test_x86 $(CC) $(CFLAGS) $(CFLAGS_FLTO) src/$@.c src/afl-common.o src/afl-sharedmem.o src/afl-forkserver.o -o $@ $(LDFLAGS) @@ -277,8 +285,8 @@ code-format: ./.custom-format.py -i gcc_plugin/*.c #./.custom-format.py -i gcc_plugin/*.h ./.custom-format.py -i gcc_plugin/*.cc - ./.custom-format.py -i experimental/*/*.c - ./.custom-format.py -i experimental/*/*.h + ./.custom-format.py -i examples/*/*.c + ./.custom-format.py -i examples/*/*.h ./.custom-format.py -i qemu_mode/patches/*.h ./.custom-format.py -i qemu_mode/libcompcov/*.c ./.custom-format.py -i qemu_mode/libcompcov/*.cc @@ -312,7 +320,7 @@ all_done: test_build @if [ ! "`which clang 2>/dev/null`" = "" ]; then echo "[+] LLVM users: see llvm_mode/README.llvm for a faster alternative to afl-gcc."; fi @echo "[+] All done! Be sure to review the README.md - it's pretty short and useful." @if [ "`uname`" = "Darwin" ]; then printf "\nWARNING: Fuzzing on MacOS X is slow because of the unusually high overhead of\nfork() on this OS. Consider using Linux or *BSD. You can also use VirtualBox\n(virtualbox.org) to put AFL inside a Linux or *BSD VM.\n\n"; fi - @! tty <&1 >/dev/null || printf "\033[0;30mNOTE: If you can read this, your terminal probably uses white background.\nThis will make the UI hard to read. See docs/status_screen.txt for advice.\033[0m\n" 2>/dev/null + @! tty <&1 >/dev/null || printf "\033[0;30mNOTE: If you can read this, your terminal probably uses white background.\nThis will make the UI hard to read. See docs/status_screen.md for advice.\033[0m\n" 2>/dev/null .NOTPARALLEL: clean @@ -323,8 +331,8 @@ clean: -$(MAKE) -C gcc_plugin clean $(MAKE) -C libdislocator clean $(MAKE) -C libtokencap clean - $(MAKE) -C experimental/socket_fuzzing clean - $(MAKE) -C experimental/argv_fuzzing clean + $(MAKE) -C examples/socket_fuzzing clean + $(MAKE) -C examples/argv_fuzzing clean $(MAKE) -C qemu_mode/unsigaction clean $(MAKE) -C qemu_mode/libcompcov clean $(MAKE) -C src/third_party/libradamsa/ clean @@ -335,16 +343,16 @@ distrib: all radamsa -$(MAKE) -C gcc_plugin $(MAKE) -C libdislocator $(MAKE) -C libtokencap - $(MAKE) -C experimental/socket_fuzzing - $(MAKE) -C experimental/argv_fuzzing + $(MAKE) -C examples/socket_fuzzing + $(MAKE) -C examples/argv_fuzzing cd qemu_mode && sh ./build_qemu_support.sh cd unicorn_mode && sh ./build_unicorn_support.sh binary-only: all radamsa $(MAKE) -C libdislocator $(MAKE) -C libtokencap - $(MAKE) -C experimental/socket_fuzzing - $(MAKE) -C experimental/argv_fuzzing + $(MAKE) -C examples/socket_fuzzing + $(MAKE) -C examples/argv_fuzzing cd qemu_mode && sh ./build_qemu_support.sh cd unicorn_mode && sh ./build_unicorn_support.sh @@ -395,8 +403,8 @@ endif if [ -f libcompcov.so ]; then set -e; install -m 755 libcompcov.so $${DESTDIR}$(HELPER_PATH); fi if [ -f libradamsa.so ]; then set -e; install -m 755 libradamsa.so $${DESTDIR}$(HELPER_PATH); fi if [ -f afl-fuzz-document ]; then set -e; install -m 755 afl-fuzz-document $${DESTDIR}$(BIN_PATH); fi - $(MAKE) -C experimental/socket_fuzzing install - $(MAKE) -C experimental/argv_fuzzing install + $(MAKE) -C examples/socket_fuzzing install + $(MAKE) -C examples/argv_fuzzing install set -e; ln -sf afl-gcc $${DESTDIR}$(BIN_PATH)/afl-g++ set -e; if [ -f afl-clang-fast ] ; then ln -sf afl-clang-fast $${DESTDIR}$(BIN_PATH)/afl-clang ; ln -sf afl-clang-fast $${DESTDIR}$(BIN_PATH)/afl-clang++ ; else ln -sf afl-gcc $${DESTDIR}$(BIN_PATH)/afl-clang ; ln -sf afl-gcc $${DESTDIR}$(BIN_PATH)/afl-clang++; fi @@ -406,21 +414,7 @@ endif install -m 755 afl-as $${DESTDIR}$(HELPER_PATH) ln -sf afl-as $${DESTDIR}$(HELPER_PATH)/as - install -m 644 docs/README.md docs/ChangeLog docs/*.txt $${DESTDIR}$(DOC_PATH) + install -m 644 docs/*.md docs/ChangeLog $${DESTDIR}$(DOC_PATH) cp -r testcases/ $${DESTDIR}$(MISC_PATH) cp -r dictionaries/ $${DESTDIR}$(MISC_PATH) -#publish: clean -# test "`basename $$PWD`" = "afl" || exit 1 -# test -f ~/www/afl/releases/$(PROGNAME)-$(VERSION).tgz; if [ "$$?" = "0" ]; then echo; echo "Change program version in config.h, mmkay?"; echo; exit 1; fi -# cd ..; rm -rf $(PROGNAME)-$(VERSION); cp -pr $(PROGNAME) $(PROGNAME)-$(VERSION); \ -# tar -cvz -f ~/www/afl/releases/$(PROGNAME)-$(VERSION).tgz $(PROGNAME)-$(VERSION) -# chmod 644 ~/www/afl/releases/$(PROGNAME)-$(VERSION).tgz -# ( cd ~/www/afl/releases/; ln -s -f $(PROGNAME)-$(VERSION).tgz $(PROGNAME)-latest.tgz ) -# cat docs/README.md >~/www/afl/README.txt -# cat docs/status_screen.txt >~/www/afl/status_screen.txt -# 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.md b/QuickStartGuide.md new file mode 120000 index 00000000..8136d85e --- /dev/null +++ b/QuickStartGuide.md @@ -0,0 +1 @@ +docs/QuickStartGuide.md \ No newline at end of file diff --git a/QuickStartGuide.txt b/QuickStartGuide.txt deleted file mode 120000 index e1687eb5..00000000 --- a/QuickStartGuide.txt +++ /dev/null @@ -1 +0,0 @@ -docs/QuickStartGuide.txt \ No newline at end of file diff --git a/README.md b/README.md index dbfdb2cc..3b572d42 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ To compare notes with other users or get notified about major new features, send a mail to <afl-users+subscribe@googlegroups.com>. - See [docs/QuickStartGuide.txt](docs/QuickStartGuide.txt) if you don't have time to + See [docs/QuickStartGuide.md](docs/QuickStartGuide.md) if you don't have time to read this file. @@ -250,7 +250,7 @@ automatically enable code hardening options that make it easier to detect simple memory bugs. Libdislocator, a helper library included with AFL (see [libdislocator/README.md](libdislocator/README.md)) can help uncover heap corruption issues, too. -PS. ASAN users are advised to review [docs/notes_for_asan.txt](docs/notes_for_asan.txt) +PS. ASAN users are advised to review [docs/notes_for_asan.md](docs/notes_for_asan.md) file for important caveats. @@ -278,7 +278,7 @@ your binary, then you can use afl-fuzz normally and it will have twice the speed compared to qemu_mode. A more comprehensive description of these and other options can be found in -[docs/binaryonly_fuzzing.txt](docs/binaryonly_fuzzing.txt) +[docs/binaryonly_fuzzing.md](docs/binaryonly_fuzzing.md) ## 5) Power schedules @@ -315,7 +315,7 @@ 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 matters, see [perf_tips.txt](docs/perf_tips.txt). + For a discussion of why size matters, see [perf_tips.md](docs/perf_tips.md). - Use multiple test cases only if they are functionally different from each other. There is no point in using fifty different vacation photos @@ -359,7 +359,7 @@ You can use -t and -m to override the default timeout and memory limit for the 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](docs/perf_tips.txt). +Tips for optimizing fuzzing performance are discussed in [perf_tips.md](docs/perf_tips.md). Note that afl-fuzz starts by performing an array of deterministic fuzzing steps, which can take several days, but tend to produce neat test cases. If you @@ -369,7 +369,7 @@ fuzzers - add the -d option to the command line. ## 8) Interpreting output -See the [docs/status_screen.txt](docs/status_screen.txt) file for information on +See the [docs/status_screen.md](docs/status_screen.md) 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. @@ -433,11 +433,11 @@ see [http://lcamtuf.coredump.cx/afl/plot/](http://lcamtuf.coredump.cx/afl/plot/) Every instance of afl-fuzz takes up roughly one core. This means that on multi-core systems, parallelization is necessary to fully utilize the hardware. For tips on how to fuzz a common target on multiple cores or multiple networked -machines, please refer to [docs/parallel_fuzzing.txt](docs/parallel_fuzzing.txt). +machines, please refer to [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md). The parallel fuzzing mode also offers a simple way for interfacing AFL to other fuzzers, to symbolic or concolic execution engines, and so forth; again, see the -last section of [docs/parallel_fuzzing.txt](docs/parallel_fuzzing.txt) for tips. +last section of [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md) for tips. ## 10) Fuzzer dictionaries @@ -521,7 +521,7 @@ file, attempts to sequentially flip bytes, and observes the behavior of the tested program. It then color-codes the input based on which sections appear to be critical, and which are not; while not bulletproof, it can often offer quick insights into complex file formats. More info about its operation can be found -near the end of [docs/technical_details.txt](docs/technical_details.txt). +near the end of [docs/technical_details.md](docs/technical_details.md). ## 12) Going beyond crashes @@ -593,12 +593,12 @@ Here are some of the most important caveats for AFL: wholly wrap the actual data format to be tested. To work around this, you can comment out the relevant checks (see - experimental/libpng_no_checksum/ for inspiration); if this is not possible, + examples/libpng_no_checksum/ for inspiration); if this is not possible, you can also write a postprocessor, as explained in - experimental/post_library/ (with AFL_POST_LIBRARY) + examples/post_library/ (with AFL_POST_LIBRARY) - There are some unfortunate trade-offs with ASAN and 64-bit binaries. This - isn't due to any specific fault of afl-fuzz; see [docs/notes_for_asan.txt](docs/notes_for_asan.txt) + isn't due to any specific fault of afl-fuzz; see [docs/notes_for_asan.md](docs/notes_for_asan.md) for tips. - There is no direct support for fuzzing network services, background diff --git a/afl-whatsup b/afl-whatsup index 6a8c5669..6156ba11 100755 --- a/afl-whatsup +++ b/afl-whatsup @@ -45,7 +45,7 @@ if [ "$DIR" = "" ]; then echo "Usage: $0 [ -s ] afl_sync_dir" 1>&2 echo 1>&2 echo "The -s option causes the tool to skip all the per-fuzzer trivia and show" 1>&2 - echo "just the summary results. See docs/parallel_fuzzing.txt for additional tips." 1>&2 + echo "just the summary results. See docs/parallel_fuzzing.md for additional tips." 1>&2 echo 1>&2 exit 1 diff --git a/custom_mutators/README b/custom_mutators/README deleted file mode 100644 index e83baa67..00000000 --- a/custom_mutators/README +++ /dev/null @@ -1,2 +0,0 @@ -This is a simple example for the AFL_CUSTOM_MUTATOR_LIBRARY feature. -For more information see docs/custom_mutator.txt diff --git a/docs/ChangeLog b/docs/ChangeLog index a559f6f2..f5430057 100644 --- a/docs/ChangeLog +++ b/docs/ChangeLog @@ -24,6 +24,7 @@ Version ++2.60d (develop): - Android: prefer bigcores when selecting a CPU - CmpLog forkserver - Redqueen input-2-state mutator (cmp instructions only ATM) + - all python 2+3 versions supported now - afl-clang-fast: - show in the help output for which llvm version it was compiled for - now does not need to be recompiled between trace-pc and pass @@ -32,6 +33,8 @@ Version ++2.60d (develop): - CmpLog mode (see llvm_mode/README.cmplog) - afl-cmin is now a sh script (invoking awk) instead of bash for portability the original script is still present as afl-cmin.bash + - afl-showmap: -i dir option now allows processing multiple inputs using the + forkserver. This is for enhanced speed in afl-cmin. - added blacklist and whitelisting function check in all modules of llvm_mode - added fix from Debian project to compile libdislocator and libtokencap - libdislocator: AFL_ALIGNED_ALLOC to force size alignment to max_align_t @@ -43,9 +46,9 @@ Version ++2.60c (release): - fixed a critical bug in afl-tmin that was introduced during ++2.53d - added test cases for afl-cmin and afl-tmin to test/test.sh - - added ./experimental/argv_fuzzing ld_preload library by Kjell Braden + - added ./examples/argv_fuzzing ld_preload library by Kjell Braden - added preeny's desock_dup ld_preload library as - ./experimental/socket_fuzzing for network fuzzing + ./examples/socket_fuzzing for network fuzzing - added AFL_AS_FORCE_INSTRUMENT environment variable for afl-as - this is for the retrorewrite project - we now set QEMU_SET_ENV from AFL_PRELOAD when qemu_mode is used @@ -512,7 +515,7 @@ Version 2.27b: - Moved libdislocator to its own dir, added README. - - The demo in experimental/instrumented_cmp is no more. + - The demo in examples/instrumented_cmp is no more. -------------- Version 2.26b: @@ -666,7 +669,7 @@ Version 2.11b: - Made an improvement to afl-gotcpu when -Z not used. - - Fixed a typo in post_library_png.so.c in experimental/. Spotted by Kostya + - Fixed a typo in post_library_png.so.c in examples/. Spotted by Kostya Serebryany. -------------- @@ -1066,7 +1069,7 @@ Version 1.75b: Version 1.74b: -------------- - - Added an example argv[] fuzzing wrapper in experimental/argv_fuzzing. + - Added an example argv[] fuzzing wrapper in examples/argv_fuzzing. Reworked the bash example to be faster, too. - Clarified llvm_mode prerequisites for FreeBSD. @@ -1231,12 +1234,12 @@ Version 1.61b: Version 1.60b: -------------- - - Allowed experimental/llvm_instrumentation/ to graduate to llvm_mode/. + - Allowed examples/llvm_instrumentation/ to graduate to llvm_mode/. - - Removed experimental/arm_support/, since it's completely broken and likely + - Removed examples/arm_support/, since it's completely broken and likely unnecessary with LLVM support in place. - - Added ASAN cgroups script to experimental/asan_cgroups/, updated existing + - Added ASAN cgroups script to examples/asan_cgroups/, updated existing docs. Courtesy Sam Hakim and David A. Wheeler. - Refactored afl-tmin to reduce the number of execs in common use cases. @@ -1256,7 +1259,7 @@ Version 1.59b: -------------- - Imported Laszlo Szekeres' experimental LLVM instrumentation into - experimental/llvm_instrumentation. I'll work on including it in the + examples/llvm_instrumentation. I'll work on including it in the "mainstream" version soon. - Fixed another typo, thanks to Jakub Wilk. @@ -1305,7 +1308,7 @@ Version 1.54b: - Added another postprocessor example for PNG. - - Made a cosmetic fix to realloc() handling in experimental/post_library/, + - Made a cosmetic fix to realloc() handling in examples/post_library/, suggested by Jakub Wilk. - Improved -ldl handling. Suggested by Jakub Wilk. @@ -1323,7 +1326,7 @@ Version 1.52b: - Added support for file format postprocessors. Requested by Ben Nagy. This feature is intentionally buried, since it's fairly easy to misuse and - useful only in some scenarios. See experimental/post_library/. + useful only in some scenarios. See examples/post_library/. -------------- Version 1.51b: @@ -1958,7 +1961,7 @@ Version 0.98b: - Fixed another cosmetic snafu with stage exec counts for -x. - Switched afl-plot to /bin/sh, since it seems bashism-free. Also tried - to remove any obvious bashisms from other experimental/ scripts, + to remove any obvious bashisms from other examples/ scripts, most notably including minimize_corpus.sh and triage_crashes.sh. Requested by Jonathan Gray. @@ -2126,7 +2129,7 @@ Version 0.84b: Version 0.83b: -------------- - - Added experimental/clang_asm_normalize/ and related notes in + - Added examples/clang_asm_normalize/ and related notes in env_variables.txt and afl-as.c. Thanks to Ryan Govostes for the idea. - Added advice on hardware utilization in README. @@ -2350,7 +2353,7 @@ Version 0.62b: - Made minor improvements to the allocator, as suggested by Tobias Ospelt. - - Added example instrumented memcmp() in experimental/instrumented_cmp. + - Added example instrumented memcmp() in examples/instrumented_cmp. - Added a speculative fix for MacOS X (clang detection, again). @@ -2475,7 +2478,7 @@ Version 0.53b: Version 0.52b: -------------- - - Added a quick summary of the contents in experimental/. + - Added a quick summary of the contents in examples/. - Made a fix to the process of writing fuzzer_stats. @@ -2637,7 +2640,7 @@ Version 0.43b: - Added status_screen.txt. - - Added experimental/canvas_harness. + - Added examples/canvas_harness. - Made a minor change to the Makefile GCC check. Suggested by Hanno Boeck. @@ -2648,7 +2651,7 @@ Version 0.42b: - Fixed a bug with red zone handling for 64-bit (oops!). Problem reported by Felix Groebert. - - Implemented horribly experimental ARM support in experimental/arm_support. + - Implemented horribly experimental ARM support in examples/arm_support. - Made several improvements to error messages. @@ -2687,7 +2690,7 @@ Version 0.40b: - Added support for parallelized fuzzing. Inspired by earlier patch from Sebastian Roschke. - - Added an example in experimental/distributed_fuzzing/. + - Added an example in examples/distributed_fuzzing/. -------------- Version 0.39b: @@ -2837,7 +2840,7 @@ Version 0.26b: - Added a built-in effort minimizer to get rid of potentially redundant inputs, - - Provided a testcase count minimization script in experimental/, + - Provided a testcase count minimization script in examples/, - Made miscellaneous improvements to directory and file handling. diff --git a/docs/INSTALL b/docs/INSTALL.md index 2e24724f..0f9673ad 100644 --- a/docs/INSTALL +++ b/docs/INSTALL.md @@ -1,28 +1,30 @@ -========================= -Installation instructions -========================= +# Installation instructions This document provides basic installation instructions and discusses known - issues for a variety of platforms. See README for the general instruction + issues for a variety of platforms. See README.md for the general instruction manual. -1) Linux on x86 +## 1) Linux on x86 --------------- This platform is expected to work well. Compile the program with: -$ make +```bash +make +``` You can start using the fuzzer without installation, but it is also possible to install it with: -# make install +```bash +make install +``` There are no special dependencies to speak of; you will need GNU make and a working compiler (gcc or clang). Some of the optional scripts bundled with the program may depend on bash, gdb, and similar basic tools. -If you are using clang, please review llvm_mode/README.llvm; the LLVM +If you are using clang, please review llvm_mode/README.md; the LLVM integration mode can offer substantial performance gains compared to the traditional approach. @@ -30,27 +32,30 @@ You may have to change several settings to get optimal results (most notably, disable crash reporting utilities and switch to a different CPU governor), but afl-fuzz will guide you through that if necessary. -2) OpenBSD, FreeBSD, NetBSD on x86 ----------------------------------- +## OpenBSD, FreeBSD, NetBSD on x86 Similarly to Linux, these platforms are expected to work well and are regularly tested. Compile everything with GNU make: -$ gmake +```bash +gmake +``` Note that BSD make will *not* work; if you do not have gmake on your system, please install it first. As on Linux, you can use the fuzzer itself without installation, or install it with: -# gmake install +``` +gmake install +``` Keep in mind that if you are using csh as your shell, the syntax of some of the -shell commands given in the README and other docs will be different. +shell commands given in the README.md and other docs will be different. -The llvm_mode requires a dynamically linked, fully-operational installation of +The `llvm_mode` requires a dynamically linked, fully-operational installation of clang. At least on FreeBSD, the clang binaries are static and do not include some of the essential tools, so if you want to make it work, you may need to -follow the instructions in llvm_mode/README.llvm. +follow the instructions in llvm_mode/README.md. Beyond that, everything should work as advertised. @@ -58,8 +63,7 @@ The QEMU mode is currently supported only on Linux. I think it's just a QEMU problem, I couldn't get a vanilla copy of user-mode emulation support working correctly on BSD at all. -3) MacOS X on x86 ------------------ +## 3. MacOS X on x86 MacOS X should work, but there are some gotchas due to the idiosyncrasies of the platform. On top of this, I have limited release testing capabilities @@ -69,8 +73,8 @@ To build AFL, install Xcode and follow the general instructions for Linux. The Xcode 'gcc' tool is just a wrapper for clang, so be sure to use afl-clang to compile any instrumented binaries; afl-gcc will fail unless you have GCC -installed from another source (in which case, please specify AFL_CC and -AFL_CXX to point to the "real" GCC binaries). +installed from another source (in which case, please specify `AFL_CC` and +`AFL_CXX` to point to the "real" GCC binaries). Only 64-bit compilation will work on the platform; porting the 32-bit instrumentation would require a fair amount of work due to the way OS X @@ -80,47 +84,45 @@ The crash reporting daemon that comes by default with MacOS X will cause problems with fuzzing. You need to turn it off by following the instructions provided here: http://goo.gl/CCcd5u -The fork() semantics on OS X are a bit unusual compared to other unix systems +The `fork()` semantics on OS X are a bit unusual compared to other unix systems and definitely don't look POSIX-compliant. This means two things: - Fuzzing will be probably slower than on Linux. In fact, some folks report considerable performance gains by running the jobs inside a Linux VM on MacOS X. - - Some non-portable, platform-specific code may be incompatible with the - AFL forkserver. If you run into any problems, set AFL_NO_FORKSRV=1 in the + AFL forkserver. If you run into any problems, set `AFL_NO_FORKSRV=1` in the environment before starting afl-fuzz. User emulation mode of QEMU does not appear to be supported on MacOS X, so -black-box instrumentation mode (-Q) will not work. +black-box instrumentation mode (`-Q`) will not work. The llvm_mode requires a fully-operational installation of clang. The one that comes with Xcode is missing some of the essential headers and helper tools. -See llvm_mode/README.llvm for advice on how to build the compiler from scratch. +See llvm_mode/README.md for advice on how to build the compiler from scratch. -4) Linux or *BSD on non-x86 systems ------------------------------------ +## 4. Linux or *BSD on non-x86 systems Standard build will fail on non-x86 systems, but you should be able to leverage two other options: - - The LLVM mode (see llvm_mode/README.llvm), which does not rely on + - The LLVM mode (see llvm_mode/README.md), which does not rely on x86-specific assembly shims. It's fast and robust, but requires a complete installation of clang. - - - The QEMU mode (see qemu_mode/README.qemu), which can be also used for + - The QEMU mode (see qemu_mode/README.md), which can be also used for fuzzing cross-platform binaries. It's slower and more fragile, but can be used even when you don't have the source for the tested app. If you're not sure what you need, you need the LLVM mode. To get it, try: -$ AFL_NO_X86=1 gmake && gmake -C llvm_mode +```bash +AFL_NO_X86=1 gmake && gmake -C llvm_mode +``` ...and compile your target program with afl-clang-fast or afl-clang-fast++ instead of the traditional afl-gcc or afl-clang wrappers. -5) Solaris on x86 ------------------ +## 5. Solaris on x86 The fuzzer reportedly works on Solaris, but I have not tested this first-hand, and the user base is fairly small, so I don't have a lot of feedback. @@ -128,36 +130,39 @@ and the user base is fairly small, so I don't have a lot of feedback. To get the ball rolling, you will need to use GNU make and GCC or clang. I'm being told that the stock version of GCC that comes with the platform does not work properly due to its reliance on a hardcoded location for 'as' (completely -ignoring the -B parameter or $PATH). +ignoring the `-B` parameter or `$PATH`). To fix this, you may want to build stock GCC from the source, like so: -$ ./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \ +```sh +./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \ --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr -$ make -$ sudo make install +make +sudo make install +``` -Do *not* specify --with-as=/usr/gnu/bin/as - this will produce a GCC binary that -ignores the -B flag and you will be back to square one. +Do *not* specify `--with-as=/usr/gnu/bin/as` - this will produce a GCC binary that +ignores the `-B` flag and you will be back to square one. Note that Solaris reportedly comes with crash reporting enabled, which causes problems with crashes being misinterpreted as hangs, similarly to the gotchas for Linux and MacOS X. AFL does not auto-detect crash reporting on this particular platform, but you may need to run the following command: -$ coreadm -d global -d global-setid -d process -d proc-setid \ +```sh +coreadm -d global -d global-setid -d process -d proc-setid \ -d kzone -d log +``` User emulation mode of QEMU is not available on Solaris, so black-box -instrumentation mode (-Q) will not work. +instrumentation mode (`-Q`) will not work. -6) Everything else ------------------- +## 6. Everything else You're on your own. On POSIX-compliant systems, you may be able to compile and run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code. -The fuzzer will not run on Windows. It will also not work under Cygwin. It +The fuzzer will run on Windows in WSL only. It will not work under Cygwin on in the normal Windows world. It could be ported to the latter platform fairly easily, but it's a pretty bad idea, because Cygwin is extremely slow. It makes much more sense to use VirtualBox or so to run a hardware-accelerated Linux VM; it will run around @@ -171,13 +176,15 @@ It's possible that all you need is this workaround: https://github.com/pelya/android-shmem Joshua J. Drake notes that the Android linker adds a shim that automatically -intercepts SIGSEGV and related signals. To fix this issue and be able to see +intercepts `SIGSEGV` and related signals. To fix this issue and be able to see crashes, you need to put this at the beginning of the fuzzed program: +```sh signal(SIGILL, SIG_DFL); signal(SIGABRT, SIG_DFL); signal(SIGBUS, SIG_DFL); signal(SIGFPE, SIG_DFL); signal(SIGSEGV, SIG_DFL); +``` -You may need to #include <signal.h> first. +You may need to `#include <signal.h>` first. diff --git a/docs/PATCHES b/docs/PATCHES.md index 50bcb32f..1dfb6622 100644 --- a/docs/PATCHES +++ b/docs/PATCHES.md @@ -1,9 +1,11 @@ +# Applied Patches + The following patches from https://github.com/vanhauser-thc/afl-patches have been installed or not installed: -INSTALLED -========= +## INSTALLED +``` afl-llvm-fix.diff by kcwu(at)csie(dot)org afl-sort-all_uniq-fix.diff by legarrec(dot)vincent(at)gmail(dot)com laf-intel.diff by heiko(dot)eissfeldt(at)hexco(dot)de @@ -16,6 +18,7 @@ afl-qemu-ppc64.diff by william(dot)barsse(at)airbus(dot)com afl-qemu-optimize-entrypoint.diff by mh(at)mh-sec(dot)de afl-qemu-speed.diff by abiondo on github afl-qemu-optimize-map.diff by mh(at)mh-sec(dot)de +``` + Custom mutator (native library) (by kyakdan) + unicorn_mode (modernized and updated by domenukk) @@ -28,10 +31,12 @@ afl-qemu-optimize-map.diff by mh(at)mh-sec(dot)de + forkserver patch for afl-tmin (github.com/nccgroup/TriforceAFL) -NOT INSTALLED -============= +## NOT INSTALLED + +``` afl-fuzz-context_sensitive.diff - changes too much of the behaviour afl-tmpfs.diff - same as afl-fuzz-tmpdir.diff but more complex afl-cmin-reduce-dataset.diff - unsure of the impact afl-llvm-fix2.diff - not needed with the other patches +``` diff --git a/docs/QuickStartGuide.txt b/docs/QuickStartGuide.md index 723611e3..f9e3b256 100644 --- a/docs/QuickStartGuide.txt +++ b/docs/QuickStartGuide.md @@ -1,11 +1,9 @@ -===================== -AFL quick start guide -===================== +# AFL quick start guide -You should read docs/README.md - it's pretty short. If you really can't, here's +You should read [README.md](README.md) - 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. +1) Compile AFL with 'make'. If build fails, see [INSTALL.md](INSTALL.md) 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. @@ -17,7 +15,7 @@ how to hit the ground running: The program must crash properly when a fault is encountered. Watch out for custom SIGSEGV or SIGABRT handlers and background processes. For tips on - detecting non-crashing flaws, see section 11 in docs/README.md . + detecting non-crashing flaws, see section 11 in [README.md](README.md) . 3) Compile the program / library to be fuzzed using afl-gcc. A common way to do this would be: @@ -40,7 +38,7 @@ how to hit the ground running: 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. + [status_screen.md](status_screen.md). 7) compile and use llvm_mode (afl-clang-fast/afl-clang-fast++) as it is way faster and has a few cool features @@ -50,7 +48,7 @@ how to hit the ground running: That's it. Sit back, relax, and - time permitting - try to skim through the following files: - - docs/README.md - 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. + - README.md - A general introduction to AFL, + - docs/perf_tips.md - Simple tips on how to fuzz more quickly, + - docs/status_screen.md - An explanation of the tidbits shown in the UI, + - docs/parallel_fuzzing.md - Advice on running AFL on multiple cores. diff --git a/docs/README.MOpt b/docs/README.MOpt.md index 94e63959..94e63959 100644 --- a/docs/README.MOpt +++ b/docs/README.MOpt.md diff --git a/docs/README.md b/docs/README.md index 32d46ee8..3b572d42 120000..100644 --- a/docs/README.md +++ b/docs/README.md @@ -1 +1,682 @@ -../README.md \ No newline at end of file +# american fuzzy lop plus plus (afl++) + +  + + Release Version: 2.60c + + Github Version: 2.60d + + includes all necessary/interesting changes from Google's afl 2.56b + + + Originally developed by Michal "lcamtuf" Zalewski. + + Repository: [https://github.com/vanhauser-thc/AFLplusplus](https://github.com/vanhauser-thc/AFLplusplus) + + afl++ is maintained by Marc "van Hauser" Heuse <mh@mh-sec.de>, + Heiko "hexcoder-" Eißfeldt <heiko.eissfeldt@hexco.de>, Andrea Fioraldi <andreafioraldi@gmail.com> and Dominik Maier <mail@dmnk.co>. + + Note that although afl now has a Google afl repository [https://github.com/Google/afl](https://github.com/Google/afl), + it is unlikely to receive any noteable enhancements: [https://twitter.com/Dor3s/status/1154737061787660288](https://twitter.com/Dor3s/status/1154737061787660288) + + +## The enhancements compared to the original stock afl + + Many improvements were made over the official afl release - which did not + get any feature improvements since November 2017. + + Among other changes afl++ has a more performant llvm_mode, supports + llvm up to version 11, QEMU 3.1, more speed and crashfixes for QEMU, + better *BSD and Android support and much, much more. + + Additionally the following features and patches have been integrated: + + * AFLfast's power schedules by Marcel Böhme: [https://github.com/mboehme/aflfast](https://github.com/mboehme/aflfast) + + * The new excellent MOpt mutator: [https://github.com/puppet-meteor/MOpt-AFL](https://github.com/puppet-meteor/MOpt-AFL) + + * InsTrim, a very effective CFG llvm_mode instrumentation implementation for large targets: [https://github.com/csienslab/instrim](https://github.com/csienslab/instrim) + + * C. Holler's afl-fuzz Python mutator module and llvm_mode whitelist support: [https://github.com/choller/afl](https://github.com/choller/afl) + + * Custom mutator by a library (instead of Python) by kyakdan + + * unicorn_mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk) + + * laf-intel or CompCov support for llvm_mode, qemu_mode and unicorn_mode + + * NeverZero patch for afl-gcc, llvm_mode, qemu_mode and unicorn_mode which prevents a wrapping map value to zero, increases coverage + + * Persistent mode and deferred forkserver for qemu_mode + + * Win32 PE binary-only fuzzing with QEMU and Wine + + * Radamsa mutator (enable with `-R` to add or `-RR` to run it exclusivly). + + * qbdi_mode: fuzz android native libraries via QBDI framework + + + A more thorough list is available in the PATCHES file. + + | Feature/Instrumentation | afl-gcc | llvm_mode | gcc_plugin | qemu_mode | unicorn_mode | + | ----------------------- |:-------:|:---------:|:----------:|:---------:|:------------:| + | laf-intel / CompCov | | x | | x86/arm | x86/arm | + | NeverZero | x | x(1) | (2) | x | x | + | Persistent mode | | x | x | x86 | x | + | Whitelist | | x | x | | | + | InsTrim | | x | | | | + + neverZero: + + (1) only in LLVM >= 9.0 due to a bug in llvm in previous versions + + (2) gcc creates non-performant code, hence it is disabled in gcc_plugin + + So all in all this is the best-of afl that is currently out there :-) + + For new versions and additional information, check out: + [https://github.com/vanhauser-thc/AFLplusplus](https://github.com/vanhauser-thc/AFLplusplus) + + To compare notes with other users or get notified about major new features, + send a mail to <afl-users+subscribe@googlegroups.com>. + + See [docs/QuickStartGuide.md](docs/QuickStartGuide.md) if you don't have time to + read this file. + + +## 0) Building and installing afl++ + +afl++ has many build options. +The easiest is to build and install everything: + +```shell +$ make distrib +$ sudo make install +``` + +Note that "make distrib" also builds llvm_mode, qemu_mode, unicorn_mode and +more. If you just want plain afl then do "make all", however compiling and +using at least llvm_mode is highly recommended for much better results - +hence in this case + +```shell +$ make source-only +``` +is what you should choose. + +These build options exist: + +* all: just the main afl++ binaries +* binary-only: everything for binary-only fuzzing: qemu_mode, unicorn_mode, libdislocator, libtokencap, radamsa +* source-only: everything for source code fuzzing: llvm_mode, libdislocator, libtokencap, radamsa +* distrib: everything (for both binary-only and source code fuzzing) +* install: installs everything you have compiled with the build options above +* clean: cleans everything. for qemu_mode and unicorn_mode it means it deletes all downloads as well +* code-format: format the code, do this before you commit and send a PR please! +* tests: runs test cases to ensure that all features are still working as they should +* help: shows these build options + +[Unless you are on Mac OS X](https://developer.apple.com/library/archive/qa/qa1118/_index.html) you can also build statically linked versions of the +afl++ binaries by passing the STATIC=1 argument to make: + +```shell +$ make all STATIC=1 +``` + +Note that afl++ is faster and better the newer the compilers used are. +Hence gcc-9 and especially llvm-9 should be the compilers of choice. +If your distribution does not have them, you can use the Dockerfile: + +```shell +$ docker build -t aflplusplus +``` + + +## 1) Challenges of guided fuzzing + +Fuzzing is one of the most powerful and proven strategies for identifying +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 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 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: + + 1) Load user-supplied initial test cases into the queue, + + 2) Take next input file from the queue, + + 3) Attempt to trim the test case to the smallest size that doesn't alter + the measured behavior of the program, + + 4) Repeatedly mutate the file using a balanced and well-researched variety + of traditional fuzzing strategies, + + 5) If any of the generated mutations resulted in a new state transition + recorded by the instrumentation, add mutated output as a new entry in the + queue. + + 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 +instrumentation-driven effort minimization steps. + +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 out-of-the-box performance far +superior to blind fuzzing or coverage-only tools. + + +## 3) Instrumenting programs for use with AFL + +PLEASE NOTE: llvm_mode compilation with afl-clang-fast/afl-clang-fast++ +instead of afl-gcc/afl-g++ is much faster and has a few cool features. +See llvm_mode/ - however few code does not compile with llvm. +We support llvm versions 3.8.0 to 11. + +When source code is available, instrumentation can be injected by a companion +tool that works as a drop-in replacement for gcc or clang in any standard build +process for third-party code. + +The instrumentation has a fairly modest performance impact; in conjunction with +other optimizations implemented by afl-fuzz, most programs can be fuzzed as fast +or even faster than possible with traditional tools. + +The correct way to recompile the target program may vary depending on the +specifics of the build process, but a nearly-universal approach would be: + +```shell +$ CC=/path/to/afl/afl-gcc ./configure +$ make clean all +``` + +For C++ programs, you'd would also want to set `CXX=/path/to/afl/afl-g++`. + +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.md](llvm_mode/README.md). +Clang/LLVM has a much better performance and works with LLVM version 3.8.0 to 11. + +Using the LAF Intel performance enhancements are also recommended, see +[llvm_mode/README.laf-intel.md](llvm_mode/README.laf-intel.md) + +Using partial instrumentation is also recommended, see +[llvm_mode/README.whitelist.md](llvm_mode/README.whitelist.md) + +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: + +```shell +$ 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. Libdislocator, a helper library included with AFL (see +[libdislocator/README.md](libdislocator/README.md)) can help uncover heap corruption issues, too. + +PS. ASAN users are advised to review [docs/notes_for_asan.md](docs/notes_for_asan.md) +file for important caveats. + + +## 4) Instrumenting binary-only apps + +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: + +```shell +$ cd qemu_mode +$ ./build_qemu_support.sh +``` + +For additional instructions and caveats, see [qemu_mode/README.md](qemu_mode/README.md). + +The mode is approximately 2-5x slower than compile-time instrumentation, is +less conducive to parallelization, and may have some other quirks. + +If [afl-dyninst](https://github.com/vanhauser-thc/afl-dyninst) works for +your binary, then you can use afl-fuzz normally and it will have twice +the speed compared to qemu_mode. + +A more comprehensive description of these and other options can be found in +[docs/binaryonly_fuzzing.md](docs/binaryonly_fuzzing.md) + + +## 5) Power schedules + +The power schedules were copied from Marcel Böhme's excellent AFLfast +implementation and expand on the ability to discover new paths and +therefore may increase the code coverage. + +The available schedules are: + + - explore (default) + - fast + - coe + - quad + - lin + - exploit + +In parallel mode (-M/-S, several instances with shared queue), we suggest to +run the master using the exploit schedule (-p exploit) and the slaves with a +combination of cut-off-exponential (-p coe), exponential (-p fast; default), +and explore (-p explore) schedules. + +In single mode, using -p fast is usually more beneficial than the default +explore mode. +(We don't want to change the default behaviour of afl, so "fast" has not been +made the default mode). + +More details can be found in the paper published at the 23rd ACM Conference on +Computer and Communications Security [CCS'16](https://www.sigsac.org/ccs/CCS2016/accepted-papers/) +## 6) Choosing initial test cases + +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 matters, see [perf_tips.md](docs/perf_tips.md). + + - 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. + + +## 7) Fuzzing binaries + +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 target binaries that accept input directly from stdin, the usual syntax is: + +```shell +$ ./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's command line where the input file name should be placed. The +fuzzer will substitute this for you: + +```shell +$ ./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 (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; 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.md](docs/perf_tips.md). + +Note that afl-fuzz starts by performing an array of deterministic fuzzing +steps, which can take several days, but tend to produce neat test cases. If you +want quick & dirty results right away - akin to zzuf and other traditional +fuzzers - add the -d option to the command line. + + +## 8) Interpreting output + +See the [docs/status_screen.md](docs/status_screen.md) 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 the synthesized corpus + mentioned in section 2. + + 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. The + default time limit before something is classified as a hang is + the larger of 1 second and the value of the -t parameter. + The value can be fine-tuned by setting AFL_HANG_TMOUT, but this + is rarely necessary. + +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 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: + +```shell +$ LIMIT_MB=50 +$ ( ulimit -Sv $[LIMIT_MB << 10]; /path/to/tested_binary ... ) +``` + +Change LIMIT_MB to match the -m parameter passed to afl-fuzz. On OpenBSD, +also change -Sv to -Sd. + +Any existing output directory can be also used to resume aborted jobs; try: + +```shell +$ ./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, +see [http://lcamtuf.coredump.cx/afl/plot/](http://lcamtuf.coredump.cx/afl/plot/). + + +## 9) Parallelized fuzzing + +Every instance of afl-fuzz takes up roughly one core. This means that on +multi-core systems, parallelization is necessary to fully utilize the hardware. +For tips on how to fuzz a common target on multiple cores or multiple networked +machines, please refer to [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md). + +The parallel fuzzing mode also offers a simple way for interfacing AFL to other +fuzzers, to symbolic or concolic execution engines, and so forth; again, see the +last section of [docs/parallel_fuzzing.md](docs/parallel_fuzzing.md) for tips. + + +## 10) Fuzzer dictionaries + +By default, afl-fuzz mutation engine is optimized for compact data formats - +say, images, multimedia, compressed data, regular expression syntax, or shell +scripts. It is somewhat less suited for languages with particularly verbose and +redundant verbiage - notably including HTML, SQL, or JavaScript. + +To avoid the hassle of building syntax-aware tools, afl-fuzz provides a way to +seed the fuzzing process with an optional dictionary of language keywords, +magic headers, or other special tokens associated with the targeted data type +-- and use that to reconstruct the underlying grammar on the go: + + [http://lcamtuf.blogspot.com/2015/01/afl-fuzz-making-up-grammar-with.html](http://lcamtuf.blogspot.com/2015/01/afl-fuzz-making-up-grammar-with.html) + +To use this feature, you first need to create a dictionary in one of the two +formats discussed in [dictionaries/README.md](dictionaries/README.md); +and then point the fuzzer to it via the -x option in the command line. + +(Several common dictionaries are already provided in that subdirectory, too.) + +There is no way to provide more structured descriptions of the underlying +syntax, but the fuzzer will likely figure out some of this based on the +instrumentation feedback alone. This actually works in practice, say: + + [http://lcamtuf.blogspot.com/2015/04/finding-bugs-in-sqlite-easy-way.html](http://lcamtuf.blogspot.com/2015/04/finding-bugs-in-sqlite-easy-way.html) + +PS. Even when no explicit dictionary is given, afl-fuzz will try to extract +existing syntax tokens in the input corpus by watching the instrumentation +very closely during deterministic byte flips. This works for some types of +parsers and grammars, but isn't nearly as good as the -x mode. + +If a dictionary is really hard to come by, another option is to let AFL run +for a while, and then use the token capture library that comes as a companion +utility with AFL. For that, see [libtokencap/README.md](libtokencap/README.tokencap.md). + + +## 11) Crash triage + +The coverage-based grouping of crashes usually produces a small data set that +can be quickly triaged manually or with a very simple GDB or Valgrind script. +Every crash is also traceable to its parent non-crashing test case in the +queue, making it easier to diagnose faults. + +Having said that, it's important to acknowledge that some fuzzing crashes can be +difficult to quickly evaluate for exploitability without a lot of debugging and +code analysis work. To assist with this task, afl-fuzz supports a very unique +"crash exploration" mode enabled with the -C flag. + +In this mode, the fuzzer takes one or more crashing test cases as the input, +and uses its feedback-driven fuzzing strategies to very quickly enumerate all +code paths that can be reached in the program while keeping it in the +crashing state. + +Mutations that do not result in a crash are rejected; so are any changes that +do not affect the execution path. + +The output is a small corpus of files that can be very rapidly examined to see +what degree of control the attacker has over the faulting address, or whether +it is possible to get past an initial out-of-bounds read - and see what lies +beneath. + +Oh, one more thing: for test case minimization, give afl-tmin a try. The tool +can be operated in a very simple way: + +```shell +$ ./afl-tmin -i test_case -o minimized_result -- /path/to/program [...] +``` + +The tool works with crashing and non-crashing test cases alike. In the crash +mode, it will happily accept instrumented and non-instrumented binaries. In the +non-crashing mode, the minimizer relies on standard AFL instrumentation to make +the file simpler without altering the execution path. + +The minimizer accepts the -m, -t, -f and @@ syntax in a manner compatible with +afl-fuzz. + +Another recent addition to AFL is the afl-analyze tool. It takes an input +file, attempts to sequentially flip bytes, and observes the behavior of the +tested program. It then color-codes the input based on which sections appear to +be critical, and which are not; while not bulletproof, it can often offer quick +insights into complex file formats. More info about its operation can be found +near the end of [docs/technical_details.md](docs/technical_details.md). + + +## 12) Going beyond crashes + +Fuzzing is a wonderful and underutilized technique for discovering non-crashing +design and implementation errors, too. Quite a few interesting bugs have been +found by modifying the target programs to call abort() when, say: + + - Two bignum libraries produce different outputs when given the same + fuzzer-generated input, + + - An image library produces different outputs when asked to decode the same + input image several times in a row, + + - A serialization / deserialization library fails to produce stable outputs + when iteratively serializing and deserializing fuzzer-supplied data, + + - A compression library produces an output inconsistent with the input file + when asked to compress and then decompress a particular blob. + +Implementing these or similar sanity checks usually takes very little time; +if you are the maintainer of a particular package, you can make this code +conditional with `#ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION` (a flag also +shared with libfuzzer) or `#ifdef __AFL_COMPILER` (this one is just for AFL). + + +## 13) Common-sense risks + +Please keep in mind that, similarly to many other computationally-intensive +tasks, fuzzing may put strain on your hardware and on the OS. In particular: + + - Your CPU will run hot and will need adequate cooling. In most cases, if + cooling is insufficient or stops working properly, CPU speeds will be + automatically throttled. That said, especially when fuzzing on less + suitable hardware (laptops, smartphones, etc), it's not entirely impossible + for something to blow up. + + - Targeted programs may end up erratically grabbing gigabytes of memory or + filling up disk space with junk files. AFL tries to enforce basic memory + limits, but can't prevent each and every possible mishap. The bottom line + is that you shouldn't be fuzzing on systems where the prospect of data loss + is not an acceptable risk. + + - Fuzzing involves billions of reads and writes to the filesystem. On modern + systems, this will be usually heavily cached, resulting in fairly modest + "physical" I/O - but there are many factors that may alter this equation. + It is your responsibility to monitor for potential trouble; with very heavy + I/O, the lifespan of many HDDs and SSDs may be reduced. + + A good way to monitor disk I/O on Linux is the 'iostat' command: + +```shell + $ iostat -d 3 -x -k [...optional disk ID...] +``` + + +## 14) Known limitations & areas for improvement + +Here are some of the most important caveats for AFL: + + - AFL detects faults by checking for the first spawned process dying due to + a signal (SIGSEGV, SIGABRT, etc). Programs that install custom handlers for + these signals may need to have the relevant code commented out. In the same + vein, faults in child processed spawned by the fuzzed target may evade + detection unless you manually add some code to catch that. + + - As with any other brute-force tool, the fuzzer offers limited coverage if + encryption, checksums, cryptographic signatures, or compression are used to + wholly wrap the actual data format to be tested. + + To work around this, you can comment out the relevant checks (see + examples/libpng_no_checksum/ for inspiration); if this is not possible, + you can also write a postprocessor, as explained in + examples/post_library/ (with AFL_POST_LIBRARY) + + - There are some unfortunate trade-offs with ASAN and 64-bit binaries. This + isn't due to any specific fault of afl-fuzz; see [docs/notes_for_asan.md](docs/notes_for_asan.md) + for tips. + + - There is no direct support for fuzzing network services, background + daemons, or interactive apps that require UI interaction to work. You may + need to make simple code changes to make them behave in a more traditional + way. Preeny may offer a relatively simple option, too - see: + [https://github.com/zardus/preeny](https://github.com/zardus/preeny) + + Some useful tips for modifying network-based services can be also found at: + [https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop](https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop) + + - AFL doesn't output human-readable coverage data. If you want to monitor + coverage, use afl-cov from Michael Rash: [https://github.com/mrash/afl-cov](https://github.com/mrash/afl-cov) + + - Occasionally, sentient machines rise against their creators. If this + happens to you, please consult [http://lcamtuf.coredump.cx/prep/](http://lcamtuf.coredump.cx/prep/). + +Beyond this, see INSTALL for platform-specific tips. + + +## 15) Special thanks + +Many of the improvements to the original afl and afl++ wouldn't be possible +without feedback, bug reports, or patches from: + +``` + Jann Horn Hanno Boeck + Felix Groebert Jakub Wilk + Richard W. M. Jones Alexander Cherepanov + Tom Ritter Hovik Manucharyan + Sebastian Roschke Eberhard Mattes + Padraig Brady Ben Laurie + @dronesec Luca Barbato + Tobias Ospelt Thomas Jarosch + Martin Carpenter Mudge Zatko + Joe Zbiciak Ryan Govostes + Michael Rash William Robinet + Jonathan Gray Filipe Cabecinhas + Nico Weber Jodie Cunningham + Andrew Griffiths Parker Thompson + Jonathan Neuschaefer Tyler Nighswander + Ben Nagy Samir Aguiar + Aidan Thornton Aleksandar Nikolich + Sam Hakim Laszlo Szekeres + David A. Wheeler Turo Lamminen + Andreas Stieger Richard Godbee + Louis Dassy teor2345 + Alex Moneger Dmitry Vyukov + Keegan McAllister Kostya Serebryany + Richo Healey Martijn Bogaard + rc0r Jonathan Foote + Christian Holler Dominique Pelle + Jacek Wielemborek Leo Barnes + Jeremy Barnes Jeff Trull + Guillaume Endignoux ilovezfs + Daniel Godas-Lopez Franjo Ivancic + Austin Seipp Daniel Komaromy + Daniel Binderman Jonathan Metzman + Vegard Nossum Jan Kneschke + Kurt Roeckx Marcel Boehme + Van-Thuan Pham Abhik Roychoudhury + Joshua J. Drake Toby Hutton + Rene Freingruber Sergey Davidoff + Sami Liedes Craig Young + Andrzej Jackowski Daniel Hodson + Nathan Voss Dominik Maier + Andrea Biondo Vincent Le Garrec + Khaled Yakdan Kuang-che Wu +``` + +Thank you! + + +## 16) Contact + +Questions? Concerns? Bug reports? The contributors can be reached via +[https://github.com/vanhauser-thc/AFLplusplus](https://github.com/vanhauser-thc/AFLplusplus) + +There is also a mailing list for the afl project; to join, send a mail to +<afl-users+subscribe@googlegroups.com>. Or, if you prefer to browse +archives first, try: [https://groups.google.com/group/afl-users](https://groups.google.com/group/afl-users) diff --git a/docs/README.radamsa.md b/docs/README.radamsa.md index b4823063..b01a4c83 120000..100644 --- a/docs/README.radamsa.md +++ b/docs/README.radamsa.md @@ -1 +1,9 @@ -../src/third_party/libradamsa/README.md \ No newline at end of file +# libradamsa + +Pretranslated radamsa library. This code belongs to the radamsa author. + +> Original repository: https://gitlab.com/akihe/radamsa + +> Source commit: 7b2cc2d0 + +> The code here is adapted for AFL++ with minor changes respect the original version diff --git a/docs/binaryonly_fuzzing.md b/docs/binaryonly_fuzzing.md index 6eff30d7..ff98ed00 100644 --- a/docs/binaryonly_fuzzing.md +++ b/docs/binaryonly_fuzzing.md @@ -43,7 +43,7 @@ emulation. Runtime environment and/or loaders have to be written from scratch, if needed. On top, block chaining has been removed. This means the speed boost introduced in the patched QEMU Mode of afl++ cannot simply be ported over to - Unicorn. For further information, check out ./unicorn_mode.txt. + Unicorn. For further information, check out [unicorn_mode/README.md](../unicorn_mode/README.md). As it is included in afl++ this needs no URL. diff --git a/docs/custom_mutator.txt b/docs/custom_mutator.md index 30e6b897..19009f92 100644 --- a/docs/custom_mutator.txt +++ b/docs/custom_mutator.md @@ -1,13 +1,10 @@ -================================================== -Adding custom mutators to AFL using -================================================== +# Adding custom mutators to AFL + This file describes how you can implement custom mutations to be used in AFL. Implemented by Khaled Yakdan from Code Intelligence <yakdan@code-intelligence.de> - -1) Description --------------- +## 1) Description Custom mutator libraries can be passed to afl-fuzz to perform custom mutations on test cases beyond those available in AFL - for example, to enable structure-aware @@ -34,6 +31,6 @@ is then transforms the data into the format expected by the API before executing afl_pre_save_handler is optional and does not have to be implemented if its functionality is not needed. -2) Example ----------- -A simple example is provided in ../custom_mutators/ +## 2) Example + +A simple example is provided in ../examples/custom_mutators/ diff --git a/docs/env_variables.txt b/docs/env_variables.md index a6162767..ebfe12c2 100644 --- a/docs/env_variables.txt +++ b/docs/env_variables.md @@ -1,14 +1,11 @@ -======================= -Environmental variables -======================= +# Environmental variables - This document discusses the environment variables used by American Fuzzy Lop + This document discusses the environment variables used by American Fuzzy Lop++ to expose various exotic functions that may be (rarely) useful for power users or for some types of custom fuzzing setups. See README for the general instruction manual. -1) Settings for afl-gcc, afl-clang, and afl-as - and gcc_plugin afl-gcc-fast ----------------------------------------------------------------------------- +## 1) Settings for afl-gcc, afl-clang, and afl-as - and gcc_plugin afl-gcc-fast Because they can't directly accept command-line options, the compile-time tools make fairly broad use of environmental variables: @@ -25,7 +22,7 @@ tools make fairly broad use of environmental variables: - Setting AFL_USE_ASAN automatically enables ASAN, provided that your compiler supports that. Note that fuzzing with ASAN is mildly challenging - - see notes_for_asan.txt. + - see [notes_for_asan.md](notes_for_asan.md). (You can also enable MSAN via AFL_USE_MSAN; ASAN and MSAN come with the same gotchas; the modes are mutually exclusive. UBSAN and other exotic @@ -37,7 +34,7 @@ tools make fairly broad use of environmental variables: in your $PATH. - AFL_PATH can be used to point afl-gcc to an alternate location of afl-as. - One possible use of this is experimental/clang_asm_normalize/, which lets + One possible use of this is examples/clang_asm_normalize/, which lets you instrument hand-written assembly when compiling clang code by plugging a normalizer into the chain. (There is no equivalent feature for GCC.) @@ -75,8 +72,7 @@ tools make fairly broad use of environmental variables: - Setting AFL_CAL_FAST will speed up the initial calibration, if the application is very slow -2) Settings for afl-clang-fast / afl-clang-fast++ / afl-gcc-fast / afl-g++-fast ---------------------------------------------------------------------------------- +## 2) Settings for afl-clang-fast / afl-clang-fast++ / afl-gcc-fast / afl-g++-fast The native instrumentation helpers (llvm_mode and gcc_plugin) accept a subset of the settings discussed in section #1, with the exception of: @@ -91,8 +87,8 @@ of the settings discussed in section #1, with the exception of: Then there are a few specific features that are only available in llvm_mode: - LAF-INTEL - ========= +### LAF-INTEL + This great feature will split compares to series of single byte comparisons to allow afl-fuzz to find otherwise rather impossible paths. It is not restricted to Intel CPUs ;-) @@ -106,8 +102,8 @@ Then there are a few specific features that are only available in llvm_mode: See llvm_mode/README.laf-intel.md for more information. - WHITELIST - ========= +### WHITELIST + This feature allows selectively instrumentation of the source - Setting AFL_LLVM_WHITELIST with a filename will only instrument those @@ -115,8 +111,8 @@ Then there are a few specific features that are only available in llvm_mode: See llvm_mode/README.whitelist.md for more information. - INSTRIM - ======= +### INSTRIM + This feature increases the speed by whopping 20% but at the cost of a lower path discovery and therefore coverage. @@ -128,8 +124,7 @@ Then there are a few specific features that are only available in llvm_mode: See llvm_mode/README.instrim.md - NOT_ZERO - ======== +### NOT_ZERO - Setting AFL_LLVM_NOT_ZERO=1 during compilation will use counters that skip zero on overflow. This is the default for llvm >= 9, @@ -139,10 +134,17 @@ Then there are a few specific features that are only available in llvm_mode: See llvm_mode/README.neverzero.md +### CMPLOG + + - Setting AFL_LLVM_CMPLOG=1 during compilation will tell afl-clang-fast to + produce a CmpLog binary. See llvm_mode/README.cmplog.md + + See llvm_mode/README.neverzero.md + Then there are a few specific features that are only available in the gcc_plugin: - WHITELIST - ========= +### WHITELIST + This feature allows selective instrumentation of the source - Setting AFL_GCC_WHITELIST with a filename will only instrument those @@ -150,8 +152,7 @@ Then there are a few specific features that are only available in the gcc_plugin See gcc_plugin/README.whitelist.md for more information. -3) Settings for afl-fuzz ------------------------- +## 3) Settings for afl-fuzz The main fuzzer binary accepts several options that disable a couple of sanity checks or alter some of the more exotic semantics of the tool: @@ -214,16 +215,16 @@ checks or alter some of the more exotic semantics of the tool: 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/ + mutated files - say, to fix up checksums. See examples/post_library/ for more. - Setting AFL_CUSTOM_MUTATOR_LIBRARY to a shared library with afl_custom_mutator() export run additional mutations though this library. If AFL_CUSTOM_MUTATOR_ONLY is also set, all mutations will solely be - performed with/from the libary. see docs/custom_mutator.txt + performed with/from the libary. see [custom_mutator.md](custom_mutator.md) - For AFL_PYTHON_MODULE and AFL_PYTHON_ONLY - they require to be compiled - with -DUSE_PYTHON. Please see docs/python_mutators.txt + with -DUSE_PYTHON. Please see [python_mutators.md](python_mutators.md) This feature allows to configure custom mutators which can be very helpful in e.g. fuzzing XML or other highly flexible structured input. @@ -257,8 +258,7 @@ checks or alter some of the more exotic semantics of the tool: - Setting AFL_DEBUG_CHILD_OUTPUT will not suppress the child output. Not pretty but good for debugging purposes. -4) Settings for afl-qemu-trace ------------------------------- +## 4) Settings for afl-qemu-trace The QEMU wrapper used to instrument binary-only code supports several settings: @@ -295,9 +295,24 @@ The QEMU wrapper used to instrument binary-only code supports several settings: binary (this can be very good for the performance!). The entrypoint is specified as hex address, e.g. 0x4004110 Note that the address must be the address of a basic block. + + - When the target is i386/x86_64 you can specify the address of the function + that has to be the body of the persistent loop using + AFL_QEMU_PERSISTENT_ADDR=`start addr`. + + - Another modality to execute the persistent loop is to specify also the + AFL_QEMU_PERSISTENT_RET=`end addr` env variable. + With this variable assigned, instead of patching the return address, the + specified instruction is transformed to a jump towards `start addr`. + + - AFL_QEMU_PERSISTENT_GPR=1 QEMU will save the original value of general + purpose registers and restore them in each persistent cycle. + + - With AFL_QEMU_PERSISTENT_RETADDR_OFFSET you can specify the offset from the + stack pointer in which QEMU can find the return address when `start addr` is + hitted. -5) Settings for afl-cmin ------------------------- +## 5) Settings for afl-cmin The corpus minimization script offers very little customization: @@ -312,8 +327,7 @@ The corpus minimization script offers very little customization: a modest security risk on multi-user systems with rogue users, but should be safe on dedicated fuzzing boxes. -6) Settings for afl-tmin ------------------------- +# #6) Settings for afl-tmin Virtually nothing to play with. Well, in QEMU mode (-Q), AFL_PATH will be searched for afl-qemu-trace. In addition to this, TMPDIR may be used if a @@ -324,14 +338,12 @@ to match when minimizing crashes. This will make minimization less useful, but may prevent the tool from "jumping" from one crashing condition to another in very buggy software. You probably want to combine it with the -e flag. -7) Settings for afl-analyze ---------------------------- +## 7) Settings for afl-analyze You can set AFL_ANALYZE_HEX to get file offsets printed as hexadecimal instead of decimal. -8) Settings for libdislocator.so --------------------------------- +## 8) Settings for libdislocator The library honors these environmental variables: @@ -349,15 +361,16 @@ The library honors these environmental variables: - AFL_LD_NO_CALLOC_OVER inhibits abort() on calloc() overflows. Most of the common allocators check for that internally and return NULL, so it's a security risk only in more exotic setups. + + - AFL_ALIGNED_ALLOC=1 will force the alignment of the allocation size to + max_align_t to be compliant with the C standard. -9) Settings for libtokencap.so ------------------------------- +## 9) Settings for libtokencap This library accepts AFL_TOKEN_FILE to indicate the location to which the discovered tokens should be written. -10) Third-party variables set by afl-fuzz & other tools -------------------------------------------------------- +## 10) Third-party variables set by afl-fuzz & other tools Several variables are not directly interpreted by afl-fuzz, but are set to optimal values if not already present in the environment: @@ -371,6 +384,7 @@ optimal values if not already present in the environment: abort_on_error=1 detect_leaks=0 + malloc_context_size=0 symbolize=0 allocator_may_return_null=1 diff --git a/docs/historical_notes.txt b/docs/historical_notes.md index 741fd925..b5d3d157 100644 --- a/docs/historical_notes.txt +++ b/docs/historical_notes.md @@ -1,17 +1,14 @@ -================ -Historical notes -================ +# Historical notes This doc talks about the rationale of some of the high-level design decisions for American Fuzzy Lop. It's adopted from a discussion with Rob Graham. - See README for the general instruction manual, and technical_details.txt for + See README.md for the general instruction manual, and technical_details.md for additional implementation-level insights. -1) Influences -------------- +## 1) Influences -In short, afl-fuzz is inspired chiefly by the work done by Tavis Ormandy back -in 2007. Tavis did some very persuasive experiments using gcov block coverage +In short, `afl-fuzz` is inspired chiefly by the work done by Tavis Ormandy back +in 2007. Tavis did some very persuasive experiments using `gcov` block coverage to select optimal test cases out of a large corpus of data, and then using them as a starting point for traditional fuzzing workflows. @@ -22,7 +19,7 @@ In parallel to this, both Tavis and I were interested in evolutionary fuzzing. Tavis had his experiments, and I was working on a tool called bunny-the-fuzzer, released somewhere in 2007. -Bunny used a generational algorithm not much different from afl-fuzz, but +Bunny used a generational algorithm not much different from `afl-fuzz`, but also tried to reason about the relationship between various input bits and the internal state of the program, with hopes of deriving some additional value from that. The reasoning / correlation part was probably in part inspired by @@ -43,7 +40,7 @@ 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 the same ballpark. His fuzzer tried to explicitly solve for the maximum coverage with a single input file; in comparison, afl simply selects for cases that do -something new (which yields better results - see technical_details.txt). +something new (which yields better results - see [technical_details.md](technical_details.md)). A few years later, Gabriel Campana released fuzzgrind, a tool that relied purely on Valgrind and a constraint solver to maximize coverage without any brute-force @@ -75,8 +72,7 @@ But I digress; ultimately, attribution is hard, and glorying the fundamental concepts behind AFL is probably a waste of time. The devil is very much in the often-overlooked details, which brings us to... -2) Design goals for afl-fuzz ----------------------------- +## 2. Design goals for afl-fuzz In short, I believe that the current implementation of afl-fuzz takes care of several itches that seemed impossible to scratch with other tools: @@ -86,7 +82,7 @@ several itches that seemed impossible to scratch with other tools: likely to find a bug, but runs 100x slower, your users are getting a bad deal. - To avoid starting with a handicap, afl-fuzz is meant to let you fuzz most of + To avoid starting with a handicap, `afl-fuzz` is meant to let you fuzz most of the intended targets at roughly their native speed - so even if it doesn't add value, you do not lose much. @@ -107,7 +103,7 @@ several itches that seemed impossible to scratch with other tools: them strictly worse than "dumb" tools, and such degradation can be difficult for less experienced users to notice and correct. - In contrast, afl-fuzz is designed to be rock solid, chiefly by keeping it + In contrast, `afl-fuzz` is designed to be rock solid, chiefly by keeping it simple. In fact, at its core, it's designed to be just a very good traditional fuzzer with a wide range of interesting, well-researched strategies to go by. The fancy parts just help it focus the effort in @@ -137,11 +133,11 @@ several itches that seemed impossible to scratch with other tools: corpora of interesting test cases that can be fed into a manual testing process or a UI harness later on. -As mentioned in technical_details.txt, AFL does all this not by systematically +As mentioned in [technical_details.md](technical_details.md), AFL does all this not by systematically applying a single overarching CS concept, but by experimenting with a variety of small, complementary methods that were shown to reliably yields results better than chance. The use of instrumentation is a part of that toolkit, but is far from being the most important one. -Ultimately, what matters is that afl-fuzz is designed to find cool bugs - and +Ultimately, what matters is that `afl-fuzz` is designed to find cool bugs - and has a pretty robust track record of doing just that. diff --git a/docs/life_pro_tips.md b/docs/life_pro_tips.md new file mode 100644 index 00000000..a0d90659 --- /dev/null +++ b/docs/life_pro_tips.md @@ -0,0 +1,90 @@ +# AFL "Life Pro Tips" + +Bite-sized advice for those who understand the basics, but can't be bothered +to read or memorize every other piece of documentation for AFL. + +## Get more bang for your buck by using fuzzing dictionaries. + +See [dictionaries/README.md](../dictionaries/README.md) to learn how. + +## You can get the most out of your hardware by parallelizing AFL jobs. + +See [parallel_fuzzing.md](parallel_fuzzing.md) for step-by-step tips. + +## Improve the odds of spotting memory corruption bugs with libdislocator.so! + +It's easy. Consult [libdislocator/README.md](../libdislocator/README.md) for usage tips. + +## Want to understand how your target parses a particular input file? + +Try the bundled `afl-analyze` tool; it's got colors and all! + +## You can visually monitor the progress of your fuzzing jobs. + +Run the bundled `afl-plot` utility to generate browser-friendly graphs. + +## Need to monitor AFL jobs programmatically? +Check out the `fuzzer_stats` file in the AFL output dir or try `afl-whatsup`. + +## Puzzled by something showing up in red or purple in the AFL UI? +It could be important - consult docs/status_screen.md right away! + +## Know your target? Convert it to persistent mode for a huge performance gain! +Consult section #5 in llvm_mode/README.md for tips. + +## Using clang? +Check out llvm_mode/ for a faster alternative to afl-gcc! + +## Did you know that AFL can fuzz closed-source or cross-platform binaries? +Check out qemu_mode/README.md and unicorn_mode/README.md for more. + +## Did you know that afl-fuzz can minimize any test case for you? +Try the bundled `afl-tmin` tool - and get small repro files fast! + +## Not sure if a crash is exploitable? AFL can help you figure it out. Specify +`-C` to enable the peruvian were-rabbit mode. + +## Trouble dealing with a machine uprising? Relax, we've all been there. + +Find essential survival tips at http://lcamtuf.coredump.cx/prep/. + +## Want to automatically spot non-crashing memory handling bugs? + +Try running an AFL-generated corpus through ASAN, MSAN, or Valgrind. + +## Good selection of input files is critical to a successful fuzzing job. + +See docs/perf_tips.md for pro tips. + +## You can improve the odds of automatically spotting stack corruption issues. + +Specify `AFL_HARDEN=1` in the environment to enable hardening flags. + +## Bumping into problems with non-reproducible crashes? +It happens, but usually +isn't hard to diagnose. See section #7 in README for tips. + +## Fuzzing is not just about memory corruption issues in the codebase. +Add some +sanity-checking `assert()` / `abort()` statements to effortlessly catch logic bugs. + +## Hey kid... pssst... want to figure out how AFL really works? + +Check out docs/technical_details.md for all the gory details in one place! + +## There's a ton of third-party helper tools designed to work with AFL! + +Be sure to check out docs/sister_projects.md before writing your own. + +## Need to fuzz the command-line arguments of a particular program? + +You can find a simple solution in examples/argv_fuzzing. + +## Attacking a format that uses checksums? + +Remove the checksum-checking code or +use a postprocessor! See examples/post_library/ for more. + +## Dealing with a very slow target or hoping for instant results? + +Specify `-d` when calling afl-fuzz! \ No newline at end of file diff --git a/docs/life_pro_tips.txt b/docs/life_pro_tips.txt deleted file mode 100644 index c8c47636..00000000 --- a/docs/life_pro_tips.txt +++ /dev/null @@ -1,128 +0,0 @@ -# =================== -# AFL "Life Pro Tips" -# =================== -# -# Bite-sized advice for those who understand the basics, but can't be bothered -# to read or memorize every other piece of documentation for AFL. -# - -% - -Get more bang for your buck by using fuzzing dictionaries. -See dictionaries/README.dictionaries to learn how. - -% - -You can get the most out of your hardware by parallelizing AFL jobs. -See docs/parallel_fuzzing.txt for step-by-step tips. - -% - -Improve the odds of spotting memory corruption bugs with libdislocator.so! -It's easy. Consult libdislocator/README.dislocator for usage tips. - -% - -Want to understand how your target parses a particular input file? -Try the bundled afl-analyze tool; it's got colors and all! - -% - -You can visually monitor the progress of your fuzzing jobs. -Run the bundled afl-plot utility to generate browser-friendly graphs. - -% - -Need to monitor AFL jobs programmatically? Check out the fuzzer_stats file -in the AFL output dir or try afl-whatsup. - -% - -Puzzled by something showing up in red or purple in the AFL UI? -It could be important - consult docs/status_screen.txt right away! - -% - -Know your target? Convert it to persistent mode for a huge performance gain! -Consult section #5 in llvm_mode/README.llvm for tips. - -% - -Using clang? Check out llvm_mode/ for a faster alternative to afl-gcc! - -% - -Did you know that AFL can fuzz closed-source or cross-platform binaries? -Check out qemu_mode/README.qemu for more. - -% - -Did you know that afl-fuzz can minimize any test case for you? -Try the bundled afl-tmin tool - and get small repro files fast! - -% - -Not sure if a crash is exploitable? AFL can help you figure it out. Specify --C to enable the peruvian were-rabbit mode. See section #10 in README for more. - -% - -Trouble dealing with a machine uprising? Relax, we've all been there. -Find essential survival tips at http://lcamtuf.coredump.cx/prep/. - -% - -AFL-generated corpora can be used to power other testing processes. -See section #2 in README for inspiration - it tends to pay off! - -% - -Want to automatically spot non-crashing memory handling bugs? -Try running an AFL-generated corpus through ASAN, MSAN, or Valgrind. - -% - -Good selection of input files is critical to a successful fuzzing job. -See section #5 in README (or docs/perf_tips.txt) for pro tips. - -% - -You can improve the odds of automatically spotting stack corruption issues. -Specify AFL_HARDEN=1 in the environment to enable hardening flags. - -% - -Bumping into problems with non-reproducible crashes? It happens, but usually -isn't hard to diagnose. See section #7 in README for tips. - -% - -Fuzzing is not just about memory corruption issues in the codebase. Add some -sanity-checking assert() / abort() statements to effortlessly catch logic bugs. - -% - -Hey kid... pssst... want to figure out how AFL really works? -Check out docs/technical_details.txt for all the gory details in one place! - -% - -There's a ton of third-party helper tools designed to work with AFL! -Be sure to check out docs/sister_projects.txt before writing your own. - -% - -Need to fuzz the command-line arguments of a particular program? -You can find a simple solution in experimental/argv_fuzzing. - -% - -Attacking a format that uses checksums? Remove the checksum-checking code or -use a postprocessor! See experimental/post_library/ for more. - -% - -Dealing with a very slow target or hoping for instant results? Specify -d -when calling afl-fuzz! - -% diff --git a/docs/notes_for_asan.txt b/docs/notes_for_asan.md index 09ca172e..c10a9726 100644 --- a/docs/notes_for_asan.txt +++ b/docs/notes_for_asan.md @@ -1,12 +1,9 @@ -================================== -Notes for using ASAN with afl-fuzz -================================== +# Notes for using ASAN with afl-fuzz This file discusses some of the caveats for fuzzing under ASAN, and suggests a handful of alternatives. See README for the general instruction manual. -1) Short version ----------------- +## 1) Short version 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. @@ -23,7 +20,7 @@ Because of this, fuzzing with ASAN is recommended only in four scenarios: - Precisely gauge memory needs using http://jwilk.net/software/recidivm . - Limit the memory available to process using cgroups on Linux (see - experimental/asan_cgroups). + examples/asan_cgroups). To compile with ASAN, set AFL_USE_ASAN=1 before calling 'make clean all'. The afl-gcc / afl-clang wrappers will pick that up and add the appropriate flags. @@ -37,8 +34,7 @@ and can give you somewhat comparable results. You can also try using libdislocator (see libdislocator/README.dislocator.md in the parent directory) as a lightweight and hassle-free (but less thorough) alternative. -2) Long version ---------------- +## 2) Long version ASAN allocates a huge region of virtual address space for bookkeeping purposes. Most of this is never actually accessed, so the OS never has to allocate any @@ -74,7 +70,7 @@ There are also cgroups, but they are Linux-specific, not universally available even on Linux systems, and they require root permissions to set up; I'm a bit hesitant to make afl-fuzz require root permissions just for that. That said, if you are on Linux and want to use cgroups, check out the contributed script -that ships in experimental/asan_cgroups/. +that ships in examples/asan_cgroups/. In settings where cgroups aren't available, we have no nice, portable way to avoid counting the ASAN allocation toward the limit. On 32-bit systems, or for @@ -105,16 +101,19 @@ examine them with ASAN, Valgrind, or other heavy-duty tools in a more controlled setting; or compile the target program with -m32 (32-bit mode) if your system supports that. -3) Interactions with the QEMU mode ----------------------------------- +## 3) Interactions with the QEMU mode ASAN, MSAN, and other sanitizers appear to be incompatible with QEMU user emulation, so please do not try to use them with the -Q option; QEMU doesn't seem to appreciate the shadow VM trick used by these tools, and will likely just allocate all your physical memory, then crash. -4) ASAN and OOM crashes ------------------------ +You can, however, use QASan to run binaries that are not instrumented with ASan +under QEMU with the AFL++ instrumentation. + +https://github.com/andreafioraldi/qasan + +## 4) ASAN and OOM crashes By default, ASAN treats memory allocation failures as fatal errors, immediately causing the program to crash. Since this is a departure from normal POSIX @@ -129,15 +128,18 @@ want to cc: yourself on this bug: https://bugs.llvm.org/show_bug.cgi?id=22026 -5) What about UBSAN? --------------------- +## 5) What about UBSAN? -Some folks expressed interest in fuzzing with UBSAN. This isn't officially -supported, because many installations of UBSAN don't offer a consistent way -to abort() on fault conditions or to terminate with a distinctive exit code. +New versions of UndefinedBehaviorSanitizer offers the +-fsanitize=undefined-trap-on-error compiler flag that tells UBSan to insert an +istruction that will cause SIGILL (ud2 on x86) when an undefined behaviour +is detected. This is the option that you want to use when combining AFL++ +and UBSan. -That said, some versions of the library can be binary-patched to address this -issue, while newer releases support explicit compile-time flags - see this -mailing list thread for tips: +AFL_USE_UBSAN=1 env var will add this compiler flag to afl-clang-fast for you. - https://groups.google.com/forum/#!topic/afl-users/GyeSBJt4M38 +Old versions of UBSAN don't offer a consistent way +to abort() on fault conditions or to terminate with a distinctive exit code +but there are some versions of the library can be binary-patched to address this +issue. You can also preload a shared library that substitute all the UBSan +routines used to report errors with abort(). diff --git a/docs/parallel_fuzzing.txt b/docs/parallel_fuzzing.md index 1e65c01f..0a2863fe 100644 --- a/docs/parallel_fuzzing.txt +++ b/docs/parallel_fuzzing.md @@ -1,12 +1,9 @@ -========================= -Tips for parallel fuzzing -========================= +# Tips for parallel fuzzing This document talks about synchronizing afl-fuzz jobs on a single machine or across a fleet of systems. See README for the general instruction manual. -1) Introduction ---------------- +## 1) Introduction Every copy of afl-fuzz will take up one CPU core. This means that on an n-core system, you can almost always run around n concurrent fuzzing jobs with @@ -28,13 +25,12 @@ cases on the fly. Note that afl++ has AFLfast's power schedules implemented. It is therefore a good idea to use different power schedules if you run -several instances in parallel. See docs/power_schedules.txt +several instances in parallel. See [power_schedules.md](power_schedules.md) Alternatively running other AFL spinoffs in parallel can be of value, e.g. Angora (https://github.com/AngoraFuzzer/Angora/) -2) Single-system parallelization --------------------------------- +## 2) Single-system parallelization If you wish to parallelize a single job across multiple cores on a local system, simply create a new, empty output directory ("sync dir") that will be @@ -43,12 +39,16 @@ for every instance - say, "fuzzer01", "fuzzer02", etc. Run the first one ("master", -M) like this: +``` $ ./afl-fuzz -i testcase_dir -o sync_dir -M fuzzer01 [...other stuff...] +``` ...and then, start up secondary (-S) instances like this: +``` $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer02 [...other stuff...] $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer03 [...other stuff...] +``` Each fuzzer will keep its state in a separate subdirectory, like so: @@ -68,9 +68,11 @@ Note that running multiple -M instances is wasteful, although there is an experimental support for parallelizing the deterministic checks. To leverage that, you need to create -M instances like so: +``` $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterA:1/3 [...] $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterB:2/3 [...] $ ./afl-fuzz -i testcase_dir -o sync_dir -M masterC:3/3 [...] +``` ...where the first value after ':' is the sequential ID of a particular master instance (starting at 1), and the second value is the total number of fuzzers to @@ -86,15 +88,16 @@ WARNING: Exercise caution when explicitly specifying the -f option. Each fuzzer must use a separate temporary file; otherwise, things will go south. One safe example may be: +``` $ ./afl-fuzz [...] -S fuzzer10 -f file10.txt ./fuzzed/binary @@ $ ./afl-fuzz [...] -S fuzzer11 -f file11.txt ./fuzzed/binary @@ $ ./afl-fuzz [...] -S fuzzer12 -f file12.txt ./fuzzed/binary @@ +``` This is not a concern if you use @@ without -f and let afl-fuzz come up with the file name. -3) Multi-system parallelization -------------------------------- +## 3) Multi-system parallelization The basic operating principle for multi-system parallelization is similar to the mechanism explained in section 2. The key difference is that you need to @@ -106,20 +109,24 @@ write a simple script that performs two actions: that includes host name in the fuzzer ID, so that you can do something like: + ```sh for s in {1..10}; do ssh user@host${s} "tar -czf - sync/host${s}_fuzzid*/[qf]*" >host${s}.tgz done + ``` - Distributes and unpacks these files on all the remaining machines, e.g.: + ```sh for s in {1..10}; do for d in {1..10}; do test "$s" = "$d" && continue ssh user@host${d} 'tar -kxzf -' <host${s}.tgz done done + ``` -There is an example of such a script in experimental/distributed_fuzzing/; +There is an example of such a script in examples/distributed_fuzzing/; you can also find a more featured, experimental tool developed by Martijn Bogaard at: @@ -167,8 +174,7 @@ It is *not* advisable to skip the synchronization script and run the fuzzers directly on a network filesystem; unexpected latency and unkillable processes in I/O wait state can mess things up. -4) Remote monitoring and data collection ----------------------------------------- +## 4) Remote monitoring and data collection You can use screen, nohup, tmux, or something equivalent to run remote instances of afl-fuzz. If you redirect the program's output to a file, it will @@ -192,8 +198,7 @@ Keep in mind that crashing inputs are *not* automatically propagated to the master instance, so you may still want to monitor for crashes fleet-wide from within your synchronization or health checking scripts (see afl-whatsup). -5) Asymmetric setups --------------------- +## 5) Asymmetric setups It is perhaps worth noting that all of the following is permitted: diff --git a/docs/perf_tips.txt b/docs/perf_tips.md index 0cac8f7b..41d74447 100644 --- a/docs/perf_tips.txt +++ b/docs/perf_tips.md @@ -1,12 +1,9 @@ -================================= -Tips for performance optimization -================================= +## Tips for performance optimization This file provides tips for troubleshooting slow or wasteful fuzzing jobs. See README for the general instruction manual. -1) Keep your test cases small ------------------------------ +## 1. Keep your test cases small This is probably the single most important step to take! Large test cases do not merely take more time and memory to be parsed by the tested binary, but @@ -29,22 +26,20 @@ as high as 500x or so. In practice, this means that you shouldn't fuzz image parsers with your vacation photos. Generate a tiny 16x16 picture instead, and run it through -jpegtran or pngcrunch for good measure. The same goes for most other types +`jpegtran` or `pngcrunch` for good measure. The same goes for most other types of documents. -There's plenty of small starting test cases in ../testcases/* - try them out +There's plenty of small starting test cases in ../testcases/ - try them out or submit new ones! -If you want to start with a larger, third-party corpus, run afl-cmin with an +If you want to start with a larger, third-party corpus, run `afl-cmin` with an aggressive timeout on that data set first. -2) Use a simpler target ------------------------ +## 2. Use a simpler target Consider using a simpler target binary in your fuzzing work. For example, for -image formats, bundled utilities such as djpeg, readpng, or gifhisto are -considerably (10-20x) faster than the convert tool from ImageMagick - all while -exercising roughly the same library-level image parsing code. +image formats, bundled utilities such as `djpeg`, `readpng`, or `gifhisto` are +considerably (10-20x) faster than the convert tool from ImageMagick - all while exercising roughly the same library-level image parsing code. Even if you don't have a lightweight harness for a particular target, remember that you can always use another, related library to generate a corpus that will @@ -53,11 +48,10 @@ be then manually fed to a more resource-hungry program later on. Also note that reading the fuzzing input via stdin is faster than reading from a file. -3) Use LLVM instrumentation ---------------------------- +## 3. Use LLVM instrumentation When fuzzing slow targets, you can gain 20-100% performance improvement by -using the LLVM-based instrumentation mode described in llvm_mode/README.llvm. +using the LLVM-based instrumentation mode described in [the llvm_mode README](../llvm_mode/README.md). Note that this mode requires the use of clang and will not work with GCC. The LLVM mode also offers a "persistent", in-process fuzzing mode that can @@ -67,25 +61,26 @@ 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. -If there are important data comparisons performed (e.g. strcmp(ptr, MAGIC_HDR) -then using laf-intel (see llvm_mode/README.laf-intel) will help afl-fuzz a lot +If there are important data comparisons performed (e.g. `strcmp(ptr, MAGIC_HDR)`) +then using laf-intel (see llvm_mode/README.laf-intel.md) will help `afl-fuzz` a lot to get to the important parts in the code. -If you are only intested in specific parts of the code being fuzzed, you can +If you are only interested in specific parts of the code being fuzzed, you can whitelist the files that are actually relevant. This improves the speed and -accuracy of afl. See llvm_mode/README.whitelist +accuracy of afl. See llvm_mode/README.whitelist.md Also use the InsTrim mode on larger binaries, this improves performance and coverage a lot. -4) Profile and optimize 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 called with: +```bash -dct fast -nosmooth -onepass -dither none -scale 1/4 +``` ...and that will speed things up. There is a corresponding drop in the quality of decoded images, but it's probably not something you care about. @@ -98,134 +93,132 @@ With some laid-back parsers, enabling "strict" mode (i.e., bailing out after 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 the program is still too slow, you can use strace -tt or an equivalent +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 +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 +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 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. Other programs may attempt fsync() and so on. +Some programs may also intentionally call `sleep()`, `usleep()`, or `nanosleep()`; +vim is a good example of that. Other programs may attempt `fsync()` and so on. There are third-party libraries that make it easy to get rid of such code, e.g.: https://launchpad.net/libeatmydata 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), +want to try the LLVM deferred forkserver mode (see llvm_mode/README.md), 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 with an ASAN-enabled binary later on. -5) Instrument just what you need --------------------------------- +## 5. Instrument just what you need Instrument just the libraries you actually want to stress-test right now, one 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 +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 +their source code (Spidermonkey is a good example of this). Check `./configure` options to use non-instrumented system-wide copies instead. -6) Parallelize your fuzzers ---------------------------- +## 6. Parallelize your fuzzers The fuzzer is designed to need ~1 core per job. This means that on a, say, 4-core system, you can easily run four parallel fuzzing jobs with relatively -little performance hit. For tips on how to do that, see parallel_fuzzing.txt. +little performance hit. For tips on how to do that, see parallel_fuzzing.md. -The afl-gotcpu utility can help you understand if you still have idle CPU +The `afl-gotcpu` utility can help you understand if you still have idle CPU capacity on your system. (It won't tell you about memory bandwidth, cache misses, or similar factors, but they are less likely to be a concern.) -7) Keep memory use and timeouts in check ----------------------------------------- +## 7. Keep memory use and timeouts in check -If you have increased the -m or -t limits more than truly necessary, consider +If you have increased the `-m` or `-t` limits more than truly necessary, consider dialing them back down. For programs that are nominally very fast, but get sluggish for some inputs, -you can also try setting -t values that are more punishing than what afl-fuzz -dares to use on its own. On fast and idle machines, going down to -t 5 may be +you can also try setting `-t` values that are more punishing than what `afl-fuzz` +dares to use on its own. On fast and idle machines, going down to `-t 5` may be a viable plan. -The -m parameter is worth looking at, too. Some programs can end up spending +The `-m` parameter is worth looking at, too. Some programs can end up spending a fair amount of time allocating and initializing megabytes of memory when -presented with pathological inputs. Low -m values can make them give up sooner +presented with pathological inputs. Low `-m` values can make them give up sooner and not waste CPU time. -8) Check OS configuration -------------------------- +## 8. Check OS configuration There are several OS-level factors that may affect fuzzing speed: - If you have no risk of power loss then run your fuzzing on a tmpfs partition. This increases the performance noticably. - Alternatively you can use AFL_TMPDIR to point to a tmpfs location to + Alternatively you can use `AFL_TMPDIR` to point to a tmpfs location to just write the input file to a tmpfs. - - High system load. Use idle machines where possible. Kill any non-essential CPU hogs (idle browser windows, media players, complex screensavers, etc). - - Network filesystems, either used for fuzzer input / output, or accessed by the fuzzed binary to read configuration files (pay special attention to the home directory - many programs search it for dot-files). - - - On-demand CPU scaling. The Linux 'ondemand' governor performs its analysis + - On-demand CPU scaling. The Linux `ondemand` governor performs its analysis on a particular schedule and is known to underestimate the needs of - short-lived processes spawned by afl-fuzz (or any other fuzzer). On Linux, + short-lived processes spawned by `afl-fuzz` (or any other fuzzer). On Linux, this can be fixed with: +``` bash cd /sys/devices/system/cpu echo performance | tee cpu*/cpufreq/scaling_governor +``` On other systems, the impact of CPU scaling will be different; when fuzzing, use OS-specific tools to find out if all cores are running at full speed. - - - Transparent huge pages. Some allocators, such as jemalloc, can incur a + - Transparent huge pages. Some allocators, such as `jemalloc`, can incur a heavy fuzzing penalty when transparent huge pages (THP) are enabled in the kernel. You can disable this via: +```bash echo never > /sys/kernel/mm/transparent_hugepage/enabled +``` - Suboptimal scheduling strategies. The significance of this will vary from one target to another, but on Linux, you may want to make sure that the following options are set: +```bash echo 1 >/proc/sys/kernel/sched_child_runs_first echo 1 >/proc/sys/kernel/sched_autogroup_enabled +``` Setting a different scheduling policy for the fuzzer process - say - SCHED_RR - can usually speed things up, too, but needs to be done with + `SCHED_RR` - can usually speed things up, too, but needs to be done with care. - - - Use the afl-system-config script to set all proc/sys settings above - + - Use the `afl-system-config` script to set all proc/sys settings above in one go. - Disable all the spectre, meltdown etc. security countermeasures in the kernel if your machine is properly separated: - "ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off - no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable - nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off - spectre_v2=off stf_barrier=off" - In most Linux distributions you can put this into a /etc/default/grub + +``` +ibpb=off ibrs=off kpti=off l1tf=off mds=off mitigations=off +no_stf_barrier noibpb noibrs nopcid nopti nospec_store_bypass_disable +nospectre_v1 nospectre_v2 pcid=off pti=off spec_store_bypass_disable=off +spectre_v2=off stf_barrier=off +``` + In most Linux distributions you can put this into a `/etc/default/grub` variable. -9) If all other options fail, use -d ------------------------------------- +## 9. If all other options fail, use `-d` For programs that are genuinely slow, in cases where you really can't escape using huge input files, or when you simply want to get quick and dirty results -early on, you can always resort to the -d mode. +early on, you can always resort to the `-d` mode. -The mode causes afl-fuzz to skip all the deterministic fuzzing steps, which +The mode causes `afl-fuzz` to skip all the deterministic fuzzing steps, which makes output a lot less neat and can ultimately make the testing a bit less in-depth, but it will give you an experience more familiar from other fuzzing -tools. +tools. \ No newline at end of file diff --git a/docs/power_schedules.txt b/docs/power_schedules.md index 7b9d34c4..4026aedf 100644 --- a/docs/power_schedules.txt +++ b/docs/power_schedules.md @@ -1,8 +1,9 @@ -afl++'s power schedules based on AFLfast +# afl++'s power schedules based on AFLfast -<a href="https://comp.nus.edu.sg/~mboehme/paper/CCS16.pdf"><img src="https://comp.nus.edu.sg/~mboehme/paper/CCS16.png" align="right" width="250"></a> +<a href="https://mboehme.github.io/paper/CCS16.pdf"><img src="https://mboehme.github.io/paper/CCS16.png" align="right" width="250"></a> Power schedules implemented by Marcel Böhme \<marcel.boehme@acm.org\>. -AFLFast is an extension of AFL which was written by Michal Zalewski. +AFLFast is an extension of AFL which is written and maintained by +Michal Zalewski \<lcamtuf@google.com\>. AFLfast has helped in the success of Team Codejitsu at the finals of the DARPA Cyber Grand Challenge where their bot Galactica took **2nd place** in terms of #POVs proven (see red bar at https://www.cybergrandchallenge.com/event#results). AFLFast exposed several previously unreported CVEs that could not be exposed by AFL in 24 hours and otherwise exposed vulnerabilities significantly faster than AFL while generating orders of magnitude more unique crashes. diff --git a/docs/python_mutators.txt b/docs/python_mutators.md index 7fd54547..a7e2c7de 100644 --- a/docs/python_mutators.txt +++ b/docs/python_mutators.md @@ -1,6 +1,4 @@ -================================================== -Adding custom mutators to AFL using Python modules -================================================== +# Adding custom mutators to AFL using Python modules This file describes how you can utilize the external Python API to write your own custom mutation routines. @@ -14,11 +12,10 @@ Adding custom mutators to AFL using Python modules python2 or python3 syntax in your scripts! After a major version upgrade (e.g. 3.7 -> 3.8), a recompilation of afl-fuzz may be needed. - For an example and a template see ../python_mutators/ + For an example and a template see ../examples/python_mutators/ -1) Description and purpose --------------------------- +## 1) Description and purpose While AFLFuzz comes with a good selection of generic deterministic and non-deterministic mutation operations, it sometimes might make sense to extend @@ -40,8 +37,7 @@ See the following information to get a better pictures: https://bugs.chromium.org/p/chromium/issues/detail?id=930663 -2) How the Python module looks like ------------------------------------ +## 2) How the Python module looks like You can find a simple example in pymodules/example.py including documentation explaining each function. In the same directory, you can find another simple @@ -55,8 +51,7 @@ There is also optional support for a trimming API, see the section below for further information about this feature. -3) How to compile AFLFuzz with Python support ---------------------------------------------- +## 3) How to compile AFLFuzz with Python support You must install the python 3 or 2 development package of your Linux distribution before this will work. On Debian/Ubuntu/Kali this can be done @@ -75,8 +70,7 @@ In case your setup is different set the necessary variables like this: PYTHON_INCLUDE=/path/to/python/include LDFLAGS=-L/path/to/python/lib make -4) How to run AFLFuzz with your custom module ---------------------------------------------- +## 4) How to run AFLFuzz with your custom module You must pass the module name inside the env variable AFL_PYTHON_MODULE. @@ -99,8 +93,7 @@ AFL_DEBUG - When combined with AFL_NO_UI, this causes the C trimming code of your custom Python trimmer. Use this to see if it works :) -5) Order and statistics ------------------------ +## 5) Order and statistics The Python stage is set to be the first non-deterministic stage (right before the havoc stage). In the statistics however, it shows up as the third number @@ -108,8 +101,7 @@ under "havoc". That's because I'm lazy and I didn't want to mess with the UI too much ;) -6) Trimming support -------------------- +## 6) Trimming support The generic trimming routines implemented in AFLFuzz can easily destroy the structure of complex formats, possibly leading to a point where you have a lot diff --git a/docs/sister_projects.md b/docs/sister_projects.md new file mode 100644 index 00000000..ecc3b924 --- /dev/null +++ b/docs/sister_projects.md @@ -0,0 +1,318 @@ +# Sister projects + +This doc lists some of the projects that are inspired by, derived from, +designed for, or meant to integrate with AFL. See README for the general +instruction manual. + +!!! +!!! This list is outdated and needs an update, missing: e.g. Angora, FairFuzz +!!! + +## Support for other languages / environments: + +### Python AFL (Jakub Wilk) + +Allows fuzz-testing of Python programs. Uses custom instrumentation and its +own forkserver. + +http://jwilk.net/software/python-afl + +### Go-fuzz (Dmitry Vyukov) + +AFL-inspired guided fuzzing approach for Go targets: + +https://github.com/dvyukov/go-fuzz + +### afl.rs (Keegan McAllister) + +Allows Rust features to be easily fuzzed with AFL (using the LLVM mode). + +https://github.com/kmcallister/afl.rs + +### OCaml support (KC Sivaramakrishnan) + +Adds AFL-compatible instrumentation to OCaml programs. + +https://github.com/ocamllabs/opam-repo-dev/pull/23 +http://canopy.mirage.io/Posts/Fuzzing + +### AFL for GCJ Java and other GCC frontends (-) + +GCC Java programs are actually supported out of the box - simply rename +afl-gcc to afl-gcj. Unfortunately, by default, unhandled exceptions in GCJ do +not result in abort() being called, so you will need to manually add a +top-level exception handler that exits with SIGABRT or something equivalent. + +Other GCC-supported languages should be fairly easy to get working, but may +face similar problems. See https://gcc.gnu.org/frontends.html for a list of +options. + +## AFL-style in-process fuzzer for LLVM (Kostya Serebryany) + +Provides an evolutionary instrumentation-guided fuzzing harness that allows +some programs to be fuzzed without the fork / execve overhead. (Similar +functionality is now available as the "persistent" feature described in +[the llvm_mode readme](../llvm_mode/README.md)) + +http://llvm.org/docs/LibFuzzer.html + +## AFL fixup shim (Ben Nagy) + +Allows AFL_POST_LIBRARY postprocessors to be written in arbitrary languages +that don't have C / .so bindings. Includes examples in Go. + +https://github.com/bnagy/aflfix + +## TriforceAFL (Tim Newsham and Jesse Hertz) + +Leverages QEMU full system emulation mode to allow AFL to target operating +systems and other alien worlds: + +https://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2016/june/project-triforce-run-afl-on-everything/ + +## WinAFL (Ivan Fratric) + +As the name implies, allows you to fuzz Windows binaries (using DynamoRio). + +https://github.com/ivanfratric/winafl + +Another Windows alternative may be: + +https://github.com/carlosgprado/BrundleFuzz/ + +## Network fuzzing + +### Preeny (Yan Shoshitaishvili) + +Provides a fairly simple way to convince dynamically linked network-centric +programs to read from a file or not fork. Not AFL-specific, but described as +useful by many users. Some assembly required. + +https://github.com/zardus/preeny + +## Distributed fuzzing and related automation + +### roving (Richo Healey) + +A client-server architecture for effortlessly orchestrating AFL runs across +a fleet of machines. You don't want to use this on systems that face the +Internet or live in other untrusted environments. + +https://github.com/richo/roving + +### Distfuzz-AFL (Martijn Bogaard) + +Simplifies the management of afl-fuzz instances on remote machines. The +author notes that the current implementation isn't secure and should not +be exposed on the Internet. + +https://github.com/MartijnB/disfuzz-afl + +### AFLDFF (quantumvm) + +A nice GUI for managing AFL jobs. + +https://github.com/quantumvm/AFLDFF + +### afl-launch (Ben Nagy) + +Batch AFL launcher utility with a simple CLI. + +https://github.com/bnagy/afl-launch + +### AFL Utils (rc0r) + +Simplifies the triage of discovered crashes, start parallel instances, etc. + +https://github.com/rc0r/afl-utils + +Another crash triage tool: + +https://github.com/floyd-fuh/afl-crash-analyzer + +### afl-fuzzing-scripts (Tobias Ospelt) + +Simplifies starting up multiple parallel AFL jobs. + +https://github.com/floyd-fuh/afl-fuzzing-scripts/ + +### afl-sid (Jacek Wielemborek) + +Allows users to more conveniently build and deploy AFL via Docker. + +https://github.com/d33tah/afl-sid + +Another Docker-related project: + +https://github.com/ozzyjohnson/docker-afl + +### afl-monitor (Paul S. Ziegler) + +Provides more detailed and versatile statistics about your running AFL jobs. + +https://github.com/reflare/afl-monitor + +### FEXM (Security in Telecommunications) + +Fully automated fuzzing framework, based on AFL + +https://github.com/fgsect/fexm + +## Crash triage, coverage analysis, and other companion tools: + +### afl-crash-analyzer (Tobias Ospelt) + +Makes it easier to navigate and annotate crashing test cases. + +https://github.com/floyd-fuh/afl-crash-analyzer/ + +### Crashwalk (Ben Nagy) + +AFL-aware tool to annotate and sort through crashing test cases. + +https://github.com/bnagy/crashwalk + +### afl-cov (Michael Rash) + +Produces human-readable coverage data based on the output queue of afl-fuzz. + +https://github.com/mrash/afl-cov + +### afl-sancov (Bhargava Shastry) + +Similar to afl-cov, but uses clang sanitizer instrumentation. + +https://github.com/bshastry/afl-sancov + +### RecidiVM (Jakub Wilk) + +Makes it easy to estimate memory usage limits when fuzzing with ASAN or MSAN. + +http://jwilk.net/software/recidivm + +### aflize (Jacek Wielemborek) + +Automatically build AFL-enabled versions of Debian packages. + +https://github.com/d33tah/aflize + +### afl-ddmin-mod (Markus Teufelberger) + +A variant of afl-tmin that uses a more sophisticated (but slower) +minimization algorithm. + +https://github.com/MarkusTeufelberger/afl-ddmin-mod + +### afl-kit (Kuang-che Wu) + +Replacements for afl-cmin and afl-tmin with additional features, such +as the ability to filter crashes based on stderr patterns. + +https://github.com/kcwu/afl-kit + +## Narrow-purpose or experimental: + +### Cygwin support (Ali Rizvi-Santiago) + +Pretty self-explanatory. As per the author, this "mostly" ports AFL to +Windows. Field reports welcome! + +https://github.com/arizvisa/afl-cygwin + +### Pause and resume scripts (Ben Nagy) + +Simple automation to suspend and resume groups of fuzzing jobs. + +https://github.com/bnagy/afl-trivia + +### Static binary-only instrumentation (Aleksandar Nikolich) + +Allows black-box binaries to be instrumented statically (i.e., by modifying +the binary ahead of the time, rather than translating it on the run). Author +reports better performance compared to QEMU, but occasional translation +errors with stripped binaries. + +https://github.com/vanhauser-thc/afl-dyninst + +### AFL PIN (Parker Thompson) + +Early-stage Intel PIN instrumentation support (from before we settled on +faster-running QEMU). + +https://github.com/mothran/aflpin + +### AFL-style instrumentation in llvm (Kostya Serebryany) + +Allows AFL-equivalent instrumentation to be injected at compiler level. +This is currently not supported by AFL as-is, but may be useful in other +projects. + +https://code.google.com/p/address-sanitizer/wiki/AsanCoverage#Coverage_counters + +### AFL JS (Han Choongwoo) + +One-off optimizations to speed up the fuzzing of JavaScriptCore (now likely +superseded by LLVM deferred forkserver init - see llvm_mode/README.llvm). + +https://github.com/tunz/afl-fuzz-js + +### AFL harness for fwknop (Michael Rash) + +An example of a fairly involved integration with AFL. + +https://github.com/mrash/fwknop/tree/master/test/afl + +### Building harnesses for DNS servers (Jonathan Foote, Ron Bowes) + +Two articles outlining the general principles and showing some example code. + +https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop +https://goo.gl/j9EgFf + +### Fuzzer shell for SQLite (Richard Hipp) + +A simple SQL shell designed specifically for fuzzing the underlying library. + +http://www.sqlite.org/src/artifact/9e7e273da2030371 + +### Support for Python mutation modules (Christian Holler) + +now integrated in AFL++, originally from here +https://github.com/choller/afl/blob/master/docs/mozilla/python_modules.txt + +### Support for selective instrumentation (Christian Holler) + +now integrated in AFL++, originally from here +https://github.com/choller/afl/blob/master/docs/mozilla/partial_instrumentation.txt + +### Syzkaller (Dmitry Vyukov) + +A similar guided approach as applied to fuzzing syscalls: + +https://github.com/google/syzkaller/wiki/Found-Bugs +https://github.com/dvyukov/linux/commit/33787098ffaaa83b8a7ccf519913ac5fd6125931 +http://events.linuxfoundation.org/sites/events/files/slides/AFL%20filesystem%20fuzzing%2C%20Vault%202016_0.pdf + + +### Kernel Snapshot Fuzzing using Unicornafl (Security in Telecommunications) + +https://github.com/fgsect/unicorefuzz + +### Android support (ele7enxxh) + +Based on a somewhat dated version of AFL: + +https://github.com/ele7enxxh/android-afl + +### CGI wrapper (floyd) + +Facilitates the testing of CGI scripts. + +https://github.com/floyd-fuh/afl-cgi-wrapper + +### Fuzzing difficulty estimation (Marcel Boehme) + +A fork of AFL that tries to quantify the likelihood of finding additional +paths or crashes at any point in a fuzzing job. + +https://github.com/mboehme/pythia diff --git a/docs/sister_projects.txt b/docs/sister_projects.txt deleted file mode 100644 index 25e5560c..00000000 --- a/docs/sister_projects.txt +++ /dev/null @@ -1,360 +0,0 @@ -=============== -Sister projects -=============== - - This doc lists some of the projects that are inspired by, derived from, - designed for, or meant to integrate with AFL. See README for the general - instruction manual. - -!!! -!!! This list is outdated and needs an update, missing: e.g. Angora, FairFuzz -!!! - -------------------------------------------- -Support for other languages / environments: -------------------------------------------- - -Python AFL (Jakub Wilk) ------------------------ - - Allows fuzz-testing of Python programs. Uses custom instrumentation and its - own forkserver. - - http://jwilk.net/software/python-afl - -Go-fuzz (Dmitry Vyukov) ------------------------ - - AFL-inspired guided fuzzing approach for Go targets: - - https://github.com/dvyukov/go-fuzz - -afl.rs (Keegan McAllister) --------------------------- - - Allows Rust features to be easily fuzzed with AFL (using the LLVM mode). - - https://github.com/kmcallister/afl.rs - -OCaml support (KC Sivaramakrishnan) ------------------------------------ - - Adds AFL-compatible instrumentation to OCaml programs. - - https://github.com/ocamllabs/opam-repo-dev/pull/23 - http://canopy.mirage.io/Posts/Fuzzing - -AFL for GCJ Java and other GCC frontends (-) --------------------------------------------- - - GCC Java programs are actually supported out of the box - simply rename - afl-gcc to afl-gcj. Unfortunately, by default, unhandled exceptions in GCJ do - not result in abort() being called, so you will need to manually add a - top-level exception handler that exits with SIGABRT or something equivalent. - - Other GCC-supported languages should be fairly easy to get working, but may - face similar problems. See https://gcc.gnu.org/frontends.html for a list of - options. - -AFL-style in-process fuzzer for LLVM (Kostya Serebryany) --------------------------------------------------------- - - Provides an evolutionary instrumentation-guided fuzzing harness that allows - some programs to be fuzzed without the fork / execve overhead. (Similar - functionality is now available as the "persistent" feature described in - ../llvm_mode/README.llvm.) - - http://llvm.org/docs/LibFuzzer.html - -AFL fixup shim (Ben Nagy) -------------------------- - - Allows AFL_POST_LIBRARY postprocessors to be written in arbitrary languages - that don't have C / .so bindings. Includes examples in Go. - - https://github.com/bnagy/aflfix - -TriforceAFL (Tim Newsham and Jesse Hertz) ------------------------------------------ - - Leverages QEMU full system emulation mode to allow AFL to target operating - systems and other alien worlds: - - https://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2016/june/project-triforce-run-afl-on-everything/ - -WinAFL (Ivan Fratric) ---------------------- - - As the name implies, allows you to fuzz Windows binaries (using DynamoRio). - - https://github.com/ivanfratric/winafl - - Another Windows alternative may be: - - https://github.com/carlosgprado/BrundleFuzz/ - ----------------- -Network fuzzing: ----------------- - -Preeny (Yan Shoshitaishvili) ----------------------------- - - Provides a fairly simple way to convince dynamically linked network-centric - programs to read from a file or not fork. Not AFL-specific, but described as - useful by many users. Some assembly required. - - https://github.com/zardus/preeny - -------------------------------------------- -Distributed fuzzing and related automation: -------------------------------------------- - -roving (Richo Healey) ---------------------- - - A client-server architecture for effortlessly orchestrating AFL runs across - a fleet of machines. You don't want to use this on systems that face the - Internet or live in other untrusted environments. - - https://github.com/richo/roving - -Distfuzz-AFL (Martijn Bogaard) ------------------------------- - - Simplifies the management of afl-fuzz instances on remote machines. The - author notes that the current implementation isn't secure and should not - be exposed on the Internet. - - https://github.com/MartijnB/disfuzz-afl - -AFLDFF (quantumvm) ------------------- - - A nice GUI for managing AFL jobs. - - https://github.com/quantumvm/AFLDFF - -afl-launch (Ben Nagy) ---------------------- - - Batch AFL launcher utility with a simple CLI. - - https://github.com/bnagy/afl-launch - -AFL Utils (rc0r) ----------------- - - Simplifies the triage of discovered crashes, start parallel instances, etc. - - https://github.com/rc0r/afl-utils - - Another crash triage tool: - - https://github.com/floyd-fuh/afl-crash-analyzer - -afl-fuzzing-scripts (Tobias Ospelt) ------------------------------------ - - Simplifies starting up multiple parallel AFL jobs. - - https://github.com/floyd-fuh/afl-fuzzing-scripts/ - -afl-sid (Jacek Wielemborek) ---------------------------- - - Allows users to more conveniently build and deploy AFL via Docker. - - https://github.com/d33tah/afl-sid - - Another Docker-related project: - - https://github.com/ozzyjohnson/docker-afl - -afl-monitor (Paul S. Ziegler) ------------------------------ - - Provides more detailed and versatile statistics about your running AFL jobs. - - https://github.com/reflare/afl-monitor - ------------------------------------------------------------ -Crash triage, coverage analysis, and other companion tools: ------------------------------------------------------------ - -afl-crash-analyzer (Tobias Ospelt) ----------------------------------- - - Makes it easier to navigate and annotate crashing test cases. - - https://github.com/floyd-fuh/afl-crash-analyzer/ - -Crashwalk (Ben Nagy) --------------------- - - AFL-aware tool to annotate and sort through crashing test cases. - - https://github.com/bnagy/crashwalk - -afl-cov (Michael Rash) ----------------------- - - Produces human-readable coverage data based on the output queue of afl-fuzz. - - https://github.com/mrash/afl-cov - -afl-sancov (Bhargava Shastry) ------------------------------ - - Similar to afl-cov, but uses clang sanitizer instrumentation. - - https://github.com/bshastry/afl-sancov - -RecidiVM (Jakub Wilk) ---------------------- - - Makes it easy to estimate memory usage limits when fuzzing with ASAN or MSAN. - - http://jwilk.net/software/recidivm - -aflize (Jacek Wielemborek) --------------------------- - - Automatically build AFL-enabled versions of Debian packages. - - https://github.com/d33tah/aflize - -afl-ddmin-mod (Markus Teufelberger) ------------------------------------ - - A variant of afl-tmin that uses a more sophisticated (but slower) - minimization algorithm. - - https://github.com/MarkusTeufelberger/afl-ddmin-mod - -afl-kit (Kuang-che Wu) ----------------------- - - Replacements for afl-cmin and afl-tmin with additional features, such - as the ability to filter crashes based on stderr patterns. - - https://github.com/kcwu/afl-kit - -------------------------------- -Narrow-purpose or experimental: -------------------------------- - -Cygwin support (Ali Rizvi-Santiago) ------------------------------------ - - Pretty self-explanatory. As per the author, this "mostly" ports AFL to - Windows. Field reports welcome! - - https://github.com/arizvisa/afl-cygwin - -Pause and resume scripts (Ben Nagy) ------------------------------------ - - Simple automation to suspend and resume groups of fuzzing jobs. - - https://github.com/bnagy/afl-trivia - -Static binary-only instrumentation (Aleksandar Nikolich) --------------------------------------------------------- - - Allows black-box binaries to be instrumented statically (i.e., by modifying - the binary ahead of the time, rather than translating it on the run). Author - reports better performance compared to QEMU, but occasional translation - errors with stripped binaries. - - https://github.com/vanhauser-thc/afl-dyninst - -AFL PIN (Parker Thompson) -------------------------- - - Early-stage Intel PIN instrumentation support (from before we settled on - faster-running QEMU). - - https://github.com/mothran/aflpin - -AFL-style instrumentation in llvm (Kostya Serebryany) ------------------------------------------------------ - - Allows AFL-equivalent instrumentation to be injected at compiler level. - This is currently not supported by AFL as-is, but may be useful in other - projects. - - https://code.google.com/p/address-sanitizer/wiki/AsanCoverage#Coverage_counters - -AFL JS (Han Choongwoo) ----------------------- - - One-off optimizations to speed up the fuzzing of JavaScriptCore (now likely - superseded by LLVM deferred forkserver init - see llvm_mode/README.llvm). - - https://github.com/tunz/afl-fuzz-js - -AFL harness for fwknop (Michael Rash) -------------------------------------- - - An example of a fairly involved integration with AFL. - - https://github.com/mrash/fwknop/tree/master/test/afl - -Building harnesses for DNS servers (Jonathan Foote, Ron Bowes) --------------------------------------------------------------- - - Two articles outlining the general principles and showing some example code. - - https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop - https://goo.gl/j9EgFf - -Fuzzer shell for SQLite (Richard Hipp) --------------------------------------- - - A simple SQL shell designed specifically for fuzzing the underlying library. - - http://www.sqlite.org/src/artifact/9e7e273da2030371 - -Support for Python mutation modules (Christian Holler) ------------------------------------------------------- - -now integrated in AFL++, originally from here - https://github.com/choller/afl/blob/master/docs/mozilla/python_modules.txt - -Support for selective instrumentation (Christian Holler) --------------------------------------------------------- - -now integrated in AFL++, originally from here - https://github.com/choller/afl/blob/master/docs/mozilla/partial_instrumentation.txt - -Kernel fuzzing (Dmitry Vyukov) ------------------------------- - - A similar guided approach as applied to fuzzing syscalls: - - https://github.com/google/syzkaller/wiki/Found-Bugs - https://github.com/dvyukov/linux/commit/33787098ffaaa83b8a7ccf519913ac5fd6125931 - http://events.linuxfoundation.org/sites/events/files/slides/AFL%20filesystem%20fuzzing%2C%20Vault%202016_0.pdf - -Android support (ele7enxxh) ---------------------------- - - Based on a somewhat dated version of AFL: - - https://github.com/ele7enxxh/android-afl - -CGI wrapper (floyd) -------------------- - - Facilitates the testing of CGI scripts. - - https://github.com/floyd-fuh/afl-cgi-wrapper - -Fuzzing difficulty estimation (Marcel Boehme) ---------------------------------------------- - - A fork of AFL that tries to quantify the likelihood of finding additional - paths or crashes at any point in a fuzzing job. - - https://github.com/mboehme/pythia diff --git a/docs/status_screen.txt b/docs/status_screen.md index c6f9f791..1ea98415 100644 --- a/docs/status_screen.txt +++ b/docs/status_screen.md @@ -1,13 +1,10 @@ -=============================== -Understanding the status screen -=============================== +# Understanding the status screen - This document provides an overview of the status screen - plus tips for - troubleshooting any warnings and red text shown in the UI. See README for - the general instruction manual. +This document provides an overview of the status screen - plus tips for +troubleshooting any warnings and red text shown in the UI. See README for +the general instruction manual. -0) A note about colors ----------------------- +## A note about colors The status screen and error messages use colors to keep things readable and attract your attention to the most important details. For example, red almost @@ -19,21 +16,18 @@ to that. If you are using inverse video, you may want to change your settings, say: - - For GNOME Terminal, go to Edit > Profile preferences, select the "colors" - tab, and from the list of built-in schemes, choose "white on black". - - - For the MacOS X Terminal app, open a new window using the "Pro" scheme via - the Shell > New Window menu (or make "Pro" your default). +- For GNOME Terminal, go to `Edit > Profile` preferences, select the "colors" tab, and from the list of built-in schemes, choose "white on black". +- For the MacOS X Terminal app, open a new window using the "Pro" scheme via the `Shell > New Window` menu (or make "Pro" your default). Alternatively, if you really like your current colors, you can edit config.h -to comment out USE_COLORS, then do 'make clean all'. +to comment out USE_COLORS, then do `make clean all`. I'm not aware of any other simple way to make this work without causing other side effects - sorry about that. With that out of the way, let's talk about what's actually on the screen... -0) The status bar +### The status bar The top line shows you which mode afl-fuzz is running in (normal: "american fuzy lop", crash exploration mode: "peruvian rabbit mode") @@ -43,15 +37,16 @@ either show the binary name being fuzzed, or the -M/-S master/slave name for parallel fuzzing. Finally, the last item is the power schedule mode being run (default: explore). -1) Process timing ------------------ +### Process timing +``` +----------------------------------------------------+ | run time : 0 days, 8 hrs, 32 min, 43 sec | | last new path : 0 days, 0 hrs, 6 min, 40 sec | | last uniq crash : none seen yet | | last uniq hang : 0 days, 1 hrs, 24 min, 32 sec | +----------------------------------------------------+ +``` This section is fairly self-explanatory: it tells you how long the fuzzer has been running and how much time has elapsed since its most recent finds. This is @@ -67,36 +62,36 @@ There's one important thing to watch out for: if the tool is not finding new paths within several minutes of starting, you're probably not invoking the target binary correctly and it never gets to parse the input files we're throwing at it; another possible explanations are that the default memory limit -(-m) is too restrictive, and the program exits after failing to allocate a +(`-m`) is too restrictive, and the program exits after failing to allocate a buffer very early on; or that the input files are patently invalid and always fail a basic header check. If there are no new paths showing up for a while, you will eventually see a big red warning in this section, too :-) -2) Overall results ------------------- +### Overall results +``` +-----------------------+ | cycles done : 0 | | total paths : 2095 | | uniq crashes : 0 | | uniq hangs : 19 | +-----------------------+ +``` -The first field in this section gives you the count of queue passes done so far -- that is, the number of times the fuzzer went over all the interesting test +The first field in this section gives you the count of queue passes done so far - that is, the number of times the fuzzer went over all the interesting test cases discovered so far, fuzzed them, and looped back to the very beginning. Every fuzzing session should be allowed to complete at least one cycle; and ideally, should run much longer than that. As noted earlier, the first pass can take a day or longer, so sit back and relax. If you want to get broader but more shallow coverage right away, try -the -d option - it gives you a more familiar experience by skipping the +the `-d` option - it gives you a more familiar experience by skipping the deterministic fuzzing steps. It is, however, inferior to the standard mode in a couple of subtle ways. -To help make the call on when to hit Ctrl-C, the cycle counter is color-coded. +To help make the call on when to hit `Ctrl-C`, the cycle counter is color-coded. It is shown in magenta during the first pass, progresses to yellow if new finds are still being made in subsequent rounds, then blue when that ends - and finally, turns green after the fuzzer hasn't been seeing any action for a @@ -105,33 +100,35 @@ longer while. The remaining fields in this part of the screen should be pretty obvious: there's the number of test cases ("paths") discovered so far, and the number of unique faults. The test cases, crashes, and hangs can be explored in real-time -by browsing the output directory, as discussed in the README. +by browsing the output directory, as discussed in README.md. -3) Cycle progress ------------------ +### Cycle progress +``` +-------------------------------------+ | now processing : 1296 (61.86%) | | paths timed out : 0 (0.00%) | +-------------------------------------+ +``` This box tells you how far along the fuzzer is with the current queue cycle: it shows the ID of the test case it is currently working on, plus the number of inputs it decided to ditch because they were persistently timing out. The "*" suffix sometimes shown in the first line means that the currently -processed path is not "favored" (a property discussed later on, in section 6). +processed path is not "favored" (a property discussed later on). If you feel that the fuzzer is progressing too slowly, see the note about the --d option in section 2 of this doc. +`-d` option in this doc. -4) Map coverage ---------------- +### Map coverage +``` +--------------------------------------+ | map density : 10.15% / 29.07% | | count coverage : 4.03 bits/tuple | +--------------------------------------+ +``` The section provides some trivia about the coverage observed by the instrumentation embedded in the target binary. @@ -148,37 +145,35 @@ Be wary of extremes: due to being linked against a non-instrumented copy of the target library); or that it is bailing out prematurely on your input test cases. The fuzzer will try to mark this in pink, just to make you aware. - - Percentages over 70% may very rarely happen with very complex programs that make heavy use of template-generated code. - Because high bitmap density makes it harder for the fuzzer to reliably discern new program states, I recommend recompiling the binary with - AFL_INST_RATIO=10 or so and trying again (see env_variables.txt). - + `AFL_INST_RATIO=10` or so and trying again (see env_variables.md). The fuzzer will flag high percentages in red. Chances are, you will never see that unless you're fuzzing extremely hairy software (say, v8, perl, ffmpeg). The other line deals with the variability in tuple hit counts seen in the binary. In essence, if every taken branch is always taken a fixed number of -times for all the inputs we have tried, this will read "1.00". As we manage +times for all the inputs we have tried, this will read `1.00`. As we manage to trigger other hit counts for every branch, the needle will start to move -toward "8.00" (every bit in the 8-bit map hit), but will probably never +toward `8.00` (every bit in the 8-bit map hit), but will probably never reach that extreme. Together, the values can be useful for comparing the coverage of several different fuzzing jobs that rely on the same instrumented binary. -5) Stage progress ------------------ +### Stage progress +``` +-------------------------------------+ | now trying : interest 32/8 | | stage execs : 3996/34.4k (11.62%) | | total execs : 27.4M | | exec speed : 891.7/sec | +-------------------------------------+ +``` This part gives you an in-depth peek at what the fuzzer is actually doing right now. It tells you about the current stage, which can be any of: @@ -186,39 +181,31 @@ now. It tells you about the current stage, which can be any of: - calibration - a pre-fuzzing stage where the execution path is examined to detect anomalies, establish baseline execution speed, and so on. Executed very briefly whenever a new find is being made. - - trim L/S - another pre-fuzzing stage where the test case is trimmed to the shortest form that still produces the same execution path. The length (L) and stepover (S) are chosen in general relationship to file size. - - bitflip L/S - deterministic bit flips. There are L bits toggled at any given time, walking the input file with S-bit increments. The current L/S variants - are: 1/1, 2/1, 4/1, 8/8, 16/8, 32/8. - + are: `1/1`, `2/1`, `4/1`, `8/8`, `16/8`, `32/8`. - arith L/8 - deterministic arithmetics. The fuzzer tries to subtract or add small integers to 8-, 16-, and 32-bit values. The stepover is always 8 bits. - - interest L/8 - deterministic value overwrite. The fuzzer has a list of known "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 a user-supplied - dictionary (-x) or an auto-created one. You will also see "over" or "insert", + 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. - - havoc - a sort-of-fixed-length cycle with stacked random tweaks. The operations attempted during this stage include bit flips, overwrites with random and "interesting" integers, block deletion, block duplication, plus assorted dictionary-related operations (if a dictionary is supplied in the first place). - - splice - a last-resort strategy that kicks in after the first full queue cycle with no new paths. It is equivalent to 'havoc', except that it first splices together two random inputs from the queue at some arbitrarily selected midpoint. - - - sync - a stage used only when -M or -S is set (see parallel_fuzzing.txt). + - sync - a stage used only when `-M` or `-S` is set (see parallel_fuzzing.md). No real fuzzing is involved, but the tool scans the output from other fuzzers and imports test cases as necessary. The first time this is done, it may take several minutes or so. @@ -231,18 +218,19 @@ most of the time - and if it stays below 100, the job will probably take very long. The fuzzer will explicitly warn you about slow targets, too. If this happens, -see the perf_tips.txt file included with the fuzzer for ideas on how to speed +see the [perf_tips.md](perf_tips.md) file included with the fuzzer for ideas on how to speed things up. -6) Findings in depth --------------------- +### Findings in depth +``` +--------------------------------------+ | favored paths : 879 (41.96%) | | new edges on : 423 (20.19%) | | total crashes : 0 (0 unique) | | total tmouts : 24 (19 unique) | +--------------------------------------+ +``` This gives you several metrics that are of interest mostly to complete nerds. The section includes the number of paths that the fuzzer likes the most based @@ -255,9 +243,9 @@ Note that the timeout counter is somewhat different from the hang counter; this one includes all test cases that exceeded the timeout, even if they did not exceed it by a margin sufficient to be classified as hangs. -7) Fuzzing strategy yields --------------------------- +### Fuzzing strategy yields +``` +-----------------------------------------------------+ | bit flips : 57/289k, 18/289k, 18/288k | | byte flips : 0/36.2k, 4/35.7k, 7/34.6k | @@ -267,6 +255,7 @@ exceed it by a margin sufficient to be classified as hangs. | havoc : 1903/20.0M, 0/0 | | trim : 20.31%/9201, 17.05% | +-----------------------------------------------------+ +``` This is just another nerd-targeted section keeping track of how many paths we have netted, in proportion to the number of execs attempted, for each of the @@ -280,9 +269,9 @@ goal. Finally, the third number shows the proportion of bytes that, although not possible to remove, were deemed to have no effect and were excluded from some of the more expensive deterministic fuzzing steps. -8) Path geometry ----------------- +### Path geometry +``` +---------------------+ | levels : 5 | | pending : 1570 | @@ -291,6 +280,7 @@ some of the more expensive deterministic fuzzing steps. | imported : 0 | | stability : 100.00% | +---------------------+ +``` The first field in this section tracks the path depth reached through the guided fuzzing process. In essence: the initial test cases supplied by the @@ -323,46 +313,40 @@ there are several things to look at: - The use of uninitialized memory in conjunction with some intrinsic sources of entropy in the tested binary. Harmless to AFL, but could be indicative of a security bug. - - Attempts to manipulate persistent resources, such as left over temporary files or shared memory objects. This is usually harmless, but you may want to double-check to make sure the program isn't bailing out prematurely. Running out of disk space, SHM handles, or other global resources can trigger this, too. - - Hitting some functionality that is actually designed to behave randomly. Generally harmless. For example, when fuzzing sqlite, an input like - 'select random();' will trigger a variable execution path. - + `select random();` will trigger a variable execution path. - Multiple threads executing at once in semi-random order. This is harmless when the 'stability' metric stays over 90% or so, but can become an issue if not. Here's what to try: - - - Use afl-clang-fast from llvm_mode/ - it uses a thread-local tracking + * Use afl-clang-fast from [llvm_mode](../llvm_mode/) - it uses a thread-local tracking model that is less prone to concurrency issues, - - - See if the target can be compiled or run without threads. Common - ./configure options include --without-threads, --disable-pthreads, or - --disable-openmp. - - - Replace pthreads with GNU Pth (https://www.gnu.org/software/pth/), which + * See if the target can be compiled or run without threads. Common + `./configure` options include `--without-threads`, `--disable-pthreads`, or + `--disable-openmp`. + * Replace pthreads with GNU Pth (https://www.gnu.org/software/pth/), which allows you to use a deterministic scheduler. - - In persistent mode, minor drops in the "stability" metric can be normal, because not all the code behaves identically when re-entered; but major - dips may signify that the code within __AFL_LOOP() is not behaving + dips may signify that the code within `__AFL_LOOP()` is not behaving correctly on subsequent iterations (e.g., due to incomplete clean-up or reinitialization of the state) and that most of the fuzzing effort goes to waste. 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 +in the `<out_dir>/queue/.state/variable_behavior/` directory, so you can look them up easily. -9) CPU load ------------ +### CPU load +``` [cpu: 25%] +``` This tiny widget shows the apparent CPU utilization on the local system. It is calculated by taking the number of processes in the "runnable" state, and then @@ -370,7 +354,7 @@ comparing it to the number of logical cores on the system. If the value is shown in green, you are using fewer CPU cores than available on your system and can probably parallelize to improve performance; for tips on -how to do that, see parallel_fuzzing.txt. +how to do that, see parallel_fuzzing.md. If the value is shown in red, your CPU is *possibly* oversubscribed, and running additional fuzzers may not give you any benefits. @@ -380,39 +364,37 @@ are ready to run, but not how resource-hungry they may be. It also doesn't distinguish between physical cores, logical cores, and virtualized CPUs; the performance characteristics of each of these will differ quite a bit. -If you want a more accurate measurement, you can run the afl-gotcpu utility -from the command line. +If you want a more accurate measurement, you can run the `afl-gotcpu` utility from the command line. -10) Addendum: status and plot files ------------------------------------ +### Addendum: status and plot files For unattended operation, some of the key status screen information can be also found in a machine-readable format in the fuzzer_stats file in the output directory. This includes: - - start_time - unix time indicating the start time of afl-fuzz - - last_update - unix time corresponding to the last update of this file - - fuzzer_pid - PID of the fuzzer process - - cycles_done - queue cycles completed so far - - execs_done - number of execve() calls attempted - - execs_per_sec - current number of execs per second - - paths_total - total number of entries in the queue - - paths_found - number of entries discovered through local fuzzing - - paths_imported - number of entries imported from other instances - - max_depth - number of levels in the generated data set - - cur_path - currently processed entry number - - pending_favs - number of favored entries still waiting to be fuzzed - - pending_total - number of all entries waiting to be fuzzed - - stability - percentage of bitmap bytes that behave consistently - - variable_paths - number of test cases showing variable behavior - - unique_crashes - number of unique crashes recorded - - unique_hangs - number of unique hangs encountered - - command_line - full command line used for the fuzzing session - - slowest_exec_ms- real time of the slowest execution in seconds - - peak_rss_mb - max rss usage reached during fuzzing in MB + - `start_time` - unix time indicating the start time of afl-fuzz + - `last_update` - unix time corresponding to the last update of this file + - `fuzzer_pid` - PID of the fuzzer process + - `cycles_done` - queue cycles completed so far + - `execs_done` - number of execve() calls attempted + - `execs_per_sec` - current number of execs per second + - `paths_total` - total number of entries in the queue + - `paths_found` - number of entries discovered through local fuzzing + - `paths_imported` - number of entries imported from other instances + - `max_depth` - number of levels in the generated data set + - `cur_path` - currently processed entry number + - `pending_favs` - number of favored entries still waiting to be fuzzed + - `pending_total` - number of all entries waiting to be fuzzed + - `stability - percentage of bitmap bytes that behave consistently + - `variable_paths` - number of test cases showing variable behavior + - `unique_crashes` - number of unique crashes recorded + - `unique_hangs` - number of unique hangs encountered + - `command_line` - full command line used for the fuzzing session + - `slowest_exec_ms`- real time of the slowest execution in seconds + - `peak_rss_mb` - max rss usage reached during fuzzing in MB Most of these map directly to the UI elements discussed earlier on. -On top of that, you can also find an entry called 'plot_data', containing a +On top of that, you can also find an entry called `plot_data`, containing a plottable history for most of these fields. If you have gnuplot installed, you -can turn this into a nice progress report with the included 'afl-plot' tool. +can turn this into a nice progress report with the included `afl-plot` tool. diff --git a/docs/technical_details.txt b/docs/technical_details.md index 1604c4d0..d53b30e3 100644 --- a/docs/technical_details.txt +++ b/docs/technical_details.md @@ -1,13 +1,10 @@ -=================================== -Technical "whitepaper" for afl-fuzz -=================================== +# Technical "whitepaper" for afl-fuzz - This document provides a quick overview of the guts of American Fuzzy Lop. - See README for the general instruction manual; and for a discussion of - motivations and design goals behind AFL, see historical_notes.txt. +This document provides a quick overview of the guts of American Fuzzy Lop. +See README for the general instruction manual; and for a discussion of +motivations and design goals behind AFL, see historical_notes.md. -0) Design statement -------------------- +## 0. Design statement American Fuzzy Lop does its best not to focus on any singular principle of operation and not be a proof-of-concept for any specific theory. The tool can @@ -20,28 +17,30 @@ lightweight instrumentation that served as a foundation for the tool, but this mechanism should be thought of merely as a means to an end. The only true governing principles are speed, reliability, and ease of use. -1) Coverage measurements ------------------------- +## 1. Coverage measurements The instrumentation injected into compiled programs captures branch (edge) coverage, along with coarse branch-taken hit counts. The code injected at branch points is essentially equivalent to: +```c cur_location = <COMPILE_TIME_RANDOM>; shared_mem[cur_location ^ prev_location]++; prev_location = cur_location >> 1; +``` -The cur_location value is generated randomly to simplify the process of +The `cur_location` value is generated randomly to simplify the process of linking complex projects and keep the XOR output distributed uniformly. -The shared_mem[] array is a 64 kB SHM region passed to the instrumented binary +The `shared_mem[]` array is a 64 kB SHM region passed to the instrumented binary by the caller. Every byte set in the output map can be thought of as a hit for -a particular (branch_src, branch_dst) tuple in the instrumented code. +a particular (`branch_src`, `branch_dst`) tuple in the instrumented code. The size of the map is chosen so that collisions are sporadic with almost all of the intended targets, which usually sport between 2k and 10k discoverable branch points: +``` Branch cnt | Colliding tuples | Example targets ------------+------------------+----------------- 1,000 | 0.75% | giflib, lzo @@ -50,6 +49,7 @@ branch points: 10,000 | 7% | libxml 20,000 | 14% | sqlite 50,000 | 30% | - +``` At the same time, its size is small enough to allow the map to be analyzed in a matter of microseconds on the receiving end, and to effortlessly fit @@ -59,8 +59,10 @@ This form of coverage provides considerably more insight into the execution path of the program than simple block coverage. In particular, it trivially distinguishes between the following execution traces: +``` A -> B -> C -> D -> E (tuples: AB, BC, CD, DE) A -> B -> D -> C -> E (tuples: AB, BD, DC, CE) +``` This aids the discovery of subtle fault conditions in the underlying code, because security vulnerabilities are more often associated with unexpected @@ -75,8 +77,7 @@ The absence of simple saturating arithmetic opcodes on Intel CPUs means that the hit counters can sometimes wrap around to zero. Since this is a fairly unlikely and localized event, it's seen as an acceptable performance trade-off. -2) Detecting new behaviors --------------------------- +### 2. Detecting new behaviors The fuzzer maintains a global map of tuples seen in previous executions; this data can be rapidly compared with individual traces and updated in just a couple @@ -97,18 +98,24 @@ To illustrate the properties of the algorithm, consider that the second trace shown below would be considered substantially new because of the presence of new tuples (CA, AE): +``` #1: A -> B -> C -> D -> E #2: A -> B -> C -> A -> E +``` At the same time, with #2 processed, the following pattern will not be seen as unique, despite having a markedly different overall execution path: +``` #3: A -> B -> C -> A -> B -> C -> A -> B -> C -> D -> E +``` In addition to detecting new tuples, the fuzzer also considers coarse tuple hit counts. These are divided into several buckets: +``` 1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+ +``` To some extent, the number of buckets is an implementation artifact: it allows an in-place mapping of an 8-bit counter generated by the instrumentation to @@ -135,8 +142,7 @@ reject them and hope that the fuzzer will find a less expensive way to reach the same code. Empirical testing strongly suggests that more generous time limits are not worth the cost. -3) Evolving the input queue ---------------------------- +## 3. Evolving the input queue Mutated test cases that produced new state transitions within the program are added to the input queue and used as a starting point for future rounds of @@ -146,7 +152,7 @@ In contrast to more greedy genetic algorithms, this approach allows the tool to progressively explore various disjoint and possibly mutually incompatible features of the underlying data format, as shown in this image: - http://lcamtuf.coredump.cx/afl/afl_gzip.png +  Several practical examples of the results of this algorithm are discussed here: @@ -165,10 +171,11 @@ of new tuples, and the remainder is associated with changes in hit counts. The following table compares the relative ability to discover file syntax and explore program states when using several different approaches to guided -fuzzing. The instrumented target was GNU patch 2.7k.3 compiled with -O3 and +fuzzing. The instrumented target was GNU patch 2.7k.3 compiled with `-O3` and seeded with a dummy text file; the session consisted of a single pass over the input queue with afl-fuzz: +``` Fuzzer guidance | Blocks | Edges | Edge hit | Highest-coverage strategy used | reached | reached | cnt var | test case generated ------------------+---------+---------+----------+--------------------------- @@ -179,6 +186,7 @@ input queue with afl-fuzz: Block coverage | 855 | 1,130 | 1.57 | Almost-valid RCS diff Edge coverage | 1,452 | 2,070 | 2.18 | One-chunk -c mode diff AFL model | 1,765 | 2,597 | 4.99 | Four-chunk -c mode diff +``` The first entry for blind fuzzing ("S") corresponds to executing just a single round of testing; the second set of figures ("L") shows the fuzzer running in a @@ -191,6 +199,7 @@ a series of rudimentary, sequential operations such as walking bit flips. Because this mode would be incapable of altering the size of the input file, the sessions were seeded with a valid unified diff: +``` Queue extension | Blocks | Edges | Edge hit | Number of unique strategy used | reached | reached | cnt var | crashes found ------------------+---------+---------+----------+------------------ @@ -200,14 +209,14 @@ the sessions were seeded with a valid unified diff: Block coverage | 1,255 | 1,649 | 1.48 | 0 Edge coverage | 1,259 | 1,734 | 1.72 | 0 AFL model | 1,452 | 2,040 | 3.16 | 1 +``` At noted earlier on, some of the prior work on genetic fuzzing relied on maintaining a single test case and evolving it to maximize coverage. At least in the tests described above, this "greedy" approach appears to confer no substantial benefits over blind fuzzing strategies. -4) Culling the corpus ---------------------- +### 4. Culling the corpus The progressive state exploration approach outlined above means that some of the test cases synthesized later on in the game may have edge coverage that @@ -225,11 +234,8 @@ for each tuple. The tuples are then processed sequentially using a simple workflow: 1) Find next tuple not yet in the temporary working set, - 2) Locate the winning queue entry for this tuple, - 3) Register *all* tuples present in that entry's trace in the working set, - 4) Go to #1 if there are any missing tuples in the set. The generated corpus of "favored" entries is usually 5-10x smaller than the @@ -238,30 +244,26 @@ with varying probabilities when encountered in the queue: - If there are new, yet-to-be-fuzzed favorites present in the queue, 99% of non-favored entries will be skipped to get to the favored ones. - - If there are no new favorites: - - - If the current non-favored entry was fuzzed before, it will be skipped + * If the current non-favored entry was fuzzed before, it will be skipped 95% of the time. - - - If it hasn't gone through any fuzzing rounds yet, the odds of skipping + * If it hasn't gone through any fuzzing rounds yet, the odds of skipping drop down to 75%. Based on empirical testing, this provides a reasonable balance between queue cycling speed and test case diversity. Slightly more sophisticated but much slower culling can be performed on input -or output corpora with afl-cmin. This tool permanently discards the redundant -entries and produces a smaller corpus suitable for use with afl-fuzz or +or output corpora with `afl-cmin`. This tool permanently discards the redundant +entries and produces a smaller corpus suitable for use with `afl-fuzz` or external tools. -5) Trimming input files ------------------------ +## 5. Trimming input files File size has a dramatic impact on fuzzing performance, both because large files make the target binary slower, and because they reduce the likelihood that a mutation would touch important format control structures, rather than -redundant data blocks. This is discussed in more detail in perf_tips.txt. +redundant data blocks. This is discussed in more detail in perf_tips.md. The possibility that the user will provide a low-quality starting corpus aside, some types of mutations can have the effect of iteratively increasing the size @@ -275,12 +277,12 @@ The built-in trimmer in afl-fuzz attempts to sequentially remove blocks of data with variable length and stepover; any deletion that doesn't affect the checksum of the trace map is committed to disk. The trimmer is not designed to be particularly thorough; instead, it tries to strike a balance between precision -and the number of execve() calls spent on the process, selecting the block size +and the number of `execve()` calls spent on the process, selecting the block size and stepover to match. The average per-file gains are around 5-20%. -The standalone afl-tmin tool uses a more exhaustive, iterative algorithm, and +The standalone `afl-tmin` tool uses a more exhaustive, iterative algorithm, and also attempts to perform alphabet normalization on the trimmed files. The -operation of afl-tmin is as follows. +operation of `afl-tmin` is as follows. First, the tool automatically selects the operating mode. If the initial input crashes the target binary, afl-tmin will run in non-instrumented mode, simply @@ -293,16 +295,13 @@ The actual minimization algorithm is: 1) Attempt to zero large blocks of data with large stepovers. Empirically, this is shown to reduce the number of execs by preempting finer-grained efforts later on. - 2) Perform a block deletion pass with decreasing block sizes and stepovers, binary-search-style. - 3) Perform alphabet normalization by counting unique characters and trying to bulk-replace each with a zero value. - 4) As a last result, perform byte-by-byte normalization on non-zero bytes. -Instead of zeroing with a 0x00 byte, afl-tmin uses the ASCII digit '0'. This +Instead of zeroing with a 0x00 byte, `afl-tmin` uses the ASCII digit '0'. This is done because such a modification is much less likely to interfere with text parsing, so it is more likely to result in successful minimization of text files. @@ -312,8 +311,7 @@ minimization approaches proposed in academic work, but requires far fewer executions and tends to produce comparable results in most real-world applications. -6) Fuzzing strategies ---------------------- +## 6. Fuzzing strategies The feedback provided by the instrumentation makes it easy to understand the value of various fuzzing strategies and optimize their parameters so that they @@ -323,15 +321,13 @@ afl-fuzz are generally format-agnostic and are discussed in more detail here: http://lcamtuf.blogspot.com/2014/08/binary-fuzzing-strategies-what-works.html It is somewhat notable that especially early on, most of the work done by -afl-fuzz is actually highly deterministic, and progresses to random stacked +`afl-fuzz` is actually highly deterministic, and progresses to random stacked modifications and test case splicing only at a later stage. The deterministic strategies include: - Sequential bit flips with varying lengths and stepovers, - - Sequential addition and subtraction of small integers, - - - Sequential insertion of known interesting integers (0, 1, INT_MAX, etc), + - Sequential insertion of known interesting integers (`0`, `1`, `INT_MAX`, etc), The purpose of opening with deterministic steps is related to their tendency to produce compact test cases and small diffs between the non-crashing and crashing @@ -341,10 +337,10 @@ With deterministic fuzzing out of the way, the non-deterministic steps include stacked bit flips, insertions, deletions, arithmetics, and splicing of different test cases. -The relative yields and execve() costs of all these strategies have been +The relative yields and `execve()` costs of all these strategies have been investigated and are discussed in the aforementioned blog post. -For the reasons discussed in historical_notes.txt (chiefly, performance, +For the reasons discussed in historical_notes.md (chiefly, performance, simplicity, and reliability), AFL generally does not try to reason about the relationship between specific mutations and program states; the fuzzing steps are nominally blind, and are guided only by the evolutionary design of the @@ -365,8 +361,7 @@ in force only during deterministic stages that do not alter the size or the general layout of the underlying file, this mechanism appears to work very reliably and proved to be simple to implement. -7) Dictionaries ---------------- +## 7. Dictionaries The feedback provided by the instrumentation makes it easy to automatically identify syntax tokens in some types of input files, and to detect that certain @@ -398,31 +393,28 @@ to a predefined value baked into the code. The fuzzer relies on this signal to build compact "auto dictionaries" that are then used in conjunction with other fuzzing strategies. -8) De-duping crashes --------------------- +## 8. De-duping crashes De-duplication of crashes is one of the more important problems for any competent fuzzing tool. Many of the naive approaches run into problems; in particular, looking just at the faulting address may lead to completely unrelated issues being clustered together if the fault happens in a common -library function (say, strcmp, strcpy); while checksumming call stack +library function (say, `strcmp`, `strcpy`); while checksumming call stack backtraces can lead to extreme crash count inflation if the fault can be reached through a number of different, possibly recursive code paths. -The solution implemented in afl-fuzz considers a crash unique if any of two +The solution implemented in `afl-fuzz` considers a crash unique if any of two conditions are met: - The crash trace includes a tuple not seen in any of the previous crashes, - - The crash trace is missing a tuple that was always present in earlier faults. The approach is vulnerable to some path count inflation early on, but exhibits a very strong self-limiting effect, similar to the execution path analysis -logic that is the cornerstone of afl-fuzz. +logic that is the cornerstone of `afl-fuzz`. -9) Investigating crashes ------------------------- +## 9. Investigating crashes The exploitability of many types of crashes can be ambiguous; afl-fuzz tries to address this by providing a crash exploration mode where a known-faulting @@ -441,13 +433,12 @@ newly-found inputs for human review. On the subject of crashes, it is worth noting that in contrast to normal queue entries, crashing inputs are *not* trimmed; they are kept exactly as discovered to make it easier to compare them to the parent, non-crashing entry -in the queue. That said, afl-tmin can be used to shrink them at will. +in the queue. That said, `afl-tmin` can be used to shrink them at will. -10) The fork server -------------------- +## 10 The fork server -To improve performance, afl-fuzz uses a "fork server", where the fuzzed process -goes through execve(), linking, and libc initialization only once, and is then +To improve performance, `afl-fuzz` uses a "fork server", where the fuzzed process +goes through `execve()`, linking, and libc initialization only once, and is then cloned from a stopped process image by leveraging copy-on-write. The implementation is described in more detail here: @@ -455,7 +446,7 @@ implementation is described in more detail here: The fork server is an integral aspect of the injected instrumentation and simply stops at the first instrumented function to await commands from -afl-fuzz. +`afl-fuzz`. With fast targets, the fork server can offer considerable performance gains, usually between 1.5x and 2x. It is also possible to: @@ -464,17 +455,14 @@ usually between 1.5x and 2x. It is also possible to: user-selected chunks of initialization code. It requires very modest code changes to the targeted program, and With some targets, can produce 10x+ performance gains. - - Enable "persistent" mode, where a single process is used to try out - multiple inputs, greatly limiting the overhead of repetitive fork() + multiple inputs, greatly limiting the overhead of repetitive `fork()` calls. This generally requires some code changes to the targeted program, - but can improve the performance of fast targets by a factor of 5 or more - - approximating the benefits of in-process fuzzing jobs while still + but can improve the performance of fast targets by a factor of 5 or more - approximating the benefits of in-process fuzzing jobs while still maintaining very robust isolation between the fuzzer process and the targeted binary. -11) Parallelization -------------------- +## 11. Parallelization The parallelization mechanism relies on periodically examining the queues produced by independently-running instances on other CPU cores or on remote @@ -485,10 +473,9 @@ This allows for extreme flexibility in fuzzer setup, including running synced instances against different parsers of a common data format, often with synergistic effects. -For more information about this design, see parallel_fuzzing.txt. +For more information about this design, see parallel_fuzzing.md. -12) Binary-only instrumentation -------------------------------- +## 12. Binary-only instrumentation Instrumentation of black-box, binary-only targets is accomplished with the help of a separately-built version of QEMU in "user emulation" mode. This also @@ -497,6 +484,7 @@ allows the execution of cross-architecture code - say, ARM binaries on x86. QEMU uses basic blocks as translation units; the instrumentation is implemented on top of this and uses a model roughly analogous to the compile-time hooks: +```c if (block_address > elf_text_start && block_address < elf_text_end) { cur_location = (block_address >> 4) ^ (block_address << 8); @@ -504,6 +492,7 @@ on top of this and uses a model roughly analogous to the compile-time hooks: prev_location = cur_location >> 1; } +``` The shift-and-XOR-based scrambling in the second line is used to mask the effects of instruction alignment. @@ -511,7 +500,7 @@ effects of instruction alignment. The start-up of binary translators such as QEMU, DynamoRIO, and PIN is fairly slow; to counter this, the QEMU mode leverages a fork server similar to that used for compiler-instrumented code, effectively spawning copies of an -already-initialized process paused at _start. +already-initialized process paused at `_start`. First-time translation of a new basic block also incurs substantial latency. To eliminate this problem, the AFL fork server is extended by providing a channel @@ -523,8 +512,7 @@ processes. As a result of these two optimizations, the overhead of the QEMU mode is roughly 2-5x, compared to 100x+ for PIN. -13) The afl-analyze tool ------------------------- +## 13. The `afl-analyze` tool The file format analyzer is a simple extension of the minimization algorithm discussed earlier on; instead of attempting to remove no-op blocks, the tool @@ -536,28 +524,22 @@ It uses the following classification scheme: - "No-op blocks" - segments where bit flips cause no apparent changes to control flow. Common examples may be comment sections, pixel data within a bitmap file, etc. - - "Superficial content" - segments where some, but not all, bitflips produce some control flow changes. Examples may include strings in rich documents (e.g., XML, RTF). - - "Critical stream" - a sequence of bytes where all bit flips alter control flow in different but correlated ways. This may be compressed data, non-atomically compared keywords or magic values, etc. - - "Suspected length field" - small, atomic integer that, when touched in any way, causes a consistent change to program control flow, suggestive of a failed length check. - - "Suspected cksum or magic int" - an integer that behaves similarly to a length field, but has a numerical value that makes the length explanation unlikely. This is suggestive of a checksum or other "magic" integer. - - "Suspected checksummed block" - a long block of data where any change always triggers the same new execution path. Likely caused by failing a checksum or a similar integrity check before any subsequent parsing takes place. - - "Magic value section" - a generic token where changes cause the type of binary behavior outlined earlier, but that doesn't meet any of the - other criteria. May be an atomically compared keyword or so. + other criteria. May be an atomically compared keyword or so. \ No newline at end of file diff --git a/experimental/README.experiments b/examples/README.md index 543c078c..37fae1a0 100644 --- a/experimental/README.experiments +++ b/examples/README.md @@ -1,5 +1,11 @@ +# AFL++ Examples + Here's a quick overview of the stuff you can find in this directory: + - custom_mutstors - An example custom mutator + + - python_mutators - Python mutators examples + - argv_fuzzing - a simple wrapper to allow cmdline to be fuzzed (e.g., to test setuid programs). @@ -20,7 +26,7 @@ Here's a quick overview of the stuff you can find in this directory: with additional gdb metadata. - distributed_fuzzing - a sample script for synchronizing fuzzer instances - across multiple machines (see parallel_fuzzing.txt). + across multiple machines (see parallel_fuzzing.md). - libpng_no_checksum - a sample patch for removing CRC checks in libpng. @@ -32,7 +38,7 @@ Here's a quick overview of the stuff you can find in this directory: - socket_fuzzing - a LD_PRELOAD library 'redirects' a socket to stdin for fuzzing access with afl++ -Note that the minimize_corpus.sh tool has graduated from the experimental/ +Note that the minimize_corpus.sh tool has graduated from the examples/ directory and is now available as ../afl-cmin. The LLVM mode has likewise graduated to ../llvm_mode/*. diff --git a/experimental/argv_fuzzing/Makefile b/examples/argv_fuzzing/Makefile index ab16be87..ab16be87 100644 --- a/experimental/argv_fuzzing/Makefile +++ b/examples/argv_fuzzing/Makefile diff --git a/experimental/argv_fuzzing/README.md b/examples/argv_fuzzing/README.md index fa8cad80..fa8cad80 100644 --- a/experimental/argv_fuzzing/README.md +++ b/examples/argv_fuzzing/README.md diff --git a/experimental/argv_fuzzing/argv-fuzz-inl.h b/examples/argv_fuzzing/argv-fuzz-inl.h index 4d880020..4d880020 100644 --- a/experimental/argv_fuzzing/argv-fuzz-inl.h +++ b/examples/argv_fuzzing/argv-fuzz-inl.h diff --git a/experimental/argv_fuzzing/argvfuzz.c b/examples/argv_fuzzing/argvfuzz.c index 4251ca4c..4251ca4c 100644 --- a/experimental/argv_fuzzing/argvfuzz.c +++ b/examples/argv_fuzzing/argvfuzz.c diff --git a/experimental/asan_cgroups/limit_memory.sh b/examples/asan_cgroups/limit_memory.sh index ac3a90fe..1f0f04ad 100755 --- a/experimental/asan_cgroups/limit_memory.sh +++ b/examples/asan_cgroups/limit_memory.sh @@ -20,7 +20,7 @@ # This tool allows the amount of actual memory allocated to a program # to be limited on Linux systems using cgroups, instead of the traditional # setrlimit() API. This helps avoid the address space problems discussed in -# docs/notes_for_asan.txt. +# docs/notes_for_asan.md. # # Important: the limit covers *both* afl-fuzz and the fuzzed binary. In some # hopefully rare circumstances, afl-fuzz could be killed before the fuzzed diff --git a/experimental/bash_shellshock/shellshock-fuzz.diff b/examples/bash_shellshock/shellshock-fuzz.diff index 3fa05bf8..3fa05bf8 100644 --- a/experimental/bash_shellshock/shellshock-fuzz.diff +++ b/examples/bash_shellshock/shellshock-fuzz.diff diff --git a/experimental/canvas_harness/canvas_harness.html b/examples/canvas_harness/canvas_harness.html index a37b6937..a37b6937 100644 --- a/experimental/canvas_harness/canvas_harness.html +++ b/examples/canvas_harness/canvas_harness.html diff --git a/experimental/clang_asm_normalize/as b/examples/clang_asm_normalize/as index 45537cae..45537cae 100755 --- a/experimental/clang_asm_normalize/as +++ b/examples/clang_asm_normalize/as diff --git a/experimental/crash_triage/triage_crashes.sh b/examples/crash_triage/triage_crashes.sh index 6d026d61..6d026d61 100755 --- a/experimental/crash_triage/triage_crashes.sh +++ b/examples/crash_triage/triage_crashes.sh diff --git a/examples/custom_mutators/README b/examples/custom_mutators/README new file mode 100644 index 00000000..f2ae0e4f --- /dev/null +++ b/examples/custom_mutators/README @@ -0,0 +1,2 @@ +This is a simple example for the AFL_CUSTOM_MUTATOR_LIBRARY feature. +For more information see [docs/custom_mutator.md](../docs/custom_mutator.md) diff --git a/custom_mutators/simple_mutator.c b/examples/custom_mutators/simple_mutator.c index bf655679..bf655679 100644 --- a/custom_mutators/simple_mutator.c +++ b/examples/custom_mutators/simple_mutator.c diff --git a/experimental/distributed_fuzzing/sync_script.sh b/examples/distributed_fuzzing/sync_script.sh index c45ae69b..c45ae69b 100755 --- a/experimental/distributed_fuzzing/sync_script.sh +++ b/examples/distributed_fuzzing/sync_script.sh diff --git a/experimental/libpng_no_checksum/libpng-nocrc.patch b/examples/libpng_no_checksum/libpng-nocrc.patch index 0a3793a0..0a3793a0 100644 --- a/experimental/libpng_no_checksum/libpng-nocrc.patch +++ b/examples/libpng_no_checksum/libpng-nocrc.patch diff --git a/experimental/persistent_demo/persistent_demo.c b/examples/persistent_demo/persistent_demo.c index 7d8638fb..7d8638fb 100644 --- a/experimental/persistent_demo/persistent_demo.c +++ b/examples/persistent_demo/persistent_demo.c diff --git a/experimental/post_library/post_library.so.c b/examples/post_library/post_library.so.c index 487b9a6d..487b9a6d 100644 --- a/experimental/post_library/post_library.so.c +++ b/examples/post_library/post_library.so.c diff --git a/experimental/post_library/post_library_png.so.c b/examples/post_library/post_library_png.so.c index 43cb1101..43cb1101 100644 --- a/experimental/post_library/post_library_png.so.c +++ b/examples/post_library/post_library_png.so.c diff --git a/python_mutators/README b/examples/python_mutators/README index 4e7d62bc..8e378405 100644 --- a/python_mutators/README +++ b/examples/python_mutators/README @@ -1,5 +1,5 @@ These are example and helper files for the AFL_PYTHON_MODULE feature. -See docs/python_mutators.txt for more information +See [docs/python_mutators.md](../docs/python_mutators.md) for more information Note that if you compile with python3.7 you must use python3 scripts, and if you use pyton2.7 to compile python2 scripts! diff --git a/python_mutators/XmlMutatorMin.py b/examples/python_mutators/XmlMutatorMin.py index 058b7e61..058b7e61 100644 --- a/python_mutators/XmlMutatorMin.py +++ b/examples/python_mutators/XmlMutatorMin.py diff --git a/python_mutators/common.py b/examples/python_mutators/common.py index 28b8ee80..28b8ee80 100644 --- a/python_mutators/common.py +++ b/examples/python_mutators/common.py diff --git a/python_mutators/example.py b/examples/python_mutators/example.py index d32a7eb2..d32a7eb2 100644 --- a/python_mutators/example.py +++ b/examples/python_mutators/example.py diff --git a/python_mutators/simple-chunk-replace.py b/examples/python_mutators/simple-chunk-replace.py index 218dd4f8..218dd4f8 100644 --- a/python_mutators/simple-chunk-replace.py +++ b/examples/python_mutators/simple-chunk-replace.py diff --git a/python_mutators/wrapper_afl_min.py b/examples/python_mutators/wrapper_afl_min.py index df09b40a..df09b40a 100644 --- a/python_mutators/wrapper_afl_min.py +++ b/examples/python_mutators/wrapper_afl_min.py diff --git a/experimental/socket_fuzzing/Makefile b/examples/socket_fuzzing/Makefile index 0191ba53..0191ba53 100644 --- a/experimental/socket_fuzzing/Makefile +++ b/examples/socket_fuzzing/Makefile diff --git a/experimental/socket_fuzzing/README.md b/examples/socket_fuzzing/README.md index 79f28bea..79f28bea 100644 --- a/experimental/socket_fuzzing/README.md +++ b/examples/socket_fuzzing/README.md diff --git a/experimental/socket_fuzzing/socketfuzz.c b/examples/socket_fuzzing/socketfuzz.c index 3ec8383b..3ec8383b 100644 --- a/experimental/socket_fuzzing/socketfuzz.c +++ b/examples/socket_fuzzing/socketfuzz.c diff --git a/gcc_plugin/README.md b/gcc_plugin/README.md index 8b944f1a..fcc778fa 100644 --- a/gcc_plugin/README.md +++ b/gcc_plugin/README.md @@ -56,7 +56,7 @@ standard operating mode of AFL, e.g.: Be sure to also include CXX set to afl-g++-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, +[env_variables.md](../docs/env_variables.md). This includes AFL_INST_RATIO, AFL_USE_ASAN, AFL_HARDEN, and AFL_DONT_OPTIMIZE. Note: if you want the GCC plugin to be installed on your system for all @@ -141,7 +141,7 @@ 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. -A more detailed template is shown in ../experimental/persistent_demo/. +A more detailed template is shown in ../examples/persistent_demo/. Similarly to the previous mode, the feature works only with afl-gcc-fast or afl-clang-fast; #ifdef guards can be used to suppress it when using other compilers. diff --git a/llvm_mode/README.md b/llvm_mode/README.md index 8af763c5..ee6e51b5 100644 --- a/llvm_mode/README.md +++ b/llvm_mode/README.md @@ -73,7 +73,7 @@ operating mode of AFL, e.g.: 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_USE_ASAN, +[docs/env_variables.md](../docs/env_variables.md)). This includes AFL_USE_ASAN, AFL_HARDEN, and AFL_DONT_OPTIMIZE. However AFL_INST_RATIO is not honored as it does not serve a good purpose with the more effective instrim CFG analysis. @@ -189,7 +189,7 @@ the impact of memory leaks and similar glitches; 1000 is a good starting point, and going much higher increases the likelihood of hiccups without giving you any real performance benefits. -A more detailed template is shown in ../experimental/persistent_demo/. +A more detailed template is shown in ../examples/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. diff --git a/qemu_mode/README.md b/qemu_mode/README.md index 60d6c060..ccfd50e3 100644 --- a/qemu_mode/README.md +++ b/qemu_mode/README.md @@ -164,7 +164,7 @@ match. ## 9) Gotchas, feedback, bugs If you need to fix up checksums or do other cleanup on mutated test cases, see -experimental/post_library/ for a viable solution. +examples/post_library/ for a viable solution. Do not mix QEMU mode with ASAN, MSAN, or the likes; QEMU doesn't appreciate the "shadow VM" trick employed by the sanitizers and will probably just diff --git a/src/afl-as.c b/src/afl-as.c index 8d689385..5fa83569 100644 --- a/src/afl-as.c +++ b/src/afl-as.c @@ -27,7 +27,7 @@ utility has right now is to be able to skip them gracefully and allow the compilation process to continue. - That said, see experimental/clang_asm_normalize/ for a solution that may + That said, see examples/clang_asm_normalize/ for a solution that may allow clang users to make things work even with hand-crafted assembly. Just note that there is no equivalent for GCC. diff --git a/src/afl-forkserver.c b/src/afl-forkserver.c index 77e1d648..b1943633 100644 --- a/src/afl-forkserver.c +++ b/src/afl-forkserver.c @@ -332,7 +332,7 @@ void init_forkserver(char **argv) { "have a\n" " restrictive memory limit configured, this is expected; please " "read\n" - " %s/notes_for_asan.txt for help.\n", + " %s/notes_for_asan.md for help.\n", doc_path); } else if (!mem_limit) { @@ -408,7 +408,7 @@ void init_forkserver(char **argv) { "with ASAN and\n" " you have a restrictive memory limit configured, this is " "expected; please\n" - " read %s/notes_for_asan.txt for help.\n", + " read %s/notes_for_asan.md for help.\n", doc_path); } else if (!mem_limit) { diff --git a/src/afl-fuzz-cmplog.c b/src/afl-fuzz-cmplog.c index 5906756d..92bac4ab 100644 --- a/src/afl-fuzz-cmplog.c +++ b/src/afl-fuzz-cmplog.c @@ -217,7 +217,7 @@ void init_cmplog_forkserver(char** argv) { "have a\n" " restrictive memory limit configured, this is expected; please " "read\n" - " %s/notes_for_asan.txt for help.\n", + " %s/notes_for_asan.md for help.\n", doc_path); } else if (!mem_limit) { @@ -293,7 +293,7 @@ void init_cmplog_forkserver(char** argv) { "with ASAN and\n" " you have a restrictive memory limit configured, this is " "expected; please\n" - " read %s/notes_for_asan.txt for help.\n", + " read %s/notes_for_asan.md for help.\n", doc_path); } else if (!mem_limit) { diff --git a/src/afl-fuzz-init.c b/src/afl-fuzz-init.c index c4a02698..9265e4a5 100644 --- a/src/afl-fuzz-init.c +++ b/src/afl-fuzz-init.c @@ -601,7 +601,7 @@ void perform_dry_run(char** argv) { "quickly\n" " estimate the required amount of virtual memory for the " "binary. Also,\n" - " if you are using ASAN, see %s/notes_for_asan.txt.\n\n" + " if you are using ASAN, see %s/notes_for_asan.md.\n\n" MSG_FORK_ON_APPLE @@ -1719,7 +1719,7 @@ void get_core_count(void) { } else if (cur_runnable + 1 <= cpu_core_count) { - OKF("Try parallel jobs - see %s/parallel_fuzzing.txt.", doc_path); + OKF("Try parallel jobs - see %s/parallel_fuzzing.md.", doc_path); } diff --git a/src/afl-fuzz-stats.c b/src/afl-fuzz-stats.c index be065647..9dc4b917 100644 --- a/src/afl-fuzz-stats.c +++ b/src/afl-fuzz-stats.c @@ -747,7 +747,7 @@ void show_init_stats(void) { SAYF("\n"); if (avg_us > ((qemu_mode || unicorn_mode) ? 50000 : 10000)) - WARNF(cLRD "The target binary is pretty slow! See %s/perf_tips.txt.", + WARNF(cLRD "The target binary is pretty slow! See %s/perf_tips.md.", doc_path); /* Let's keep things moving with slow binaries. */ @@ -762,10 +762,10 @@ void show_init_stats(void) { if (!resuming_fuzz) { if (max_len > 50 * 1024) - WARNF(cLRD "Some test cases are huge (%s) - see %s/perf_tips.txt!", + WARNF(cLRD "Some test cases are huge (%s) - see %s/perf_tips.md!", DMS(max_len), doc_path); else if (max_len > 10 * 1024) - WARNF("Some test cases are big (%s) - see %s/perf_tips.txt.", + WARNF("Some test cases are big (%s) - see %s/perf_tips.md.", DMS(max_len), doc_path); if (useless_at_start && !in_bitmap) diff --git a/src/afl-fuzz.c b/src/afl-fuzz.c index eae4ba1f..8833244d 100644 --- a/src/afl-fuzz.c +++ b/src/afl-fuzz.c @@ -96,7 +96,7 @@ static void usage(u8* argv0) { "score.\n" " <explore (default), fast, coe, lin, quad, or " "exploit>\n" - " see docs/power_schedules.txt\n" + " see docs/power_schedules.md\n" " -f file - location read by the fuzzed program (stdin)\n" " -t msec - timeout for each run (auto-scaled, 50-%d ms)\n" " -m megs - memory limit for child process (%d MB)\n" @@ -133,7 +133,7 @@ static void usage(u8* argv0) { "Other stuff:\n" " -T text - text banner to show on the screen\n" - " -M / -S id - distributed mode (see parallel_fuzzing.txt)\n" + " -M / -S id - distributed mode (see parallel_fuzzing.md)\n" " -I command - execute this command/script when a new crash is " "found\n" " -B bitmap.txt - mutate a specific test case, use the out/fuzz_bitmap " @@ -145,7 +145,7 @@ static void usage(u8* argv0) { argv0, EXEC_TIMEOUT, MEM_LIMIT); #ifdef USE_PYTHON - SAYF("Compiled with %s module support, see docs/python_mutators.txt\n", + SAYF("Compiled with %s module support, see docs/python_mutators.md\n", (char*)PYTHON_VERSION); #endif diff --git a/src/afl-gotcpu.c b/src/afl-gotcpu.c index 5be30238..214862a9 100644 --- a/src/afl-gotcpu.c +++ b/src/afl-gotcpu.c @@ -19,7 +19,7 @@ This tool provides a fairly accurate measurement of CPU preemption rate. It is meant to complement the quick-and-dirty load average widget shown - in the afl-fuzz UI. See docs/parallel_fuzzing.txt for more info. + in the afl-fuzz UI. See docs/parallel_fuzzing.md for more info. For some work loads, the tool may actually suggest running more instances than you have CPU cores. This can happen if the tested program is spending diff --git a/src/afl-showmap.c b/src/afl-showmap.c index b9da3208..0aa5c158 100644 --- a/src/afl-showmap.c +++ b/src/afl-showmap.c @@ -39,6 +39,7 @@ #include "alloc-inl.h" #include "hash.h" #include "sharedmem.h" +#include "forkserver.h" #include "common.h" #include <stdio.h> @@ -58,19 +59,39 @@ #include <sys/types.h> #include <sys/resource.h> -static s32 child_pid; /* PID of the tested program */ +u8* trace_bits; /* SHM with instrumentation bitmap */ + +s32 forksrv_pid, /* PID of the fork server */ + child_pid; /* PID of the tested program */ + +s32 fsrv_ctl_fd, /* Fork server control pipe (write) */ + fsrv_st_fd; /* Fork server status pipe (read) */ + +s32 out_fd; /* Persistent fd for out_file */ +s32 dev_null_fd = -1; /* FD to /dev/null */ + +s32 out_fd = -1, out_dir_fd = -1, dev_urandom_fd = -1; +FILE* plot_file; +u8 uses_asan; u8* trace_bits; /* SHM with instrumentation bitmap */ -static u8 *out_file, /* Trace output file */ +u8 *out_file, /* Trace output file */ + *in_dir, /* input folder */ *doc_path, /* Path to docs */ *at_file; /* Substitution string for @@ */ -static u32 exec_tmout; /* Exec timeout (ms) */ +static u8* in_data; /* Input data */ + +u32 exec_tmout; /* Exec timeout (ms) */ static u32 total, highest; /* tuple content information */ -static u64 mem_limit = MEM_LIMIT; /* Memory limit (MB) */ +static u32 in_len, /* Input data length */ + arg_offset, + total_execs; /* Total number of execs */ + +u64 mem_limit = MEM_LIMIT; /* Memory limit (MB) */ u8 quiet_mode, /* Hide non-essential messages? */ edges_only, /* Ignore hit counts? */ @@ -139,7 +160,7 @@ static void classify_counts(u8* mem, const u8* map) { /* Write results. */ -static u32 write_results(void) { +static u32 write_results_to_file(u8 *out_file) { s32 fd; u32 i, ret = 0; @@ -208,15 +229,172 @@ static u32 write_results(void) { } -/* Handle timeout signal. */ +/* Write results. */ -static void handle_timeout(int sig) { +static u32 write_results(void) { - child_timed_out = 1; - if (child_pid > 0) kill(child_pid, SIGKILL); + return write_results_to_file(out_file); + +} + +/* Write output file. */ + +static s32 write_to_file(u8* path, u8* mem, u32 len) { + + s32 ret; + + unlink(path); /* Ignore errors */ + + ret = open(path, O_RDWR | O_CREAT | O_EXCL, 0600); + + if (ret < 0) PFATAL("Unable to create '%s'", path); + + ck_write(ret, mem, len, path); + + lseek(ret, 0, SEEK_SET); + + return ret; + +} + +/* Write modified data to file for testing. If use_stdin is clear, the old file + is unlinked and a new one is created. Otherwise, out_fd is rewound and + truncated. */ + +static void write_to_testcase(void* mem, u32 len) { + + if (use_stdin) { + + lseek(0, 0, SEEK_SET); + + ck_write(0, mem, len, out_file); + + if (ftruncate(0, len)) PFATAL("ftruncate() failed"); + lseek(0, 0, SEEK_SET); + + } } +/* Execute target application. Returns 0 if the changes are a dud, or + 1 if they should be kept. */ + +static u8 run_target_forkserver(char** argv, u8* mem, u32 len) { + + static struct itimerval it; + static u32 prev_timed_out = 0; + int status = 0; + + memset(trace_bits, 0, MAP_SIZE); + MEM_BARRIER(); + + write_to_testcase(mem, len); + + s32 res; + + /* we have the fork server up and running, so simply + tell it to have at it, and then read back PID. */ + + if ((res = write(fsrv_ctl_fd, &prev_timed_out, 4)) != 4) { + + if (stop_soon) return 0; + RPFATAL(res, "Unable to request new process from fork server (OOM?)"); + + } + + if ((res = read(fsrv_st_fd, &child_pid, 4)) != 4) { + + if (stop_soon) return 0; + RPFATAL(res, "Unable to request new process from fork server (OOM?)"); + + } + + if (child_pid <= 0) FATAL("Fork server is misbehaving (OOM?)"); + + /* Configure timeout, wait for child, cancel timeout. */ + + if (exec_tmout) { + + it.it_value.tv_sec = (exec_tmout / 1000); + it.it_value.tv_usec = (exec_tmout % 1000) * 1000; + + } + + setitimer(ITIMER_REAL, &it, NULL); + + if ((res = read(fsrv_st_fd, &status, 4)) != 4) { + + if (stop_soon) return 0; + RPFATAL(res, "Unable to communicate with fork server (OOM?)"); + + } + + child_pid = 0; + it.it_value.tv_sec = 0; + it.it_value.tv_usec = 0; + + setitimer(ITIMER_REAL, &it, NULL); + + MEM_BARRIER(); + + /* Clean up bitmap, analyze exit condition, etc. */ + + if (*(u32*)trace_bits == EXEC_FAIL_SIG) + FATAL("Unable to execute '%s'", argv[0]); + + classify_counts(trace_bits, + binary_mode ? count_class_binary : count_class_human); + total_execs++; + + if (stop_soon) { + + SAYF(cRST cLRD "\n+++ afl-showmap folder mode aborted by user +++\n" cRST); + close(write_to_file(out_file, in_data, in_len)); + exit(1); + + } + + /* Always discard inputs that time out. */ + + if (child_timed_out) { return 0; } + + /* Handle crashing inputs depending on current mode. */ + + if (WIFSIGNALED(status) || + (WIFEXITED(status) && WEXITSTATUS(status) == MSAN_ERROR) || + (WIFEXITED(status) && WEXITSTATUS(status))) { + + return 0; + + } + + return 0; + +} + +/* Read initial file. */ + +u32 read_file(u8 *in_file) { + + struct stat st; + s32 fd = open(in_file, O_RDONLY); + + if (fd < 0) WARNF("Unable to open '%s'", in_file); + + if (fstat(fd, &st) || !st.st_size) WARNF("Zero-sized input file '%s'.", in_file); + + in_len = st.st_size; + in_data = ck_alloc_nozero(in_len); + + ck_read(fd, in_data, in_len, in_file); + + close(fd); + + //OKF("Read %u byte%s from '%s'.", in_len, in_len == 1 ? "" : "s", in_file); + + return in_len; +} + /* Execute target application. */ static void run_target(char** argv) { @@ -456,6 +634,8 @@ static void usage(u8* argv0) { "Other settings:\n\n" + " -i dir - process all files in this directory, -o most be a directory\n" + " and each bitmap will be written there individually.\n" " -q - sink program's output and don't show messages\n" " -e - show edge coverage only, ignore hit counts\n" " -r - show real tuple values instead of AFL filter values\n" @@ -529,17 +709,22 @@ static void find_binary(u8* fname) { int main(int argc, char** argv) { - s32 opt; + s32 opt, i; u8 mem_limit_given = 0, timeout_given = 0, unicorn_mode = 0, use_wine = 0; u32 tcnt = 0; char** use_argv; doc_path = access(DOC_PATH, F_OK) ? "docs" : DOC_PATH; - while ((opt = getopt(argc, argv, "+o:f:m:t:A:eqZQUWbcrh")) > 0) + while ((opt = getopt(argc, argv, "+i:o:f:m:t:A:eqZQUWbcrh")) > 0) switch (opt) { + case 'i': + if (in_dir) FATAL("Multiple -i options not supported"); + in_dir = optarg; + break; + case 'o': if (out_file) FATAL("Multiple -o options not supported"); @@ -707,7 +892,13 @@ int main(int argc, char** argv) { } + if (in_dir) at_file = "@@"; + detect_file_args(argv + optind, at_file); + + for (i = optind; i < argc; i++) + if (strcmp(argv[i], "@@") == 0) + arg_offset = i; if (qemu_mode) { @@ -720,9 +911,48 @@ int main(int argc, char** argv) { use_argv = argv + optind; - run_target(use_argv); + if (in_dir) { + + DIR *dir_in, *dir_out; + struct dirent* dir_ent; + int done = 0; + u8 infile[4096], outfile[4096]; + + dev_null_fd = open("/dev/null", O_RDWR); + if (dev_null_fd < 0) PFATAL("Unable to open /dev/null"); - tcnt = write_results(); + if (!(dir_in = opendir(in_dir))) PFATAL("cannot open directory %s", in_dir); + + if (!(dir_out = opendir(out_file))) + if (mkdir(out_file, 0700)) + PFATAL("cannot create output directory %s", out_file); + + if (arg_offset) argv[arg_offset] = infile; + + init_forkserver(use_argv); + + while (done == 0 && (dir_ent = readdir(dir_in))) { + + if (dir_ent->d_name[0] == '.') continue; // skip anything that starts with '.' + if (dir_ent->d_type != DT_REG) continue; // only regular files + + snprintf(infile, sizeof(infile), "%s/%s", in_dir, dir_ent->d_name); + snprintf(outfile, sizeof(outfile), "%s/%s", out_file, dir_ent->d_name); + + if (read_file(infile)) { + run_target_forkserver(use_argv, in_data, in_len); + ck_free(in_data); + tcnt = write_results_to_file(outfile); + } + + } + + } else { + + run_target(use_argv); + tcnt = write_results(); + + } if (!quiet_mode) { @@ -735,4 +965,3 @@ int main(int argc, char** argv) { exit(child_crashed * 2 + child_timed_out); } - diff --git a/src/afl-tmin.c b/src/afl-tmin.c index 7ce0ccaa..e783b5f0 100644 --- a/src/afl-tmin.c +++ b/src/afl-tmin.c @@ -524,14 +524,16 @@ static u8 run_target(char** argv, u8* mem, u32 len, u8 first_run) { } - } else + } else { - /* Handle non-crashing inputs appropriately. */ + /* Handle non-crashing inputs appropriately. */ - if (crash_mode) { + if (crash_mode) { - missed_paths++; - return 0; + missed_paths++; + return 0; + + } } diff --git a/test/test.sh b/test/test.sh index 20e02a83..79cba57a 100755 --- a/test/test.sh +++ b/test/test.sh @@ -318,7 +318,7 @@ test -e ../afl-clang-fast -a -e ../split-switches-pass.so && { CODE=1 } rm -f test-compcov test.out whitelist.txt - ../afl-clang-fast -o test-persistent ../experimental/persistent_demo/persistent_demo.c > /dev/null 2>&1 + ../afl-clang-fast -o test-persistent ../examples/persistent_demo/persistent_demo.c > /dev/null 2>&1 test -e test-persistent && { echo foo | ../afl-showmap -o /dev/null -q -r ./test-persistent && { $ECHO "$GREEN[+] llvm_mode persistent mode feature works correctly" @@ -427,7 +427,7 @@ test -e ../afl-gcc-fast -a -e ../afl-gcc-rt.o && { CODE=1 } rm -f test-compcov test.out whitelist.txt - ../afl-gcc-fast -o test-persistent ../experimental/persistent_demo/persistent_demo.c > /dev/null 2>&1 + ../afl-gcc-fast -o test-persistent ../examples/persistent_demo/persistent_demo.c > /dev/null 2>&1 test -e test-persistent && { echo foo | ../afl-showmap -o /dev/null -q -r ./test-persistent && { $ECHO "$GREEN[+] gcc_plugin persistent mode feature works correctly" |