Fuzz Introspector

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.

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.

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