.. _module-pw_fuzzer-concepts:

===================
pw_fuzzer: Concepts
===================
.. pigweed-module-subpage::
   :name: pw_fuzzer

Fuzzing is an approach to testing software with generated data. Guided fuzzing
uses feedback from the code being tested, such as code coverage, to direct the
generation of additional inputs. This feedback loop typically has three steps
that it executes repeatedly:

#. The `fuzzing engine`_ generates a new `test input`_. The details of the
   test input depend on the engine. For example, `libFuzzer`_ generates
   sequences of bytes of arbitrary length, while `FuzzTest`_ generates
   parameters to match a function signature.

#. The `test input`_ is used to exercise the `fuzz target`_. This is targeted
   interface to the code being tested.

#. The code under test is monitored for feedback or any abnormal conditions.
   The feedback is commonly code coverage information generated by
   compiler-added `instrumentation`_.

The loop ends when a configured limit is reached, such as a specific duration or
number of iterations, or when an abnormal condition is detected. These can be
failed assertions, bug detections by `sanitizers`_, unhandled signals, etc.
When a loop terminates due to one of these errors, the fuzzer will typically
create a `reproducer`_ that developers can use to reproduce the fault.

.. image:: doc_resources/pw_fuzzer_coverage_guided.png
   :alt: Coverage Guided Fuzzing
   :align: left

.. Diagram created using Google Drawings:
   https://docs.google.com/drawings/d/1nGHCNp6iOiz_Qee9XCoIhMH01E_bB6tg3mipC-HJ0bo/edit

To learn more about how effective fuzzing can be or explore some of fuzzing's
"trophy lists", see `Why fuzz?`_.

.. inclusive-language: disable
.. _fuzz target: https://github.com/google/fuzzing/blob/master/docs/glossary.md#fuzz-target
.. _fuzzing engine: https://github.com/google/fuzzing/blob/master/docs/glossary.md#fuzzing-engine
.. _FuzzTest: https://github.com/google/fuzztest
.. _instrumentation: https://clang.llvm.org/docs/SanitizerCoverage.html
.. _libFuzzer: https://llvm.org/docs/LibFuzzer.html
.. _reproducer: https://github.com/google/fuzzing/blob/master/docs/glossary.md#reproducer
.. _sanitizers: https://github.com/google/fuzzing/blob/master/docs/glossary.md#sanitizer
.. _test input: https://github.com/google/fuzzing/blob/master/docs/glossary.md#test-input
.. _Why fuzz?: https://github.com/google/fuzzing/blob/master/docs/why-fuzz.md
.. inclusive-language: enable