several documentation fixes
MODIFY
docs/ChangeLog
docs/ChangeLog
@@ -30,7 +30,7 @@ Version ++2.52d (tbd):
path discovery. See llvm_mode/README.instrim (https://github.com/csienslab/instrim)
- added MOpt (github.com/puppet-meteor/MOpt-AFL) mode, see docs/README.MOpt
- added code to make it more portable to other platforms than Intel Linux
- - added never zero counters for afl-gcc and optional (because of an
+ - added never zero counters for afl-gcc and optionally (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
@@ -46,7 +46,7 @@ Version ++2.52d (tbd):
- 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
+ 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

MODIFY
docs/README.MOpt
docs/README.MOpt
@@ -17,7 +17,8 @@ We open source all the seed sets used in the paper
### 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.
+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
@@ -26,18 +27,25 @@ MOpt_TechReport.pdf is the technical report of the paper
### 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
+
+Option '-L' controls the time to move on to the pacemaker fuzzing mode.
+'-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 minutes, MOpt-AFL will
enter the pacemaker fuzzing mode.
-<br>Setting 0 will enter the pacemaker fuzzing mode at first, which is
+
+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!
+'swarm_num': the number of the PSO swarms used in the fuzzing process.
+'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.
+'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.
+'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.
+
+Have fun with MOpt in AFL!

MODIFY
docs/binaryonly_fuzzing.txt
docs/binaryonly_fuzzing.txt
@@ -11,7 +11,7 @@ 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
+TL;DR: try DYNINST with afl-dyninst. If it produces too many crashes then
use afl -Q qemu_mode.
!!!!!
@@ -22,7 +22,7 @@ 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.
+It is the easiest to use alternative and even works for cross-platform binaries.
As it is included in afl++ this needs no URL.
@@ -30,7 +30,7 @@ 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
+(see far below). However 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.
@@ -38,15 +38,15 @@ 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.
+Sounds great? It is. The issue though - it is a non-trivial problem to
+insert instructions, which change addresses in the process space, so
+everything is still working afterwards. Hence more often than not binaries
+crash when they are run (because of instrumentation).
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
+So if dyninst works, it is the best option available. Otherwise it just doesn't
work well.
https://github.com/vanhauser-thc/afl-dyninst
@@ -54,13 +54,14 @@ https://github.com/vanhauser-thc/afl-dyninst
INTEL-PT
--------
+If you have a newer Intel CPU, you can make use of Intels processor trace.
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)
+the implementation and other factors).
-there are two afl intel-pt implementations:
+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.
@@ -73,13 +74,13 @@ there are two afl intel-pt implementations:
CORESIGHT
---------
-Coresight is the ARM answer to Intel's PT.
+Coresight is ARM's 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
+it working on an ARM Linux is very difficult due to 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:
+If anyone finds any coresight implementation for afl please ping me:
vh@thc.org

MODIFY
docs/env_variables.txt
docs/env_variables.txt
@@ -90,7 +90,8 @@ Then there are a few specific features that are only available in llvm_mode:
LAF-INTEL
=========
This great feature will split compares to series of single byte comparisons
- to allow afl-fuzz to find otherwise rather impossible paths.
+ to allow afl-fuzz to find otherwise rather impossible paths. It is not
+ restricted to Intel CPUs ;-)
- Setting AFL_LLVM_LAF_SPLIT_SWITCHES will split switch()es
@@ -105,20 +106,20 @@ Then there are a few specific features that are only available in llvm_mode:
This feature allows selectively instrumentation of the source
- Setting AFL_LLVM_WHITELIST with a filename will only instrument those
- files that match these names.
+ files that match the names listed in this file.
See llvm_mode/README.whitelist for more information.
INSTRIM
=======
This feature increases the speed by whopping 20% but at the cost of a
- lower path discovery and thefore coverage.
+ lower path discovery and therefore coverage.
- Setting AFL_LLVM_INSTRIM activates this mode
- Setting AFL_LLVM_INSTRIM_LOOPHEAD=1 expands on INSTRIM to optimize 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).
+ many times it was called (unless it is a complex loop).
See llvm_mode/README.instrim

MODIFY
gcc_plugin/README.gcc
gcc_plugin/README.gcc
@@ -65,8 +65,8 @@ directory.
This is an early-stage mechanism, so field reports are welcome. You can send bug
reports to <aseipp@pobox.com>.
-4) Bonus feature #1: deferred instrumentation
----------------------------------------------
+4) Bonus feature #1: deferred initialization
+--------------------------------------------
AFL tries to optimize performance by executing the targeted binary just once,
stopping it just before main(), and then cloning this "master" process to get

MODIFY
llvm_mode/README.llvm
llvm_mode/README.llvm
@@ -109,8 +109,8 @@ See README.neverzero
This is an early-stage mechanism, so field reports are welcome. You can send bug
reports to <afl-users@googlegroups.com>.
-5) Bonus feature #1: deferred instrumentation
----------------------------------------------
+5) Bonus feature #1: deferred initialization
+--------------------------------------------
AFL tries to optimize performance by executing the targeted binary just once,
stopping it just before main(), and then cloning this "master" process to get

several documentation fixes