Python Library Fuzzers

This repository contains the fuzzer definitions, seed corpora, and dictionaries used by OSS-Fuzz to fuzz-test Python standard library modules.

Getting Started

Read the getting started guide for OSS-Fuzz to learn about the architecture of the fuzzer and the necessary dependencies for local development (Docker, Python).

Architecture

There are four components of the OSS-Fuzz architecture hosted in this repository. Other components of the OSS-Fuzz architecture are hosted in other repositories.

Components that are hosted in this repository:

• Fuzz target definitions. These are typically .py files that are bootstrapped into binaries by fuzzer.cpp and Makefile.
• Fuzz seed corpora (corp-*): These files contain "starting points" byte sequences that the fuzzer can use to get results quicker than random bytes.
• Fuzz dictionaries (*.dict): These files contain possible byte sequences that the fuzzer can use when mutating input sequences.
• Coverage header file (python_coverage.h): This file is compiled with CPython so that line coverage is tracked over time as the fuzzer executes.

Components that are hosted elsewhere:

• Project configuration: This component controls the OSS-Fuzz project definition, maintainers.
• Fuzzer image configuration: Dockerfile and build.sh describe how the fuzzer image is built and what fuzz targets are executed by OSS-Fuzz.

When you create a new fuzz target don't forget to add the target to the fuzzer image so that the fuzz target is executed by OSS-Fuzz.

Local development

To do develop locally with OSS-Fuzz you need to fork and clone the following repositories:

• https://github.com/google/oss-fuzz
• https://github.com/python/library-fuzzers
• https://github.com/python/cpython

After cloning forks of these repositories, move into the oss-fuzz repository and run the following to build the base and fuzzer image:

python infra/helper.py build_image python3-libraries
python infra/helper.py build_fuzzers python3-libraries

Once this succeeds you have the proper toolset to locally develop fuzzers. You can run fuzz targets using the same helper script:

python infra/helper.py run_fuzzer python3-libraries fuzzer-email

This will run the fuzzer indefinitely, so stop the fuzzer whenever you've confirmed that it works. Now we need to point the oss-fuzz repository to our own forks to start local development.

Modify the projects/python3-libraries/Dockerfile file git clone lines to point to your own forks (example below using sethmlarson). It's recommended to use a branch on forks instead of main, so the example below also uses --branch fork-branch which you can change to your own branch depending on which repository you are modifying during development.

-RUN git clone https://github.com/python/cpython.git cpython
-RUN git clone --depth 1 https://github.com/python/library-fuzzers.git
+RUN git clone --depth 1 --branch fork-branch https://github.com/sethmlarson/cpython.git cpython
+RUN git clone --depth 1 --branch fork-branch https://github.com/sethmlarson/library-fuzzers.git

After this you can now re-run the python infra/helper.py commands to rebuild the image and fuzzers using the fork repositories instead. From here local development proceeds through pushing commits to your fork branches, rebuilding the image and fuzzers, and then running the fuzzers.