=========================================================
                        libFuzzer
=========================================================

Thin interface for LLVM/Clang libFuzzer, an in-process, coverage-guided,
evolutionary fuzzing engine.

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

Fuzzing is a type of automated testing which continuously manipulates inputs to
a program to find issues such as panics or bugs. These semi-random data mutations
can discover new code coverage that existing unit tests may miss, and uncover
edge case bugs which would otherwise go unnoticed. Since fuzzing can reach these
edge cases, fuzz testing is particularly valuable for finding security exploits
and vulnerabilities.

Read the `Documentation <https://planetis-m.github.io/libfuzzer/fuzztarget.html>`_

Clang Sanitizers
================

Sanitizers are compiler build-in error detectors with relatively small runtime
cost. Clang has:

- `AddressSanitizer <https://clang.llvm.org/docs/AddressSanitizer.html>`_ - use-after-free, double-free, ...
- `MemorySanitizer <https://clang.llvm.org/docs/MemorySanitizer.html>`_ - uninitialized reads
- `UndefinedBehaviourSanitizer <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_ - overflows, divide by zero, ...
- `ThreadSanitizer <https://clang.llvm.org/docs/ThreadSanitizer.html>`_ - data races

For more information watch the talk *Sanitize your C++ code* [4]_
There are demos at the `tests <tests/>`_ directory.

Example
=======

In 95% of cases all you need is to define the procedure ``testOneInput`` in your file.


.. code-block:: nim

  proc fuzzMe(data: openarray[byte]): bool =
    result = data.len >= 3 and
      data[0].char == 'F' and
      data[1].char == 'U' and
      data[2].char == 'Z' and
      data[3].char == 'Z' # :‑<

  proc initialize(): cint {.exportc: "LLVMFuzzerInitialize".} =
    {.emit: "N_CDECL(void, NimMain)(void); NimMain();".}

  proc testOneInput(data: ptr UncheckedArray[byte], len: int): cint {.
      exportc: "LLVMFuzzerTestOneInput", raises: [].} =
    result = 0
    discard fuzzMe(data.toOpenArray(0, len-1))


Compile with:

.. code-block::

  $ nim c --cc:clang -t:"-fsanitize=fuzzer,address,undefined" -l:"-fsanitize=fuzzer,address,undefined" -d:nosignalhandler --nomain:on -g tfuzz.nim


Coverage report
===============

Use `Clang Coverage <http://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_ to visualize and study your code coverage.

- Include the `standalone <libfuzzer/standalone.nim>`_ main procedure for fuzz targets.
- Follow the instructions given at the `test coverage <tests/tcov.nim>`_ example.
- When running the executable, pass as parameter a list of test units.

Structure-Aware Fuzzing
=======================

  But the lack of an input grammar can also result in inefficient fuzzing
  for complicated input types, where any traditional mutation (e.g. bit
  flipping) leads to an invalid input rejected by the target API in the
  early stage of parsing. With some additional effort, however, libFuzzer
  can be turned into a grammar-aware (i.e. structure-aware) fuzzing engine
  for a specific input type.

—*Structure-Aware Fuzzing with libFuzzer* [5]_

Take a look at the snappy compression `example <examples/compress/>`_
and ` <experiments/nfpsum.nim>`_

Installation
============

- Copy the files ``libfuzzer/fuzztarget.{nim,nims}``, ``libfuzzer/standalone.nim`` at your testing directory.
- Fill in the implementations of the exported procedures.
- Compile and run with an empty corpus directory as an argument.

Presentations
=============

.. [#] Jonathan Metzman `Fuzzing 101 <https://www.youtube.com/watch?v=NI2w6eT8p-E>`_
.. [#] Kostya Serebryany `Fuzz or lose... <https://www.youtube.com/watch?v=k-Cv8Q3zWNQ>`_
.. [#] Kostya Serebryany `Sanitize your C++ code <https://www.youtube.com/watch?v=V2_80g0eOMc>`_

Further Readings
================

.. [#] `libFuzzer Tutorial <https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md>`_
.. [#] `Structure-Aware Fuzzing with libFuzzer <https://github.com/google/fuzzing/blob/master/docs/structure-aware-fuzzing.md>`_
.. [#] `Efficient Fuzzing Guide <https://chromium.googlesource.com/chromium/src/+/refs/heads/main/testing/libfuzzer/efficient_fuzzing.md#efficient-fuzzing-guide>`_