blob: d7c44b19464091eed40cacb49cfd46b449af206c (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
# base-libfuzzer
> Abstract base image for libfuzzer builders.
Every project image supports multiple commands that can be invoked through docker after the image is built:
<pre>
docker run --rm -ti ossfuzz/<b><i>$project</i></b> <i><command></i> <i><arguments...></i>
</pre>
# Supported Commands
| Command | Description |
|---------|-------------|
| `compile` (default) | build all fuzz targets
| `reproduce <fuzzer_name> <fuzzer_options>` | build all fuzz targets and run specified one with testcase `/testcase` and given options.
| `run <fuzzer_name> <fuzzer_options...>` | build all fuzz targets and run specified one with given options.
| `/bin/bash` | drop into shell, execute `compile` script to start build.
# Examples
- *Reproduce using latest OSS-Fuzz build:*
<pre>
docker run --rm -ti -v <b><i>$testcase_file</i></b>:/testcase ossfuzz/<b><i>$project</i></b> reproduce <b><i>$fuzzer</i></b>
</pre>
- *Reproduce using local source checkout:*
<pre>
docker run --rm -ti -v <b><i>$local_source_checkout_dir</i></b>:/src/<b><i>$project</i></b> \
-v <b><i>$testcase_file</i></b>:/testcase ossfuzz/<b><i>$project</i></b> reproduce <b><i>$fuzzer</i></b>
</pre>
# Build Configuration
Build configuration is performed through following environment variables:
| Env Variable | Description
| ------------- | --------
| `$SANITIZER ("address")` | Specifies sanitizer configuration to use. `address` or `undefined`.
| `$SANITIZER_FLAGS` | Specify compiler sanitizer flags directly. Overrides `$SANITIZER`.
# Examples
- *building sqlite3 fuzzer with UBSan (`SANITIZER=undefined`):*
<pre>
docker run --rm -ti -e <i>SANITIZER</i>=<i>undefined</i> ossfuzz/sqlite3
</pre>
# Image Files Layout
| Location|Env| Description |
|---------| -------- | ---------- |
| `/out/` | `$OUT` | Directory to store build artifacts (fuzz targets, dictionaries, options files, seed corpus archives). |
| `/src/` | `$SRC` | Directory to checkout source files |
| `/work/`| `$WORK` | Directory for storing intermediate files |
| `/usr/lib/libfuzzer.a` | | Location of prebuilt libFuzzer library that needs to be linked into all fuzz targets (`-lfuzzer`). |
While files layout is fixed within a container, `$SRC`, `$OUT`, `$WORK` are
provided to be able to write retargetable scripts.
## Compiler Flags
You *must* use special compiler flags to build your project and fuzz targets.
These flags are provided in following environment variables:
| Env Variable | Description
| ------------- | --------
| `$CC` | The C compiler binary.
| `$CXX`, `$CCC` | The C++ compiler binary.
| `$CFLAGS` | C compiler flags.
| `$CXXFLAGS` | C++ compiler flags.
Most well-crafted build scripts will automatically use these variables. If not,
pass them manually to the build tool.
# Child Image Interface
## Sources
Child image has to checkout all sources that it needs to compile fuzz targets into
`$SRC` directory. When the image is executed, a directory could be mounted on top
of these with local checkouts using
`docker run -v $HOME/my_project:/src/my_project ...`.
## Other Required Files
Following files have to be added by child images:
| File Location | Description |
| ------------- | ----------- |
| `$SRC/build.sh` | build script to build the project and its fuzz targets |
|
