[test suite] AFL fuzzing README update master
authorMichael Rash <mbr@cipherdyne.org>
Sat, 22 Nov 2014 03:18:17 +0000 (22:18 -0500)
committerMichael Rash <mbr@cipherdyne.org>
Sat, 22 Nov 2014 03:18:17 +0000 (22:18 -0500)
test/afl/README

index f2d5ab6..aa2dd44 100644 (file)
@@ -1,38 +1,53 @@
 
+-- Quick Start --
+
+To get going with AFL fuzzing against fwknop:
+
+$ ./compile/afl-compile.sh
+$ ./fuzzing-wrappers/spa-pkts.sh
+
+Output will be placed in fuzzing-output/server-conf.out/
+
+
+-- More Information --
+
 The fwknop project supports various fuzzing strategies, and one of the most
 important is usage of the 'American Fuzzy Lop' (AFL) fuzzer written by Michal
-Zalewski (see: https://code.google.com/p/american-fuzzy-lop/). Because AFL is
-not designed to handle encryption schemes (see the README included in the AFL
-sources for more information on this), a special --enable-afl-fuzzing command
-line switch is available to the fwknop autoconf configure script. This argument
-allows encryption and base64 encoding to be bypassed when feeding SPA packet
-data to fwknopd via stdin. It is the feature that enables AFL fuzzing.
-
-This directory contains enabling scripts in order to make it easy to fuzz
-fwknop with AFL. It is assumed that AFL is installed and in your path. The
+Zalewski (see: http://lcamtuf.coredump.cx/afl/). Because AFL is not designed to
+handle encryption schemes (see the README included in the AFL sources for more
+information on this), a special --enable-afl-fuzzing command line switch is
+available in the fwknop autoconf configure script. This argument allows
+encryption and base64 encoding to be bypassed when feeding SPA packet data to
+fwknopd via stdin. It is this feature that enables AFL fuzzing. One exception
+to this is made when using AFL to fuzz the fwknoprc file that is leveraged by
+the fwknop client - in this case, fwknop should not be compiled with
+--enable-afl-fuzzing (use the compile/afl-compile-no-enable-arg.sh script).
+
+The top level directory contains enabling scripts in order to make it easy to
+fuzz fwknop with AFL. It is assumed that AFL is installed and in your path. The
 files are in this directory are organized as follows:
 
-afl-fuzzing.in   - Directory for initial AFL test case(s).
-afl-fuzzing.out  - Directory for AFL results after a fuzzing run.
+fuzzing-wrappers/  - Directory that contains wrapper scripts for running AFL
+                     against fwknop. All interaction with AFL should be done
+                     with these scripts, and they should be executed from the
+                     test/afl/ directory, e.g. "./fuzzing-wrappers/client-rc.sh"
 
-afl-compile.sh   - Script to compile fwknop underneath afl-gcc.
-afl-fuzzing.in   - AFL input directory which contains input test cases.
-afl-fuzzing.out  - AFL output directory.
-afl-run.sh       - Script to invoke AFL with proper command line arguments to
-                   fwknopd for fuzzing enablement.
+test-cases/        - Directory for ALF test cases used by the wrapper scripts.
+                     There are four areas in fwknop that are fuzzed: SPA packet
+                     encoding/decoding, server access.conf and fwknopd.conf
+                     parsing, and client fwknoprc file parsing.
 
-For gcov code coverage only:
+compile/           - Directory for compilation scripts to ensure fwknop is
+                     compiled underneath afl-gcc.
 
-afl-compile-code-coverage.sh    - Compile fwknop with code coverage support.
-afl-gen-code-coverage.sh        - Generate code coverage report after running
-                                  afl-run.sh (and with coverage support
-                                  compiled in)
+fuzzing-output/    - Results directory that is made underneath an AFL fuzzing
+                     cycle.
 
 Here is an example of what fwknopd produces when compiled for AFL support when
 a dummy SPA packet is provided in non-encoded/encrypted form via fwknopd's
 stdin:
 
-$ ./fwknopd-stdin-test.sh
+$ ./fuzzing-wrappers/helpers/fwknopd-stdin-test.sh
 + SPA_PKT=1716411011200157:root:1397329899:2.0.1:1:127.0.0.2,tcp/22:AAAAA
 + LD_LIBRARY_PATH=../../lib/.libs ../../server/.libs/fwknopd -c ../conf/default_fwknopd.conf -a ../conf/default_access.conf -A -f -t
 + echo -n 1716411011200157:root:1397329899:2.0.1:1:127.0.0.2,tcp/22:AAAAA