mirror of
https://github.com/c64scene-ar/llvm-6502.git
synced 2024-08-21 18:29:46 +00:00
c9baf3befb
Summary: A simple genetic in-process coverage-guided fuzz testing library. I've used this fuzzer to test clang-format (it found 12+ bugs, thanks djasper@ for the fixes!) and it may also help us test other parts of LLVM. So why not keep it in the LLVM repository? I plan to add the cmake build rules later (in a separate patch, if that's ok) and also add a clang-format-fuzzer target. See README.txt for details. Test Plan: Tests will follow separately. Reviewers: djasper, chandlerc, rnk Reviewed By: rnk Subscribers: majnemer, ygribov, dblaikie, llvm-commits Differential Revision: http://reviews.llvm.org/D7184 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@227252 91177308-0d34-0410-b5e6-96231b3b80d8
57 lines
3.0 KiB
Plaintext
57 lines
3.0 KiB
Plaintext
===============================
|
|
Fuzzer -- a library for coverage-guided fuzz testing.
|
|
===============================
|
|
|
|
This library is intended primarily for in-process coverage-guided fuzz testing
|
|
(fuzzing) of other libraries. The typical workflow looks like this:
|
|
|
|
* Build the Fuzzer library as a static archive (or just a set of .o files).
|
|
Note that the Fuzzer contains the main() function.
|
|
Preferably do *not* use sanitizers while building the Fuzzer.
|
|
* Build the library you are going to test with -fsanitize-coverage=[234]
|
|
and one of the sanitizers. We recommend to build the library in several
|
|
different modes (e.g. asan, msan, lsan, ubsan, etc) and even using different
|
|
optimizations options (e.g. -O0, -O1, -O2) to diversify testing.
|
|
* Build a test driver using the same options as the library.
|
|
The test driver is a C/C++ file containing interesting calls to the library
|
|
inside a single function:
|
|
extern "C" void TestOneInput(const uint8_t *Data, size_t Size);
|
|
* Link the Fuzzer, the library and the driver together into an executable
|
|
using the same sanitizer options as for the library.
|
|
* Collect the initial corpus of inputs for the
|
|
fuzzer (a directory with test inputs, one file per input).
|
|
The better your inputs are the faster you will find something interesting.
|
|
Also try to keep your inputs small, otherwise the Fuzzer will run too slow.
|
|
* Run the fuzzer with the test corpus. As new interesting test cases are
|
|
discovered they will be added to the corpus. If a bug is discovered by
|
|
the sanitizer (asan, etc) it will be reported as usual and the reproducer
|
|
will be written to disk.
|
|
Each Fuzzer process is single-threaded (unless the library starts its own
|
|
threads). You can run the Fuzzer on the same corpus in multiple processes.
|
|
in parallel. For run-time options run the Fuzzer binary with '-help=1'.
|
|
|
|
|
|
The Fuzzer is similar in concept to AFL (http://lcamtuf.coredump.cx/afl/),
|
|
but uses in-process Fuzzing, which is more fragile, more restrictive, but
|
|
potentially much faster as it has no overhead for process start-up.
|
|
It uses LLVM's "Sanitizer Coverage" instrumentation to get in-process
|
|
coverage-feedback https://code.google.com/p/address-sanitizer/wiki/AsanCoverage
|
|
|
|
The code resides in the LLVM repository and is (or will be) used by 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. Ideally, the Fuzzer's code
|
|
should not have any external dependencies. Right now it uses STL, which may need
|
|
to be fixed later.
|
|
|
|
Examples of usage in LLVM:
|
|
* clang-format-fuzzer. The inputs are random pieces of C++-like text.
|
|
* TODO: add more
|
|
|
|
Toy example (see SimpleTest.cpp):
|
|
a simple function that does something interesting if it receives bytes "Hi!".
|
|
# Build the Fuzzer with asan:
|
|
% clang++ -std=c++11 -fsanitize=address -fsanitize-coverage=3 -O1 -g \
|
|
Fuzzer*.cpp test/SimpleTest.cpp
|
|
# Run the fuzzer with no corpus (assuming on empty input)
|
|
% ./a.out
|