Roll src/third_party/afl/src/ 2.14b..2.30b (16 versions).

third_party/afl/src/docs/status_screen.txt

 ===============================
 Understanding the status screen
 ===============================
 
   This document provides an overview of the status screen - plus tips for
   troubleshooting any warnings and red text shown in the UI. See README for
   the general instruction manual.
 
 0) A note about colors
 ----------------------
@@ skipping 101 matching lines @@
 The "*" suffix sometimes shown in the first line means that the currently
 processed path is not "favored" (a property discussed later on, in section 6).
 
 If you feel that the fuzzer is progressing too slowly, see the note about the
 -d option in section 2 of this doc.
 
 4) Map coverage
 ---------------
 
   +--------------------------------------+
-  |    map density : 4763 (29.07%)       |
+  |    map density : 10.15% / 29.07%     |
   | count coverage : 4.03 bits/tuple     |
   +--------------------------------------+
 
 The section provides some trivia about the coverage observed by the
 instrumentation embedded in the target binary.
 
 The first line in the box tells you how many branch tuples we have already
-hit, in proportion to how much the bitmap can hold. Be wary of extremes:
+hit, in proportion to how much the bitmap can hold. The number on the left
+describes the current input; the one on the right is the value for the entire
+input corpus.
+
+Be wary of extremes:
 
   - Absolute numbers below 200 or so suggest one of three things: that the
     program is extremely simple; that it is not instrumented properly (e.g.,
     due to being linked against a non-instrumented copy of the target
     library); or that it is bailing out prematurely on your input test cases.
     The fuzzer will try to mark this in pink, just to make you aware.
 
   - Percentages over 70% may very rarely happen with very complex programs
     that make heavy use of template-generated code.
 
@@ skipping 123 matching lines @@
 
 8) Path geometry
 ----------------
 
   +---------------------+
   |    levels : 5       |
   |   pending : 1570    |
   |  pend fav : 583     |
   | own finds : 0       |
   |  imported : 0       |
-  |  variable : 0       |
+  | stability : 100.00% |
   +---------------------+
 
 The first field in this section tracks the path depth reached through the
 guided fuzzing process. In essence: the initial test cases supplied by the
 user are considered "level 1". The test cases that can be derived from that
 through traditional fuzzing are considered "level 2"; the ones derived by
 using these as inputs to subsequent fuzzing rounds are "level 3"; and so forth.
 The maximum depth is therefore a rough proxy for how much value you're getting
 out of the instrumentation-guided approach taken by afl-fuzz.
 
 The next field shows you the number of inputs that have not gone through any
 fuzzing yet. The same stat is also given for "favored" entries that the fuzzer
 really wants to get to in this queue cycle (the non-favored entries may have to
 wait a couple of cycles to get their chance).
 
 Next, we have the number of new paths found during this fuzzing section and
 imported from other fuzzer instances when doing parallelized fuzzing; and the
 number of inputs that produce seemingly variable behavior in the tested binary.
 
-That last bit is actually fairly interesting. There are four quasi-common
-explanations for variable behavior of the tested program:
+That last bit is actually fairly interesting: it measures the consistency of
+observed traces. If a program always behaves the same for the same input data,
+it will earn a score of 100%. When the value is lower but still shown in purple,
+the fuzzing process is unlikely to be negatively affected. If it goes into red,
+you may be in trouble, since AFL will have difficulty discerning between
+meaningful and "phantom" effects of tweaking the input file.
 
-  - Use of uninitialized memory in conjunction with some intrinsic sources of
-    entropy in the tested binary. This can be indicative of a security bug.
+Now, most targets will just get a 100% score, but when you see lower figures,
+there are several things to look at:
 
-  - Attempts to create files that were already created during previous runs, or
-    otherwise interact with some form of persistent state. This is harmless,
-    but you may want to instruct the targeted program to write to stdout or to
-    /dev/null to avoid surprises (and disable the creation of temporary files
-    and similar artifacts, if applicable).
+  - The use of uninitialized memory in conjunction with some intrinsic sources
+    of entropy in the tested binary. Harmless to AFL, but could be indicative
+    of a security bug.
 
-  - Hitting functionality that is actually designed to behave randomly. For
-    example, when fuzzing sqlite, the fuzzer will dutifully detect variable
-    behavior once the mutation engine generates something like:
+  - Attempts to manipulate persistent resources, such as left over temporary
+    files or shared memory objects. This is usually harmless, but you may want
+    to double-check to make sure the program isn't bailing out prematurely.
+    Running out of disk space, SHM handles, or other global resources can
+    trigger this, too.
 
-    select random();
+  - Hitting some functionality that is actually designed to behave randomly.
+    Generally harmless. For example, when fuzzing sqlite, an input like
+    'select random();' will trigger a variable execution path.
 
-  - Multiple threads executing at once in semi-random order. This is usually
-    just a nuisance, but if the number of variable paths is very high, try the
-    following options:
+  - Multiple threads executing at once in semi-random order. This is harmless
+    when the 'stability' metric stays over 90% or so, but can become an issue
+    if not. Here's what to try:
 
     - Use afl-clang-fast from llvm_mode/ - it uses a thread-local tracking
       model that is less prone to concurrency issues,
 
     - See if the target can be compiled or run without threads. Common
       ./configure options include --without-threads, --disable-pthreads, or
       --disable-openmp.
 
     - Replace pthreads with GNU Pth (https://www.gnu.org/software/pth/), which
       allows you to use a deterministic scheduler.
 
-Less likely causes may include running out of disk space, SHM handles, or other
-globally limited resources.
+  - In persistent mode, minor drops in the "stability" metric can be normal,
+    because not all the code behaves identically when re-entered; but major
+    dips may signify that the code within __AFL_LOOP() is not behaving
+    correctly on subsequent iterations (e.g., due to incomplete clean-up or
+    reinitialization of the state) and that most of the fuzzing effort goes
+    to waste.
 
 The paths where variable behavior is detected are marked with a matching entry
 in the <out_dir>/queue/.state/variable_behavior/ directory, so you can look
 them up easily.
 
-If you can't suppress variable behavior and don't want to see these warnings,
-simply set AFL_NO_VAR_CHECK=1 in the environment before running afl-fuzz. This
-will also dramatically speed up session resumption.
-
 9) CPU load
 -----------
 
   [cpu: 25%]
 
 This tiny widget shows the apparent CPU utilization on the local system. It is
 calculated by taking the number of processes in the "runnable" state, and then
 comparing it to the number of logical cores on the system.
 
 If the value is shown in green, you are using fewer CPU cores than available on
@@ skipping 24 matching lines @@
   - cycles_done    - queue cycles completed so far
   - execs_done     - number of execve() calls attempted
   - execs_per_sec  - current number of execs per second
   - paths_total    - total number of entries in the queue
   - paths_found    - number of entries discovered through local fuzzing
   - paths_imported - number of entries imported from other instances
   - max_depth      - number of levels in the generated data set
   - cur_path       - currently processed entry number
   - pending_favs   - number of favored entries still waiting to be fuzzed
   - pending_total  - number of all entries waiting to be fuzzed
+  - stability      - percentage of bitmap bytes that behave consistently
   - variable_paths - number of test cases showing variable behavior
   - unique_crashes - number of unique crashes recorded
   - unique_hangs   - number of unique hangs encountered
 
 Most of these map directly to the UI elements discussed earlier on.
 
 On top of that, you can also find an entry called 'plot_data', containing a
 plottable history for most of these fields. If you have gnuplot installed, you
 can turn this into a nice progress report with the included 'afl-plot' tool.