1======================================================= 2libFuzzer – a library for coverage-guided fuzz testing. 3======================================================= 4.. contents:: 5 :local: 6 :depth: 1 7 8Introduction 9============ 10 11LibFuzzer is an in-process, coverage-guided, evolutionary fuzzing engine. 12 13LibFuzzer is linked with the library under test, and feeds fuzzed inputs to the 14library via a specific fuzzing entrypoint (aka "target function"); the fuzzer 15then tracks which areas of the code are reached, and generates mutations on the 16corpus of input data in order to maximize the code coverage. 17The code coverage 18information for libFuzzer is provided by LLVM's SanitizerCoverage_ 19instrumentation. 20 21Contact: libfuzzer(#)googlegroups.com 22 23Status 24====== 25 26The original authors of libFuzzer have stopped active work on it and switched 27to working on another fuzzing engine, Centipede_. LibFuzzer is still fully 28supported in that important bugs will get fixed. However, please do not expect 29major new features or code reviews, other than for bug fixes. 30 31Versions 32======== 33 34LibFuzzer requires a matching version of Clang. 35 36 37Getting Started 38=============== 39 40.. contents:: 41 :local: 42 :depth: 1 43 44Fuzz Target 45----------- 46 47The first step in using libFuzzer on a library is to implement a 48*fuzz target* -- a function that accepts an array of bytes and 49does something interesting with these bytes using the API under test. 50Like this: 51 52.. code-block:: c++ 53 54 // fuzz_target.cc 55 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) { 56 DoSomethingInterestingWithMyAPI(Data, Size); 57 return 0; // Values other than 0 and -1 are reserved for future use. 58 } 59 60Note that this fuzz target does not depend on libFuzzer in any way 61and so it is possible and even desirable to use it with other fuzzing engines 62e.g. AFL_ and/or Radamsa_. 63 64Some important things to remember about fuzz targets: 65 66* The fuzzing engine will execute the fuzz target many times with different inputs in the same process. 67* It must tolerate any kind of input (empty, huge, malformed, etc). 68* It must not `exit()` on any input. 69* It may use threads but ideally all threads should be joined at the end of the function. 70* It must be as deterministic as possible. Non-determinism (e.g. random decisions not based on the input bytes) will make fuzzing inefficient. 71* It must be fast. Try avoiding cubic or greater complexity, logging, or excessive memory consumption. 72* Ideally, it should not modify any global state (although that's not strict). 73* Usually, the narrower the target the better. E.g. if your target can parse several data formats, split it into several targets, one per format. 74 75 76Fuzzer Usage 77------------ 78 79Recent versions of Clang (starting from 6.0) include libFuzzer, and no extra installation is necessary. 80 81In order to build your fuzzer binary, use the `-fsanitize=fuzzer` flag during the 82compilation and linking. In most cases you may want to combine libFuzzer with 83AddressSanitizer_ (ASAN), UndefinedBehaviorSanitizer_ (UBSAN), or both. You can 84also build with MemorySanitizer_ (MSAN), but support is experimental:: 85 86 clang -g -O1 -fsanitize=fuzzer mytarget.c # Builds the fuzz target w/o sanitizers 87 clang -g -O1 -fsanitize=fuzzer,address mytarget.c # Builds the fuzz target with ASAN 88 clang -g -O1 -fsanitize=fuzzer,signed-integer-overflow mytarget.c # Builds the fuzz target with a part of UBSAN 89 clang -g -O1 -fsanitize=fuzzer,memory mytarget.c # Builds the fuzz target with MSAN 90 91This will perform the necessary instrumentation, as well as linking with the libFuzzer library. 92Note that ``-fsanitize=fuzzer`` links in the libFuzzer's ``main()`` symbol. 93 94If modifying ``CFLAGS`` of a large project, which also compiles executables 95requiring their own ``main`` symbol, it may be desirable to request just the 96instrumentation without linking:: 97 98 clang -fsanitize=fuzzer-no-link mytarget.c 99 100Then libFuzzer can be linked to the desired driver by passing in 101``-fsanitize=fuzzer`` during the linking stage. 102 103.. _libfuzzer-corpus: 104 105Corpus 106------ 107 108Coverage-guided fuzzers like libFuzzer rely on a corpus of sample inputs for the 109code under test. This corpus should ideally be seeded with a varied collection 110of valid and invalid inputs for the code under test; for example, for a graphics 111library the initial corpus might hold a variety of different small PNG/JPG/GIF 112files. The fuzzer generates random mutations based around the sample inputs in 113the current corpus. If a mutation triggers execution of a previously-uncovered 114path in the code under test, then that mutation is saved to the corpus for 115future variations. 116 117LibFuzzer will work without any initial seeds, but will be less 118efficient if the library under test accepts complex, 119structured inputs. 120 121The corpus can also act as a sanity/regression check, to confirm that the 122fuzzing entrypoint still works and that all of the sample inputs run through 123the code under test without problems. 124 125If you have a large corpus (either generated by fuzzing or acquired by other means) 126you may want to minimize it while still preserving the full coverage. One way to do that 127is to use the `-merge=1` flag: 128 129.. code-block:: console 130 131 mkdir NEW_CORPUS_DIR # Store minimized corpus here. 132 ./my_fuzzer -merge=1 NEW_CORPUS_DIR FULL_CORPUS_DIR 133 134You may use the same flag to add more interesting items to an existing corpus. 135Only the inputs that trigger new coverage will be added to the first corpus. 136 137.. code-block:: console 138 139 ./my_fuzzer -merge=1 CURRENT_CORPUS_DIR NEW_POTENTIALLY_INTERESTING_INPUTS_DIR 140 141Running 142------- 143 144To run the fuzzer, first create a Corpus_ directory that holds the 145initial "seed" sample inputs: 146 147.. code-block:: console 148 149 mkdir CORPUS_DIR 150 cp /some/input/samples/* CORPUS_DIR 151 152Then run the fuzzer on the corpus directory: 153 154.. code-block:: console 155 156 ./my_fuzzer CORPUS_DIR # -max_len=1000 -jobs=20 ... 157 158As the fuzzer discovers new interesting test cases (i.e. test cases that 159trigger coverage of new paths through the code under test), those test cases 160will be added to the corpus directory. 161 162By default, the fuzzing process will continue indefinitely – at least until 163a bug is found. Any crashes or sanitizer failures will be reported as usual, 164stopping the fuzzing process, and the particular input that triggered the bug 165will be written to disk (typically as ``crash-<sha1>``, ``leak-<sha1>``, 166or ``timeout-<sha1>``). 167 168 169Parallel Fuzzing 170---------------- 171 172Each libFuzzer process is single-threaded, unless the library under test starts 173its own threads. However, it is possible to run multiple libFuzzer processes in 174parallel with a shared corpus directory; this has the advantage that any new 175inputs found by one fuzzer process will be available to the other fuzzer 176processes (unless you disable this with the ``-reload=0`` option). 177 178This is primarily controlled by the ``-jobs=N`` option, which indicates that 179that `N` fuzzing jobs should be run to completion (i.e. until a bug is found or 180time/iteration limits are reached). These jobs will be run across a set of 181worker processes, by default using half of the available CPU cores; the count of 182worker processes can be overridden by the ``-workers=N`` option. For example, 183running with ``-jobs=30`` on a 12-core machine would run 6 workers by default, 184with each worker averaging 5 bugs by completion of the entire process. 185 186Fork mode 187--------- 188 189**Experimental** mode ``-fork=N`` (where ``N`` is the number of parallel jobs) 190enables oom-, timeout-, and crash-resistant 191fuzzing with separate processes (using ``fork-exec``, not just ``fork``). 192 193The top libFuzzer process will not do any fuzzing itself, but will 194spawn up to ``N`` concurrent child processes providing them 195small random subsets of the corpus. After a child exits, the top process 196merges the corpus generated by the child back to the main corpus. 197 198Related flags: 199 200``-ignore_ooms`` 201 True by default. If an OOM happens during fuzzing in one of the child processes, 202 the reproducer is saved on disk, and fuzzing continues. 203``-ignore_timeouts`` 204 True by default, same as ``-ignore_ooms``, but for timeouts. 205``-ignore_crashes`` 206 False by default, same as ``-ignore_ooms``, but for all other crashes. 207 208The plan is to eventually replace ``-jobs=N`` and ``-workers=N`` with ``-fork=N``. 209 210Resuming merge 211-------------- 212 213Merging large corpora may be time consuming, and it is often desirable to do it 214on preemptable VMs, where the process may be killed at any time. 215In order to seamlessly resume the merge, use the ``-merge_control_file`` flag 216and use ``killall -SIGUSR1 /path/to/fuzzer/binary`` to stop the merge gracefully. Example: 217 218.. code-block:: console 219 220 % rm -f SomeLocalPath 221 % ./my_fuzzer CORPUS1 CORPUS2 -merge=1 -merge_control_file=SomeLocalPath 222 ... 223 MERGE-INNER: using the control file 'SomeLocalPath' 224 ... 225 # While this is running, do `killall -SIGUSR1 my_fuzzer` in another console 226 ==9015== INFO: libFuzzer: exiting as requested 227 228 # This will leave the file SomeLocalPath with the partial state of the merge. 229 # Now, you can continue the merge by executing the same command. The merge 230 # will continue from where it has been interrupted. 231 % ./my_fuzzer CORPUS1 CORPUS2 -merge=1 -merge_control_file=SomeLocalPath 232 ... 233 MERGE-OUTER: non-empty control file provided: 'SomeLocalPath' 234 MERGE-OUTER: control file ok, 32 files total, first not processed file 20 235 ... 236 237Options 238======= 239 240To run the fuzzer, pass zero or more corpus directories as command line 241arguments. The fuzzer will read test inputs from each of these corpus 242directories, and any new test inputs that are generated will be written 243back to the first corpus directory: 244 245.. code-block:: console 246 247 ./fuzzer [-flag1=val1 [-flag2=val2 ...] ] [dir1 [dir2 ...] ] 248 249If a list of files (rather than directories) are passed to the fuzzer program, 250then it will re-run those files as test inputs but will not perform any fuzzing. 251In this mode the fuzzer binary can be used as a regression test (e.g. on a 252continuous integration system) to check the target function and saved inputs 253still work. 254 255The most important command line options are: 256 257``-help`` 258 Print help message (``-help=1``). 259``-seed`` 260 Random seed. If 0 (the default), the seed is generated. 261``-runs`` 262 Number of individual test runs, -1 (the default) to run indefinitely. 263``-max_len`` 264 Maximum length of a test input. If 0 (the default), libFuzzer tries to guess 265 a good value based on the corpus (and reports it). 266``-len_control`` 267 Try generating small inputs first, then try larger inputs over time. 268 Specifies the rate at which the length limit is increased (smaller == faster). 269 Default is 100. If 0, immediately try inputs with size up to max_len. 270``-timeout`` 271 Timeout in seconds, default 1200. If an input takes longer than this timeout, 272 the process is treated as a failure case. 273``-rss_limit_mb`` 274 Memory usage limit in Mb, default 2048. Use 0 to disable the limit. 275 If an input requires more than this amount of RSS memory to execute, 276 the process is treated as a failure case. 277 The limit is checked in a separate thread every second. 278 If running w/o ASAN/MSAN, you may use 'ulimit -v' instead. 279``-malloc_limit_mb`` 280 If non-zero, the fuzzer will exit if the target tries to allocate this 281 number of Mb with one malloc call. 282 If zero (default) same limit as rss_limit_mb is applied. 283``-timeout_exitcode`` 284 Exit code (default 77) used if libFuzzer reports a timeout. 285``-error_exitcode`` 286 Exit code (default 77) used if libFuzzer itself (not a sanitizer) reports a bug (leak, OOM, etc). 287``-max_total_time`` 288 If positive, indicates the maximum total time in seconds to run the fuzzer. 289 If 0 (the default), run indefinitely. 290``-merge`` 291 If set to 1, any corpus inputs from the 2nd, 3rd etc. corpus directories 292 that trigger new code coverage will be merged into the first corpus 293 directory. Defaults to 0. This flag can be used to minimize a corpus. 294``-merge_control_file`` 295 Specify a control file used for the merge process. 296 If a merge process gets killed it tries to leave this file in a state 297 suitable for resuming the merge. By default a temporary file will be used. 298``-minimize_crash`` 299 If 1, minimizes the provided crash input. 300 Use with -runs=N or -max_total_time=N to limit the number of attempts. 301``-reload`` 302 If set to 1 (the default), the corpus directory is re-read periodically to 303 check for new inputs; this allows detection of new inputs that were discovered 304 by other fuzzing processes. 305``-jobs`` 306 Number of fuzzing jobs to run to completion. Default value is 0, which runs a 307 single fuzzing process until completion. If the value is >= 1, then this 308 number of jobs performing fuzzing are run, in a collection of parallel 309 separate worker processes; each such worker process has its 310 ``stdout``/``stderr`` redirected to ``fuzz-<JOB>.log``. 311``-workers`` 312 Number of simultaneous worker processes to run the fuzzing jobs to completion 313 in. If 0 (the default), ``min(jobs, NumberOfCpuCores()/2)`` is used. 314``-dict`` 315 Provide a dictionary of input keywords; see Dictionaries_. 316``-use_counters`` 317 Use `coverage counters`_ to generate approximate counts of how often code 318 blocks are hit; defaults to 1. 319``-reduce_inputs`` 320 Try to reduce the size of inputs while preserving their full feature sets; 321 defaults to 1. 322``-use_value_profile`` 323 Use `value profile`_ to guide corpus expansion; defaults to 0. 324``-only_ascii`` 325 If 1, generate only ASCII (``isprint``+``isspace``) inputs. Defaults to 0. 326``-artifact_prefix`` 327 Provide a prefix to use when saving fuzzing artifacts (crash, timeout, or 328 slow inputs) as ``$(artifact_prefix)file``. Defaults to empty. 329``-exact_artifact_path`` 330 Ignored if empty (the default). If non-empty, write the single artifact on 331 failure (crash, timeout) as ``$(exact_artifact_path)``. This overrides 332 ``-artifact_prefix`` and will not use checksum in the file name. Do not use 333 the same path for several parallel processes. 334``-print_pcs`` 335 If 1, print out newly covered PCs. Defaults to 0. 336``-print_final_stats`` 337 If 1, print statistics at exit. Defaults to 0. 338``-detect_leaks`` 339 If 1 (default) and if LeakSanitizer is enabled 340 try to detect memory leaks during fuzzing (i.e. not only at shut down). 341``-close_fd_mask`` 342 Indicate output streams to close at startup. Be careful, this will 343 remove diagnostic output from target code (e.g. messages on assert failure). 344 345 - 0 (default): close neither ``stdout`` nor ``stderr`` 346 - 1 : close ``stdout`` 347 - 2 : close ``stderr`` 348 - 3 : close both ``stdout`` and ``stderr``. 349 350For the full list of flags run the fuzzer binary with ``-help=1``. 351 352Output 353====== 354 355During operation the fuzzer prints information to ``stderr``, for example:: 356 357 INFO: Seed: 1523017872 358 INFO: Loaded 1 modules (16 guards): [0x744e60, 0x744ea0), 359 INFO: -max_len is not provided, using 64 360 INFO: A corpus is not provided, starting from an empty corpus 361 #0 READ units: 1 362 #1 INITED cov: 3 ft: 2 corp: 1/1b exec/s: 0 rss: 24Mb 363 #3811 NEW cov: 4 ft: 3 corp: 2/2b exec/s: 0 rss: 25Mb L: 1 MS: 5 ChangeBit-ChangeByte-ChangeBit-ShuffleBytes-ChangeByte- 364 #3827 NEW cov: 5 ft: 4 corp: 3/4b exec/s: 0 rss: 25Mb L: 2 MS: 1 CopyPart- 365 #3963 NEW cov: 6 ft: 5 corp: 4/6b exec/s: 0 rss: 25Mb L: 2 MS: 2 ShuffleBytes-ChangeBit- 366 #4167 NEW cov: 7 ft: 6 corp: 5/9b exec/s: 0 rss: 25Mb L: 3 MS: 1 InsertByte- 367 ... 368 369The early parts of the output include information about the fuzzer options and 370configuration, including the current random seed (in the ``Seed:`` line; this 371can be overridden with the ``-seed=N`` flag). 372 373Further output lines have the form of an event code and statistics. The 374possible event codes are: 375 376``READ`` 377 The fuzzer has read in all of the provided input samples from the corpus 378 directories. 379``INITED`` 380 The fuzzer has completed initialization, which includes running each of 381 the initial input samples through the code under test. 382``NEW`` 383 The fuzzer has created a test input that covers new areas of the code 384 under test. This input will be saved to the primary corpus directory. 385``REDUCE`` 386 The fuzzer has found a better (smaller) input that triggers previously 387 discovered features (set ``-reduce_inputs=0`` to disable). 388``pulse`` 389 The fuzzer has generated 2\ :sup:`n` inputs (generated periodically to reassure 390 the user that the fuzzer is still working). 391``DONE`` 392 The fuzzer has completed operation because it has reached the specified 393 iteration limit (``-runs``) or time limit (``-max_total_time``). 394``RELOAD`` 395 The fuzzer is performing a periodic reload of inputs from the corpus 396 directory; this allows it to discover any inputs discovered by other 397 fuzzer processes (see `Parallel Fuzzing`_). 398 399Each output line also reports the following statistics (when non-zero): 400 401``cov:`` 402 Total number of code blocks or edges covered by executing the current corpus. 403``ft:`` 404 libFuzzer uses different signals to evaluate the code coverage: 405 edge coverage, edge counters, value profiles, indirect caller/callee pairs, etc. 406 These signals combined are called *features* (`ft:`). 407``corp:`` 408 Number of entries in the current in-memory test corpus and its size in bytes. 409``lim:`` 410 Current limit on the length of new entries in the corpus. Increases over time 411 until the max length (``-max_len``) is reached. 412``exec/s:`` 413 Number of fuzzer iterations per second. 414``rss:`` 415 Current memory consumption. 416 417For ``NEW`` and ``REDUCE`` events, the output line also includes information 418about the mutation operation that produced the new input: 419 420``L:`` 421 Size of the new input in bytes. 422``MS: <n> <operations>`` 423 Count and list of the mutation operations used to generate the input. 424 425 426Examples 427======== 428.. contents:: 429 :local: 430 :depth: 1 431 432Toy example 433----------- 434 435A simple function that does something interesting if it receives the input 436"HI!":: 437 438 cat << EOF > test_fuzzer.cc 439 #include <stdint.h> 440 #include <stddef.h> 441 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) { 442 if (size > 0 && data[0] == 'H') 443 if (size > 1 && data[1] == 'I') 444 if (size > 2 && data[2] == '!') 445 __builtin_trap(); 446 return 0; 447 } 448 EOF 449 # Build test_fuzzer.cc with asan and link against libFuzzer. 450 clang++ -fsanitize=address,fuzzer test_fuzzer.cc 451 # Run the fuzzer with no corpus. 452 ./a.out 453 454You should get an error pretty quickly:: 455 456 INFO: Seed: 1523017872 457 INFO: Loaded 1 modules (16 guards): [0x744e60, 0x744ea0), 458 INFO: -max_len is not provided, using 64 459 INFO: A corpus is not provided, starting from an empty corpus 460 #0 READ units: 1 461 #1 INITED cov: 3 ft: 2 corp: 1/1b exec/s: 0 rss: 24Mb 462 #3811 NEW cov: 4 ft: 3 corp: 2/2b exec/s: 0 rss: 25Mb L: 1 MS: 5 ChangeBit-ChangeByte-ChangeBit-ShuffleBytes-ChangeByte- 463 #3827 NEW cov: 5 ft: 4 corp: 3/4b exec/s: 0 rss: 25Mb L: 2 MS: 1 CopyPart- 464 #3963 NEW cov: 6 ft: 5 corp: 4/6b exec/s: 0 rss: 25Mb L: 2 MS: 2 ShuffleBytes-ChangeBit- 465 #4167 NEW cov: 7 ft: 6 corp: 5/9b exec/s: 0 rss: 25Mb L: 3 MS: 1 InsertByte- 466 ==31511== ERROR: libFuzzer: deadly signal 467 ... 468 artifact_prefix='./'; Test unit written to ./crash-b13e8756b13a00cf168300179061fb4b91fefbed 469 470 471More examples 472------------- 473 474Examples of real-life fuzz targets and the bugs they find can be found 475at http://tutorial.libfuzzer.info. Among other things you can learn how 476to detect Heartbleed_ in one second. 477 478 479Advanced features 480================= 481.. contents:: 482 :local: 483 :depth: 1 484 485Dictionaries 486------------ 487LibFuzzer supports user-supplied dictionaries with input language keywords 488or other interesting byte sequences (e.g. multi-byte magic values). 489Use ``-dict=DICTIONARY_FILE``. For some input languages using a dictionary 490may significantly improve the search speed. 491The dictionary syntax is similar to that used by AFL_ for its ``-x`` option:: 492 493 # Lines starting with '#' and empty lines are ignored. 494 495 # Adds "blah" (w/o quotes) to the dictionary. 496 kw1="blah" 497 # Use \\ for backslash and \" for quotes. 498 kw2="\"ac\\dc\"" 499 # Use \xAB for hex values 500 kw3="\xF7\xF8" 501 # the name of the keyword followed by '=' may be omitted: 502 "foo\x0Abar" 503 504 505 506Tracing CMP instructions 507------------------------ 508 509With an additional compiler flag ``-fsanitize-coverage=trace-cmp`` 510(on by default as part of ``-fsanitize=fuzzer``, see SanitizerCoverageTraceDataFlow_) 511libFuzzer will intercept CMP instructions and guide mutations based 512on the arguments of intercepted CMP instructions. This may slow down 513the fuzzing but is very likely to improve the results. 514 515Value Profile 516------------- 517 518With ``-fsanitize-coverage=trace-cmp`` (default with ``-fsanitize=fuzzer``) 519and extra run-time flag ``-use_value_profile=1`` the fuzzer will 520collect value profiles for the parameters of compare instructions 521and treat some new values as new coverage. 522 523The current implementation does roughly the following: 524 525* The compiler instruments all CMP instructions with a callback that receives both CMP arguments. 526* The callback computes `(caller_pc&4095) | (popcnt(Arg1 ^ Arg2) << 12)` and uses this value to set a bit in a bitset. 527* Every new observed bit in the bitset is treated as new coverage. 528 529 530This feature has a potential to discover many interesting inputs, 531but there are two downsides. 532First, the extra instrumentation may bring up to 2x additional slowdown. 533Second, the corpus may grow by several times. 534 535Fuzzer-friendly build mode 536--------------------------- 537Sometimes the code under test is not fuzzing-friendly. Examples: 538 539 - The target code uses a PRNG seeded e.g. by system time and 540 thus two consequent invocations may potentially execute different code paths 541 even if the end result will be the same. This will cause a fuzzer to treat 542 two similar inputs as significantly different and it will blow up the test corpus. 543 E.g. libxml uses ``rand()`` inside its hash table. 544 - The target code uses checksums to protect from invalid inputs. 545 E.g. png checks CRC for every chunk. 546 547In many cases it makes sense to build a special fuzzing-friendly build 548with certain fuzzing-unfriendly features disabled. We propose to use a common build macro 549for all such cases for consistency: ``FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION``. 550 551.. code-block:: c++ 552 553 void MyInitPRNG() { 554 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 555 // In fuzzing mode the behavior of the code should be deterministic. 556 srand(0); 557 #else 558 srand(time(0)); 559 #endif 560 } 561 562 563 564AFL compatibility 565----------------- 566LibFuzzer can be used together with AFL_ on the same test corpus. 567Both fuzzers expect the test corpus to reside in a directory, one file per input. 568You can run both fuzzers on the same corpus, one after another: 569 570.. code-block:: console 571 572 ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@ 573 ./llvm-fuzz testcase_dir findings_dir # Will write new tests to testcase_dir 574 575Periodically restart both fuzzers so that they can use each other's findings. 576Currently, there is no simple way to run both fuzzing engines in parallel while sharing the same corpus dir. 577 578You may also use AFL on your target function ``LLVMFuzzerTestOneInput``: 579see an example `here <https://github.com/llvm/llvm-project/tree/main/compiler-rt/lib/fuzzer/afl>`__. 580 581How good is my fuzzer? 582---------------------- 583 584Once you implement your target function ``LLVMFuzzerTestOneInput`` and fuzz it to death, 585you will want to know whether the function or the corpus can be improved further. 586One easy to use metric is, of course, code coverage. 587 588We recommend to use 589`Clang Coverage <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_, 590to visualize and study your code coverage 591(`example <https://github.com/google/fuzzer-test-suite/blob/master/tutorial/libFuzzerTutorial.md#visualizing-coverage>`_). 592 593 594User-supplied mutators 595---------------------- 596 597LibFuzzer allows to use custom (user-supplied) mutators, see 598`Structure-Aware Fuzzing <https://github.com/google/fuzzing/blob/master/docs/structure-aware-fuzzing.md>`_ 599for more details. 600 601Startup initialization 602---------------------- 603If the library being tested needs to be initialized, there are several options. 604 605The simplest way is to have a statically initialized global object inside 606`LLVMFuzzerTestOneInput` (or in global scope if that works for you): 607 608.. code-block:: c++ 609 610 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) { 611 static bool Initialized = DoInitialization(); 612 ... 613 614Alternatively, you may define an optional init function and it will receive 615the program arguments that you can read and modify. Do this **only** if you 616really need to access ``argv``/``argc``. 617 618.. code-block:: c++ 619 620 extern "C" int LLVMFuzzerInitialize(int *argc, char ***argv) { 621 ReadAndMaybeModify(argc, argv); 622 return 0; 623 } 624 625Using libFuzzer as a library 626---------------------------- 627If the code being fuzzed must provide its own `main`, it's possible to 628invoke libFuzzer as a library. Be sure to pass ``-fsanitize=fuzzer-no-link`` 629during compilation, and link your binary against the no-main version of 630libFuzzer. On Linux installations, this is typically located at: 631 632.. code-block:: bash 633 634 /usr/lib/<llvm-version>/lib/clang/<clang-version>/lib/linux/libclang_rt.fuzzer_no_main-<architecture>.a 635 636If building libFuzzer from source, this is located at the following path 637in the build output directory: 638 639.. code-block:: bash 640 641 lib/linux/libclang_rt.fuzzer_no_main-<architecture>.a 642 643From here, the code can do whatever setup it requires, and when it's ready 644to start fuzzing, it can call `LLVMFuzzerRunDriver`, passing in the program 645arguments and a callback. This callback is invoked just like 646`LLVMFuzzerTestOneInput`, and has the same signature. 647 648.. code-block:: c++ 649 650 extern "C" int LLVMFuzzerRunDriver(int *argc, char ***argv, 651 int (*UserCb)(const uint8_t *Data, size_t Size)); 652 653 654Rejecting unwanted inputs 655------------------------- 656 657It may be desirable to reject some inputs, i.e. to not add them to the corpus. 658 659For example, when fuzzing an API consisting of parsing and other logic, 660one may want to allow only those inputs into the corpus that parse successfully. 661 662If the fuzz target returns -1 on a given input, 663libFuzzer will not add that input top the corpus, regardless of what coverage 664it triggers. 665 666 667.. code-block:: c++ 668 669 extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) { 670 if (auto *Obj = ParseMe(Data, Size)) { 671 Obj->DoSomethingInteresting(); 672 return 0; // Accept. The input may be added to the corpus. 673 } 674 return -1; // Reject; The input will not be added to the corpus. 675 } 676 677Leaks 678----- 679 680Binaries built with AddressSanitizer_ or LeakSanitizer_ will try to detect 681memory leaks at the process shutdown. 682For in-process fuzzing this is inconvenient 683since the fuzzer needs to report a leak with a reproducer as soon as the leaky 684mutation is found. However, running full leak detection after every mutation 685is expensive. 686 687By default (``-detect_leaks=1``) libFuzzer will count the number of 688``malloc`` and ``free`` calls when executing every mutation. 689If the numbers don't match (which by itself doesn't mean there is a leak) 690libFuzzer will invoke the more expensive LeakSanitizer_ 691pass and if the actual leak is found, it will be reported with the reproducer 692and the process will exit. 693 694If your target has massive leaks and the leak detection is disabled 695you will eventually run out of RAM (see the ``-rss_limit_mb`` flag). 696 697 698Developing libFuzzer 699==================== 700 701LibFuzzer is built as a part of LLVM project by default on macos and Linux. 702Users of other operating systems can explicitly request compilation using 703``-DCOMPILER_RT_BUILD_LIBFUZZER=ON`` flag. 704Tests are run using ``check-fuzzer`` target from the build directory 705which was configured with ``-DCOMPILER_RT_INCLUDE_TESTS=ON`` flag. 706 707.. code-block:: console 708 709 ninja check-fuzzer 710 711 712FAQ 713========================= 714 715Q. Why doesn't libFuzzer use any of the LLVM support? 716----------------------------------------------------- 717 718There are two reasons. 719 720First, we want this library to be used outside of the LLVM without users having to 721build the rest of LLVM. This may sound unconvincing for many LLVM folks, 722but in practice the need for building the whole LLVM frightens many potential 723users -- and we want more users to use this code. 724 725Second, there is a subtle technical reason not to rely on the rest of LLVM, or 726any other large body of code (maybe not even STL). When coverage instrumentation 727is enabled, it will also instrument the LLVM support code which will blow up the 728coverage set of the process (since the fuzzer is in-process). In other words, by 729using more external dependencies we will slow down the fuzzer while the main 730reason for it to exist is extreme speed. 731 732Q. Does libFuzzer Support Windows? 733------------------------------------------------------------------------------------ 734 735Yes, libFuzzer now supports Windows. Initial support was added in r341082. 736Any build of Clang 9 supports it. You can download a build of Clang for Windows 737that has libFuzzer from 738`LLVM Snapshot Builds <https://llvm.org/builds/>`_. 739 740Using libFuzzer on Windows without ASAN is unsupported. Building fuzzers with the 741``/MD`` (dynamic runtime library) compile option is unsupported. Support for these 742may be added in the future. Linking fuzzers with the ``/INCREMENTAL`` link option 743(or the ``/DEBUG`` option which implies it) is also unsupported. 744 745Send any questions or comments to the mailing list: libfuzzer(#)googlegroups.com 746 747Q. When libFuzzer is not a good solution for a problem? 748--------------------------------------------------------- 749 750* If the test inputs are validated by the target library and the validator 751 asserts/crashes on invalid inputs, in-process fuzzing is not applicable. 752* Bugs in the target library may accumulate without being detected. E.g. a memory 753 corruption that goes undetected at first and then leads to a crash while 754 testing another input. This is why it is highly recommended to run this 755 in-process fuzzer with all sanitizers to detect most bugs on the spot. 756* It is harder to protect the in-process fuzzer from excessive memory 757 consumption and infinite loops in the target library (still possible). 758* The target library should not have significant global state that is not 759 reset between the runs. 760* Many interesting target libraries are not designed in a way that supports 761 the in-process fuzzer interface (e.g. require a file path instead of a 762 byte array). 763* If a single test run takes a considerable fraction of a second (or 764 more) the speed benefit from the in-process fuzzer is negligible. 765* If the target library runs persistent threads (that outlive 766 execution of one test) the fuzzing results will be unreliable. 767 768Q. So, what exactly this Fuzzer is good for? 769-------------------------------------------- 770 771This Fuzzer might be a good choice for testing libraries that have relatively 772small inputs, each input takes < 10ms to run, and the library code is not expected 773to crash on invalid inputs. 774Examples: regular expression matchers, text or binary format parsers, compression, 775network, crypto. 776 777Q. LibFuzzer crashes on my complicated fuzz target (but works fine for me on smaller targets). 778---------------------------------------------------------------------------------------------- 779 780Check if your fuzz target uses ``dlclose``. 781Currently, libFuzzer doesn't support targets that call ``dlclose``, 782this may be fixed in future. 783 784 785Trophies 786======== 787* Thousands of bugs found on OSS-Fuzz: https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html 788 789* GLIBC: https://sourceware.org/glibc/wiki/FuzzingLibc 790 791* MUSL LIBC: `[1] <http://git.musl-libc.org/cgit/musl/commit/?id=39dfd58417ef642307d90306e1c7e50aaec5a35c>`__ `[2] <http://www.openwall.com/lists/oss-security/2015/03/30/3>`__ 792 793* `pugixml <https://github.com/zeux/pugixml/issues/39>`_ 794 795* PCRE: Search for "LLVM fuzzer" in http://vcs.pcre.org/pcre2/code/trunk/ChangeLog?view=markup; 796 also in `bugzilla <https://bugs.exim.org/buglist.cgi?bug_status=__all__&content=libfuzzer&no_redirect=1&order=Importance&product=PCRE&query_format=specific>`_ 797 798* `ICU <http://bugs.icu-project.org/trac/ticket/11838>`_ 799 800* `Freetype <https://savannah.nongnu.org/search/?words=LibFuzzer&type_of_search=bugs&Search=Search&exact=1#options>`_ 801 802* `Harfbuzz <https://github.com/behdad/harfbuzz/issues/139>`_ 803 804* `SQLite <http://www3.sqlite.org/cgi/src/info/088009efdd56160b>`_ 805 806* `Python <http://bugs.python.org/issue25388>`_ 807 808* 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>`_ 809 810* `Libxml2 811 <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) 812 813* `Linux Kernel's BPF verifier <https://github.com/iovisor/bpf-fuzzer>`_ 814 815* `Linux Kernel's Crypto code <https://www.spinics.net/lists/stable/msg199712.html>`_ 816 817* Capstone: `[1] <https://github.com/aquynh/capstone/issues/600>`__ `[2] <https://github.com/aquynh/capstone/commit/6b88d1d51eadf7175a8f8a11b690684443b11359>`__ 818 819* file:`[1] <http://bugs.gw.com/view.php?id=550>`__ `[2] <http://bugs.gw.com/view.php?id=551>`__ `[3] <http://bugs.gw.com/view.php?id=553>`__ `[4] <http://bugs.gw.com/view.php?id=554>`__ 820 821* Radare2: `[1] <https://github.com/revskills?tab=contributions&from=2016-04-09>`__ 822 823* gRPC: `[1] <https://github.com/grpc/grpc/pull/6071/commits/df04c1f7f6aec6e95722ec0b023a6b29b6ea871c>`__ `[2] <https://github.com/grpc/grpc/pull/6071/commits/22a3dfd95468daa0db7245a4e8e6679a52847579>`__ `[3] <https://github.com/grpc/grpc/pull/6071/commits/9cac2a12d9e181d130841092e9d40fa3309d7aa7>`__ `[4] <https://github.com/grpc/grpc/pull/6012/commits/82a91c91d01ce9b999c8821ed13515883468e203>`__ `[5] <https://github.com/grpc/grpc/pull/6202/commits/2e3e0039b30edaf89fb93bfb2c1d0909098519fa>`__ `[6] <https://github.com/grpc/grpc/pull/6106/files>`__ 824 825* WOFF2: `[1] <https://github.com/google/woff2/commit/a15a8ab>`__ 826 827* LLVM: `Clang <https://bugs.llvm.org/show_bug.cgi?id=23057>`_, `Clang-format <https://bugs.llvm.org/show_bug.cgi?id=23052>`_, `libc++ <https://bugs.llvm.org/show_bug.cgi?id=24411>`_, `llvm-as <https://bugs.llvm.org/show_bug.cgi?id=24639>`_, `Demangler <https://bugs.chromium.org/p/chromium/issues/detail?id=606626>`_, 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. 828 829* Tensorflow: `[1] <https://da-data.blogspot.com/2017/01/finding-bugs-in-tensorflow-with.html>`__ 830 831* Ffmpeg: `[1] <https://github.com/FFmpeg/FFmpeg/commit/c92f55847a3d9cd12db60bfcd0831ff7f089c37c>`__ `[2] <https://github.com/FFmpeg/FFmpeg/commit/25ab1a65f3acb5ec67b53fb7a2463a7368f1ad16>`__ `[3] <https://github.com/FFmpeg/FFmpeg/commit/85d23e5cbc9ad6835eef870a5b4247de78febe56>`__ `[4] <https://github.com/FFmpeg/FFmpeg/commit/04bd1b38ee6b8df410d0ab8d4949546b6c4af26a>`__ 832 833* `Wireshark <https://bugs.wireshark.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=IN_PROGRESS&bug_status=INCOMPLETE&bug_status=RESOLVED&bug_status=VERIFIED&f0=OP&f1=OP&f2=product&f3=component&f4=alias&f5=short_desc&f7=content&f8=CP&f9=CP&j1=OR&o2=substring&o3=substring&o4=substring&o5=substring&o6=substring&o7=matches&order=bug_id%20DESC&query_format=advanced&v2=libfuzzer&v3=libfuzzer&v4=libfuzzer&v5=libfuzzer&v6=libfuzzer&v7=%22libfuzzer%22>`_ 834 835* `QEMU <https://researchcenter.paloaltonetworks.com/2017/09/unit42-palo-alto-networks-discovers-new-qemu-vulnerability/>`_ 836 837.. _pcre2: http://www.pcre.org/ 838.. _AFL: http://lcamtuf.coredump.cx/afl/ 839.. _Radamsa: https://github.com/aoh/radamsa 840.. _SanitizerCoverage: https://clang.llvm.org/docs/SanitizerCoverage.html 841.. _SanitizerCoverageTraceDataFlow: https://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow 842.. _AddressSanitizer: https://clang.llvm.org/docs/AddressSanitizer.html 843.. _LeakSanitizer: https://clang.llvm.org/docs/LeakSanitizer.html 844.. _Heartbleed: http://en.wikipedia.org/wiki/Heartbleed 845.. _FuzzerInterface.h: https://github.com/llvm/llvm-project/blob/main/compiler-rt/lib/fuzzer/FuzzerInterface.h 846.. _3.7.0: https://llvm.org/releases/3.7.0/docs/LibFuzzer.html 847.. _building Clang from trunk: https://clang.llvm.org/get_started.html 848.. _MemorySanitizer: https://clang.llvm.org/docs/MemorySanitizer.html 849.. _UndefinedBehaviorSanitizer: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html 850.. _`coverage counters`: https://clang.llvm.org/docs/SanitizerCoverage.html#coverage-counters 851.. _`value profile`: #value-profile 852.. _`caller-callee pairs`: https://clang.llvm.org/docs/SanitizerCoverage.html#caller-callee-coverage 853.. _BoringSSL: https://boringssl.googlesource.com/boringssl/ 854.. _Centipede: https://github.com/google/centipede 855 856