FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Dockerized "Direct Execution of Fuzz Targets" · gitpython-developers/GitPython@fdce837 · GitHub

  1. gitpython-developers
  2. GitPython

Repository navigation

Commit fdce837

Browse files
DaveLak
committed
Dockerized "Direct Execution of Fuzz Targets"
Adds a Dockerfile to enable easily executing the fuzz targets directly inside a container environment instead of directly on a host machine. This addresses concerns raised in PR #1901 related to how `fuzz_tree.py` writes to the real `/tmp` directory of the file system it is executed on as part of setting up its own test fixtures, but also makes for an easier to use development workflow. See this related comment on PR #1901 for additional context: #1901 (comment)
1 parent 00bc707 commit fdce837

2 files changed

Lines changed: 59 additions & 6 deletions

File tree

‎fuzzing/README.md‎

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,7 @@ capabilities, jump into the "Getting Started" section below.
4444
### Setting Up Your Local Environment
4545

4646
Before contributing to fuzzing efforts, ensure Python and Docker are installed on your machine. Docker is required for
47-
running fuzzers in containers provided by OSS-Fuzz. [Install Docker](https://docs.docker.com/get-docker/) following the
48-
official guide if you do not already have it.
47+
running fuzzers in containers provided by OSS-Fuzz and for safely executing test files directly. [Install Docker](https://docs.docker.com/get-docker/) following the official guide if you do not already have it.
4948

5049
### Understanding Existing Fuzz Targets
5150

@@ -110,19 +109,51 @@ Includes scripts for building and integrating fuzz targets with OSS-Fuzz:
110109
- [OSS-Fuzz documentation on the build.sh](https://google.github.io/oss-fuzz/getting-started/new-project-guide/#buildsh)
111110
- [See GitPython's build.sh and Dockerfile in the OSS-Fuzz repository](https://github.com/google/oss-fuzz/tree/master/projects/gitpython)
112111

112+
### Local Development Helpers (`local-dev-helpers/`)
113+
114+
Contains tools to make local development tasks easier.
115+
See [the "Running Fuzzers Locally" section below](#running-fuzzers-locally) for further documentation and use cases related to files found here.
116+
113117
## Running Fuzzers Locally
114118

119+
> [!WARNING]
120+
> **Some fuzz targets in this repository write to the filesystem** during execution.
121+
> For that reason, it is strongly recommended to **always use Docker when executing fuzz targets**, even when it may be
122+
> possible to do so without it.
123+
>
124+
> Although [I/O operations such as writing to disk are not considered best practice](https://github.com/google/fuzzing/blob/master/docs/good-fuzz-target.md#io), the current implementation of at least one test requires it.
125+
> See [the "Setting Up Your Local Environment" section above](#setting-up-your-local-environment) if you do not already have Docker installed on your machine.
126+
>
127+
> PRs that replace disk I/O with in-memory alternatives are very much welcomed!
128+
115129
### Direct Execution of Fuzz Targets
116130

117-
For quick testing of changes, [Atheris][atheris-repo] makes it possible to execute a fuzz target directly:
131+
Directly executing fuzz targets allows for quick iteration and testing of changes which can be helpful during early
132+
development of new fuzz targets or for validating changes made to an existing test.
133+
The [Dockerfile](./local-dev-helpers/Dockerfile) located in the `local-dev-helpers/` subdirectory provides a lightweight
134+
container environment preconfigured with [Atheris][atheris-repo] that makes it easy to execute a fuzz target directly.
135+
136+
**From the root directory of your GitPython repository clone**:
118137

119-
1. Install Atheris following the [installation guide][atheris-repo] for your operating system.
120-
2. Execute a fuzz target, for example:
138+
1. Build the local development helper image:
121139

122140
```shell
123-
python fuzzing/fuzz-targets/fuzz_config.py
141+
docker build -f fuzzing/local-dev-helpers/Dockerfile -t gitpython-fuzzdev .
124142
```
125143

144+
2. Then execute a fuzz target inside the image, for example:
145+
146+
```shell
147+
docker run -it -v "$PWD":/src gitpython-fuzzdev python fuzzing/fuzz-targets/fuzz_config.py -atheris_runs=10000
148+
```
149+
150+
The above command executes [`fuzz_config.py`](./fuzz-targets/fuzz_config.py) and exits after `10000` runs, or earlier if
151+
the fuzzer finds an error.
152+
153+
Docker CLI's `-v` flag specifies a volume mount in Docker that maps the directory in which the command is run (which
154+
should be the root directory of your local GitPython clone) to a directory inside the container, so any modifications
155+
made between invocations will be reflected immediately without the need to rebuild the image each time.
156+
126157
### Running OSS-Fuzz Locally
127158

128159
This approach uses Docker images provided by OSS-Fuzz for building and running fuzz tests locally. It offers

‎fuzzing/local-dev-helpers/Dockerfile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# syntax=docker/dockerfile:1
2+
3+
# Use the same Python version as OSS-Fuzz to accidental incompatibilities in test code
4+
FROM python:3.8-slim
5+
6+
LABEL project="GitPython Fuzzing Local Dev Helper"
7+
8+
WORKDIR /src
9+
10+
COPY . .
11+
12+
# Update package managers, install necessary packages, and cleanup unnecessary files in a single RUN to keep the image smaller.
13+
RUN apt-get update && \
14+
apt-get install --no-install-recommends -y git && \
15+
python -m pip install --upgrade pip && \
16+
python -m pip install atheris && \
17+
python -m pip install -e . && \
18+
apt-get clean && \
19+
apt-get autoremove -y && \
20+
rm -rf /var/lib/apt/lists/* /root/.cache
21+
22+
CMD ["bash"]

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL