1.. _module-pw_fuzzer: 2 3========= 4pw_fuzzer 5========= 6.. pigweed-module:: 7 :name: pw_fuzzer 8 9Use state of the art tools to automatically find bugs in your C++ code with 5 10lines of code or less! 11 12 13.. code-block:: cpp 14 15 FUZZ_TEST(MyTestSuite, TestMyInterestingFunction) 16 .WithDomains(Arbitrary<size_t>(), AsciiString()); 17 18---------- 19Background 20---------- 21You've written some code. You've written unit tests for that code. The unit 22tests pass. But could there be bugs in inputs or code paths the unit tests do 23not cover? `Fuzzing`_ can help! 24 25However, fuzzing requires some complex interactions between compiler-added 26`instrumentation`_, `compiler runtimes`_, code under test, and the fuzzer code 27itself. And to be reliably useful, fuzzers need to be part of a continuous 28fuzzing infrastructure, adding even more complexity. 29 30See :ref:`module-pw_fuzzer-concepts` to learn more about the different 31components of a fuzzer and how they work together to discover hard-to-find bugs. 32 33------------ 34Our solution 35------------ 36``pw_fuzzer`` makes it easier to write, build, run, and deploy fuzzers. It 37provides convenient integration with two fuzzing `engines`_: 38 39* `libFuzzer`_, allowing integration of legacy fuzzers. 40 41* `FuzzTest`_, allowing easy creation of fuzzers from unit tests in around 5 42 lines of code. 43 44Additionally, it produces artifacts for continuous fuzzing infrastructures such 45as `ClusterFuzz`_ and `OSS-Fuzz`_, and provides the artifacts those systems need. 46 47--------------- 48Who this is for 49--------------- 50``pw_fuzzer`` is useful for authors of `wide range`_ of C++ code who have 51written unit tests and are interested in finding actionable bugs in their code. 52 53In particular, coverage-guided is effective for testing and finding bugs in code 54that: 55 56* Receives inputs from **untrusted sources** and must be secure. 57 58* Has **complex algorithms** with some equivalence, e.g. compress and 59 decompress, and must be correct. 60 61* Handles **high volumes** of inputs and/or unreliable dependencies and must be 62 stable. 63 64Fuzzing works best when code handles inputs deterministically, that is, given 65the same input it behaves the same way. Fuzzing will be less effective with code 66that modifies global state or has some randomness, e.g. depends on how multiple 67threads are scheduled. Simply put, good fuzzers typically resemble unit tests in 68terms of scope and isolation. 69 70-------------------- 71Is it right for you? 72-------------------- 73Currently, ``pw_fuzzer`` only provides support for fuzzers that: 74 75* Run on **host**. Sanitizer runtimes such as `AddressSanitizer`_ add 76 significant memory overhead and are not suitable for running on device. 77 Additionally, the currently supported engines assume the presence of certain 78 POSIX features. 79 80* Are built with **Clang**. The `instrumentation`_ used in fuzzing is added by 81 ``clang``. 82 83.. _module-pw_fuzzer-get-started: 84 85--------------- 86Getting started 87--------------- 88The first step in adding a fuzzer is to determine what fuzzing engine should you 89use. Pigweed currently supports two fuzzing engines: 90 91* **FuzzTest** is the recommended engine. It makes it easy to create fuzzers 92 from your existing unit tests, but it does requires additional third party 93 dependencies and at least C++17. See 94 :ref:`module-pw_fuzzer-guides-using_fuzztest` for details on how to set up a 95 project to use FuzzTest and on how to create and run fuzzers with it. 96 97* **libFuzzer** is a mature, proven engine. It is a part of LLVM and requires 98 code authors to implement a specific function, ``LLVMFuzzerTestOneInput``. See 99 :ref:`module-pw_fuzzer-guides-using_libfuzzer` for details on how to write 100 fuzzers with it. 101 102------- 103Roadmap 104------- 105``pw_fuzzer`` is under active development. There are a number of improvements we 106would like to add, including: 107 108* `b/282560789`_ - Document workflows for analyzing coverage and improving 109 fuzzers. 110 111* `b/280457542`_ - Add CMake support for FuzzTest. 112 113* `b/281138993`_ - Add a ``pw_cli`` plugin for fuzzing. 114 115* `b/281139237`_ - Develop OSS-Fuzz and ClusterFuzz workflow templates for 116 downtream projects. 117 118.. _b/282560789: https://issues.pigweed.dev/issues/282560789 119.. _b/280457542: https://issues.pigweed.dev/issues/280457542 120.. _b/281138993: https://issues.pigweed.dev/issues/281138993 121.. _b/281139237: https://issues.pigweed.dev/issues/281139237 122 123.. toctree:: 124 :maxdepth: 1 125 :hidden: 126 127 concepts 128 guides/fuzztest 129 guides/libfuzzer 130 guides/reproducing_oss_fuzz_bugs 131 132.. inclusive-language: disable 133.. _AddressSanitizer: https://github.com/google/sanitizers/wiki/AddressSanitizer 134.. _ClusterFuzz: https://github.com/google/clusterfuzz/ 135.. _compiler runtimes: https://compiler-rt.llvm.org/ 136.. _engines: https://github.com/google/fuzzing/blob/master/docs/glossary.md#fuzzing-engine 137.. _Fuzzing: https://github.com/google/fuzzing/blob/master/docs/intro-to-fuzzing.md 138.. _FuzzTest: https://github.com/google/fuzztest 139.. _instrumentation: https://clang.llvm.org/docs/SanitizerCoverage.html#instrumentation-points 140.. _libFuzzer: https://llvm.org/docs/LibFuzzer.html 141.. _OSS-Fuzz: https://github.com/google/oss-fuzz 142.. _wide range: https://github.com/google/fuzzing/blob/master/docs/why-fuzz.md 143.. inclusive-language: enable 144