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