Skip to main content

Overview

Implementation​

From an implementation perspective, several modules exist to make the fuzzer reusable.

Fuzzing loop​

The main fuzzing loop is made of the following modules, each at a different layer (from high-level to low-level):

  1. puffin: Core fuzzing engine which is protocol- and target-agnostic. It deals at a high level with the terms algebra, the input traces and the fuzzing process (scheduling, logging, mutations, ...). This module is built on top of the libAFL crate.
  2. tlspuffin: TLS fuzzer which instantiates puffin to the TLS protocol and is PUTs-agnostic. It notably instantiates the traces to TLS traces with the TLS-specific terms and functions for the TLS terms algebra, based on the rustls crate (e.g., ECDSA signatures, ECDHE encryption, ClientHello, etc.).
  3. harness: the layer between the fuzzer and the PUTs (the tested libraries, e.g. OpenSSL 3.4.0). A harness is written in C, once per library family (openssl, libressl, wolfssl, boringssl), and implements the C interface TLS_PUT_INTERFACE, see for example the OpenSSL harness harness/openssl. Compiling a harness with a given PUT gives a target (e.g. openssl340 = harness/openssl + OpenSSL 3.4.0), which is what the fuzzer actually executes. See the terminology for these terms.

Finally, other protocols and PUTs can be fuzzed as well, by extending the fuzzer at layer 2. (new protocols) and 3. (new harnesses). We did a preliminary version of those for SSH and libssh in the module sshpuffin (WIP).

The following diagram shows the dependencies between the modules:

The content of the bundle depends on the vendor libraries built with mk_vendor; see build process for how targets are produced and linked into the fuzzer.

The interfaces between the modules are the following:

  • Protocol <-> puffin: a protocol is defined by implementing the Rust trait ProtocolBehavior (message types, terms algebra, claims, ...).
  • PUTs <-> puffin: PUTs are exposed to puffin through the Rust traits Factory<PB: ProtocolBehavior>, which creates agents for a given PUT, and Put<PB: ProtocolBehavior>, which represents a running agent.
  • tlspuffin <-> C harnesses: tlspuffin implements Factory and Put once, with CPut and CAgent, on top of the C interface TLS_PUT_INTERFACE. Each C harness implements this interface for one library family, so adding a new TLS library does not require any Rust code.

Program Under Tests (PUTs)​

The fuzzer then requires a target (that is a harness linked to some PUT) to fuzz. To build the PUTs (vendor libraries) and link them to the fuzzer, the following tooling is used:

  • puffin-build (generates the mk_vendor tool): a crate implementing the build process, from creating PUTs (vendor libraries) to linking PUTs into the fuzzer (through some fuzzing harness).

Benchmarks​

To benchmark the fuzzer and perform regression tests, the following tooling is used:

  • puffin-bench: performance testbench for the puffin fuzzer (external tooling; not part of the puffin crate), see benchmarks.

Setup​

Ongoing Work

The rest of this page is currently under development. Information presented here might be incomplete or outdated.

Configure your environment for development on the puffin project:

  • nix
  • editor setup
    • vscode (recommended extensions, change default features, ...)

Testing my changes​

  • justfile: use just fmt for code formatting, just check for basic checks, and just check-workspace for more advanced checks. Under-the-hood, it uses:
    • rustfmt
    • clang-format
    • cargo clippy
    • cargo bench
  • github PRs/github CI: use the PR's labels ci:none, ci:fast, ci:full to fine-tune the CI checks. The full checks (ci:full) must be checked prior to merging PRs.
  • puffin-bench: run uv run benchmark for end-to-end, long, and comprehensive regressions and performance checks, see benchmarks.