about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/ChangeLog8
-rw-r--r--docs/PATCHES6
-rw-r--r--docs/README30
-rw-r--r--docs/README.MOpt43
-rw-r--r--docs/binaryonly_fuzzing.txt115
-rw-r--r--docs/env_variables.txt23
6 files changed, 204 insertions, 21 deletions
diff --git a/docs/ChangeLog b/docs/ChangeLog
index 0d730118..dca674a2 100644
--- a/docs/ChangeLog
+++ b/docs/ChangeLog
@@ -17,6 +17,10 @@ sending a mail to <afl-users+subscribe@googlegroups.com>.
 Version ++2.52d (tbd):
 -----------------------------
 
+  - added MOpt (github.com/puppet-meteor/MOpt-AFL) mode
+  - added never zero counters for afl-gcc and optional (because of an
+    optimization issue in llvm < 9) for llvm_mode (AFL_LLVM_NEVER_ZERO=1)
+  - added a new doc about binary only fuzzing: docs/binaryonly_fuzzing.txt
   - more cpu power for afl-system-config
   - added forkserver patch to afl-tmin, makes it much faster (originally from
     github.com/nccgroup/TriforceAFL)
@@ -27,9 +31,13 @@ Version ++2.52d (tbd):
     see docs/python_mutators.txt (originally by choller@mozilla)
   - added AFL_CAL_FAST for slow applications and AFL_DEBUG_CHILD_OUTPUT for
     debugging
+  - added -V time and -E execs option to better comparison runs, runs afl-fuzz
+    for a specific time/executions.
   - added a  -s seed  switch to allow afl run with a fixed initial
     seed that is not updated. this is good for performance and path discovery
     tests as the random numbers are deterministic then
+  - llvm_mode LAF_... env variables can now be specified as AFL_LLVM_LAF_...
+    that is longer but in line with other llvm specific env vars
   - ... your idea or patch?
 
 
diff --git a/docs/PATCHES b/docs/PATCHES
index f61f8d24..f6ca9284 100644
--- a/docs/PATCHES
+++ b/docs/PATCHES
@@ -17,10 +17,12 @@ 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
 
++ instrim (https://github.com/csienslab/instrim) was integrated
++ MOpt (github.com/puppet-meteor/MOpt-AFL) was imported
 + AFLfast additions (github.com/mboehme/aflfast) were incorporated.
 + Qemu 3.1 upgrade with enhancement patches (github.com/andreafioraldi/afl)
-+ Python mutator modules support (github.com/choeller/afl)
-+ Whitelisting in LLVM mode (github.com/choeller/afl)
++ Python mutator modules support (github.com/choller/afl)
++ Whitelisting in LLVM mode (github.com/choller/afl)
 + forkserver patch for afl-tmin (github.com/nccgroup/TriforceAFL)
 
 
diff --git a/docs/README b/docs/README
index ca8533f7..54e3e4a4 100644
--- a/docs/README
+++ b/docs/README
@@ -2,27 +2,31 @@
 american fuzzy lop plus plus
 ============================
 
-  Written by Michal Zalewski <lcamtuf@google.com>
+  Originally written by Michal Zalewski <lcamtuf@google.com>
 
   Repository: https://github.com/vanhauser-thc/AFLplusplus
 
-  afl++ is maintained by Marc Heuse <mh@mh-sec.de> and Heiko Eissfeldt
-  <heiko.eissfeldt@hexco.de> as there have been no updates to afl since
-  November 2017.
+  afl++ is maintained by Marc Heuse <mh@mh-sec.de>, Heiko Eissfeldt
+  <heiko.eissfeldt@hexco.de> and Andrea Fioraldi as there have been no
+  updates to afl since November 2017.
 
-  This version has several bug fixes, new features and speed enhancements
-  based on community patches from https://github.com/vanhauser-thc/afl-patches
-  To see the list of which patches have been applied, see the PATCHES file.
+  Many improvements were made, e.g. more performant llvm_mode, supporting
+  llvm up to version 8, Qemu 3.1, more speed for Qemu, etc.
 
   Additionally AFLfast's power schedules by Marcel Boehme from
-  github.com/mboehme/aflfast have been incorporated.
+  https://github.com/mboehme/aflfast have been incorporated.
 
-  Plus it was upgraded to qemu 3.1 from 2.1 with the work of 
-  https://github.com/andreafioraldi/afl and got the community patches applied
-  to it.
+  C. Hollers afl-fuzz Python mutator module and llvm_mode whitelist support
+  was added too (https://github.com/choller/afl)
 
-  C. Hoellers afl-fuzz Python mutator module and llvm_mode whitelist support
-  was added too (https://github.com/choeller/afl)
+  New is the excellent MOpt mutator from
+  https://github.com/puppet-meteor/MOpt-AFL  
+
+  Also newly integrated is instrim, a very effective CFG llvm_mode
+  instrumentation implementation which replaced the original afl one and is
+  from https://github.com/csienslab/instrim
+
+  A more thorough list is available in the PATCHES file.
 
   So all in all this is the best-of AFL that is currently out there :-)
 
diff --git a/docs/README.MOpt b/docs/README.MOpt
new file mode 100644
index 00000000..836f5200
--- /dev/null
+++ b/docs/README.MOpt
@@ -0,0 +1,43 @@
+# MOpt(imized) AFL by <puppet@zju.edu.cn>
+
+### 1. Description
+MOpt-AFL is a AFL-based fuzzer that utilizes a customized Particle Swarm
+Optimization (PSO) algorithm to find the optimal selection probability
+distribution of operators with respect to fuzzing effectiveness.
+More details can be found in the technical report.
+
+### 2. Cite Information
+Chenyang Lv, Shouling Ji, Chao Zhang, Yuwei Li, Wei-Han Lee, Yu Song and
+Raheem Beyah, MOPT: Optimized Mutation Scheduling for Fuzzers,
+USENIX Security 2019. 
+
+### 3. Seed Sets
+We open source all the seed sets used in the paper 
+"MOPT: Optimized Mutation Scheduling for Fuzzers".
+
+### 4. Experiment Results
+The experiment results can be found in 
+https://drive.google.com/drive/folders/184GOzkZGls1H2NuLuUfSp9gfqp1E2-lL?usp=sharing.  We only open source the crash files since the space is limited. 
+
+### 5. Technical Report
+MOpt_TechReport.pdf is the technical report of the paper 
+"MOPT: Optimized Mutation Scheduling for Fuzzers", which contains more deatails.
+
+### 6. Parameter Introduction
+Most important, you must add the parameter `-L` (e.g., `-L 0`) to launch the
+MOpt scheme. 
+<br>`-L` controls the time to move on to the pacemaker fuzzing mode.
+<br>`-L t:` when MOpt-AFL finishes the mutation of one input, if it has not
+discovered any new unique crash or path for more than t min, MOpt-AFL will
+enter the pacemaker fuzzing mode. 
+<br>Setting 0 will enter the pacemaker fuzzing mode at first, which is
+recommended in a short time-scale evaluation. 
+
+Other important parameters can be found in afl-fuzz.c, for instance, 
+<br>`swarm_num:` the number of the PSO swarms used in the fuzzing process.
+<br>`period_pilot:` how many times MOpt-AFL will execute the target program in the pilot fuzzing module, then it will enter the core fuzzing module. 
+<br>`period_core:` how many times MOpt-AFL will execute the target program in the core fuzzing module, then it will enter the PSO updating module. 
+<br>`limit_time_bound:` control how many interesting test cases need to be found before MOpt-AFL quits the pacemaker fuzzing mode and reuses the deterministic stage. 
+0 < `limit_time_bound` < 1, MOpt-AFL-tmp.  `limit_time_bound` >= 1, MOpt-AFL-ever. 
+
+Having fun with MOpt in AFL!
diff --git a/docs/binaryonly_fuzzing.txt b/docs/binaryonly_fuzzing.txt
new file mode 100644
index 00000000..f370ec74
--- /dev/null
+++ b/docs/binaryonly_fuzzing.txt
@@ -0,0 +1,115 @@
+
+Fuzzing binary-only programs with afl++
+=======================================
+
+afl++, libfuzzer and others are great if you have the source code, and
+it allows for very fast and coverage guided fuzzing.
+
+However, if there is only the binary program and not source code available,
+then standard afl++ (dumb mode) is not effective.
+
+The following is a description of how these can be fuzzed with afl++
+
+!!!!!
+DTLR: try DYNINST with afl-dyninst. If it produces too many crashes then
+      use afl -Q qemu_mode.
+!!!!!
+
+
+QEMU
+----
+Qemu is the "native" solution to the program.
+It is available in the ./qemu_mode/ directory and once compiled it can
+be accessed by the afl-fuzz -Q command line option.
+The speed decrease is at about 50%
+It the easiest to use alternative and even works for cross-platform binaries.
+
+As it is included in afl++ this needs no URL.
+
+
+DYNINST
+-------
+Dyninst is a binary instrumentation framework similar to Pintool and Dynamorio
+(see far below). Howver whereas Pintool and Dynamorio work at runtime, dyninst
+instruments the target at load time, and then let it run.
+This is great for some things, e.g. fuzzing, and not so effective for others,
+e.g. malware analysis.
+
+So what we can do with dyninst is taking every basic block, and put afl's
+instrumention code in there - and then save the binary.
+Afterwards we can just fuzz the newly saved target binary with afl-fuzz.
+Sounds great? It is. The issue though - this is a non-trivial problem to
+insert instructions, which changes addresses in the process space and that
+everything still works afterwards. Hence more often than not binaries
+crash when they are run.
+
+The speed decrease is about 15-35%, depending on the optimization options
+used with afl-dyninst.
+
+So if dyninst works, its the best option available. Otherwise it just doesn't
+work well.
+
+https://github.com/vanhauser-thc/afl-dyninst
+
+
+INTEL-PT
+--------
+The big issue with Intel's PT is the small buffer size and the complex
+encoding of the debug information collected through PT.
+This makes the decoding very CPU intensive and hence slow.
+As a result, the overall speed decrease is about 70-90% (depending on
+the implementation and other factors)
+
+there are two afl intel-pt implementations:
+
+1. https://github.com/junxzm1990/afl-pt
+ => this needs Ubuntu 14.04.05 without any updates and the 4.4 kernel.
+
+2. https://github.com/hunter-ht-2018/ptfuzzer
+ => this needs a 4.14 or 4.15 kernel. the "nopti" kernel boot option must
+    be used. This one is faster than the other.
+
+
+CORESIGHT
+---------
+
+Coresight is the ARM answer to Intel's PT.
+There is no implementation so far which handle coresight and getting
+it working on an ARM Linux is very difficult due custom kernel building
+on embedded systems is difficult. And finding one that has coresight in
+the ARM chip is difficult too.
+My guess is that it is slower than Qemu, but faster than Intel PT.
+If anyone finds any coresight implemention for afl please ping me:
+vh@thc.org
+
+
+PIN & DYNAMORIO
+---------------
+
+Pintool and Dynamorio are dynamic instrumentation engines, and they can be
+used for getting basic block information at runtime.
+Pintool is only available for Intel x32/x64 on Linux, Mac OS and Windows
+whereas Dynamorio is additionally available for ARM and AARCH64.
+Dynamorio is also 10x faster than Pintool.
+
+The big issue with Dynamorio (and therefore Pintool too) is speed.
+Dynamorio has a speed decrease of 98-99%
+Pintool has a speed decrease of 99.5%
+
+Hence Dynamorio is the option to go for if everything fails, and Pintool
+only if Dynamorio fails too.
+
+Dynamorio solutions:
+  https://github.com/vanhauser-thc/afl-dynamorio
+  https://github.com/mxmssh/drAFL
+  https://github.com/googleprojectzero/winafl/ <= very good but windows only
+
+Pintool solutions:
+  https://github.com/vanhauser-thc/afl-pin
+  https://github.com/mothran/aflpin
+  https://github.com/spinpx/afl_pin_mode  <= only old Pintool version supported
+
+
+That's it!
+News, corrections, updates?
+Email vh@thc.org
diff --git a/docs/env_variables.txt b/docs/env_variables.txt
index f5db3b4f..8e2723d7 100644
--- a/docs/env_variables.txt
+++ b/docs/env_variables.txt
@@ -82,6 +82,9 @@ discussed in section #1, with the exception of:
   - TMPDIR and AFL_KEEP_ASSEMBLY, since no temporary assembly files are
     created.
 
+  - AFL_INST_RATIO, as we switched for instrim instrumentation which
+    is more effective but makes not much sense together with this option.
+
 Then there are a few specific features that are only available in llvm_mode:
 
   LAF-INTEL
@@ -89,11 +92,11 @@ Then there are a few specific features that are only available in llvm_mode:
     This great feature will split compares to series of single byte comparisons
     to allow afl-fuzz to find otherwise rather impossible paths.
 
-    - Setting LAF_SPLIT_SWITCHES will split switch()es
+    - Setting AFL_LLVM_LAF_SPLIT_SWITCHES will split switch()es
 
-    - Setting LAF_TRANSFORM_COMPARES will split string compare functions
+    - Setting AFL_LLVM_LAF_TRANSFORM_COMPARES will split string compare functions
 
-    - Setting LAF_SPLIT_COMPARES will split > 8 bit CMP instructions
+    - Setting AFL_LLVM_LAF_SPLIT_COMPARES will split > 8 bit CMP instructions
 
     See llvm_mode/README.laf-intel for more information. 
 
@@ -106,9 +109,17 @@ Then there are a few specific features that are only available in llvm_mode:
 
     See llvm_mode/README.whitelist for more information.
 
-Note that AFL_INST_RATIO will behave a bit differently than for afl-gcc,
-because functions are *not* instrumented unconditionally - so low values
-will have a more striking effect. For this tool, 0 is not a valid choice.
+  OTHER
+  =====
+    - Setting LOOPHEAD=1 optimized loops. afl-fuzz will only be able to
+      see the path the loop took, but not how many times it was called
+      (unless its a complex loop).
+
+    - Setting AFL_LLVM_NOT_ZERO=1 during compilation will use counters
+      that skip zero on overflow. This is the default for llvm >= 9,
+      however for llvm versions below that this will increase an unnecessary
+      slowdown due a performance issue that is only fixed in llvm 9+.
+      This feature increases path discovery by a little bit.
 
 3) Settings for afl-fuzz
 ------------------------
generated by cgit-pink 1.4.1 (git 2.36.1) at 2025-05-16 20:45:35 +0000