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

third_party/afl/src/docs/README

 ==================
 american fuzzy lop
 ==================
 
   Written and maintained by Michal Zalewski <lcamtuf@google.com>
 
   Copyright 2013, 2014, 2015, 2016 Google Inc. All rights reserved.
   Released under terms and conditions of Apache License, Version 2.0.
 
   For new versions and additional information, check out:
@@ skipping 97 matching lines @@
 data from stdin or from a file and passes it to the tested library. In such a
 case, it is essential to link this executable against a static version of the
 instrumented library, or to make sure that the correct .so file is loaded at
 runtime (usually by setting LD_LIBRARY_PATH). The simplest option is a static
 build, usually possible via:
 
 $ CC=/path/to/afl/afl-gcc ./configure --disable-shared
 
 Setting AFL_HARDEN=1 when calling 'make' will cause the CC wrapper to
 automatically enable code hardening options that make it easier to detect
-simple memory bugs.
+simple memory bugs. Libdislocator, a helper library included with AFL (see
+libdislocator/README.dislocator) can help uncover heap corruption issues, too.
 
 PS. ASAN users are advised to review notes_for_asan.txt file for important
 caveats.
 
 4) Instrumenting binary-only apps
 ---------------------------------
 
 When source code is *NOT* available, the fuzzer offers experimental support for
 fast, on-the-fly instrumentation of black-box binaries. This is accomplished
 with a version of QEMU running in the lesser-known "user space emulation" mode.
@@ skipping 140 matching lines @@
 redundant verbiage - notably including HTML, SQL, or JavaScript.
 
 To avoid the hassle of building syntax-aware tools, afl-fuzz provides a way to
 seed the fuzzing process with an optional dictionary of language keywords,
 magic headers, or other special tokens associated with the targeted data type
 - and use that to reconstruct the underlying grammar on the go:
 
   http://lcamtuf.blogspot.com/2015/01/afl-fuzz-making-up-grammar-with.html
 
 To use this feature, you first need to create a dictionary in one of the two
-formats discussed in testcases/README.testcases; and then point the fuzzer to
-it via the -x option in the command line.
+formats discussed in dictionaries/README.dictionaries; and then point the fuzzer
+to it via the -x option in the command line.
+
+(Several common dictionaries are already provided in that subdirectory, too.)
 
 There is no way to provide more structured descriptions of the underlying
 syntax, but the fuzzer will likely figure out some of this based on the
 instrumentation feedback alone. This actually works in practice, say:
 
   http://lcamtuf.blogspot.com/2015/04/finding-bugs-in-sqlite-easy-way.html
 
 PS. Even when no explicit dictionary is given, afl-fuzz will try to extract
 existing syntax tokens in the input corpus by watching the instrumentation
 very closely during deterministic byte flips. This works for some types of
 parsers and grammars, but isn't nearly as good as the -x mode.
 
+If a dictionary is really hard to come by, another option is to let AFL run
+for a while, and then use the token capture library that comes as a companion
+utility with AFL. For that, see libtokencap/README.tokencap.
+
 10) Crash triage
 ----------------
 
 The coverage-based grouping of crashes usually produces a small data set that
 can be quickly triaged manually or with a very simple GDB or Valgrind script.
 Every crash is also traceable to its parent non-crashing test case in the
 queue, making it easier to diagnose faults.
 
 Having said that, it's important to acknowledge that some fuzzing crashes can be
 difficult quickly evaluate for exploitability without a lot of debugging and
@@ skipping 26 matching lines @@
 The minimizer accepts the -m, -t, -f and @@ syntax in a manner compatible with
 afl-fuzz.
 
 Another recent addition to AFL is the afl-analyze tool. It takes an input
 file, attempts to sequentially flip bytes, and observes the behavior of the
 tested program. It then color-codes the input based on which sections appear to
 be critical, and which are not; while not bulletproof, it can often offer quick
 insights into complex file formats. More info about its operation can be found
 near the end of technical_details.txt.
 
-11) Common-sense risks
+11) Going beyond crashes
+------------------------
+
+Fuzzing is a wonderful and underutilized technique for discovering non-crashing
+design and implementation errors, too. Quite a few interesting bugs have been
+found by modifying the target programs to call abort() when, say:
+
+  - Two bignum libraries produce different outputs when given the same
+    fuzzer-generated input,
+
+  - An image library produces different outputs when asked to decode the same
+    input image several times in a row,
+
+  - A serialization / deserialization library fails to produce stable outputs
+    when iteratively serializing and deserializing fuzzer-supplied data,
+
+  - A compression library produces an output inconsistent with the input file
+    when asked to compress and then decompress a particular blob.
+
+Implementing these or similar sanity checks usually takes very little time;
+if you are the maintainer of a particular package, you can make this code
+conditional with #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION (a flag also
+shared with libfuzzer) or #ifdef __AFL_COMPILER (this one is just for AFL).
+
+12) Common-sense risks
 ----------------------
 
 Please keep in mind that, similarly to many other computationally-intensive
 tasks, fuzzing may put strain on your hardware and on the OS. In particular:
 
   - Your CPU will run hot and will need adequate cooling. In most cases, if
     cooling is insufficient or stops working properly, CPU speeds will be
     automatically throttled. That said, especially when fuzzing on less
     suitable hardware (laptops, smartphones, etc), it's not entirely impossible
     for something to blow up.
 
   - Targeted programs may end up erratically grabbing gigabytes of memory or
     filling up disk space with junk files. AFL tries to enforce basic memory
     limits, but can't prevent each and every possible mishap. The bottom line
     is that you shouldn't be fuzzing on systems where the prospect of data loss
     is not an acceptable risk.
 
   - Fuzzing involves billions of reads and writes to the filesystem. On modern
     systems, this will be usually heavily cached, resulting in fairly modest
     "physical" I/O - but there are many factors that may alter this equation.
     It is your responsibility to monitor for potential trouble; with very heavy
     I/O, the lifespan of many HDDs and SSDs may be reduced.
 
     A good way to monitor disk I/O on Linux is the 'iostat' command:
 
     $ iostat -d 3 -x -k [...optional disk ID...]
 
-12) Known limitations & areas for improvement
+13) Known limitations & areas for improvement
 ---------------------------------------------
 
 Here are some of the most important caveats for AFL:
 
   - AFL detects faults by checking for the first spawned process dying due to
     a signal (SIGSEGV, SIGABRT, etc). Programs that install custom handlers for
     these signals may need to have the relevant code commented out. In the same
     vein, faults in child processed spawned by the fuzzed target may evade
     detection unless you manually add some code to catch that.
 
@@ skipping 15 matching lines @@
     need to make simple code changes to make them behave in a more traditional
     way. Preeny may offer a relatively simple option, too - see:
     https://github.com/zardus/preeny
 
     Some useful tips for modifying network-based services can be also found at:
     https://www.fastly.com/blog/how-to-fuzz-server-american-fuzzy-lop
 
   - AFL doesn't output human-readable coverage data. If you want to monitor
     coverage, use afl-cov from Michael Rash: https://github.com/mrash/afl-cov
 
+  - Occasionally, sentient machines rise against their creators. If this
+    happens to you, please consult http://lcamtuf.coredump.cx/prep/.
+
 Beyond this, see INSTALL for platform-specific tips.
 
-13) Special thanks
+14) Special thanks
 ------------------
 
 Many of the improvements to afl-fuzz wouldn't be possible without feedback,
 bug reports, or patches from:
 
   Jann Horn                             Hanno Boeck
   Felix Groebert                        Jakub Wilk
   Richard W. M. Jones                   Alexander Cherepanov
   Tom Ritter                            Hovik Manucharyan
   Sebastian Roschke                     Eberhard Mattes
@@ skipping 16 matching lines @@
   Alex Moneger                          Dmitry Vyukov
   Keegan McAllister                     Kostya Serebryany
   Richo Healey                          Martijn Bogaard
   rc0r                                  Jonathan Foote
   Christian Holler                      Dominique Pelle
   Jacek Wielemborek                     Leo Barnes
   Jeremy Barnes                         Jeff Trull
   Guillaume Endignoux                   ilovezfs
   Daniel Godas-Lopez                    Franjo Ivancic
   Austin Seipp                          Daniel Komaromy
-  Daniel Binderman
+  Daniel Binderman                      Jonathan Metzman
+  Vegard Nossum                         Jan Kneschke
+  Kurt Roeckx
 
 Thank you!
 
-14) Contact
+15) Contact
 -----------
 
 Questions? Concerns? Bug reports? The author can be usually reached at
 <lcamtuf@google.com>.
 
 There is also a mailing list for the project; to join, send a mail to
 <afl-users+subscribe@googlegroups.com>. Or, if you prefer to browse
 archives first, try:
 
   https://groups.google.com/group/afl-users
 
 PS. If you wish to submit raw code to be incorporated into the project, please
 be aware that the copyright on most of AFL is claimed by Google. While you do
 retain copyright on your contributions, they do ask people to agree to a simple
 CLA first:
 
   https://cla.developers.google.com/clas
 
 Sorry about the hassle. Of course, no CLA is required for feature requests or
 bug reports.