Merge branch 'dev' into docs_edit_readme_fix_links

11 files changed, 142 insertions, 122 deletions

diff --git a/docs/Changelog.md b/docs/Changelog.md
index de217c2e..dad5fee2 100644
--- a/docs/Changelog.md
+++ b/docs/Changelog.md
@@ -15,6 +15,7 @@ sending a mail to <afl-users+subscribe@googlegroups.com>.
       information on how to deal with instrumenting libraries
     - fix a regression introduced in 3.10 that resulted in less
       coverage being detected. thanks to Collin May for reporting!
+    - fix -n dumb mode (nobody should use this)
   - afl-showmap, afl-tmin and afl-analyze now honor persistent mode
     for more speed. thanks to dloffre-snl for reporting!
   - afl-cc:
diff --git a/docs/best_practices.md b/docs/best_practices.md
index 1521748a..0708d49d 100644
--- a/docs/best_practices.md
+++ b/docs/best_practices.md
@@ -62,7 +62,7 @@ which allows you to define network state with different type of data packets.
 4. If you do not use shmem persistent mode, use `AFL_TMPDIR` to put the input file directory on a tempfs location, see [env_variables.md](env_variables.md).
 5. Improve Linux kernel performance: modify `/etc/default/grub`, set `GRUB_CMDLINE_LINUX_DEFAULT="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"`; then `update-grub` and `reboot` (warning: makes the system less secure).
 6. Running on an `ext2` filesystem with `noatime` mount option will be a bit faster than on any other journaling filesystem.
-7. Use your cores! [README.md:3.b) Using multiple cores/threads](../README.md#b-using-multiple-coresthreads).
+7. Use your cores! [fuzzing_expert.md:b) Using multiple cores](fuzzing_expert.md#b-using-multiple-cores).
 
 ### Improving stability
 
@@ -117,4 +117,4 @@ Four steps are required to do this and it also requires quite some knowledge of
 
      Recompile, fuzz it, be happy :)
 
-     This link explains this process for [Fuzzbench](https://github.com/google/fuzzbench/issues/677).
\ No newline at end of file
+     This link explains this process for [Fuzzbench](https://github.com/google/fuzzbench/issues/677).
diff --git a/docs/branches.md b/docs/branches.md
index 81c73a0f..ae147b08 100644
--- a/docs/branches.md
+++ b/docs/branches.md
@@ -7,4 +7,5 @@ The following branches exist:
 * [dev](https://github.com/AFLplusplus/AFLplusplus/tree/dev): development state of AFL++ - bleeding edge and you might catch a checkout which does not compile or has a bug. *We only accept PRs in dev!!*
 * (any other): experimental branches to work on specific features or testing new functionality or changes.
 
-For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab. Also take a look at the list of [important changes in AFL++](important_changes.md).
\ No newline at end of file
+For releases, please see the [Releases](https://github.com/AFLplusplus/AFLplusplus/releases) tab.
+Also take a look at the list of [important changes in AFL++](important_changes.md).
\ No newline at end of file
diff --git a/docs/ci_fuzzing.md b/docs/ci_fuzzing.md
index 316059f8..8d1a2f99 100644
--- a/docs/ci_fuzzing.md
+++ b/docs/ci_fuzzing.md
@@ -26,4 +26,4 @@ Some notes on CI Fuzzing - this fuzzing is different to normal fuzzing campaigns
 `-M` enables old queue handling etc. which is good for a fuzzing campaign but not good for short CI runs.
 
 How this can look like can e.g. be seen at AFL++'s setup in Google's [oss-fuzz](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/compile_afl)
-and [clusterfuzz](https://github.com/google/clusterfuzz/blob/master/src/python/bot/fuzzers/afl/launcher.py).
\ No newline at end of file
+and [clusterfuzz](https://github.com/google/clusterfuzz/blob/master/src/clusterfuzz/_internal/bot/fuzzers/afl/launcher.py).
diff --git a/docs/env_variables.md b/docs/env_variables.md
index 0686f1a8..5f5c2510 100644
--- a/docs/env_variables.md
+++ b/docs/env_variables.md
@@ -2,7 +2,7 @@
 
   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.md](README.md) for the general
+  users or for some types of custom fuzzing setups. See [../README.md](../README.md) for the general
   instruction manual.
 
   Note that most tools will warn on any unknown AFL environment variables.
@@ -422,7 +422,7 @@ checks or alter some of the more exotic semantics of the tool:
   - Setting `AFL_FORCE_UI` will force painting the UI on the screen even if
     no valid terminal was detected (for virtual consoles)
 
-  - If you are using persistent mode (you should, see [instrumentation/README.persistent_mode.md](instrumentation/README.persistent_mode.md))
+  - If you are using persistent mode (you should, see [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md))
     some targets keep inherent state due which a detected crash testcase does
     not crash the target again when the testcase is given. To be able to still
     re-trigger these crashes you can use the `AFL_PERSISTENT_RECORD` variable
diff --git a/docs/fuzzing_binary-only_targets.md b/docs/fuzzing_binary-only_targets.md
index d568b976..ea262f6e 100644
--- a/docs/fuzzing_binary-only_targets.md
+++ b/docs/fuzzing_binary-only_targets.md
@@ -51,7 +51,7 @@ make
 ```
 
 For additional instructions and caveats, see [frida_mode/README.md](../frida_mode/README.md).
-If possible you should use the persistent mode, see [qemu_frida/README.persistent.md](../qemu_frida/README.persistent.md).
+If possible you should use the persistent mode, see [qemu_frida/README.md](../qemu_frida/README.md).
 The mode is approximately 2-5x slower than compile-time instrumentation, and is
 less conducive to parallelization.
 
@@ -71,7 +71,8 @@ cd unicorn_mode
 
 If the goal is to fuzz a dynamic library then there are two options available.
 For both you need to write a small harness that loads and calls the library.
-Faster is the frida solution: [frida_mode/README.md](../frida_mode/README.md)
+Then you fuzz this with either frida_mode or qemu_mode, and either use
+`AFL_INST_LIBS=1` or `AFL_QEMU/FRIDA_INST_RANGES`.
 
 Another, less precise and slower option is using ptrace with debugger interrupt
 instrumentation: [utils/afl_untracer/README.md](../utils/afl_untracer/README.md).
diff --git a/docs/fuzzing_expert.md b/docs/fuzzing_expert.md
index 37ab8e2f..96193f88 100644
--- a/docs/fuzzing_expert.md
+++ b/docs/fuzzing_expert.md
@@ -472,7 +472,7 @@ If you are using AFL spinoffs or AFL conforming fuzzers, then just use the
 same -o directory and give it a unique `-S` name.
 Examples are:
  * [Fuzzolic](https://github.com/season-lab/fuzzolic)
- * [symcc](https://github.com/eurecom-s/symcc/)
+ * [symcc](https://github.com/eurecom-s3/symcc/)
  * [Eclipser](https://github.com/SoftSec-KAIST/Eclipser/)
  * [AFLsmart](https://github.com/aflsmart/aflsmart)
  * [FairFuzz](https://github.com/carolemieux/afl-rb)
@@ -540,6 +540,11 @@ To have only the summary use the `-s` switch e.g.: `afl-whatsup -s out/`
 If you have multiple servers then use the command after a sync, or you have
 to execute this script per server.
 
+Another tool to inspect the current state and history of a specific instance
+is afl-plot, which generates an index.html file and a graphs that show how
+the fuzzing instance is performing.
+The syntax is `afl-plot instance_dir web_dir`, e.g. `afl-plot out/default /srv/www/htdocs/plot`
+
 #### e) Stopping fuzzing, restarting fuzzing, adding new seeds
 
 To stop an afl-fuzz run, simply press Control-C.
@@ -608,7 +613,7 @@ switch or honggfuzz.
  * If you do not use shmem persistent mode, use `AFL_TMPDIR` to point the input file on a tempfs location, see [env_variables.md](env_variables.md)
  * Linux: Improve kernel performance: modify `/etc/default/grub`, set `GRUB_CMDLINE_LINUX_DEFAULT="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"`; then `update-grub` and `reboot` (warning: makes the system more insecure) - you can also just run `sudo afl-persistent-config`
  * Linux: Running on an `ext2` filesystem with `noatime` mount option will be a bit faster than on any other journaling filesystem
- * Use your cores! [3.b) Using multiple cores/threads](#b-using-multiple-coresthreads)
+ * Use your cores! [b) Using multiple cores](#b-using-multiple-cores)
  * Run `sudo afl-system-config` before starting the first afl-fuzz instance after a reboot
 
 ### The End
diff --git a/docs/interpreting_output.md b/docs/interpreting_output.md
index 364d2cf4..327a0ac0 100644
--- a/docs/interpreting_output.md
+++ b/docs/interpreting_output.md
@@ -68,4 +68,4 @@ cd utils/plot_ui
 make
 cd ../../
 sudo make install
-```
\ No newline at end of file
+```
diff --git a/docs/known_limitations.md b/docs/known_limitations.md
index b5fc8446..2d8f84a5 100644
--- a/docs/known_limitations.md
+++ b/docs/known_limitations.md
@@ -33,4 +33,4 @@ Here are some of the most important caveats for AFL:
   - 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.md](INSTALL.md) for platform-specific tips.
\ No newline at end of file
+Beyond this, see [INSTALL.md](INSTALL.md) for platform-specific tips.
diff --git a/docs/parallel_fuzzing.md b/docs/parallel_fuzzing.md
index 90e12e89..e37276a5 100644
--- a/docs/parallel_fuzzing.md
+++ b/docs/parallel_fuzzing.md
@@ -4,7 +4,7 @@ This document talks about synchronizing afl-fuzz jobs on a single machine
 or across a fleet of systems. See README.md for the general instruction manual.
 
 Note that this document is rather outdated. please refer to the main document
-section on multiple core usage [../README.md#Using multiple cores](../README.md#b-using-multiple-coresthreads)
+section on multiple core usage [fuzzing_expert.md#Using multiple cores](fuzzing_expert.md#b-using-multiple-cores)
 for up to date strategies!
 
 ## 1) Introduction
diff --git a/docs/rpc_statsd.md b/docs/rpc_statsd.md
index efbd550b..9b3d8d40 100644
--- a/docs/rpc_statsd.md
+++ b/docs/rpc_statsd.md
@@ -1,143 +1,155 @@
-# Remote monitoring with StatsD
+# Remote monitoring and metrics visualization
 
-StatsD allows you to receive and aggregate metrics from a wide range of applications and retransmit them to the backend of your choice.
-This enables you to create nice and readable dashboards containing all the information you need on your fuzzer instances.
-No need to write your own statistics parsing system, deploy and maintain it to all your instances, sync with your graph rendering system...
+AFL++ can send out metrics as StatsD messages. For remote monitoring and visualization of the metrics, you can set up a tool chain. For example, with Prometheus and Grafana. All tools are free and open source.
 
-The available metrics are :
+This enables you to create nice and readable dashboards containing all the information you need on your fuzzer instances. There is no need to write your own statistics parsing system, deploy and maintain it to all your instances, and sync with your graph rendering system.
+
+Compared to the default integrated UI of AFL++, this can help you to visualize trends and the fuzzing state over time. You might be able to see when the fuzzing process has reached a state of no progress and visualize what are the "best strategies" for your targets (according to your own criteria). You can do so without logging into each instance individually.
+
+![example visualization with Grafana](resources/statsd-grafana.png)
+
+This is an example visualization with Grafana. The dashboard can be imported with [this JSON template](resources/grafana-afl++.json).
+
+## AFL++ metrics and StatsD
+
+StatsD allows you to receive and aggregate metrics from a wide range of applications and retransmit them to a backend of your choice.
+
+From AFL++, StatsD can receive the following metrics:
+- cur_path
 - cycle_done
 - cycles_wo_finds
+- edges_found
 - execs_done
 - execs_per_sec
-- paths_total
+- havoc_expansion
+- max_depth
 - paths_favored
 - paths_found
 - paths_imported
-- max_depth
-- cur_path
+- paths_total
 - pending_favs
 - pending_total
-- variable_paths
+- slowest_exec_ms
+- total_crashes
 - unique_crashes
 - unique_hangs
-- total_crashes
-- slowest_exec_ms
-- edges_found
 - var_byte_count
-- havoc_expansion
+- variable_paths
 
-Compared to the default integrated UI, these metrics give you the opportunity to visualize trends and fuzzing state over time.
-By doing so, you might be able to see when the fuzzing process has reached a state of no progress, visualize what are the "best strategies"
-(according to your own criteria) for your targets, etc. And doing so without requiring to log into each instance manually.
+Depending on your StatsD server, you will be able to monitor, trigger alerts, or perform actions based on these metrics (for example: alert on slow exec/s for a new build, threshold of crashes, time since last crash > X, and so on).
 
-An example visualisation may look like the following:
-![StatsD Grafana](resources/statsd-grafana.png)
+## Setting environment variables in AFL++
 
-*Notes: The exact same dashboard can be imported with [this JSON template](resources/grafana-afl++.json).*
+1. To enable the StatsD metrics collection on your fuzzer instances, set the environment variable `AFL_STATSD=1`. By default, AFL++ will send the metrics over UDP to 127.0.0.1:8125.
 
-## How to use
+2. To enable tags for each metric based on their format (banner and afl_version), set the environment variable `AFL_STATSD_TAGS_FLAVOR`. By default, no tags will be added to the metrics.
 
-To enable the StatsD reporting on your fuzzer instances, you need to set the environment variable `AFL_STATSD=1`.
+    The available values are the following:
+    -  `dogstatsd`
+    -  `influxdb`
+    -  `librato`
+    -  `signalfx`
+    
+    For more information on environment variables, see [env_variables.md](env_variables.md).
 
-Setting `AFL_STATSD_TAGS_FLAVOR` to the provider of your choice will assign tags / labels to each metric based on their format.
-The possible values are  `dogstatsd`, `librato`, `signalfx` or `influxdb`.
-For more information on these env vars, check out [env_variables.md](env_variables.md).
+    Note: When using multiple fuzzer instances with StatsD it is *strongly* recommended to set up `AFL_STATSD_TAGS_FLAVOR` to match your StatsD server. This will allow you to see individual fuzzer performance, detect bad ones, and see the progress of each strategy.
 
-The simplest way of using this feature is to use any metric provider and change the host/port of your StatsD daemon,
-with `AFL_STATSD_HOST` and `AFL_STATSD_PORT`, if required (defaults are `localhost` and port `8125`).
-To get started, here are some instructions with free and open source tools.
-The following setup is based on Prometheus, statsd_exporter and Grafana.
-Grafana here is not mandatory, but gives you some nice graphs and features.
+3. Optional: To set the host and port of your StatsD daemon, set `AFL_STATSD_HOST` and `AFL_STATSD_PORT`. The default values are `localhost` and `8125`.
 
-Depending on your setup and infrastructure, you may want to run these applications not on your fuzzer instances.
-Only one instance of these 3 application is required for all your fuzzers.
+## Installing and setting up StatsD, Prometheus, and Grafana
 
-To simplify everything, we will use Docker and docker-compose.
-Make sure you have them both installed. On most common Linux distributions, it's as simple as:
+The easiest way to install and set up the infrastructure is with Docker and Docker Compose.
 
-```sh
-curl -fsSL https://get.docker.com -o get-docker.sh
-sh get-docker.sh
-```
+Depending on your fuzzing setup and infrastructure, you may not want to run these applications on your fuzzer instances. This setup may be modified before use in a production environment; for example, adding passwords, creating volumes for storage, tweaking the metrics gathering to get host metrics (CPU, RAM, and so on).
 
-Once that's done, we can create the infrastructure.
-Create and move into the directory of your choice. This will store all the configurations files required.
-
-First, create a `docker-compose.yml` containing the following:
-```yml
-version: '3'
-
-networks:
-  statsd-net:
-    driver: bridge
-
-services:
-  prometheus:
-    image: prom/prometheus
-    container_name: prometheus
-    volumes:
-      - ./prometheus.yml:/prometheus.yml
-    command:
-      - '--config.file=/prometheus.yml'
-    restart: unless-stopped
-    ports:
-      - "9090:9090"
-    networks:
-      - statsd-net
-
-  statsd_exporter:
-    image: prom/statsd-exporter
-    container_name: statsd_exporter
-    volumes:
-      - ./statsd_mapping.yml:/statsd_mapping.yml
-    command:
-      - "--statsd.mapping-config=/statsd_mapping.yml"
-    ports:
-      - "9102:9102/tcp"
-      - "8125:9125/udp"
-    networks:
-      - statsd-net
-  
-  grafana:
-    image: grafana/grafana
-    container_name: grafana
-    restart: unless-stopped
-    ports:
-        - "3000:3000"
-    networks:
-      - statsd-net
-```
+For all your fuzzing instances, only one instance of Prometheus and Grafana is required. The [statsd exporter](https://registry.hub.docker.com/r/prom/statsd-exporter) converts the StatsD metrics to Prometheus. If you are using a provider that supports StatsD directly, you can skip this part of the setup."
 
-Then `prometheus.yml`
-```yml
-global:
-  scrape_interval:      15s
-  evaluation_interval:  15s
+You can create and move the infrastructure files into a directory of your choice. The directory will store all the required configuration files.
 
-scrape_configs:
-  - job_name: 'fuzzing_metrics'
-    static_configs:
-      - targets: ['statsd_exporter:9102']
-```
+To install and set up Prometheus and Grafana:
 
-And finally `statsd_mapping.yml`
-```yml 
-mappings:
-- match: "fuzzing.*"
-  name: "fuzzing"
-  labels:
-      type: "$1"
-```
+1. Install Docker and Docker Compose:
+
+    ```sh
+    curl -fsSL https://get.docker.com -o get-docker.sh
+    sh get-docker.sh
+    ```
 
-Run `docker-compose up -d`.
+2. Create a `docker-compose.yml` containing the following:
+    ```yml
+    version: '3'
 
-Everything should now be setup, you are now able to run your fuzzers with
+    networks:
+      statsd-net:
+        driver: bridge
+
+    services:
+      prometheus:
+        image: prom/prometheus
+        container_name: prometheus
+        volumes:
+          - ./prometheus.yml:/prometheus.yml
+        command:
+          - '--config.file=/prometheus.yml'
+        restart: unless-stopped
+        ports:
+          - "9090:9090"
+        networks:
+          - statsd-net
+
+      statsd_exporter:
+        image: prom/statsd-exporter
+        container_name: statsd_exporter
+        volumes:
+          - ./statsd_mapping.yml:/statsd_mapping.yml
+        command:
+          - "--statsd.mapping-config=/statsd_mapping.yml"
+        ports:
+          - "9102:9102/tcp"
+          - "8125:9125/udp"
+        networks:
+          - statsd-net
+      
+      grafana:
+        image: grafana/grafana
+        container_name: grafana
+        restart: unless-stopped
+        ports:
+            - "3000:3000"
+        networks:
+          - statsd-net
+    ```
+
+3. Create a `prometheus.yml` containing the following:
+
+    ```yml
+    global:
+      scrape_interval:      15s
+      evaluation_interval:  15s
+
+    scrape_configs:
+      - job_name: 'fuzzing_metrics'
+        static_configs:
+          - targets: ['statsd_exporter:9102']
+    ```
+
+4. Create a `statsd_mapping.yml` containing the following:
+    ```yml 
+    mappings:
+    - match: "fuzzing.*"
+      name: "fuzzing"
+      labels:
+          type: "$1"
+    ```
+
+5. Run `docker-compose up -d`.
+
+## Running AFL++ with StatsD
+
+To run your fuzzing instances:
 
 ```
-AFL_STATSD_TAGS_FLAVOR=dogstatsd AFL_STATSD=1 afl-fuzz -M test-fuzzer-1 -i i -o o ./bin/my-application @@
-AFL_STATSD_TAGS_FLAVOR=dogstatsd AFL_STATSD=1 afl-fuzz -S test-fuzzer-2 -i i -o o ./bin/my-application @@
+AFL_STATSD_TAGS_FLAVOR=dogstatsd AFL_STATSD=1 afl-fuzz -M test-fuzzer-1 -i i -o o [./bin/my-application] @@
+AFL_STATSD_TAGS_FLAVOR=dogstatsd AFL_STATSD=1 afl-fuzz -S test-fuzzer-2 -i i -o o [./bin/my-application] @@
 ...
 ```
-
-This setup may be modified before use in a production environment. Depending on your needs: adding passwords, creating volumes for storage,
-tweaking the metrics gathering to get host metrics (CPU, RAM ...).