oss-fuzz/infra/base-images/base-libfuzzer

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:

docker run --rm -ti ossfuzz/$project <command> <arguments...>

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:

docker run --rm -ti -v $testcase_file:/testcase ossfuzz/$project reproduce $fuzzer

• Reproduce using local source checkout:

    docker run --rm -ti -v $local_source_checkout_dir:/src/$project \
                        -v $testcase_file:/testcase ossfuzz/$project reproduce $fuzzer
    

Build Configuration

A single build image can build same set of fuzzers in many configurations. The configuration is picked through one or more environment variables.

Sanitizer Configuration

Fuzzers are usually built with some sanitizer enabled.

Env Variable	Description
$SANITIZER ("address")	Specifies predefined sanitizer configuration to use. address or undefined.
$SANITIZER_FLAGS	Specify compiler sanitizer flags directly. Overrides $SANITIZER.

Flag values for predefined configurations are specified in Dockerfile. You can specify which configurations to run your fuzzers with in project.yaml file (sqlite3):

sanitizers:
  - address
  - undefined

Other Configuration

Env Variable	Description
$COVERAGE_FLAGS	Specify compiler flags to use for fuzzer feedback coverage.
$BUILD_UID	User id to use while building fuzzers.

Examples

• building sqlite3 fuzzer with UBSan (SANITIZER=undefined):

docker run --rm -ti -e SANITIZER=undefined ossfuzz/sqlite3

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/libFuzzingEngine.a	$LIB_FUZZING_ENGINE	Location of prebuilt fuzzing engine library (e.g. libFuzzer ) that needs to be linked with all fuzz targets (-lFuzzingEngine).

While files layout is fixed within a container, the environment variables 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