| .. _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 |