commit	bd484933045d1314121f840b1b29910650803311	[log] [tgz]
author	Fabian Meumertzheim <fabian@meumertzhe.im>	Thu Jul 08 16:15:56 2021 +0200
committer	GitHub <noreply@github.com>	Thu Jul 08 10:15:56 2021 -0400
tree	ec00fabfbe6796c9ac65bd66818e35a919a76cd4
parent	2a2268c0ca63f402cbe9a6a7ea3577bf035c57db [diff]

tree: ec00fabfbe6796c9ac65bd66818e35a919a76cd4

README.md

Bazel Rules for Fuzz Tests

This repository contains Bazel Starlark extensions for defining fuzz tests in Bazel projects.

Fuzzing is an effective technique for uncovering security and stability bugs in software. Fuzzing works by invoking the code under test (e.g., a library API) with automatically generated data, and observing its execution to discover incorrect behavior, such as memory corruption or failed invariants. Read more here about fuzzing, additional examples, best practices, and other resources.

Features at a glance

Multiple fuzzing engines out of the box:
Multiple sanitizer configurations:
- Address Sanitizer
- Memory Sanitizer
Corpora and dictionaries.
Simple “bazel run/test” commands to build and run the fuzz tests.
- No need to understand the details of each fuzzing engine.
- No need to explicitly manage its corpus or dictionary.
Out-of-the-box OSS-Fuzz support that substantially simplifies the project integration effort.
Regression testing support, useful in continuous integration.
Customization options:
- Defining additional fuzzing engines
- Customizing the behavior of the fuzz test rule.

The rule library currently provides support for C++ and Java fuzz tests. Support for additional languages may be added in the future.

Contributions are welcome! Please read the contribution guidelines.

Getting started

This section will walk you through the steps to set up fuzzing in your Bazel project and write your first fuzz test. We assume Bazel is installed on your machine.

Prerequisites

The fuzz tests require a Clang compiler. The libFuzzer engine requires at least Clang 6.0. In addition, the Honggfuzz engine requires the libunwind-dev and libblocksruntime-dev packages:

$ sudo apt-get install clang libunwind-dev libblocksruntime-dev

Configuring the WORKSPACE

Add the following to your WORKSPACE file:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_fuzzing",
    sha256 = "94f25c7a18db0502ace26a3ef7d0a25fd7c195c4e9770ddd1b1ec718e8936091",
    strip_prefix = "rules_fuzzing-0.1.3",
    urls = ["https://github.com/bazelbuild/rules_fuzzing/archive/v0.1.3.zip"],
)

load("@rules_fuzzing//fuzzing:repositories.bzl", "rules_fuzzing_dependencies")

# Pass jazzer = True to rules_fuzzing_dependencies for Java fuzzing support.
rules_fuzzing_dependencies()

load("@rules_fuzzing//fuzzing:init.bzl", "rules_fuzzing_init")

rules_fuzzing_init()

# For Java fuzzing support, uncomment the following lines.
# load("@jazzer//:repositories.bzl", "jazzer_dependencies")
#
# jazzer_dependencies()
#
# load("@jazzer//:init.bzl", "jazzer_init")
#
# jazzer_init()

NOTE: Replace this snippet with the latest release instructions. To get the latest unreleased features, you may need to change the urls and sha256 attributes to fetch from HEAD. For more complex WORKSPACE files, you may also need to reconcile conflicting dependencies; read more in the Bazel documentation.

Configuring the .bazelrc file

It is best to create command shorthands for the fuzzing configurations you will use during development. In our case, let's create a configuration for libFuzzer + Address Sanitizer. In your .bazelrc file, add the following:

# Force the use of Clang for C++ builds.
build --action_env=CC=clang
build --action_env=CXX=clang++

# Define the --config=asan-libfuzzer configuration.
build:asan-libfuzzer --@rules_fuzzing//fuzzing:cc_engine=@rules_fuzzing//fuzzing/engines:libfuzzer
build:asan-libfuzzer --@rules_fuzzing//fuzzing:cc_engine_instrumentation=libfuzzer
build:asan-libfuzzer --@rules_fuzzing//fuzzing:cc_engine_sanitizer=asan

Examples for other combinations of fuzzing engine and sanitizer can be found in the project's .bazelrc.

Defining a C++ fuzz test

A C++ fuzz test is specified using a cc_fuzz_test rule. In the most basic form, a fuzz test requires a source file that implements the fuzz driver entry point.

Let's create a fuzz test that exhibits a buffer overflow. Create a fuzz_test.cc file in your workspace root, as follows:

#include <cstddef>
#include <cstdint>
#include <cstdio>

void TriggerBufferOverflow(const uint8_t *data, size_t size) {
  if (size >= 3 && data[0] == 'F' && data[1] == 'U' && data[2] == 'Z' &&
      data[size] == 'Z') {
    fprintf(stderr, "BUFFER OVERFLOW!\n");
  }
}

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
  TriggerBufferOverflow(data, size);
  return 0;
}

Let's now define its build target in the BUILD file:

load("@rules_fuzzing//fuzzing:cc_defs.bzl", "cc_fuzz_test")

cc_fuzz_test(
    name = "fuzz_test",
    srcs = ["fuzz_test.cc"],
)

Running the fuzz test

You can now build and run the fuzz test. For each fuzz test <name> defined, the framework automatically generates a launcher tool <name>_run that will build and run the fuzz test according to the configuration specified:

$ bazel run --config=asan-libfuzzer //:fuzz_test_run

Our libFuzzer test will start running and immediately discover the buffer overflow issue in the code:

INFO: Seed: 2957541205
INFO: Loaded 1 modules   (8 inline 8-bit counters): 8 [0x5aab10, 0x5aab18),
INFO: Loaded 1 PC tables (8 PCs): 8 [0x5aab18,0x5aab98),
INFO:      755 files found in /tmp/fuzzing/corpus
INFO:        0 files found in fuzz_test_corpus
INFO: -max_len is not provided; libFuzzer will not generate inputs larger than 35982 bytes
INFO: seed corpus: files: 755 min: 1b max: 35982b total: 252654b rss: 35Mb
#756    INITED cov: 6 ft: 7 corp: 4/10b exec/s: 0 rss: 47Mb
=================================================================
==724294==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x602000047a74 at pc 0x0000005512d9 bp 0x7fff3049d270 sp 0x7fff3049d268

The crash is saved under /tmp/fuzzing/artifacts and can be further inspected.

Defining a Java fuzz test

A Java fuzz test is specified using a java_fuzz_test rule. In the most basic form, a Java fuzz test consists of a single .java file with a class that defines a function public static fuzzerTestOneInput(byte[] input).

The Java equivalent of the C++ fuzz test above would look as follows:

package com.example;

public class JavaFuzzTest {
    public static void fuzzerTestOneInput(byte[] data) {
        if (data.length >= 3 && data[0] == 'F' && data[1] == 'U' &&
            data[2] == 'Z' && data[data.length] == 'Z') {
            throw new IllegalStateException(
                "ArrayIndexOutOfBoundException thrown above");
        }
    }
}

The corresponding build target looks very much like a regular java_binary:

load("@rules_fuzzing//fuzzing:java_defs.bzl", "java_fuzz_test")

java_fuzz_test(
    name = "JavaFuzzTest",
    srcs = ["JavaFuzzTest.java"],
    # target_class is not needed if using the Maven directory layout.
    target_class = "com.example.JavaFuzzTest",
)

As with the C++ fuzz tests, you can start the fuzzer (Jazzer) via

$ bazel run --config=jazzer //:JavaFuzzTest_run

Jazzer will quickly hit an ArrayIndexOutOfBoundsException:

INFO: Instrumented com.example.JavaFuzzTest (took 98 ms, size +96%)
INFO: Seed: 4010526312
INFO: Loaded 1 modules   (512 inline 8-bit counters): 512 [0x7fae23acd800, 0x7fae23acda00),
INFO: Loaded 1 PC tables (512 PCs): 512 [0x7fae226c9800,0x7fae226cb800),
INFO:       16 files found in /tmp/fuzzing/corpus
INFO:        0 files found in test/JavaFuzzTest_corpus
INFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes
INFO: seed corpus: files: 16 min: 1b max: 19b total: 210b rss: 199Mb
#18     INITED cov: 3 ft: 3 corp: 2/5b exec/s: 0 rss: 200Mb
...
#6665   REDUCE cov: 5 ft: 5 corp: 4/10b lim: 63 exec/s: 0 rss: 202Mb L: 3/3 MS: 3 ChangeBit-ChangeBit-EraseBytes-

== Java Exception: java.lang.ArrayIndexOutOfBoundsException: Index 3 out of bounds for length 3
    at com.example.JavaFuzzTest.fuzzerTestOneInput(JavaFuzzTest.java:5)

OSS-Fuzz integration

Once you wrote and tested the fuzz test, you should run it on continuous fuzzing infrastructure so it starts generating tests and finding new crashes in your code.

The C++ and Java fuzzing rules provide out-of-the-box support for OSS-Fuzz, free continuous fuzzing infrastructure from Google for open source projects. Read its Bazel project guide for detailed instructions.

Where to go from here?

Congratulations, you have built and run your first fuzz test with the Bazel rules!

Check out the examples/ directory, which showcases additional features. Read the User Guide for detailed usage instructions.