Link Search Menu Expand Document

Integrating a Rust project


The process of integrating a project written in Rust with ClusterFuzzLite is very similar to the general Build integration process. The key specifics of integrating a Rust project are outlined below.

cargo-fuzz support

Rust integration with ClusterFuzzLite is expected to use cargo fuzz to build fuzzers. The cargo fuzz tool will build code with required compiler flags as well as link to the correct libFuzzer. Note that using cargo fuzz also makes it quite easy to run the fuzzers locally yourself if you get a failing test case!

Project files

First you’ll want to follow the setup instructions for cargo fuzz itself. Afterwards your project should have:

  • A top-level fuzz directory.
  • A fuzz/Cargo.toml manifest which pulls in necessary dependencies to fuzz.
  • Some fuzz/fuzz_targets/*.rs files which are the fuzz targets that will be compiled and run.

Note that you can customize this layout as well, but you’ll need to edit some the scripts below.

project.yaml

The language attribute must be specified.

language: rust

The only supported sanitizer is address.

Dockerfile

The Dockerfile should start by FROM gcr.io/oss-fuzz-base/base-builder-rust

The builder image has the latest nightly release of Rust as well as cargo fuzz pre-installed and in PATH. In the Dockerfile for your project all you’ll need to do is fetch the latest copy of your code and install any system dependencies necessary to build your project.

build.sh

Here it’s expected that you’ll build the fuzz targets for your project and then copy the final binaries into the output directory. Example:

cd $SRC/json
cargo fuzz build -O
cp fuzz/target/x86_64-unknown-linux-gnu/release/from_slice $OUT/

Note that you likely want to pass the -O flag to cargo fuzz build which builds fuzzers in release mode. You may also want to pass the --debug-assertions flag to enable more checks while fuzzing. In this example the from_slice binary is the fuzz target.

With some bash-fu you can also automatically copy over all fuzz targets into the output directory so when you add a fuzz target to your project it’s automatically integrated into OSS-Fuzz:

FUZZ_TARGET_OUTPUT_DIR=target/x86_64-unknown-linux-gnu/release
for f in fuzz/fuzz_targets/*.rs
do
    FUZZ_TARGET_NAME=$(basename ${f%.*})
    cp $FUZZ_TARGET_OUTPUT_DIR/$FUZZ_TARGET_NAME $OUT/
done

Writing fuzzers using a test-style strategy

In Rust you will often have tests written in a way so they are only compiled into the final binary when build in test-mode. This is, achieved by wrapping your test code in cfg(test), e.g.

#[cfg(test)]
mod tests {
    use super::*;
    
    ...

Cargo-fuzz automatically enables the fuzzing feature, which means you can follow a similar strategy to writing fuzzers as you do when writing tests. Specifically, you can create modules wrapped in the fuzzing feature:

#[cfg(fuzzing)]
pub mod fuzz_logic {
    use super::*;

    ...

and then call the logic within fuzz_logic from your fuzzer.

Furthermore, within your .toml files, you can then specify fuzzing-specific depedencies by wrapping them as follows:

[target.'cfg(fuzzing)'.dependencies]

similar to how you wrap test-dependencies as follows:

[dev-dependencies]

Finally, you can also combine the testing logic you have and the fuzz logic. This can be achieved simply by using

#[cfg(any(test, fuzzing))]