Add American Fuzzy Lop (afl) to third_party/afl/

third_party/afl/src/docs/env_variables.txt

Index: third_party/afl/src/docs/env_variables.txt
diff --git a/third_party/afl/src/docs/env_variables.txt b/third_party/afl/src/docs/env_variables.txt
new file mode 100644
index 0000000000000000000000000000000000000000..16de03442364100602409484d80c16f0bd9d125b
--- /dev/null
+++ b/third_party/afl/src/docs/env_variables.txt
@@ -0,0 +1,219 @@
+=======================
+Environmental variables
+=======================
+
+  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 for the general
+  instruction manual.
+
+1) Settings for afl-gcc, afl-clang, and afl-as
+----------------------------------------------
+
+Because they can't directly accept command-line options, the compile-time
+tools make fairly broad use of environmental variables:
+
+  - Setting AFL_HARDEN automatically adds code hardening options when invoking
+    the downstream compiler. This currently includes -D_FORTIFY_SOURCE=2 and
+    -fstack-protector-all. The setting is useful for catching non-crashing
+    memory bugs at the expense of a very slight (sub-5%) performance loss.
+
+  - By default, the wrapper appends -O3 to optimize builds. Very rarely, this
+    will cause problems in programs built with -Werror, simply because -O3
+    enables more thorough code analysis and can spew out additional warnings.
+    To disable optimizations, set AFL_DONT_OPTIMIZE.
+
+  - Setting AFL_USE_ASAN automatically enables ASAN, provided that your
+    compiler supports that. Note that fuzzing with ASAN is mildly challenging
+    - see notes_for_asan.txt.
+
+    (You can also enable MSAN via AFL_USE_MSAN; ASAN and MSAN come with the
+    same gotchas; the modes are mutually exclusive. UBSAN and other exotic
+    sanitizers are not officially supported yet, but are easy to get to work
+    by hand.)
+
+  - Setting AFL_CC, AFL_CXX, and AFL_AS lets you use alternate downstream
+    compilation tools, rather than the default 'clang', 'gcc', or 'as' binaries
+    in your $PATH.
+
+  - AFL_PATH can be used to point afl-gcc to an alternate location of afl-as.
+    One possible use of this is experimental/clang_asm_normalize/, which lets
+    you instrument hand-written assembly when compiling clang code by plugging
+    a normalizer into the chain. (There is no equivalent feature for GCC.)
+
+  - Setting AFL_INST_RATIO to a percentage between 0 and 100% controls the
+    probability of instrumenting every branch. This is (very rarely) useful
+    when dealing with exceptionally complex programs that saturate the output
+    bitmap. Examples include v8, ffmpeg, and perl.
+
+    (If this ever happens, afl-fuzz will warn you ahead of the time by
+    displaying the "bitmap density" field in fiery red.)
+
+    Setting AFL_INST_RATIO to 0 is a valid choice. This will instrument only
+    the transitions between function entry points, but not individual branches.
+
+  - TMPDIR is used by afl-as for temporary files; if this variable is not set,
+    the tool defaults to /tmp.
+
+  - Setting AFL_KEEP_ASSEMBLY prevents afl-as from deleting instrumented
+    assembly files. Useful for troubleshooting problems or understanding how
+    the tool works. To get them in a predictable place, try something like:
+
+    mkdir assembly_here
+    TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all
+
+  - Setting AFL_QUIET will prevent afl-cc and afl-as banners from being
+    displayed during compilation, in case you find them distracting.
+
+2) Settings for afl-clang-fast
+------------------------------
+
+The native LLVM instrumentation helper accepts a subset of the settings
+discussed in section #1, with the exception of:
+
+  - AFL_AS, since this toolchain does not directly invoke GNU as.
+
+  - TMPDIR and AFL_KEEP_ASSEMBLY, since no temporary assembly files are
+    created.
+
+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.
+
+3) Settings for afl-fuzz
+------------------------
+
+The main fuzzer binary accepts several options that disable a couple of sanity
+checks or alter some of the more exotic semantics of the tool:
+
+  - Setting AFL_SKIP_CPUFREQ skips the check for CPU scaling policy. This is
+    useful if you can't change the defaults (e.g., no root access to the
+    system) and are OK with some performance loss.
+
+  - Setting AFL_NO_FORKSRV disables the forkserver optimization, reverting to
+    fork + execve() call for every tested input. This is useful mostly when
+    working with unruly libraries that create threads or do other crazy
+    things when initializing (before the instrumentation has a chance to run).
+
+    Note that this setting inhibits some of the user-friendly diagnostics
+    normally done when starting up the forkserver and causes a pretty
+    significant performance drop.
+
+  - Setting AFL_NO_VAR_CHECK skips the detection of variable test cases,
+    greatly speeding up session resumption and path discovery for complex
+    multi-threaded apps (but depriving you of a potentially useful signal
+    in more orderly programs).
+
+  - AFL_EXIT_WHEN_DONE causes afl-fuzz to terminate when all existing paths
+    have been fuzzed and there were no new finds for a while. This would be
+    normally indicated by the cycle counter in the UI turning green. May be
+    convenient for some types of automated jobs.
+
+  - AFL_SKIP_CRASHES causes AFL to tolerate crashing files in the input
+    queue. This can help with rare situations where a program crashes only
+    intermittently, but it's not really recommended under normal operating
+    conditions.
+
+  - AFL_SHUFFLE_QUEUE randomly reorders the input queue on startup. Requested
+    by some users for unorthodox parallelized fuzzing setups, but not
+    advisable otherwise.
+
+  - When developing custom instrumentation on top of afl-fuzz, you can use
+    AFL_SKIP_BIN_CHECK to inhibit the checks for non-instrumented binaries
+    and shell scripts; and AFL_DUMB_FORKSRV in conjunction with the -n
+    setting to instruct afl-fuzz to still follow the fork server protocol
+    without expecting any instrumentation data in return.
+
+  - When running in the -M or -S mode, setting AFL_IMPORT_FIRST causes the
+    fuzzer to import test cases from other instances before doing anything
+    else. This makes the "own finds" counter in the UI more accurate.
+    Beyond counter aesthetics, not much else should change.
+
+  - Setting AFL_POST_LIBRARY allows you to configure a postprocessor for
+    mutated files - say, to fix up checksums. See experimental/post_library/
+    for more.
+
+  - The CPU widget shown at the bottom of the screen is fairly simplistic and
+    may complain of high load prematurely, especially on systems with low core
+    counts. To avoid the alarming red color, you can set AFL_NO_CPU_RED.
+
+  - In QEMU mode (-Q), AFL_PATH will be searched for afl-qemu-trace.
+
+  - Setting AFL_LD_PRELOAD causes AFL to set LD_PRELOAD for the target binary
+    without disrupting the afl-fuzz process itself.
+
+  - If you are Jakub, you may need AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES.
+    Others need not apply.
+
+  - Benchmarking only: AFL_BENCH_JUST_ONE causes the fuzzer to exit after
+    processing the first queue entry; and AFL_BENCH_UNTIL_CRASH causes it to
+    exit when first crash is found.
+
+4) Settings for afl-qemu-trace
+------------------------------
+
+The QEMU wrapper used to instrument binary-only code supports several settings:
+
+  - It is possible to set AFL_INST_RATIO to skip the instrumentation on some
+    of the basic blocks, which can be useful when dealing with very complex
+    binaries.
+
+  - Setting AFL_INST_LIBS causes the translator to also instrument the code
+    inside any dynamically linked libraries (notably including glibc).
+
+  - The underlying QEMU binary will recognize any standard "user space
+    emulation" variables (e.g., QEMU_STACK_SIZE), but there should be no
+    reason to touch them.
+
+5) Settings for afl-cmin
+------------------------
+
+The corpus minimization script offers very little customization:
+
+  - Setting AFL_PATH offers a way to specify the location of afl-showmap
+    and afl-qemu-trace (the latter only in -Q mode).
+
+  - AFL_KEEP_TRACES makes the tool keep traces and other metadata used for
+    minimization and normally deleted at exit. The files can be found in the
+    <out_dir>/.traces/*.
+
+6) Settings for afl-tmin
+------------------------
+
+Virtually nothing to play with. Well, in QEMU mode (-Q), AFL_PATH will be
+searched for afl-qemu-trace. In addition to this, TMPDIR may be used if a
+temporary file can't be created in the current working directory.
+
+7) Third-party variables set by afl-fuzz & other tools
+------------------------------------------------------
+
+Several variables are not directly interpreted by afl-fuzz, but are set to
+optimal values if not already present in the environment:
+
+  - By default, LD_BIND_NOW is set to speed up fuzzing by forcing the
+    linker to do all the work before the fork server kicks in. You can
+    override this by setting LD_BIND_LAZY beforehand, but it is almost
+    certainly pointless.
+
+  - By default, ASAN_OPTIONS are set to:
+
+    abort_on_error=1
+    detect_leaks=0
+    symbolize=0
+    allocator_may_return_null=1
+
+    If you want to set your own options, be sure to include abort_on_error=1 -
+    otherwise, the fuzzer will not be able to detect crashes in the tested
+    app. Similarly, include symbolize=0, since without it, AFL may have
+    difficulty telling crashes and hangs apart.
+
+  - In the same vein, by default, MSAN_OPTIONS are set to:
+
+    exit_code=86 (required for legacy reasons)    
+    abort_on_error=1
+    symbolize=0
+    msan_track_origins=0
+    allocator_may_return_null=1
+
+    Be sure to include the first one when customizing anything, since MSAN
+    doesn't call abort() on error, and we need a way to detect faults.