<commit_before>=======================================================
libFuzzer – a library for coverage-guided fuzz testing.
=======================================================
.. contents::
   :local:
   :depth: 1

Introduction
============

LibFuzzer is in-process, coverage-guided, evolutionary fuzzing engine.

LibFuzzer is linked with the library under test, and feeds fuzzed inputs to the
library via a specific fuzzing entrypoint (aka "target function"); the fuzzer
then tracks which areas of the code are reached, and generates mutations on the
corpus of input data in order to maximize the code coverage.
The code coverage
information for libFuzzer is provided by LLVM's SanitizerCoverage_
instrumentation.

Contact: libfuzzer(#)googlegroups.com

Versions
========

LibFuzzer is under active development so you will need the current
(or at least a very recent) version of the Clang compiler.

(If `building Clang from trunk`_ is too time-consuming or difficult, then
the Clang binaries that the Chromium developers build are likely to be
fairly recent:

.. code-block:: console

  mkdir TMP_CLANG
  cd TMP_CLANG
  git clone https://chromium.googlesource.com/chromium/src/tools/clang
  cd ..
  TMP_CLANG/clang/scripts/update.py

This installs the Clang binary as
``./third_party/llvm-build/Release+Asserts/bin/clang``)

The libFuzzer code resides in the LLVM repository, and requires a recent Clang
compiler to build (and is used to `fuzz various parts of LLVM itself`_).
However the fuzzer itself does not (and should not) depend on any part of LLVM
infrastructure and can be used for other projects without requiring the rest
of LLVM.


Getting Started
===============

.. contents::
   :local:
   :depth: 1

Fuzz Target
-----------

The first step in using libFuzzer on a library is to implement a
*fuzz target* -- a function that accepts an array of bytes and
does something interesting with these bytes using the API under test.
Like this:

.. code-block:: c++

  // fuzz_target.cc
  extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
    DoSomethingInterestingWithMyAPI(Data, Size);
    return 0;  // Non-zero return values are reserved for future use.
  }

Note that this fuzz target does not depend on libFuzzer in any way
ans so it is possible and even desirable to use it with other fuzzing engines
e.g. AFL_ and/or Radamsa_.

Some important things to remember about fuzz targets:

* The fuzzing engine will execute the fuzz target many times with different inputs in the same process.
* It must tolerate any kind of input (empty, huge, malformed, etc).
* It must not `exit()` on any input.
* It may use threads but ideally all threads should be joined at the end of the function.
* It must be as deterministic as possible. Non-determinism (e.g. random decisions not based on the input byte) will make fuzzing inefficient.
* It must be fast. Try avoiding cubic or greater complexity.
* Ideally, it should not modify any global state (although that's not strict).


Building
--------

Next, build the libFuzzer library as a static archive, without any sanitizer
options. Note that the libFuzzer library contains the ``main()`` function:

.. code-block:: console

  svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer  # or git clone https://chromium.googlesource.com/chromium/llvm-project/llvm/lib/Fuzzer
  ./Fuzzer/build.sh  # Produces libFuzzer.a

Then build the fuzzing target function and the library under test using
the SanitizerCoverage_ option, which instruments the code so that the fuzzer
can retrieve code coverage information (to guide the fuzzing).  Linking with
the libFuzzer code then gives a fuzzer executable.

You should also enable one or more of the *sanitizers*, which help to expose
latent bugs by making incorrect behavior generate errors at runtime:

 - AddressSanitizer_ (ASAN) detects memory access errors. Use `-fsanitize=address`.
 - UndefinedBehaviorSanitizer_ (UBSAN) detects the use of various features of C/C++ that are explicitly
   listed as resulting in undefined behavior.  Use `-fsanitize=undefined -fno-sanitize-recover=undefined`
   or any individual UBSAN check, e.g.  `-fsanitize=signed-integer-overflow -fno-sanitize-recover=undefined`.
   You may combine ASAN and UBSAN in one build.
 - MemorySanitizer_ (MSAN) detects uninitialized reads: code whose behavior relies on memory
   contents that have not been initialized to a specific value. Use `-fsanitize=memory`.<commit_msg>[libFuzzer] minor docs update<commit_after>=======================================================
libFuzzer – a library for coverage-guided fuzz testing.
=======================================================
.. contents::
   :local:
   :depth: 1

Introduction
============

LibFuzzer is in-process, coverage-guided, evolutionary fuzzing engine.

LibFuzzer is linked with the library under test, and feeds fuzzed inputs to the
library via a specific fuzzing entrypoint (aka "target function"); the fuzzer
then tracks which areas of the code are reached, and generates mutations on the
corpus of input data in order to maximize the code coverage.
The code coverage
information for libFuzzer is provided by LLVM's SanitizerCoverage_
instrumentation.

Contact: libfuzzer(#)googlegroups.com

Versions
========

LibFuzzer is under active development so you will need the current
(or at least a very recent) version of the Clang compiler.

(If `building Clang from trunk`_ is too time-consuming or difficult, then
the Clang binaries that the Chromium developers build are likely to be
fairly recent:

.. code-block:: console

  mkdir TMP_CLANG
  cd TMP_CLANG
  git clone https://chromium.googlesource.com/chromium/src/tools/clang
  cd ..
  TMP_CLANG/clang/scripts/update.py

This installs the Clang binary as
``./third_party/llvm-build/Release+Asserts/bin/clang``)

The libFuzzer code resides in the LLVM repository, and requires a recent Clang
compiler to build (and is used to `fuzz various parts of LLVM itself`_).
However the fuzzer itself does not (and should not) depend on any part of LLVM
infrastructure and can be used for other projects without requiring the rest
of LLVM.


Getting Started
===============

.. contents::
   :local:
   :depth: 1

Fuzz Target
-----------

The first step in using libFuzzer on a library is to implement a
*fuzz target* -- a function that accepts an array of bytes and
does something interesting with these bytes using the API under test.
Like this:

.. code-block:: c++

  // fuzz_target.cc
  extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
    DoSomethingInterestingWithMyAPI(Data, Size);
    return 0;  // Non-zero return values are reserved for future use.
  }

Note that this fuzz target does not depend on libFuzzer in any way
and so it is possible and even desirable to use it with other fuzzing engines
e.g. AFL_ and/or Radamsa_.

Some important things to remember about fuzz targets:

* The fuzzing engine will execute the fuzz target many times with different inputs in the same process.
* It must tolerate any kind of input (empty, huge, malformed, etc).
* It must not `exit()` on any input.
* It may use threads but ideally all threads should be joined at the end of the function.
* It must be as deterministic as possible. Non-determinism (e.g. random decisions not based on the input bytes) will make fuzzing inefficient.
* It must be fast. Try avoiding cubic or greater complexity, logging, or excessive memory consumption.
* Ideally, it should not modify any global state (although that's not strict).


Building
--------

Next, build the libFuzzer library as a static archive, without any sanitizer
options. Note that the libFuzzer library contains the ``main()`` function:

.. code-block:: console

  svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer  # or git clone https://chromium.googlesource.com/chromium/llvm-project/llvm/lib/Fuzzer
  ./Fuzzer/build.sh  # Produces libFuzzer.a

Then build the fuzzing target function and the library under test using
the SanitizerCoverage_ option, which instruments the code so that the fuzzer
can retrieve code coverage information (to guide the fuzzing).  Linking with
the libFuzzer code then gives a fuzzer executable.

You should also enable one or more of the *sanitizers*, which help to expose
latent bugs by making incorrect behavior generate errors at runtime:

 - AddressSanitizer_ (ASAN) detects memory access errors. Use `-fsanitize=address`.
 - UndefinedBehaviorSanitizer_ (UBSAN) detects the use of various features of C/C++ that are explicitly
   listed as resulting in undefined behavior.  Use `-fsanitize=undefined -fno-sanitize-recover=undefined`
   or any individual UBSAN check, e.g.  `-fsanitize=signed-integer-overflow -fno-sanitize-recover=undefined`.
   You may combine ASAN and UBSAN in one build.
 - MemorySanitizer_ (MSAN) detects uninitialized reads: code whose behavior relies on memory
   contents that have not been initialized to a specific value. Use `-fsanitize=memory`.
{'fraction_non_alphanumeric': 0.09610476084785262, 'fraction_numerical': 0.0008878037953612252, 'mean_word_length': 4.32309509746013, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5351183', 'n_tokens_mistral': 2591, 'n_tokens_neox': 2482, 'n_words': 1167}