[llvm] r264803 - [libFuzzer] more docs
Kostya Serebryany via llvm-commits
llvm-commits at lists.llvm.org
Tue Mar 29 16:07:37 PDT 2016
Author: kcc
Date: Tue Mar 29 18:07:36 2016
New Revision: 264803
URL: http://llvm.org/viewvc/llvm-project?rev=264803&view=rev
Log:
[libFuzzer] more docs
Modified:
llvm/trunk/docs/LibFuzzer.rst
llvm/trunk/lib/Fuzzer/FuzzerFlags.def
Modified: llvm/trunk/docs/LibFuzzer.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LibFuzzer.rst?rev=264803&r1=264802&r2=264803&view=diff
==============================================================================
--- llvm/trunk/docs/LibFuzzer.rst (original)
+++ llvm/trunk/docs/LibFuzzer.rst Tue Mar 29 18:07:36 2016
@@ -16,7 +16,7 @@ First, implement a fuzzing target functi
// fuzz_target.cc
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
DoSomethingInterestingWithMyAPI(Data, Size);
- return 0;
+ return 0; // Non-zero return values are reserved for future use.
}
Next, build the Fuzzer library as a static archive. Note that libFuzzer contains the `main()` function::
@@ -56,11 +56,28 @@ potentially much faster as it has no ove
It uses LLVM's SanitizerCoverage_ instrumentation to get in-process
coverage-feedback
-The code resides in the LLVM repository, requires the fresh Clang compiler to build
+The code resides in the LLVM repository,
+requires the fresh Clang compiler to build
and is used to fuzz various parts of LLVM,
but the Fuzzer itself does not (and should not) depend on any
part of LLVM and can be used for other projects w/o requiring the rest of LLVM.
+Fresh Clang
+-----------
+
+If you don't know where to get the fresh Clang binaries and don't want to build
+it from trunk (why wouldn't you?) you may grab the fresh Clang binaries
+maintained by the Chromium developers::
+
+ mkdir TMP_CLANG
+ cd TMP_CLANG
+ git clone https://chromium.googlesource.com/chromium/src/tools/clang
+ cd ..
+ TMP_CLANG/clang/scripts/update.py
+
+This will install a reasonably fresh and well tested clang binaries as
+`third_party/llvm-build/Release+Asserts/bin/clang`
+
Usage
=====
To run fuzzing pass 0 or more directories. New samples will be written into `dir1`, other directories will be read once during startup.::
@@ -88,7 +105,7 @@ The most important flags are::
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.
print_final_stats 0 If 1, print statistics at exit.
- close_fd_mask 0 If 1, close stdout at startup; if 2, close stderr; if 3, close both.
+ close_fd_mask 0 If 1, close stdout at startup; if 2, close stderr; if 3, close both. Be careful, this will also close e.g. asan's stderr/stdout.
For the full list of flags run the fuzzer binary with ``-help=1``.
@@ -294,7 +311,6 @@ 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
@@ -326,14 +342,15 @@ This mode can be combined with DataFlowS
AFL compatibility
-----------------
-LibFuzzer can be used in parallel with AFL_ on the same test corpus.
+LibFuzzer can be used together 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::
+You can run both fuzzers on the same corpus, one after another::
- ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program -r @@
+ ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@
./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.
+Currently, there is no simple way to run both fuzzing engines in parallel while sharing the same corpus dir.
How good is my fuzzer?
----------------------
@@ -382,6 +399,22 @@ it will skew the coverage data. Don't do
}
}
+Leaks
+-----
+
+When running libFuzzer with AddressSanitizer_ the latter will be able to report
+memory leaks, but only when the process exits, so if you suspect memory leaks
+in your target you should run libFuzzer with `-runs=N` or `-max_total_time=N`.
+If a leak is reported at the end, you will not get the reproducer from libFuzzer.
+You will need to re-run the target on every file in the corpus separately to
+find which one causes the leak.
+
+If your target has massive leaks you will eventually run out of RAM.
+To protect your machine from OOM death you may use
+e.g. `ASAN_OPTIONS=hard_rss_limit_mb=2000` (with AddressSanitizer_).
+
+In future libFuzzer may support finding/reporting leaks better than this, stay tuned.
+
Fuzzing components of LLVM
==========================
.. contents::
@@ -534,6 +567,7 @@ Trophies
.. _SanitizerCoverage: http://clang.llvm.org/docs/SanitizerCoverage.html
.. _SanitizerCoverageTraceDataFlow: http://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow
.. _DataFlowSanitizer: http://clang.llvm.org/docs/DataFlowSanitizer.html
+.. _AddressSanitizer: http://clang.llvm.org/docs/AddressSanitizer.html
.. _Heartbleed: http://en.wikipedia.org/wiki/Heartbleed
Modified: llvm/trunk/lib/Fuzzer/FuzzerFlags.def
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Fuzzer/FuzzerFlags.def?rev=264803&r1=264802&r2=264803&view=diff
==============================================================================
--- llvm/trunk/lib/Fuzzer/FuzzerFlags.def (original)
+++ llvm/trunk/lib/Fuzzer/FuzzerFlags.def Tue Mar 29 18:07:36 2016
@@ -77,7 +77,8 @@ FUZZER_FLAG_INT(handle_fpe, 1, "If 1, tr
FUZZER_FLAG_INT(handle_int, 1, "If 1, try to intercept SIGINT.")
FUZZER_FLAG_INT(handle_term, 1, "If 1, try to intercept SIGTERM.")
FUZZER_FLAG_INT(close_fd_mask, 0, "If 1, close stdout at startup; "
- "if 2, close stderr; if 3, close both.")
+ "if 2, close stderr; if 3, close both. "
+ "Be careful, this will also close e.g. asan's stderr/stdout.")
FUZZER_DEPRECATED_FLAG(exit_on_first)
FUZZER_DEPRECATED_FLAG(save_minimized_corpus)
More information about the llvm-commits
mailing list