RPCSX/llvm
1
0
Fork 0
mirror of https://github.com/RPCSX/llvm.git synced 2025-02-03 11:08:32 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[libFuzzer] more docs

Browse Source 
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@264803 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Kostya Serebryany 2016-03-29 23:07:36 +00:00
parent 5a417a10c4
commit 7544ffc130
2 changed files with 43 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/LibFuzzer.rst
View File

@ -16,7 +16,7 @@ First, implement a fuzzing target function, like this::
// 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 overhead for process start-up.
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 DataFlowSanitizer_ to achieve better sensitivity.
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 this::
}
}
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

3
lib/Fuzzer/FuzzerFlags.def
View File

@ -77,7 +77,8 @@ FUZZER_FLAG_INT(handle_fpe, 1, "If 1, try to intercept SIGFPE.")
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)