Merge branch 'dev' into text_inputs

4 files changed, 129 insertions, 3 deletions

diff --git a/docs/Changelog.md b/docs/Changelog.md
index 50f5629f..cadfcb04 100644
--- a/docs/Changelog.md
+++ b/docs/Changelog.md
@@ -11,16 +11,21 @@ sending a mail to <afl-users+subscribe@googlegroups.com>.
 
 ### Version ++2.66d (devel)
   - afl-fuzz:
+     - added -F option to allow -M main fuzzers to sync to foreign fuzzers,
+       e.g. honggfuzz or libfuzzer
      - eliminated CPU affinity race condition for -S/-M runs
   - llvm_mode:
+     - now supports llvm 12!
      - fixes for laf-intel float splitting (thanks to mark-griffin for
        reporting)
      - LTO: autodictionary mode is a default
      - LTO: instrim instrumentation disabled, only classic support used
             as it is always better
+  - added honggfuzz mangle as a custom mutator in custom_mutators/honggfuzz :)
   - added afl-frida gum solution to examples/afl_frida (mostly imported
     from https://github.com/meme/hotwax/)
   - small fixes to afl-plot, afl-whatsup and man page creation
+  - new README, added FAQ
 
 
 ### Version ++2.66c (release)
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 00000000..d848e08a
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,113 @@
+# Frequently asked questions about afl++
+
+## Contents
+
+  1. [What is an edge?](#what-is-an-edge)
+  2. [Why is my stability below 100%?](#why-is-my-stability-below-100)
+  3. [How can I improve the stability value](#how-can-i-improve-the-stability-value)
+
+If you find an interesting or important question missing, submit it via
+[https://github.com/AFLplusplus/AFLplusplus/issues](https://github.com/AFLplusplus/AFLplusplus/issues)
+
+## What is an "edge"
+
+A program contains `functions`, `functions` contain the compiled machine code.
+The compiled machine code in a `function` can be in a single or many `basic blocks`.
+A `basic block` is the largest possible number of subsequent machine code
+instructions that runs independent, meaning it does not split up to different
+locations nor is it jumped into it from a different location:
+```
+function() {
+  A:
+    some
+    code
+  B:
+    if (x) goto C; else goto D;
+  C:
+    some code
+    goto D
+  D:
+    some code
+    goto B
+  E:
+    return
+}
+```
+Every code block between two jump locations is a `basic block`.
+
+An `edge` is then the unique relationship between two `basic blocks` (from the
+code example above):
+```
+              Block A
+                |
+                v
+              Block B  <------+
+             /        \       |
+            v          v      |
+         Block C    Block D --+
+             \
+              v
+              Block E
+```
+Every line between two blocks is an `edge`.
+
+## Why is my stability below 100
+
+Stability is measured by how many percent of the edges in the target are
+"stable". Sending the same input again and again should take the exact same
+path through the target every time. If that is the case, the stability is 100%.
+
+If however randomness happens, e.g. a thread reading from shared memory,
+reaction to timing, etc. then in some of the re-executions with the same data
+will result in the edge information being different accross runs.
+Those edges that change are then flagged "unstable".
+
+The more "unstable" edges, the more difficult for afl++ to identify valid new
+paths.
+
+A value above 90% is usually fine and a value above 80% is also still ok, and
+even above 20% can still result in successful finds of bugs.
+However, it is recommended that below 90% or 80% you should take measures to
+improve the stability.
+
+## How can I improve the stability value
+
+Four steps are required to do this and requires quite some knowledge of
+coding and/or disassembly and it is only effectively possible with
+afl-clang-fast PCGUARD and afl-clang-lto LTO instrumentation!
+
+  1. First step: Identify which edge ID numbers are unstable
+
+     run the target with `export AFL_DEBUG=1` for a few minutes then terminate.
+     The out/fuzzer_stats file will then show the edge IDs that were identified
+     as unstable.
+
+  2. Second step: Find the responsible function.
+
+     a) For LTO instrumented binaries just disassemble or decompile the target
+        and look which edge is writing to that edge ID. Ghidra is a good tool
+        for this: [https://ghidra-sre.org/](https://ghidra-sre.org/)
+
+     b) For PCGUARD instrumented binaries it is more difficult. Here you can
+        either modify the __sanitizer_cov_trace_pc_guard function in
+        llvm_mode/afl-llvm-rt.o.c to write a backtrace to a file if the ID in
+        __afl_area_ptr[*guard] is one of the unstable edge IDs. Then recompile
+        and reinstall llvm_mode and rebuild your target. Run the recompiled
+	target with afl-fuzz for a while and then check the file that you
+        wrote with the backtrace information.
+        Alternatively you can use `gdb` to hook __sanitizer_cov_trace_pc_guard_init
+        on start, check to which memory address the edge ID value is written
+        and set a write breakpoint to that address (`watch 0x.....`).
+
+  3. Third step: create a text file with the filenames
+
+     Identify which source code files contain the functions that you need to
+     remove from instrumentation.
+
+     Simply follow this document on how to do this: [llvm_mode/README.instrument_file.md](llvm_mode/README.instrument_file.md)
+     If PCGUARD is used, then you need to follow this guide: [http://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation](http://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation)
+
+  4. Fourth step: recompile the target
+
+     Recompile, fuzz it, be happy :)
+
diff --git a/docs/parallel_fuzzing.md b/docs/parallel_fuzzing.md
index 271f8369..2ab1466c 100644
--- a/docs/parallel_fuzzing.md
+++ b/docs/parallel_fuzzing.md
@@ -99,7 +99,15 @@ example may be:
 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) Syncing with non-afl fuzzers or independant instances
+
+A -M main node can be told with the `-F other_fuzzer_queue_directory` option
+to sync results from other fuzzers, e.g. libfuzzer or honggfuzz.
+
+Only the specified directory will by synced into afl, not subdirectories.
+The specified directories do not need to exist yet at the start of afl.
+
+## 4) 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
@@ -176,7 +184,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
+## 5) 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
@@ -200,7 +208,7 @@ Keep in mind that crashing inputs are *not* automatically propagated to the
 main 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
+## 6) Asymmetric setups
 
 It is perhaps worth noting that all of the following is permitted:
 
diff --git a/docs/screenshot.png b/docs/screenshot.png
new file mode 100644
index 00000000..7b4dd7e4
--- /dev/null
+++ b/docs/screenshot.png