Skip to main content

Fuzz Container

CI Fuzz and CI Sense use so called Fuzz Container to package and distribute fuzz tests and describe their execution. It is the primary way of executing fuzz tests in CI Sense and replaces the previously used fuzzing bundles.

This article describes the Fuzz Container format on a high level and details requirements to run Fuzz Containers with CI Sense.

Under the hood​

At it's core a Fuzz Container is a Docker image with a defined execution behaviour. This allows us to leverage existing tooling such as storing fuzz container images in container registries and executing fuzz tests in a reproducible manner accross machines with different architectures.

Included in a typical Fuzz Container image are

  • compiled fuzz tests (e.g. binaries or .jar files)
  • fuzz test dependencies (e.g. .so or additional .jar files)
  • CI Fuzz binary - used to execute the fuzz tests
  • metadata file describing how fuzz tests are executed
  • distribution and additional tools from the base image

Execution​

A Fuzz Container takes a fuzz test identifier as the first argument and can be started locally e.g. with docker:

docker run <fuzz-container-image> <fuzz-test-name>

Running a Fuzz Container without any arguments typically outputs metadata information, including the fuzz tests in a Fuzz Container image.

Additionally, CI Sense expects the Fuzz Container to understand a small number of CLI flags to configure where files are persisted. A full list of the flags and details on the output format can be found in the Fuzz Container API reference.

Requirements​

Running fuzz tests in CI Sense via Fuzz Containers requires access to a Docker registry. Depending on the CI Sense environment this will already be configured and CI Fuzz will use a suitable container registry automatically. However, it is possible to use any container registry that CI Sense has access to.

See our container registry how-to on how to use you own container registry in an on-prem installation or SaaS environment.

Supported architectures​

Currently CI Sense only supports running Fuzz Containers images for the architecture linux/amd64. Note: CI Fuzz can build linux/amd64 Fuzz Container images on all supported platforms for programming languages that are architecture agnostic (e.g. Java).

Using remote Docker engine builders we are planning to support an even wider cross-compatibility between architectures in the future and at the same time removing the requirement of a local Docker engine installed on the host machine.

Coverage​

Most Fuzz Containers support reporting the code coverage of executed fuzz tests. Coverage reports are generated after the fuzz tests execution completes or times out. CI Sense then picks up coverage reports of individual fuzz tests and merges them into a single coverage report which is displayed in the CI Sense UI.

We collect coverage information in the LCOV format independently of a programming language used for the fuzz test. A merged coverage report can be downloaded via the CI Sense UI.

CI/CD integration​

CI Fuzz currently requires a Docker daemon to build and push the Fuzz Container image. Our CI/CD templates include some hints on how to add a Docker engine in your CI/CD pipeline if one is not available so far. See our Fuzz Container CI/CD guide for more information on setting up your CI/CD templates with Fuzz Containers.