blob: 28d0d3c2dc8ba54b80dd4434cbfb871e7aa99a67 [file] [log] [blame]
Kostya Serebryany79677382015-03-31 21:39:38 +00001========================================================
Kostya Serebryany35ce8632015-03-30 23:05:30 +00002LibFuzzer -- a library for coverage-guided fuzz testing.
3========================================================
Kostya Serebryany79677382015-03-31 21:39:38 +00004.. contents::
5 :local:
Kostya Serebryanyd11dc172016-03-12 02:56:25 +00006 :depth: 1
Kostya Serebryany79677382015-03-31 21:39:38 +00007
8Introduction
9============
Kostya Serebryany35ce8632015-03-30 23:05:30 +000010
Kostya Serebryanyd11dc172016-03-12 02:56:25 +000011libFuzzer -- library for in-process evolutionary fuzzing of other libraries.
Kostya Serebryany35ce8632015-03-30 23:05:30 +000012
Kostya Serebryanyd11dc172016-03-12 02:56:25 +000013The typical workflow looks like the following.
14First, implement a fuzzing target function, like this::
15
16 // fuzz_target.cc
17 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
18 DoSomethingInterestingWithMyAPI(Data, Size);
Kostya Serebryany9e1a2382016-03-29 23:07:36 +000019 return 0; // Non-zero return values are reserved for future use.
Kostya Serebryanyd11dc172016-03-12 02:56:25 +000020 }
21
22Next, build the Fuzzer library as a static archive. Note that libFuzzer contains the `main()` function::
23
24 svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
Kostya Serebryanya283ddc2016-04-15 21:10:27 +000025 # Alternative: get libFuzzer from a dedicated git mirror:
26 # git clone https://chromium.googlesource.com/chromium/llvm-project/llvm/lib/Fuzzer
Kostya Serebryanyd11dc172016-03-12 02:56:25 +000027 clang++ -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
28 ar ruv libFuzzer.a Fuzzer*.o
29
30Then build the target function and the library you are going to test.
31You should use SanitizerCoverage_ and one of ASan, MSan, or UBSan.
32Link it with `libFuzzer.a`::
33
34 clang -fsanitize-coverage=edge -fsanitize=address your_lib.cc fuzz_target.cc libFuzzer.a -o my_fuzzer
35
36Create a directory with the initial "seed" samlpes.
37For some input types libFuzzer will work just fine w/o any seeds,
38but for complex inputs this step is very important::
39
40 mkdir CORPUS_DIR
41 cp /some/input/samples/* CORPUS_DIR
42
43Finally, run the fuzzer on the `CORPUS_DIR`::
44
45 ./my_fuzzer CORPUS_DIR # -max_len=1000 -jobs=20 -more_lags=...
Kostya Serebryany35ce8632015-03-30 23:05:30 +000046
47
Kostya Serebryanyd11dc172016-03-12 02:56:25 +000048As new interesting test cases are discovered they will be added to the corpus.
49If a bug is discovered by the sanitizer (ASan, etc) it will be reported as usual and the reproducer
50will be written to disk.
51Each Fuzzer process is single-threaded (unless the library starts its own
52threads). You can run the libFuzzer on the same corpus in multiple processes
53in parallel (use the flags `-jobs=N` and `-workers=N`).
54
55libFuzzer is similar in concept to AFL_,
56but uses in-process Fuzzing, which is more fragile and restrictive, but
Kostya Serebryany35ce8632015-03-30 23:05:30 +000057potentially much faster as it has no overhead for process start-up.
Kostya Serebryany79677382015-03-31 21:39:38 +000058It uses LLVM's SanitizerCoverage_ instrumentation to get in-process
59coverage-feedback
Kostya Serebryany35ce8632015-03-30 23:05:30 +000060
Kostya Serebryany9e1a2382016-03-29 23:07:36 +000061The code resides in the LLVM repository,
62requires the fresh Clang compiler to build
Kostya Serebryany79677382015-03-31 21:39:38 +000063and is used to fuzz various parts of LLVM,
64but the Fuzzer itself does not (and should not) depend on any
65part of LLVM and can be used for other projects w/o requiring the rest of LLVM.
Kostya Serebryany35ce8632015-03-30 23:05:30 +000066
Kostya Serebryany9e1a2382016-03-29 23:07:36 +000067Fresh Clang
68-----------
69
70If you don't know where to get the fresh Clang binaries and don't want to build
71it from trunk (why wouldn't you?) you may grab the fresh Clang binaries
72maintained by the Chromium developers::
73
74 mkdir TMP_CLANG
75 cd TMP_CLANG
76 git clone https://chromium.googlesource.com/chromium/src/tools/clang
77 cd ..
78 TMP_CLANG/clang/scripts/update.py
79
80This will install a reasonably fresh and well tested clang binaries as
81`third_party/llvm-build/Release+Asserts/bin/clang`
82
Kostya Serebryanyd11dc172016-03-12 02:56:25 +000083Usage
84=====
85To run fuzzing pass 0 or more directories. New samples will be written into `dir1`, other directories will be read once during startup.::
Kostya Serebryanybfbe7fc2016-02-02 03:03:47 +000086
87./fuzzer [-flag1=val1 [-flag2=val2 ...] ] [dir1 [dir2 ...] ]
88
89To run individual tests without fuzzing pass 1 or more files::
90
91./fuzzer [-flag1=val1 [-flag2=val2 ...] ] file1 [file2 ...]
92
Kostya Serebryany2adfa3b2015-05-20 21:03:03 +000093The most important flags are::
94
95 seed 0 Random seed. If 0, seed is generated.
96 runs -1 Number of individual test runs (-1 for infinite runs).
Kostya Serebryany64d24572016-03-12 01:57:04 +000097 max_len 0 Maximum length of the test input. If 0, libFuzzer tries to guess a good value based on the corpus and reports it.
Kostya Serebryany316b5712015-05-26 20:57:47 +000098 timeout 1200 Timeout in seconds (if positive). If one unit runs more than this number of seconds the process will abort.
Kostya Serebryany54a63632016-01-29 23:30:07 +000099 timeout_exitcode 77 Unless abort_on_timeout is set, use this exitcode on timeout.
Kostya Serebryanyb85db172015-10-02 20:47:55 +0000100 max_total_time 0 If positive, indicates the maximal total time in seconds to run the fuzzer.
Kostya Serebryany2adfa3b2015-05-20 21:03:03 +0000101 help 0 Print help.
Kostya Serebryany9cc3b0d2015-10-24 01:16:40 +0000102 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.
Kostya Serebryany2adfa3b2015-05-20 21:03:03 +0000103 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.
104 workers 0 Number of simultaneous worker processes to run the jobs. If zero, "min(jobs,NumberOfCpuCores()/2)" is used.
Kostya Serebryanyb17e2982015-07-31 21:48:10 +0000105 use_traces 0 Experimental: use instruction traces
Kostya Serebryanybc7c0ad2015-08-11 01:44:42 +0000106 only_ascii 0 If 1, generate only ASCII (isprint+isspace) inputs.
Kostya Serebryanybd5d1cd2015-10-09 03:57:59 +0000107 artifact_prefix "" Write fuzzing artifacts (crash, timeout, or slow inputs) as $(artifact_prefix)file
Kostya Serebryany2d0ef142015-11-25 21:40:46 +0000108 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.
Kostya Serebryany3c767db2016-02-27 05:45:12 +0000109 print_final_stats 0 If 1, print statistics at exit.
Kostya Serebryany9e1a2382016-03-29 23:07:36 +0000110 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.
Kostya Serebryany2adfa3b2015-05-20 21:03:03 +0000111
112For the full list of flags run the fuzzer binary with ``-help=1``.
113
Kostya Serebryany79677382015-03-31 21:39:38 +0000114Usage examples
115==============
Kostya Serebryanyd11dc172016-03-12 02:56:25 +0000116.. contents::
117 :local:
118 :depth: 1
Kostya Serebryany79677382015-03-31 21:39:38 +0000119
120Toy example
121-----------
122
123A simple function that does something interesting if it receives the input "HI!"::
124
125 cat << EOF >> test_fuzzer.cc
Kostya Serebryany1c80b9d2015-11-26 00:12:57 +0000126 #include <stdint.h>
127 #include <stddef.h>
128 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
Kostya Serebryany79677382015-03-31 21:39:38 +0000129 if (size > 0 && data[0] == 'H')
130 if (size > 1 && data[1] == 'I')
131 if (size > 2 && data[2] == '!')
132 __builtin_trap();
Kostya Serebryany20bb5e72015-10-02 23:34:06 +0000133 return 0;
Kostya Serebryany79677382015-03-31 21:39:38 +0000134 }
135 EOF
Kostya Serebryanyabca88e2016-03-12 03:05:37 +0000136 # Build test_fuzzer.cc with asan and link against libFuzzer.a
137 clang++ -fsanitize=address -fsanitize-coverage=edge test_fuzzer.cc libFuzzer.a
Kostya Serebryany79677382015-03-31 21:39:38 +0000138 # Run the fuzzer with no corpus.
139 ./a.out
140
Kostya Serebryanyabca88e2016-03-12 03:05:37 +0000141You should get an error pretty quickly::
142
143 #0 READ units: 1 exec/s: 0
144 #1 INITED cov: 3 units: 1 exec/s: 0
145 #2 NEW cov: 5 units: 2 exec/s: 0 L: 64 MS: 0
146 #19237 NEW cov: 9 units: 3 exec/s: 0 L: 64 MS: 0
147 #20595 NEW cov: 10 units: 4 exec/s: 0 L: 1 MS: 4 ChangeASCIIInt-ShuffleBytes-ChangeByte-CrossOver-
148 #34574 NEW cov: 13 units: 5 exec/s: 0 L: 2 MS: 3 ShuffleBytes-CrossOver-ChangeBit-
149 #34807 NEW cov: 15 units: 6 exec/s: 0 L: 3 MS: 1 CrossOver-
150 ==31511== ERROR: libFuzzer: deadly signal
151 ...
152 artifact_prefix='./'; Test unit written to ./crash-b13e8756b13a00cf168300179061fb4b91fefbed
153
Kostya Serebryany79677382015-03-31 21:39:38 +0000154
155PCRE2
156-----
157
Kostya Serebryanyabca88e2016-03-12 03:05:37 +0000158Here we show how to use libFuzzer on something real, yet simple: pcre2_::
Kostya Serebryany79677382015-03-31 21:39:38 +0000159
Alexey Samsonov21a33812015-05-07 23:33:24 +0000160 COV_FLAGS=" -fsanitize-coverage=edge,indirect-calls,8bit-counters"
Kostya Serebryany79677382015-03-31 21:39:38 +0000161 # Get PCRE2
162 svn co svn://vcs.exim.org/pcre2/code/trunk pcre
Kostya Serebryany79677382015-03-31 21:39:38 +0000163 # Build PCRE2 with AddressSanitizer and coverage.
164 (cd pcre; ./autogen.sh; CC="clang -fsanitize=address $COV_FLAGS" ./configure --prefix=`pwd`/../inst && make -j && make install)
Kostya Serebryanyabca88e2016-03-12 03:05:37 +0000165 # Build the fuzzing target function that does something interesting with PCRE2.
Kostya Serebryany79677382015-03-31 21:39:38 +0000166 cat << EOF > pcre_fuzzer.cc
167 #include <string.h>
Kostya Serebryany1c80b9d2015-11-26 00:12:57 +0000168 #include <stdint.h>
Kostya Serebryany79677382015-03-31 21:39:38 +0000169 #include "pcre2posix.h"
Kostya Serebryany1c80b9d2015-11-26 00:12:57 +0000170 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
Kostya Serebryany20bb5e72015-10-02 23:34:06 +0000171 if (size < 1) return 0;
Kostya Serebryany79677382015-03-31 21:39:38 +0000172 char *str = new char[size+1];
173 memcpy(str, data, size);
174 str[size] = 0;
175 regex_t preg;
176 if (0 == regcomp(&preg, str, 0)) {
177 regexec(&preg, str, 0, 0, 0);
178 regfree(&preg);
179 }
180 delete [] str;
Kostya Serebryany20bb5e72015-10-02 23:34:06 +0000181 return 0;
Kostya Serebryany79677382015-03-31 21:39:38 +0000182 }
183 EOF
184 clang++ -g -fsanitize=address $COV_FLAGS -c -std=c++11 -I inst/include/ pcre_fuzzer.cc
185 # Link.
Kostya Serebryanyabca88e2016-03-12 03:05:37 +0000186 clang++ -g -fsanitize=address -Wl,--whole-archive inst/lib/*.a -Wl,-no-whole-archive libFuzzer.a pcre_fuzzer.o -o pcre_fuzzer
Kostya Serebryany79677382015-03-31 21:39:38 +0000187
188This will give you a binary of the fuzzer, called ``pcre_fuzzer``.
189Now, create a directory that will hold the test corpus::
190
191 mkdir -p CORPUS
192
193For simple input languages like regular expressions this is all you need.
194For more complicated inputs populate the directory with some input samples.
195Now run the fuzzer with the corpus dir as the only parameter::
196
197 ./pcre_fuzzer ./CORPUS
198
199You will see output like this::
200
201 Seed: 1876794929
202 #0 READ cov 0 bits 0 units 1 exec/s 0
203 #1 pulse cov 3 bits 0 units 1 exec/s 0
204 #1 INITED cov 3 bits 0 units 1 exec/s 0
205 #2 pulse cov 208 bits 0 units 1 exec/s 0
206 #2 NEW cov 208 bits 0 units 2 exec/s 0 L: 64
207 #3 NEW cov 217 bits 0 units 3 exec/s 0 L: 63
208 #4 pulse cov 217 bits 0 units 3 exec/s 0
209
210* The ``Seed:`` line shows you the current random seed (you can change it with ``-seed=N`` flag).
211* 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).
212* The ``INITED`` line shows you that how many inputs will be fuzzed.
213* 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.
214* The ``pulse`` lines appear periodically to show the current status.
215
216Now, interrupt the fuzzer and run it again the same way. You will see::
217
218 Seed: 1879995378
219 #0 READ cov 0 bits 0 units 564 exec/s 0
220 #1 pulse cov 502 bits 0 units 564 exec/s 0
221 ...
222 #512 pulse cov 2933 bits 0 units 564 exec/s 512
223 #564 INITED cov 2991 bits 0 units 344 exec/s 564
224 #1024 pulse cov 2991 bits 0 units 344 exec/s 1024
225 #1455 NEW cov 2995 bits 0 units 345 exec/s 1455 L: 49
226
227This time you were running the fuzzer with a non-empty input corpus (564 items).
228As the first step, the fuzzer minimized the set to produce 344 interesting items (the ``INITED`` line)
229
230You may run ``N`` independent fuzzer jobs in parallel on ``M`` CPUs::
231
232 N=100; M=4; ./pcre_fuzzer ./CORPUS -jobs=$N -workers=$M
233
Kostya Serebryany9690fcf2015-05-12 18:51:57 +0000234By default (``-reload=1``) the fuzzer processes will periodically scan the CORPUS directory
235and reload any new tests. This way the test inputs found by one process will be picked up
236by all others.
Kostya Serebryany79677382015-03-31 21:39:38 +0000237
Kostya Serebryany9690fcf2015-05-12 18:51:57 +0000238If ``-workers=$M`` is not supplied, ``min($N,NumberOfCpuCore/2)`` will be used.
Kostya Serebryany79677382015-03-31 21:39:38 +0000239
Kostya Serebryany5e593a42015-04-08 06:16:11 +0000240Heartbleed
241----------
242Remember Heartbleed_?
243As it was recently `shown <https://blog.hboeck.de/archives/868-How-Heartbleed-couldve-been-found.html>`_,
244fuzzing with AddressSanitizer can find Heartbleed. Indeed, here are the step-by-step instructions
245to find Heartbleed with LibFuzzer::
246
247 wget https://www.openssl.org/source/openssl-1.0.1f.tar.gz
248 tar xf openssl-1.0.1f.tar.gz
Alexey Samsonov21a33812015-05-07 23:33:24 +0000249 COV_FLAGS="-fsanitize-coverage=edge,indirect-calls" # -fsanitize-coverage=8bit-counters
Kostya Serebryany5e593a42015-04-08 06:16:11 +0000250 (cd openssl-1.0.1f/ && ./config &&
251 make -j 32 CC="clang -g -fsanitize=address $COV_FLAGS")
252 # Get and build LibFuzzer
253 svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
254 clang -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
255 # Get examples of key/pem files.
256 git clone https://github.com/hannob/selftls
257 cp selftls/server* . -v
258 cat << EOF > handshake-fuzz.cc
259 #include <openssl/ssl.h>
260 #include <openssl/err.h>
261 #include <assert.h>
Kostya Serebryany1c80b9d2015-11-26 00:12:57 +0000262 #include <stdint.h>
263 #include <stddef.h>
264
Kostya Serebryany5e593a42015-04-08 06:16:11 +0000265 SSL_CTX *sctx;
266 int Init() {
267 SSL_library_init();
268 SSL_load_error_strings();
269 ERR_load_BIO_strings();
270 OpenSSL_add_all_algorithms();
271 assert (sctx = SSL_CTX_new(TLSv1_method()));
272 assert (SSL_CTX_use_certificate_file(sctx, "server.pem", SSL_FILETYPE_PEM));
273 assert (SSL_CTX_use_PrivateKey_file(sctx, "server.key", SSL_FILETYPE_PEM));
274 return 0;
275 }
Kostya Serebryany1c80b9d2015-11-26 00:12:57 +0000276 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
Kostya Serebryany5e593a42015-04-08 06:16:11 +0000277 static int unused = Init();
278 SSL *server = SSL_new(sctx);
279 BIO *sinbio = BIO_new(BIO_s_mem());
280 BIO *soutbio = BIO_new(BIO_s_mem());
281 SSL_set_bio(server, sinbio, soutbio);
282 SSL_set_accept_state(server);
283 BIO_write(sinbio, Data, Size);
284 SSL_do_handshake(server);
285 SSL_free(server);
Kostya Serebryany20bb5e72015-10-02 23:34:06 +0000286 return 0;
Kostya Serebryany5e593a42015-04-08 06:16:11 +0000287 }
288 EOF
Mehdi Amini30618f92015-09-17 15:59:52 +0000289 # Build the fuzzer.
Kostya Serebryany5e593a42015-04-08 06:16:11 +0000290 clang++ -g handshake-fuzz.cc -fsanitize=address \
291 openssl-1.0.1f/libssl.a openssl-1.0.1f/libcrypto.a Fuzzer*.o
292 # Run 20 independent fuzzer jobs.
293 ./a.out -jobs=20 -workers=20
294
295Voila::
296
297 #1048576 pulse cov 3424 bits 0 units 9 exec/s 24385
298 =================================================================
299 ==17488==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x629000004748 at pc 0x00000048c979 bp 0x7fffe3e864f0 sp 0x7fffe3e85ca8
300 READ of size 60731 at 0x629000004748 thread T0
301 #0 0x48c978 in __asan_memcpy
302 #1 0x4db504 in tls1_process_heartbeat openssl-1.0.1f/ssl/t1_lib.c:2586:3
303 #2 0x580be3 in ssl3_read_bytes openssl-1.0.1f/ssl/s3_pkt.c:1092:4
304
Kostya Serebryany1c80b9d2015-11-26 00:12:57 +0000305Note: a `similar fuzzer <https://boringssl.googlesource.com/boringssl/+/HEAD/FUZZING.md>`_
306is now a part of the boringssl source tree.
307
Kostya Serebryany043ab1c2015-04-01 21:33:20 +0000308Advanced features
309=================
Kostya Serebryanyd11dc172016-03-12 02:56:25 +0000310.. contents::
311 :local:
312 :depth: 1
Kostya Serebryany043ab1c2015-04-01 21:33:20 +0000313
Kostya Serebryany7d211662015-09-04 00:12:11 +0000314Dictionaries
315------------
Kostya Serebryany7d211662015-09-04 00:12:11 +0000316LibFuzzer supports user-supplied dictionaries with input language keywords
317or other interesting byte sequences (e.g. multi-byte magic values).
318Use ``-dict=DICTIONARY_FILE``. For some input languages using a dictionary
319may significantly improve the search speed.
320The dictionary syntax is similar to that used by AFL_ for its ``-x`` option::
321
322 # Lines starting with '#' and empty lines are ignored.
323
324 # Adds "blah" (w/o quotes) to the dictionary.
325 kw1="blah"
326 # Use \\ for backslash and \" for quotes.
327 kw2="\"ac\\dc\""
328 # Use \xAB for hex values
329 kw3="\xF7\xF8"
330 # the name of the keyword followed by '=' may be omitted:
331 "foo\x0Abar"
332
Kostya Serebryanyb17e2982015-07-31 21:48:10 +0000333Data-flow-guided fuzzing
334------------------------
335
336*EXPERIMENTAL*.
337With an additional compiler flag ``-fsanitize-coverage=trace-cmp`` (see SanitizerCoverageTraceDataFlow_)
338and extra run-time flag ``-use_traces=1`` the fuzzer will try to apply *data-flow-guided fuzzing*.
339That is, the fuzzer will record the inputs to comparison instructions, switch statements,
Kostya Serebryany7f4227d2015-08-05 18:23:01 +0000340and several libc functions (``memcmp``, ``strcmp``, ``strncmp``, etc).
Kostya Serebryanyb17e2982015-07-31 21:48:10 +0000341It will later use those recorded inputs during mutations.
342
343This mode can be combined with DataFlowSanitizer_ to achieve better sensitivity.
344
Kostya Serebryany6bd016b2015-04-10 05:44:43 +0000345AFL compatibility
346-----------------
Kostya Serebryany9e1a2382016-03-29 23:07:36 +0000347LibFuzzer can be used together with AFL_ on the same test corpus.
Kostya Serebryany6bd016b2015-04-10 05:44:43 +0000348Both fuzzers expect the test corpus to reside in a directory, one file per input.
Kostya Serebryany9e1a2382016-03-29 23:07:36 +0000349You can run both fuzzers on the same corpus, one after another::
Kostya Serebryany6bd016b2015-04-10 05:44:43 +0000350
Kostya Serebryany9e1a2382016-03-29 23:07:36 +0000351 ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@
Kostya Serebryany6bd016b2015-04-10 05:44:43 +0000352 ./llvm-fuzz testcase_dir findings_dir # Will write new tests to testcase_dir
353
354Periodically restart both fuzzers so that they can use each other's findings.
Kostya Serebryany9e1a2382016-03-29 23:07:36 +0000355Currently, there is no simple way to run both fuzzing engines in parallel while sharing the same corpus dir.
Kostya Serebryany79677382015-03-31 21:39:38 +0000356
Kostya Serebryanycd073d52015-04-10 06:32:29 +0000357How good is my fuzzer?
358----------------------
359
Kostya Serebryany566bc5a2015-05-06 22:19:00 +0000360Once you implement your target function ``LLVMFuzzerTestOneInput`` and fuzz it to death,
Kostya Serebryanycd073d52015-04-10 06:32:29 +0000361you will want to know whether the function or the corpus can be improved further.
362One easy to use metric is, of course, code coverage.
363You can get the coverage for your corpus like this::
364
Kostya Serebryany7ead9262016-03-12 03:11:27 +0000365 ASAN_OPTIONS=coverage=1 ./fuzzer CORPUS_DIR -runs=0
Kostya Serebryanycd073d52015-04-10 06:32:29 +0000366
367This will run all the tests in the CORPUS_DIR but will not generate any new tests
368and dump covered PCs to disk before exiting.
369Then you can subtract the set of covered PCs from the set of all instrumented PCs in the binary,
370see SanitizerCoverage_ for details.
371
Kostya Serebryany926b9bd2015-05-22 22:43:05 +0000372User-supplied mutators
373----------------------
374
375LibFuzzer allows to use custom (user-supplied) mutators,
376see FuzzerInterface.h_
377
Kostya Serebryanyaca76962016-01-16 01:23:12 +0000378Startup initialization
379----------------------
380If the library being tested needs to be initialized, there are several options.
381
382The simplest way is to have a statically initialized global object::
383
384 static bool Initialized = DoInitialization();
385
386Alternatively, you may define an optional init function and it will receive
387the program arguments that you can read and modify::
388
389 extern "C" int LLVMFuzzerInitialize(int *argc, char ***argv) {
390 ReadAndMaybeModify(argc, argv);
391 return 0;
392 }
393
Kostya Serebryanyaca76962016-01-16 01:23:12 +0000394Try to avoid initialization inside the target function itself as
395it will skew the coverage data. Don't do this::
396
397 extern "C" int LLVMFuzzerTestOneInput(...) {
398 static bool initialized = false;
399 if (!initialized) {
400 ...
401 }
402 }
403
Kostya Serebryany9e1a2382016-03-29 23:07:36 +0000404Leaks
405-----
406
407When running libFuzzer with AddressSanitizer_ the latter will be able to report
408memory leaks, but only when the process exits, so if you suspect memory leaks
409in your target you should run libFuzzer with `-runs=N` or `-max_total_time=N`.
410If a leak is reported at the end, you will not get the reproducer from libFuzzer.
411You will need to re-run the target on every file in the corpus separately to
412find which one causes the leak.
413
414If your target has massive leaks you will eventually run out of RAM.
415To protect your machine from OOM death you may use
416e.g. `ASAN_OPTIONS=hard_rss_limit_mb=2000` (with AddressSanitizer_).
417
418In future libFuzzer may support finding/reporting leaks better than this, stay tuned.
419
Kostya Serebryany79677382015-03-31 21:39:38 +0000420Fuzzing components of LLVM
421==========================
Kostya Serebryanyd11dc172016-03-12 02:56:25 +0000422.. contents::
423 :local:
424 :depth: 1
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000425
426clang-format-fuzzer
427-------------------
428The inputs are random pieces of C++-like text.
429
430Build (make sure to use fresh clang as the host compiler)::
431
432 cmake -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLLVM_USE_SANITIZER=Address -DLLVM_USE_SANITIZE_COVERAGE=YES -DCMAKE_BUILD_TYPE=Release /path/to/llvm
433 ninja clang-format-fuzzer
434 mkdir CORPUS_DIR
435 ./bin/clang-format-fuzzer CORPUS_DIR
436
437Optionally build other kinds of binaries (asan+Debug, msan, ubsan, etc).
438
Kostya Serebryany79677382015-03-31 21:39:38 +0000439Tracking bug: https://llvm.org/bugs/show_bug.cgi?id=23052
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000440
Kostya Serebryany79677382015-03-31 21:39:38 +0000441clang-fuzzer
442------------
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000443
Kostya Serebryany866e0d12015-09-02 22:44:46 +0000444The behavior is very similar to ``clang-format-fuzzer``.
Kostya Serebryany79677382015-03-31 21:39:38 +0000445
446Tracking bug: https://llvm.org/bugs/show_bug.cgi?id=23057
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000447
Kostya Serebryanyb98e3272015-08-31 18:57:24 +0000448llvm-as-fuzzer
449--------------
450
451Tracking bug: https://llvm.org/bugs/show_bug.cgi?id=24639
452
Daniel Sanders5151b202015-09-18 10:47:45 +0000453llvm-mc-fuzzer
454--------------
455
456This tool fuzzes the MC layer. Currently it is only able to fuzz the
457disassembler but it is hoped that assembly, and round-trip verification will be
458added in future.
459
460When run in dissassembly mode, the inputs are opcodes to be disassembled. The
461fuzzer will consume as many instructions as possible and will stop when it
462finds an invalid instruction or runs out of data.
463
Daniel Sanders4fe1c8b2015-09-26 17:09:01 +0000464Please note that the command line interface differs slightly from that of other
465fuzzers. The fuzzer arguments should follow ``--fuzzer-args`` and should have
466a single dash, while other arguments control the operation mode and target in a
467similar manner to ``llvm-mc`` and should have two dashes. For example::
Daniel Sanders5151b202015-09-18 10:47:45 +0000468
Daniel Sanders4fe1c8b2015-09-26 17:09:01 +0000469 llvm-mc-fuzzer --triple=aarch64-linux-gnu --disassemble --fuzzer-args -max_len=4 -jobs=10
Daniel Sanders5151b202015-09-18 10:47:45 +0000470
Kostya Serebryanyfb2f3312015-05-13 22:42:28 +0000471Buildbot
472--------
473
474We have a buildbot that runs the above fuzzers for LLVM components
47524/7/365 at http://lab.llvm.org:8011/builders/sanitizer-x86_64-linux-fuzzer .
476
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000477FAQ
478=========================
479
Kostya Serebryany241fb612016-03-12 03:23:02 +0000480Q. Why libFuzzer does not use any of the LLVM support?
481------------------------------------------------------
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000482
483There are two reasons.
484
485First, we want this library to be used outside of the LLVM w/o users having to
486build the rest of LLVM. This may sound unconvincing for many LLVM folks,
487but in practice the need for building the whole LLVM frightens many potential
488users -- and we want more users to use this code.
489
490Second, there is a subtle technical reason not to rely on the rest of LLVM, or
491any other large body of code (maybe not even STL). When coverage instrumentation
492is enabled, it will also instrument the LLVM support code which will blow up the
493coverage set of the process (since the fuzzer is in-process). In other words, by
494using more external dependencies we will slow down the fuzzer while the main
495reason for it to exist is extreme speed.
496
497Q. What about Windows then? The Fuzzer contains code that does not build on Windows.
498------------------------------------------------------------------------------------
499
Kostya Serebryany241fb612016-03-12 03:23:02 +0000500Volunteers are welcome.
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000501
502Q. When this Fuzzer is not a good solution for a problem?
503---------------------------------------------------------
504
505* If the test inputs are validated by the target library and the validator
Kostya Serebryany241fb612016-03-12 03:23:02 +0000506 asserts/crashes on invalid inputs, in-process fuzzing is not applicable.
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000507* Bugs in the target library may accumulate w/o being detected. E.g. a memory
508 corruption that goes undetected at first and then leads to a crash while
509 testing another input. This is why it is highly recommended to run this
510 in-process fuzzer with all sanitizers to detect most bugs on the spot.
511* It is harder to protect the in-process fuzzer from excessive memory
512 consumption and infinite loops in the target library (still possible).
513* The target library should not have significant global state that is not
514 reset between the runs.
515* Many interesting target libs are not designed in a way that supports
516 the in-process fuzzer interface (e.g. require a file path instead of a
517 byte array).
518* If a single test run takes a considerable fraction of a second (or
519 more) the speed benefit from the in-process fuzzer is negligible.
520* If the target library runs persistent threads (that outlive
521 execution of one test) the fuzzing results will be unreliable.
522
523Q. So, what exactly this Fuzzer is good for?
524--------------------------------------------
525
526This Fuzzer might be a good choice for testing libraries that have relatively
Kostya Serebryany241fb612016-03-12 03:23:02 +0000527small inputs, each input takes < 10ms to run, and the library code is not expected
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000528to crash on invalid inputs.
Kostya Serebryany241fb612016-03-12 03:23:02 +0000529Examples: regular expression matchers, text or binary format parsers, compression,
530network, crypto.
Kostya Serebryany35ce8632015-03-30 23:05:30 +0000531
Kostya Serebryanyfab4fba2015-08-11 01:53:45 +0000532Trophies
533========
534* GLIBC: https://sourceware.org/glibc/wiki/FuzzingLibc
Kostya Serebryanyfdf44182015-08-11 04:16:37 +0000535
Kostya Serebryanyfab4fba2015-08-11 01:53:45 +0000536* MUSL LIBC:
Kostya Serebryanyfdf44182015-08-11 04:16:37 +0000537
538 * http://git.musl-libc.org/cgit/musl/commit/?id=39dfd58417ef642307d90306e1c7e50aaec5a35c
539 * http://www.openwall.com/lists/oss-security/2015/03/30/3
540
Kostya Serebryany928eb332015-10-12 18:15:42 +0000541* `pugixml <https://github.com/zeux/pugixml/issues/39>`_
Kostya Serebryanyfdf44182015-08-11 04:16:37 +0000542
Kostya Serebryany45dac2a2015-10-10 02:14:18 +0000543* PCRE: Search for "LLVM fuzzer" in http://vcs.pcre.org/pcre2/code/trunk/ChangeLog?view=markup;
Kostya Serebryany928eb332015-10-12 18:15:42 +0000544 also in `bugzilla <https://bugs.exim.org/buglist.cgi?bug_status=__all__&content=libfuzzer&no_redirect=1&order=Importance&product=PCRE&query_format=specific>`_
Kostya Serebryanyfdf44182015-08-11 04:16:37 +0000545
Kostya Serebryany928eb332015-10-12 18:15:42 +0000546* `ICU <http://bugs.icu-project.org/trac/ticket/11838>`_
Kostya Serebryanyed483772015-08-11 20:34:48 +0000547
Kostya Serebryany928eb332015-10-12 18:15:42 +0000548* `Freetype <https://savannah.nongnu.org/search/?words=LibFuzzer&type_of_search=bugs&Search=Search&exact=1#options>`_
Kostya Serebryany62921282015-09-11 16:34:14 +0000549
Kostya Serebryany928eb332015-10-12 18:15:42 +0000550* `Harfbuzz <https://github.com/behdad/harfbuzz/issues/139>`_
551
Kostya Serebryany240a1592015-11-11 05:25:24 +0000552* `SQLite <http://www3.sqlite.org/cgi/src/info/088009efdd56160b>`_
Kostya Serebryany65e71262015-11-11 05:20:55 +0000553
Kostya Serebryany12fa3b52015-11-13 02:44:16 +0000554* `Python <http://bugs.python.org/issue25388>`_
555
Kostya Serebryanyfece6742016-04-18 18:41:25 +0000556* OpenSSL/BoringSSL: `[1] <https://boringssl.googlesource.com/boringssl/+/cb852981cd61733a7a1ae4fd8755b7ff950e857d>`_ `[2] <https://openssl.org/news/secadv/20160301.txt>`_ `[3] <https://boringssl.googlesource.com/boringssl/+/2b07fa4b22198ac02e0cee8f37f3337c3dba91bc>`_ `[4] <https://boringssl.googlesource.com/boringssl/+/6b6e0b20893e2be0e68af605a60ffa2cbb0ffa64>`_ `[5] <https://github.com/openssl/openssl/pull/931/commits/dd5ac557f052cc2b7f718ac44a8cb7ac6f77dca8>`_ `[6] <https://github.com/openssl/openssl/pull/931/commits/19b5b9194071d1d84e38ac9a952e715afbc85a81>`_
Kostya Serebryany064a6722015-12-05 02:23:49 +0000557
Kostya Serebryany928eb332015-10-12 18:15:42 +0000558* `Libxml2
Kostya Serebryany0d234c32016-03-29 23:13:25 +0000559 <https://bugzilla.gnome.org/buglist.cgi?bug_status=__all__&content=libFuzzer&list_id=68957&order=Importance&product=libxml2&query_format=specific>`_ and `[HT206167] <https://support.apple.com/en-gb/HT206167>`_ (CVE-2015-5312, CVE-2015-7500, CVE-2015-7942)
Kostya Serebryany45dac2a2015-10-10 02:14:18 +0000560
Kostya Serebryany240a1592015-11-11 05:25:24 +0000561* `Linux Kernel's BPF verifier <https://github.com/iovisor/bpf-fuzzer>`_
Kostya Serebryany62921282015-09-11 16:34:14 +0000562
Kostya Serebryany240a1592015-11-11 05:25:24 +0000563* LLVM: `Clang <https://llvm.org/bugs/show_bug.cgi?id=23057>`_, `Clang-format <https://llvm.org/bugs/show_bug.cgi?id=23052>`_, `libc++ <https://llvm.org/bugs/show_bug.cgi?id=24411>`_, `llvm-as <https://llvm.org/bugs/show_bug.cgi?id=24639>`_, Disassembler: http://reviews.llvm.org/rL247405, http://reviews.llvm.org/rL247414, http://reviews.llvm.org/rL247416, http://reviews.llvm.org/rL247417, http://reviews.llvm.org/rL247420, http://reviews.llvm.org/rL247422.
Kostya Serebryanyfab4fba2015-08-11 01:53:45 +0000564
Kostya Serebryany79677382015-03-31 21:39:38 +0000565.. _pcre2: http://www.pcre.org/
566
567.. _AFL: http://lcamtuf.coredump.cx/afl/
568
Alexey Samsonov675e5392015-04-27 22:50:06 +0000569.. _SanitizerCoverage: http://clang.llvm.org/docs/SanitizerCoverage.html
Kostya Serebryanyb17e2982015-07-31 21:48:10 +0000570.. _SanitizerCoverageTraceDataFlow: http://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow
571.. _DataFlowSanitizer: http://clang.llvm.org/docs/DataFlowSanitizer.html
Kostya Serebryany9e1a2382016-03-29 23:07:36 +0000572.. _AddressSanitizer: http://clang.llvm.org/docs/AddressSanitizer.html
Kostya Serebryany5e593a42015-04-08 06:16:11 +0000573
574.. _Heartbleed: http://en.wikipedia.org/wiki/Heartbleed
Kostya Serebryany926b9bd2015-05-22 22:43:05 +0000575
576.. _FuzzerInterface.h: https://github.com/llvm-mirror/llvm/blob/master/lib/Fuzzer/FuzzerInterface.h