libFuzzer Integration Reference

Additional Sanitizer Configuration

MSan

Memory Sanitizer (MSan) in Chromium only supports Ubuntu Precise/Trusty and not Rodete. Thus, our reproduce tool cannot reproduce bugs found using MSan. You can try to reproduce them manually by using these instructions on how to run MSan-instrumented code in docker.

UBSan

By default, UBSan does not crash when undefined behavior is detected. To make it crash, the following option needs to be set in environment:

UBSAN_OPTIONS=halt_on_error=1 ./fuzzer <corpus_directory_or_single_testcase_path>

Other useful options are (also used by ClusterFuzz):

UBSAN_OPTIONS=symbolize=1:halt_on_error=1:print_stacktrace=1 ./fuzzer <corpus_directory_or_single_testcase_path>

Supported Platforms and Configurations

Builder configurations

The exact GN arguments that are used on our builders can be generated by running (from Chromium's src directory):

BuilderDescription
Linux ASantools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux ASan' out/libfuzzer
Linux ASan (x86)tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux32 ASan' out/libfuzzer
Linux ASan Debugtools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux ASan Debug' out/libfuzzer
Linux ASan Debug (x86)tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux32 ASan Debug' out/libfuzzer
Linux MSan*tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux MSan' out/libfuzzer
Linux UBSan*tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux UBSan' out/libfuzzer
Chrome OS ASantools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Chrome OS ASan' out/libfuzzer
Mac ASantools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Mac ASan' out/libfuzzer
Windows ASanpython tools\mb\mb.py gen -m chromium.fuzz -b "Libfuzzer Upload Windows ASan" out\libfuzzer
Linux ASan V8 ARM Simulator*tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux32 V8-ARM ASan' out/libfuzzer
Linux ASan V8 ARM64 Simulator*tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux V8-ARM64 ASan' out/libfuzzer
Linux ASan Debug V8 ARM Simulator*tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux32 V8-ARM ASan Debug' out/libfuzzer
Linux ASan Debug V8 ARM64 Simulator*tools/mb/mb.py gen -m chromium.fuzz -b 'Libfuzzer Upload Linux V8-ARM64 ASan Debug' out/libfuzzer

Linux

Linux is fully supported by libFuzzer and ClusterFuzz with following sanitizer configurations:

GN ArgumentDescription
is_asan=trueenables Address Sanitizer to catch problems like buffer overruns.
is_msan=trueenables Memory Sanitizer to catch problems like uninitialized reads. [*]
is_ubsan_security=trueenables Undefined Behavior Sanitizer to catch undefined behavior like integer overflow. [*]

Configuration example:

# With address sanitizer
gn gen out/libfuzzer '--args=use_libfuzzer=true is_asan=true' --check

Linux x86 (32-bit)

Fuzzing targets built for x86 can discover bugs that are not found by x64 builds. Linux x86 is supported by libFuzzer with is_asan configuration.

Configuration example:

gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true host_cpu=\"x86\" target_cpu=\"x86\"" --check

Chrome OS

Chrome OS is supported by libFuzzer with is_asan configuration.

Configuration example:

gn gen out/libfuzzer '--args=use_libfuzzer=true is_asan=true target_os="chromeos"' --check

To do a Chrome OS build on Linux (not just for libFuzzer), your .gclient file must be configured appropriately, see the Chrome OS build docs for more details.

Mac

Mac is supported by libFuzzer with is_asan configuration.

Configuration example:

gn gen out/libfuzzer '--args=use_libfuzzer=true is_asan=true mac_deployment_target="10.7"' --check

Windows

Windows is supported by libFuzzer with is_asan configuration.

Configuration example:

gn gen out/libfuzzer "--args=use_libfuzzer=true is_asan=true is_debug=false is_component_build=false" --check

On Windows you must use is_component_build=false as libFuzzer does not support component builds on Windows. If you are using is_asan=true then you must use is_debug=false as ASan does not support debug builds on Windows. You may also want to consider using symbol_level=1 which will reduce build size by reducing symbol level to the level necessary for libFuzzer (useful if building many fuzz targets).

ARM and ARM64

The V8 ARM and ARM64 simulators are supported by libFuzzer with is_asan configuration. Note that there is nothing special about these builds for non-V8 fuzz targets.

ARM configuration example:

gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true host_cpu=\"x86\" target_cpu=\"x86\" v8_target_cpu=\"arm\"" --check

ARM64 configuration example:

gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true target_cpu=\"x64\" v8_target_cpu=\"arm64\"" --check

fuzzer_test GN Template

Use fuzzer_test to define libFuzzer targets:

fuzzer_test("my_fuzzer") {
  ...
}

Following arguments are supported:

ArgumentDescription
sourcesrequired list of fuzzer test source files
depsfuzzer dependencies
additional_configsadditional GN configurations to be used for compilation
dicta dictionary file for the fuzzer
libfuzzer_optionsruntime options file for the fuzzer. See Fuzzer Runtime Options
seed_corpussingle directory containing test inputs, parsed recursively
seed_corpusesmultiple directories with the same purpose as seed_corpus
libsadditional libraries to link. Same as libs for gn targets.

Fuzzer Runtime Options

There are many different runtime options supported by libFuzzer. Options are passed as command line arguments:

./fuzzer [-flag1=val1 [-flag2=val2 ...] ] [dir1 [dir2 ...] ]

Most common flags are:

FlagDescription
max_lenMaximum length of test input.
timeoutTimeout of seconds. Units slower than this value will be reported as bugs.

Full list of options can be found at libFuzzer options page and by running the binary with -help=1.

To specify these options for ClusterFuzz, list all parameters in libfuzzer_options target attribute:

fuzzer_test("my_fuzzer") {
  ...
  libfuzzer_options = [
    # Suppress stdout and stderr output (not recommended, as it may silence useful info).
    "close_fd_mask=3",
  ]
}