1.. _module-pw_fuzzer-guides-reproducing_oss_fuzz_bugs: 2 3============================================= 4pw_fuzzer: Using OSS-Fuzz 5============================================= 6.. pigweed-module-subpage:: 7 :name: pw_fuzzer 8 9.. TODO: b/281139237 - Update with better instructions for downstream projects. 10 11Core Pigweed is integrated with `OSS-Fuzz`_, a continuous fuzzing infrastructure 12for open source software. Fuzzers listed in in ``pw_test_groups`` will 13automatically start being run within a day or so of appearing in the git 14repository. 15 16------------------------- 17Reproducing Bugs Directly 18------------------------- 19 20Bugs produced by OSS-Fuzz can be found in its `Monorail instance`_. These bugs 21include: 22 23* A detailed report, including a symbolized backtrace. 24* A revision range indicating when the bug has been detected. 25* A minimized testcase, which is a fuzzer input that can be used to reproduce 26 the bug. 27 28To reproduce a bug: 29 30#. Build the fuzzers in a local source checkout using one of the 31 :ref:`module-pw_fuzzer-guides`. 32#. Download the minimized testcase from the OSS-Fuzz bug. 33#. Run the fuzzer with the testcase as an argument. 34 35For example, if the testcase is saved as ``~/Downloads/testcase`` 36and the fuzzer is the same as in the examples above, you could run: 37 38.. code-block:: 39 40 $ ./out/host/obj/pw_fuzzer/toy_fuzzer ~/Downloads/testcase 41 42As noted in OSS-Fuzz's documentation on `timeouts and OOMs`_, you may want to 43add a `-timeout=25` or `-rss_limit_mb=2560` argument to reproduce timeouts or 44OOMs, respectively. 45 46-------------------------------- 47Using a OSS-Fuzz Docker Instance 48-------------------------------- 49 50If Pigweed fails to build for OSS-Fuzz, or if a fuzzer only triggers a bug in 51OSS-Fuzz and not when run directly, you may want to recreate the OSS-Fuzz 52environment locally using Docker. You can do so using OSS-Fuzz's documentation 53on `reproducing`_ issues. 54 55In particular, you can recreate the OSS-Fuzz environment using: 56 57.. code-block:: 58 59 $ python infra/helper.py pull_images 60 $ python infra/helper.py build_image pigweed 61 $ python infra/helper.py build_fuzzers --sanitizer <address/undefined> pigweed 62 63Using a Local Source Checkout 64============================= 65 66When addressing build failures or issues related to specific fuzzers, it is 67very useful to have an OSS-Fuzz instance use a local source checkout with edits 68rather than pull from a public repo. Unfortunately, the normal workflow for 69`using a local source checkout`_ **does not work** for Pigweed. Pigweed provides 70an embedded development environment along with source code for individual 71modules, and this environment includes checks that conflict with the way 72OSS-Fuzz tries to remap and change ownership of the source code. 73 74To work around this, a helper script is provided as part of the ``pigweed`` 75project on OSS-Fuzz that wraps the usual ``infra/helper.py``. For commands that 76take a local source path, the wrapper instead provides a ``--local`` flag. This 77flag will use the ``PW_ROOT`` environment variable to find the source checkout, 78and attempt to mount it in the correct location and set specific environment 79variables in order to present a working development environment to the OSS-Fuzz 80instance. Also, the ``pigweed`` project is implied: 81 82.. code-block:: 83 84 $ python project/pigweed/helper.py build_fuzzers --sanitizer <sanitizer> --local 85 86The ``sanitizer`` value is one of the usual values based to Clang via 87``-fsanitize=...``, e.g. "address" or "undefined". 88 89After building with a local source checkout, you can verify an issue previously 90found by a fuzzer is fixed: 91 92.. code-block:: 93 94 $ python project/pigweed/helper.py reproduce <fuzzer> ~/Downloads/testcase 95 96For libFuzzer-based fuzzers, ``fuzzer`` will be of the form 97``{module_name}_{fuzzer_name}``, e.g. ``pw_protobuf_encoder_fuzzer``. 98 99For FuzzTest-based fuzzers, ``fuzzer`` will additionally include the test case 100and be of the form ``{module_name}_{fuzzer_name}@{test_case}``, e.g. 101``[email protected]``. 102 103The helper script attempts to restore proper ownership of the source checkout to 104the current user on completion. This can also be triggered manually using: 105 106.. code-block:: 107 108 $ python project/pigweed/helper.py reset_local 109 110 111.. _Monorail instance: https://bugs.chromium.org/p/oss-fuzz/issues/list?q=pigweed 112.. _OSS-Fuzz: https://github.com/google/oss-fuzz 113.. _reproducing: https://google.github.io/oss-fuzz/advanced-topics/reproducing/ 114.. _timeouts and OOMs: https://google.github.io/oss-fuzz/faq/#how-do-you-handle-timeouts-and-ooms 115.. _using a local source checkout: https://google.github.io/oss-fuzz/advanced-topics/reproducing/#reproduce-using-local-source-checkout 116