+Flags
+=====
+The most important flags are::
+
+ seed 0 Random seed. If 0, seed is generated.
+ runs -1 Number of individual test runs (-1 for infinite runs).
+ max_len 64 Maximum length of the test input.
+ cross_over 1 If 1, cross over inputs.
+ mutate_depth 5 Apply this number of consecutive mutations to each input.
+ timeout 1200 Timeout in seconds (if positive). If one unit runs more than this number of seconds the process will abort.
+ max_total_time 0 If positive, indicates the maximal total time in seconds to run the fuzzer.
+ help 0 Print help.
+ save_minimized_corpus 0 If 1, the minimized corpus is saved into the first input directory. Example: ./fuzzer -save_minimized_corpus=1 NEW_EMPTY_DIR OLD_CORPUS
+ merge 0 If 1, the 2-nd, 3-rd, etc corpora will be merged into the 1-st corpus. Only interesting units will be taken.
+ jobs 0 Number of jobs to run. If jobs >= 1 we spawn this number of jobs in separate worker processes with stdout/stderr redirected to fuzz-JOB.log.
+ workers 0 Number of simultaneous worker processes to run the jobs. If zero, "min(jobs,NumberOfCpuCores()/2)" is used.
+ sync_command 0 Execute an external command "<sync_command> <test_corpus>" to synchronize the test corpus.
+ sync_timeout 600 Minimum timeout between syncs.
+ use_traces 0 Experimental: use instruction traces
+ only_ascii 0 If 1, generate only ASCII (isprint+isspace) inputs.
+ test_single_input "" Use specified file content as test input. Test will be run only once. Useful for debugging a particular case.
+ artifact_prefix "" Write fuzzing artifacts (crash, timeout, or slow inputs) as $(artifact_prefix)file
+ exact_artifact_path "" Write the single artifact on failure (crash, timeout) as $(exact_artifact_path). This overrides -artifact_prefix and will not use checksum in the file name. Do not use the same path for several parallel processes.
+
+For the full list of flags run the fuzzer binary with ``-help=1``.
+
+Usage examples
+==============
+
+Toy example
+-----------
+
+A simple function that does something interesting if it receives the input "HI!"::
+
+ cat << EOF >> test_fuzzer.cc
+ #include <stdint.h>
+ #include <stddef.h>
+ extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
+ if (size > 0 && data[0] == 'H')
+ if (size > 1 && data[1] == 'I')
+ if (size > 2 && data[2] == '!')
+ __builtin_trap();
+ return 0;
+ }
+ EOF
+ # Get lib/Fuzzer. Assuming that you already have fresh clang in PATH.
+ svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
+ # Build lib/Fuzzer files.
+ clang -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
+ # Build test_fuzzer.cc with asan and link against lib/Fuzzer.
+ clang++ -fsanitize=address -fsanitize-coverage=edge test_fuzzer.cc Fuzzer*.o
+ # Run the fuzzer with no corpus.
+ ./a.out
+
+You should get ``Illegal instruction (core dumped)`` pretty quickly.
+
+PCRE2
+-----
+
+Here we show how to use lib/Fuzzer on something real, yet simple: pcre2_::
+
+ COV_FLAGS=" -fsanitize-coverage=edge,indirect-calls,8bit-counters"
+ # Get PCRE2
+ svn co svn://vcs.exim.org/pcre2/code/trunk pcre
+ # Get lib/Fuzzer. Assuming that you already have fresh clang in PATH.
+ svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
+ # Build PCRE2 with AddressSanitizer and coverage.
+ (cd pcre; ./autogen.sh; CC="clang -fsanitize=address $COV_FLAGS" ./configure --prefix=`pwd`/../inst && make -j && make install)
+ # Build lib/Fuzzer files.
+ clang -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
+ # Build the actual function that does something interesting with PCRE2.
+ cat << EOF > pcre_fuzzer.cc
+ #include <string.h>
+ #include <stdint.h>
+ #include "pcre2posix.h"
+ extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
+ if (size < 1) return 0;
+ char *str = new char[size+1];
+ memcpy(str, data, size);
+ str[size] = 0;
+ regex_t preg;
+ if (0 == regcomp(&preg, str, 0)) {
+ regexec(&preg, str, 0, 0, 0);
+ regfree(&preg);
+ }
+ delete [] str;
+ return 0;
+ }
+ EOF
+ clang++ -g -fsanitize=address $COV_FLAGS -c -std=c++11 -I inst/include/ pcre_fuzzer.cc
+ # Link.
+ clang++ -g -fsanitize=address -Wl,--whole-archive inst/lib/*.a -Wl,-no-whole-archive Fuzzer*.o pcre_fuzzer.o -o pcre_fuzzer
+
+This will give you a binary of the fuzzer, called ``pcre_fuzzer``.
+Now, create a directory that will hold the test corpus::
+
+ mkdir -p CORPUS
+
+For simple input languages like regular expressions this is all you need.
+For more complicated inputs populate the directory with some input samples.
+Now run the fuzzer with the corpus dir as the only parameter::
+
+ ./pcre_fuzzer ./CORPUS
+
+You will see output like this::
+
+ Seed: 1876794929
+ #0 READ cov 0 bits 0 units 1 exec/s 0
+ #1 pulse cov 3 bits 0 units 1 exec/s 0
+ #1 INITED cov 3 bits 0 units 1 exec/s 0
+ #2 pulse cov 208 bits 0 units 1 exec/s 0
+ #2 NEW cov 208 bits 0 units 2 exec/s 0 L: 64
+ #3 NEW cov 217 bits 0 units 3 exec/s 0 L: 63
+ #4 pulse cov 217 bits 0 units 3 exec/s 0
+
+* The ``Seed:`` line shows you the current random seed (you can change it with ``-seed=N`` flag).
+* The ``READ`` line shows you how many input files were read (since you passed an empty dir there were inputs, but one dummy input was synthesised).
+* The ``INITED`` line shows you that how many inputs will be fuzzed.
+* The ``NEW`` lines appear with the fuzzer finds a new interesting input, which is saved to the CORPUS dir. If multiple corpus dirs are given, the first one is used.
+* The ``pulse`` lines appear periodically to show the current status.
+
+Now, interrupt the fuzzer and run it again the same way. You will see::
+
+ Seed: 1879995378
+ #0 READ cov 0 bits 0 units 564 exec/s 0
+ #1 pulse cov 502 bits 0 units 564 exec/s 0
+ ...
+ #512 pulse cov 2933 bits 0 units 564 exec/s 512
+ #564 INITED cov 2991 bits 0 units 344 exec/s 564
+ #1024 pulse cov 2991 bits 0 units 344 exec/s 1024
+ #1455 NEW cov 2995 bits 0 units 345 exec/s 1455 L: 49
+
+This time you were running the fuzzer with a non-empty input corpus (564 items).
+As the first step, the fuzzer minimized the set to produce 344 interesting items (the ``INITED`` line)
+
+It is quite convenient to store test corpuses in git.
+As an example, here is a git repository with test inputs for the above PCRE2 fuzzer::
+
+ git clone https://github.com/kcc/fuzzing-with-sanitizers.git
+ ./pcre_fuzzer ./fuzzing-with-sanitizers/pcre2/C1/
+
+You may run ``N`` independent fuzzer jobs in parallel on ``M`` CPUs::
+
+ N=100; M=4; ./pcre_fuzzer ./CORPUS -jobs=$N -workers=$M
+
+By default (``-reload=1``) the fuzzer processes will periodically scan the CORPUS directory
+and reload any new tests. This way the test inputs found by one process will be picked up
+by all others.
+
+If ``-workers=$M`` is not supplied, ``min($N,NumberOfCpuCore/2)`` will be used.
+
+Heartbleed
+----------
+Remember Heartbleed_?
+As it was recently `shown <https://blog.hboeck.de/archives/868-How-Heartbleed-couldve-been-found.html>`_,
+fuzzing with AddressSanitizer can find Heartbleed. Indeed, here are the step-by-step instructions
+to find Heartbleed with LibFuzzer::
+
+ wget https://www.openssl.org/source/openssl-1.0.1f.tar.gz
+ tar xf openssl-1.0.1f.tar.gz
+ COV_FLAGS="-fsanitize-coverage=edge,indirect-calls" # -fsanitize-coverage=8bit-counters
+ (cd openssl-1.0.1f/ && ./config &&
+ make -j 32 CC="clang -g -fsanitize=address $COV_FLAGS")
+ # Get and build LibFuzzer
+ svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
+ clang -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
+ # Get examples of key/pem files.
+ git clone https://github.com/hannob/selftls
+ cp selftls/server* . -v
+ cat << EOF > handshake-fuzz.cc
+ #include <openssl/ssl.h>
+ #include <openssl/err.h>
+ #include <assert.h>
+ #include <stdint.h>
+ #include <stddef.h>
+
+ SSL_CTX *sctx;
+ int Init() {
+ SSL_library_init();
+ SSL_load_error_strings();
+ ERR_load_BIO_strings();
+ OpenSSL_add_all_algorithms();
+ assert (sctx = SSL_CTX_new(TLSv1_method()));
+ assert (SSL_CTX_use_certificate_file(sctx, "server.pem", SSL_FILETYPE_PEM));
+ assert (SSL_CTX_use_PrivateKey_file(sctx, "server.key", SSL_FILETYPE_PEM));
+ return 0;
+ }
+ extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
+ static int unused = Init();
+ SSL *server = SSL_new(sctx);
+ BIO *sinbio = BIO_new(BIO_s_mem());
+ BIO *soutbio = BIO_new(BIO_s_mem());
+ SSL_set_bio(server, sinbio, soutbio);
+ SSL_set_accept_state(server);
+ BIO_write(sinbio, Data, Size);
+ SSL_do_handshake(server);
+ SSL_free(server);
+ return 0;
+ }
+ EOF
+ # Build the fuzzer.
+ clang++ -g handshake-fuzz.cc -fsanitize=address \
+ openssl-1.0.1f/libssl.a openssl-1.0.1f/libcrypto.a Fuzzer*.o
+ # Run 20 independent fuzzer jobs.
+ ./a.out -jobs=20 -workers=20
+
+Voila::
+
+ #1048576 pulse cov 3424 bits 0 units 9 exec/s 24385
+ =================================================================
+ ==17488==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x629000004748 at pc 0x00000048c979 bp 0x7fffe3e864f0 sp 0x7fffe3e85ca8
+ READ of size 60731 at 0x629000004748 thread T0
+ #0 0x48c978 in __asan_memcpy
+ #1 0x4db504 in tls1_process_heartbeat openssl-1.0.1f/ssl/t1_lib.c:2586:3
+ #2 0x580be3 in ssl3_read_bytes openssl-1.0.1f/ssl/s3_pkt.c:1092:4
+
+Note: a `similar fuzzer <https://boringssl.googlesource.com/boringssl/+/HEAD/FUZZING.md>`_
+is now a part of the boringssl source tree.
+
+Advanced features
+=================
+
+Dictionaries
+------------
+*EXPERIMENTAL*.
+LibFuzzer supports user-supplied dictionaries with input language keywords
+or other interesting byte sequences (e.g. multi-byte magic values).
+Use ``-dict=DICTIONARY_FILE``. For some input languages using a dictionary
+may significantly improve the search speed.
+The dictionary syntax is similar to that used by AFL_ for its ``-x`` option::
+
+ # Lines starting with '#' and empty lines are ignored.
+
+ # Adds "blah" (w/o quotes) to the dictionary.
+ kw1="blah"
+ # Use \\ for backslash and \" for quotes.
+ kw2="\"ac\\dc\""
+ # Use \xAB for hex values
+ kw3="\xF7\xF8"
+ # the name of the keyword followed by '=' may be omitted:
+ "foo\x0Abar"
+
+Data-flow-guided fuzzing
+------------------------
+
+*EXPERIMENTAL*.
+With an additional compiler flag ``-fsanitize-coverage=trace-cmp`` (see SanitizerCoverageTraceDataFlow_)
+and extra run-time flag ``-use_traces=1`` the fuzzer will try to apply *data-flow-guided fuzzing*.
+That is, the fuzzer will record the inputs to comparison instructions, switch statements,
+and several libc functions (``memcmp``, ``strcmp``, ``strncmp``, etc).
+It will later use those recorded inputs during mutations.
+
+This mode can be combined with DataFlowSanitizer_ to achieve better sensitivity.
+
+AFL compatibility
+-----------------
+LibFuzzer can be used in parallel with AFL_ on the same test corpus.
+Both fuzzers expect the test corpus to reside in a directory, one file per input.
+You can run both fuzzers on the same corpus in parallel::
+
+ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program -r @@
+ ./llvm-fuzz testcase_dir findings_dir # Will write new tests to testcase_dir
+
+Periodically restart both fuzzers so that they can use each other's findings.
+
+How good is my fuzzer?
+----------------------
+
+Once you implement your target function ``LLVMFuzzerTestOneInput`` and fuzz it to death,
+you will want to know whether the function or the corpus can be improved further.
+One easy to use metric is, of course, code coverage.
+You can get the coverage for your corpus like this::
+
+ ASAN_OPTIONS=coverage_pcs=1 ./fuzzer CORPUS_DIR -runs=0
+
+This will run all the tests in the CORPUS_DIR but will not generate any new tests
+and dump covered PCs to disk before exiting.
+Then you can subtract the set of covered PCs from the set of all instrumented PCs in the binary,
+see SanitizerCoverage_ for details.
+
+User-supplied mutators
+----------------------
+
+LibFuzzer allows to use custom (user-supplied) mutators,
+see FuzzerInterface.h_
+
+Fuzzing components of LLVM
+==========================