From dcf42b48cde27b26079331ef8cb4fc78fde8d929 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Thu, 6 Nov 2025 09:53:40 -0600 Subject: [PATCH 1/2] Add a README with local development instructions --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0257502 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# Python Library Fuzzers + +This repository contains the fuzzer definitions, seed corpora, +and dictionaries used by [OSS-Fuzz](https://github.com/google/oss-fuzz) to fuzz-test Python standard library modules. + +## Getting Started + +Read the [getting started](https://google.github.io/oss-fuzz/getting-started/) +guide for OSS-Fuzz to learn about the [architecture of the fuzzer](https://google.github.io/oss-fuzz/architecture/) +and the necessary dependencies for local development (Docker, Python). + +## Architecture + +There are four components of the [OSS-Fuzz architecture](https://google.github.io/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](https://github.com/google/oss-fuzz/tree/master/projects/python3-libraries): + This component controls the OSS-Fuzz project definition, maintainers. +* [Fuzzer image configuration](https://github.com/google/oss-fuzz/tree/master/projects/python3-libraries): + `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 local development with OSS-Fuzz you need to fork and clone the +following repositories: + +* https://github.com/google/oss-fuzz +* https://github.com/hugovk/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: + +```terminal +$ 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: + +```terminal +$ 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. + +```diff +-RUN git clone https://github.com/python/cpython.git cpython +-RUN git clone --depth 1 https://github.com/hugovk/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/python-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. From 51b0679ad8e0e271e3d38218f8534876869a33f2 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Thu, 6 Nov 2025 16:17:41 +0000 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- README.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0257502..ab362a6 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ so that the fuzz target is executed by OSS-Fuzz. ## Local development -To do local development with OSS-Fuzz you need to fork and clone the +To do develop locally with OSS-Fuzz you need to fork and clone the following repositories: * https://github.com/google/oss-fuzz @@ -49,17 +49,15 @@ following repositories: After cloning forks of these repositories, move into the `oss-fuzz` repository and run the following to build the base and fuzzer image: -```terminal -$ python infra/helper.py build_image python3-libraries -$ python infra/helper.py build_fuzzers python3-libraries -``` +```sh +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: -```terminal -$ python infra/helper.py run_fuzzer python3-libraries fuzzer-email -``` +```sh +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.