CbC/CbC_llvm: docs/LibFuzzer.rst comparison

comparison docs/LibFuzzer.rst @ 148:63bd29f05246

merged

author	Shinji KONO <kono@ie.u-ryukyu.ac.jp>
date	Wed, 14 Aug 2019 19:46:37 +0900
parents	c2174574ed3a
children

comparison

equal deleted inserted replaced

-:3fc4d5c3e21e
+:63bd29f05246
 Recent versions of Clang (starting from 6.0) include libFuzzer, and no extra installation is necessary.
 In order to build your fuzzer binary, use the `-fsanitize=fuzzer` flag during the
 compilation and linking. In most cases you may want to combine libFuzzer with
-AddressSanitizer_ (ASAN), UndefinedBehaviorSanitizer_ (UBSAN), or both::
+AddressSanitizer_ (ASAN), UndefinedBehaviorSanitizer_ (UBSAN), or both.  You can
+also build with MemorySanitizer_ (MSAN), but support is experimental::
 clang -g -O1 -fsanitize=fuzzer                         mytarget.c # Builds the fuzz target w/o sanitizers
 clang -g -O1 -fsanitize=fuzzer,address                 mytarget.c # Builds the fuzz target with ASAN
 clang -g -O1 -fsanitize=fuzzer,signed-integer-overflow mytarget.c # Builds the fuzz target with a part of UBSAN
+clang -g -O1 -fsanitize=fuzzer,memory                  mytarget.c # Builds the fuzz target with MSAN
 This will perform the necessary instrumentation, as well as linking with the libFuzzer library.
 Note that ``-fsanitize=fuzzer`` links in the libFuzzer's ``main()`` symbol.
 If modifying ``CFLAGS`` of a large project, which also compiles executables
 clang -fsanitize=fuzzer-no-link mytarget.c
 Then libFuzzer can be linked to the desired driver by passing in
 ``-fsanitize=fuzzer`` during the linking stage.
-Using MemorySanitizer_ (MSAN) with libFuzzer is possible too, but tricky.
-The exact details are out of scope, we expect to simplify this in future
-versions.
 .. _libfuzzer-corpus:
 Corpus
 ------
 worker processes, by default using half of the available CPU cores; the count of
 worker processes can be overridden by the ``-workers=N`` option.  For example,
 running with ``-jobs=30`` on a 12-core machine would run 6 workers by default,
 with each worker averaging 5 bugs by completion of the entire process.
+Fork mode
+---------
+**Experimental** mode ``-fork=N`` (where ``N`` is the number of parallel jobs)
+enables oom-, timeout-, and crash-resistant
+fuzzing with separate processes (using ``fork-exec``, not just ``fork``).
+The top libFuzzer process will not do any fuzzing itself, but will
+spawn up to ``N`` concurrent child processes providing them
+small random subsets of the corpus. After a child exits, the top process
+merges the corpus generated by the child back to the main corpus.
+Related flags:
+``-ignore_ooms``
+True by default. If an OOM happens during fuzzing in one of the child processes,
+the reproducer is saved on disk, and fuzzing continues.
+``-ignore_timeouts``
+True by default, same as ``-ignore_ooms``, but for timeouts.
+``-ignore_crashes``
+False by default, same as ``-ignore_ooms``, but for all other crashes.
+The plan is to eventually replace ``-jobs=N`` and ``-workers=N`` with ``-fork=N``.
 Resuming merge
 --------------
 Merging large corpora may be time consuming, and it is often desirable to do it
 ``-runs``
 Number of individual test runs, -1 (the default) to run indefinitely.
 ``-max_len``
 Maximum length of a test input. If 0 (the default), libFuzzer tries to guess
 a good value based on the corpus (and reports it).
+``len_control``
+Try generating small inputs first, then try larger inputs over time.
+Specifies the rate at which the length limit is increased (smaller == faster).
+Default is 100. If 0, immediately try inputs with size up to max_len.
 ``-timeout``
 Timeout in seconds, default 1200. If an input takes longer than this timeout,
 the process is treated as a failure case.
 ``-rss_limit_mb``
 Memory usage limit in Mb, default 2048. Use 0 to disable the limit.
 fuzzer processes (see `Parallel Fuzzing`_).
 Each output line also reports the following statistics (when non-zero):
 ``cov:``
-Total number of code blocks or edges covered by the executing the current
+Total number of code blocks or edges covered by executing the current corpus.
-corpus.
 ``ft:``
 libFuzzer uses different signals to evaluate the code coverage:
 edge coverage, edge counters, value profiles, indirect caller/callee pairs, etc.
 These signals combined are called *features* (`ft:`).
 ``corp:``
 Number of entries in the current in-memory test corpus and its size in bytes.
+``lim:``
+Current limit on the length of new entries in the corpus.  Increases over time
+until the max length (``-max_len``) is reached.
 ``exec/s:``
 Number of fuzzer iterations per second.
 ``rss:``
 Current memory consumption.
 if (size > 2 && data[2] == '!')
 __builtin_trap();
 return 0;
 }
 EOF
-# Build test_fuzzer.cc with asan and link against libFuzzer.a
+# Build test_fuzzer.cc with asan and link against libFuzzer.
-clang++ -fsanitize=address -fsanitize-coverage=trace-pc-guard test_fuzzer.cc libFuzzer.a
+clang++ -fsanitize=address,fuzzer test_fuzzer.cc
 # Run the fuzzer with no corpus.
 ./a.out
 You should get an error pretty quickly::
 the fuzzing but is very likely to improve the results.
 Value Profile
 -------------
-With  ``-fsanitize-coverage=trace-cmp``
+With  ``-fsanitize-coverage=trace-cmp`` (default with ``-fsanitize=fuzzer``)
 and extra run-time flag ``-use_value_profile=1`` the fuzzer will
 collect value profiles for the parameters of compare instructions
 and treat some new values as new coverage.
 The current imlpementation does roughly the following:
 Periodically restart both fuzzers so that they can use each other's findings.
 Currently, there is no simple way to run both fuzzing engines in parallel while sharing the same corpus dir.
 You may also use AFL on your target function ``LLVMFuzzerTestOneInput``:
-see an example `here <https://github.com/llvm-mirror/compiler-rt/tree/master/lib/fuzzer/afl>`__.
+see an example `here <https://github.com/llvm/llvm-project/tree/master/compiler-rt/lib/fuzzer/afl>`__.
 How good is my fuzzer?
 ----------------------
 Once you implement your target function ``LLVMFuzzerTestOneInput`` and fuzz it to death,
 User-supplied mutators
 ----------------------
-LibFuzzer allows to use custom (user-supplied) mutators,
+LibFuzzer allows to use custom (user-supplied) mutators, see
-see FuzzerInterface.h_
+`Structure-Aware Fuzzing <https://github.com/google/fuzzer-test-suite/blob/master/tutorial/structure-aware-fuzzing.md>`_
+for more details.
 Startup initialization
 ----------------------
 If the library being tested needs to be initialized, there are several options.
 is enabled, it will also instrument the LLVM support code which will blow up the
 coverage set of the process (since the fuzzer is in-process). In other words, by
 using more external dependencies we will slow down the fuzzer while the main
 reason for it to exist is extreme speed.
-Q. What about Windows then? The fuzzer contains code that does not build on Windows.
+Q. Does libFuzzer Support Windows?
 ------------------------------------------------------------------------------------
-Volunteers are welcome.
+Yes, libFuzzer now supports Windows. Initial support was added in r341082.
+Any build of Clang 9 supports it. You can download a build of Clang for Windows
+that has libFuzzer from
+`LLVM Snapshot Builds <https://llvm.org/builds/>`_.
+Using libFuzzer on Windows without ASAN is unsupported. Building fuzzers with the
+``/MD`` (dynamic runtime library) compile option is unsupported. Support for these
+may be added in the future. Linking fuzzers with the ``/INCREMENTAL`` link option
+(or the ``/DEBUG`` option which implies it) is also unsupported.
+Send any questions or comments to the mailing list: libfuzzer(#)googlegroups.com
 Q. When libFuzzer is not a good solution for a problem?
 ---------------------------------------------------------
 * If the test inputs are validated by the target library and the validator
 small inputs, each input takes < 10ms to run, and the library code is not expected
 to crash on invalid inputs.
 Examples: regular expression matchers, text or binary format parsers, compression,
 network, crypto.
+Q. LibFuzzer crashes on my complicated fuzz target (but works fine for me on smaller targets).
+----------------------------------------------------------------------------------------------
+Check if your fuzz target uses ``dlclose``.
+Currently, libFuzzer doesn't support targets that call ``dlclose``,
+this may be fixed in future.
 Trophies
 ========
 * Thousands of bugs found on OSS-Fuzz:  https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html
 .. _SanitizerCoverage: http://clang.llvm.org/docs/SanitizerCoverage.html
 .. _SanitizerCoverageTraceDataFlow: http://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow
 .. _AddressSanitizer: http://clang.llvm.org/docs/AddressSanitizer.html
 .. _LeakSanitizer: http://clang.llvm.org/docs/LeakSanitizer.html
 .. _Heartbleed: http://en.wikipedia.org/wiki/Heartbleed
-.. _FuzzerInterface.h: https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/FuzzerInterface.h
+.. _FuzzerInterface.h: https://github.com/llvm/llvm-project/blob/master/compiler-rt/lib/fuzzer/FuzzerInterface.h
 .. _3.7.0: http://llvm.org/releases/3.7.0/docs/LibFuzzer.html
 .. _building Clang from trunk: http://clang.llvm.org/get_started.html
 .. _MemorySanitizer: http://clang.llvm.org/docs/MemorySanitizer.html
 .. _UndefinedBehaviorSanitizer: http://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
 .. _`coverage counters`: http://clang.llvm.org/docs/SanitizerCoverage.html#coverage-counters

Mercurial > hg > CbC > CbC_llvm

comparison docs/LibFuzzer.rst @ 148:63bd29f05246