5.5 KiB
| layout | title | parent | nav_order | permalink |
|---|---|---|---|---|
| default | Fuzz Introspector | Advanced topics | 2 | /advanced-topics/fuzz-introspector/ |
Fuzz Introspector
{: .no_toc}
For projects written in C/C++, Python and Java you can generate Fuzz Introspector reports to help guide the development of your fuzzing suite. These reports help to extract details about the fuzzing setup of your project with the goal of making it easier to improve the fuzzing set up. The Fuzz Introspector reports are generated automatically and uploaded to the cloud like code coverage reports, and you can also generate them locally using the OSS-Fuzz helper script.
- TOC {:toc}
Fuzz Introspector overview
As soon as your project is run with ClusterFuzz (<1 day), you can view the Fuzz Introspector report for your project. Fuzz Introspector helps you understand your fuzzers' performance and identify any potential blockers. It provides individual and aggregated fuzzer reachability and coverage reports. You can monitor each fuzzer's static reachability potential and compare it against dynamic coverage and identify any potential bottlenecks. Fuzz Introspector can offer suggestions on increasing coverage by adding new fuzz targets or modify existing ones. Fuzz Introspector reports can be viewed from the OSS-Fuzz homepage or through this index.
Tutorials and guides
The reports generated can be a lot to digest when first viewing them. The Fuzz Introspector documentation provides various user guides and tutorials rooted in OSS-Fuzz projects, which is a useful reference on how to make use of the reports.
For ideas on how to use Fuzz Introspector, see user guides which includes sections e.g.
- Quickly extract overview of a given project
- Get ideas for new fuzz targets
- Comparing introspector reports
Run Fuzz Introspector locally
To generate a Fuzz Introspector report locally use infra/helper.py and the
introspector command. Fuzz Introspector relies on code coverage to
analyze a given project, and this means we need to extract code coverage in the
Fuzz Introspector process. We can do this in two ways. First, by running the fuzzers
for a given amount of time, and, second, by generating code coverage using the public
corpus available from OSS-Fuzz.
Generate reports by running fuzzers for X seconds
The following command will generate a Fuzz Introspector report for the libdwarf project
and will extract code coverage based on a corpus created from running the fuzzers for 30
seconds.
$ python3 infra/helper.py introspector libdwarf --seconds=30
If the above command was succesful, you should see output along the lines of:
INFO:root:To browse the report, run: python3 -m http.server 8008 --directory /home/my_user/oss-fuzz/build/out/libdwarf/introspector-report/inspector and navigate to localhost:8008/fuzz_report.html in your browser
The above output gives you directions on how to start a simple webserver using
python3 -m http.server, which you can use to view the Fuzz Introspector report.
Generate reports by using public corpora
The following command will generate a Fuzz Introspector report for the libdwarf project
and will extract code coverage based on a corpus created from running the fuzzers for 30
seconds.
$ python3 infra/helper.py introspector libdwarf --public-corpora
Assuming the above command is succesful you can view the report using python3 -m http.server
following the example described above.
Differences in build tooling
There are some differences in build environment for Fuzz Introspector builds in comparison to e.g. ASAN or code coverage builds. The reason is that Fuzz Introspector relies on certain compile-time tools to do its analysis. This compile time tooling differs between languages, namely:
- For C/C++, Fuzz Introspector relies on LLVM LTO and LLVM Gold
- For Python, Fuzz Introspector relies on a modified PyCG
- For Java, Fuzz Introspector relies on Soot
The consequence of this is your project must be compatible with these projects.
PyCG and Soot have not shown to be a blocker for many projects, however, experience
has shown that sometimes a project's build needs modification in order to compile
with LLVM LTO. The easiest way to test if your project works with LLVM is checking
whether your project can compile with the flags -flto -fuse-ld=gold and using
the gold linker. OSS-Fuzz automatically sets these flags and linker options when
using infra/helper.py to build your project with --sanitizer=introspector, e.g.
python3 infra/helper.py build_fuzzers --sanitizer=introspector PROJ_NAME