Skip to content

Commit 1b6e319

Browse files
author
Marge Bot
committed
Merge branch 'cm/add-oss-fuzz-docs' into 'main'
(#1070): Add documentation for the OSS-Fuzz integration Closes #1070 See merge request GNOME/librsvg!983
2 parents 2d621d3 + 9918a92 commit 1b6e319

File tree

5 files changed

+151
-2
lines changed

5 files changed

+151
-2
lines changed

‎devel-docs/compiling.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ Build-time dependencies
2929
-----------------------
3030

3131
..
32-
Please keep this in sync with devel_environment.rst in the _manual_setup section
32+
Please keep this in sync with devel_environment.rst in the _manual_setup section.
33+
Please also check to see if OSS-Fuzz dependencies need to be changed (see oss_fuzz.rst).
3334
3435
To compile librsvg, you need the following packages installed. The
3536
minimum version is listed here; you may use a newer version instead.

‎devel-docs/devel_environment.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,8 @@ Setting up dependencies manually
101101
--------------------------------
102102

103103
..
104-
Please keep this in sync with compiling.rst in the "Build-time dependencies" section
104+
Please keep this in sync with compiling.rst in the "Build-time dependencies" section.
105+
Please also check to see if OSS-Fuzz dependencies need to be changed (see oss_fuzz.rst).
105106
106107
To compile librsvg, you need the following packages installed. The
107108
minimum version is listed here; you may use a newer version instead.

‎devel-docs/index.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ Development guide for librsvg
4545

4646
releasing
4747
ci
48+
oss_fuzz
4849

4950
Welcome to the developer's guide for librsvg. This is for people who
5051
want to work on the development of librsvg itself, not for users of
@@ -110,13 +111,16 @@ Information for maintainers
110111

111112
- :doc:`releasing`
112113
- :doc:`ci`
114+
- :doc:`oss_fuzz`
113115

114116
Overview of the maintainer's workflow.
115117

116118
Marge-bot.
117119

118120
Documentation on the CI.
119121

122+
Documentation on the OSS-Fuzz integration and its maintenance.
123+
120124
References
121125
----------
122126

‎devel-docs/oss_fuzz.rst

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
OSS-Fuzz
2+
========
3+
4+
Platform overview
5+
-----------------
6+
7+
`OSS-Fuzz <https://google.github.io/oss-fuzz/>`_ is Google's free fuzzing platform for open source
8+
software.
9+
It runs librsvg's `fuzz targets <https://gitlab.gnome.org/GNOME/librsvg/-/tree/main/fuzz>`_ to help
10+
detect reliability issues.
11+
12+
Google provides public `build logs <https://oss-fuzz-build-logs.storage.googleapis.com/index.html#librsvg>`_
13+
and `fuzzing stats <https://introspector.oss-fuzz.com/project-profile?project=librsvg>`_, but most
14+
of the details about bug reports and fuzzed testcases require approved access.
15+
16+
Gaining access
17+
^^^^^^^^^^^^^^
18+
19+
The configuration files for the OSS-Fuzz integration can be found in the
20+
`OSS-Fuzz repository <https://github.com/google/oss-fuzz/tree/master/projects/librsvg>`_.
21+
The ``project.yaml`` file controls who has access to bug reports and testcases.
22+
Ping the maintainer if you'd like to be added to the list (note: a Google account is required for
23+
access).
24+
25+
Fuzzing progress
26+
----------------
27+
28+
Once you have access to OSS-Fuzz, you can log in to https://oss-fuzz.com/ with your Google account
29+
to see a dashboard of librsvg's fuzzing progress.
30+
31+
Testcases
32+
^^^^^^^^^
33+
34+
The dashboard contains a link to a `testcases page <https://oss-fuzz.com/testcases?project=librsvg&open=yes>`_
35+
that lists all testcases that currently trigger a bug in librsvg.
36+
37+
Every testcase has a dedicated page with links to view and download a minimized testcase for
38+
reproducing the failure.
39+
Each testcase page also contains a stacktrace for the failure and stats about how often the failure
40+
is encountered while fuzzing.
41+
42+
Reproducing a failure
43+
"""""""""""""""""""""
44+
45+
You can download a minimized testcase and run it with a local fuzz target to debug a failure on your
46+
machine.
47+
For example, to reproduce a failure with the ``render_document`` fuzz target, you can run a command
48+
like this: ``cargo fuzz run render_document minimized.svg``
49+
50+
Individual fuzz targets can also be run inside of a debugger for further debugging information:
51+
52+
.. code:: bash
53+
54+
FUZZ_TARGET=$(find ./target/*/release/ -type f -name render_document)
55+
gdb --args "$FUZZ_TARGET" minimized.svg
56+
57+
58+
Code coverage
59+
^^^^^^^^^^^^^
60+
61+
The dashboard also links to code coverage data for individual fuzz targets and combined code
62+
coverage data for all targets (click on the "TOTAL COVERAGE" link for the combined data).
63+
64+
The combined coverage data is helpful for identifying coverage gaps, insufficient corpus data, and
65+
potential candidates for future fuzz targets.
66+
67+
Bug reports
68+
^^^^^^^^^^^
69+
70+
Bug reports for new failures are automatically filed in the OSS-Fuzz bug tracker with a
71+
`librsvg label <https://bugs.chromium.org/p/oss-fuzz/issues/list?q=label:Proj-librsvg>`_.
72+
Make sure you are logged in to view all existing issues.
73+
74+
Build maintenance
75+
-----------------
76+
77+
Google runs compiled fuzz targets on Google Compute Engine VMs.
78+
This architecture requires each project to provide a ``Dockerfile`` and ``build.sh`` script to
79+
download code, configure dependencies, compile fuzz targets, and package any corpus files.
80+
81+
librsvg's build files can be found in the
82+
`OSS-Fuzz repo <https://github.com/google/oss-fuzz/blob/master/projects/librsvg/>`_.
83+
84+
If dependencies change or if new fuzz targets are added, then you may need to modify the build files
85+
and build a new Docker image for OSS-Fuzz.
86+
87+
Building an image
88+
^^^^^^^^^^^^^^^^^
89+
90+
Use the following commands to build librsvg's OSS-Fuzz image and fuzz targets:
91+
92+
.. code:: bash
93+
94+
git clone https://github.com/google/oss-fuzz.git
95+
cd oss-fuzz
96+
97+
python infra/helper.py build_image librsvg
98+
python infra/helper.py build_fuzzers librsvg
99+
100+
Any changes you make to the build files must be submitted as pull requests to the OSS-Fuzz repo.
101+
102+
Debugging build failures
103+
""""""""""""""""""""""""
104+
105+
You can debug build failures during the ``build_fuzzers`` stage by creating a container and manually
106+
running the ``compile`` command:
107+
108+
.. code:: bash
109+
110+
# Create a container for building fuzz targets
111+
python infra/helper.py shell librsvg
112+
113+
# Run this command inside the container to build the fuzz targets
114+
compile
115+
116+
This approach is faster than re-running the ``build_fuzzers`` command, which recompiles everything
117+
from scratch each time the command is run.
118+
119+
The ``build.sh`` script will be located at ``/src/build.sh`` inside the container.
120+
121+
Quick links
122+
-----------
123+
124+
* `OSS-Fuzz dashboard <https://oss-fuzz.com/>`_
125+
* `OSS-Fuzz configuration files and build scripts for librsvg <https://github.com/google/oss-fuzz/tree/master/projects/librsvg>`_
126+
* `All bugs found by OSS-Fuzz in librsvg <https://bugs.chromium.org/p/oss-fuzz/issues/list?q=label:Proj-librsvg>`_
127+
* `Google's OSS-Fuzz documentation <https://google.github.io/oss-fuzz/>`_

‎fuzz/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,20 @@ cargo fuzz run render_document -- -seed_inputs=corpus1.svg,corpus2.svg,corpus3.s
1515

1616
To get a list of available options, `cargo fuzz run render_document -- -help=1`
1717

18+
19+
## Reproducing a failure
20+
You can reproduce a failure by supplying a path to the fuzzed data:
21+
22+
`cargo fuzz run render_document fuzzed.svg`
23+
24+
Fuzz targets can also be run inside of a debugger for further debugging information:
25+
26+
```
27+
FUZZ_TARGET=$(find ./target/*/release/ -type f -name render_document)
28+
gdb --args "$FUZZ_TARGET" fuzzed.svg
29+
```
30+
31+
## Related documents
1832
See `../afl-fuzz/README.md` for a to-do list for people who want to help with fuzzing.
33+
34+
See `../devel-docs/oss_fuzz.rst` for an overview of librsvg's integration with OSS-Fuzz.

0 commit comments

Comments
 (0)