/harness-writing

name: harness-writing
type: technique
description: "Designs and improves fuzzing harnesses for C/C++ and Rust. Covers mapping raw bytes onto a target API, generating structured inputs, avoiding non-determinism and false crashes, and deciding what to fuzz together. Use when writing a first LLVMFuzzerTestOneInput or fuzz_target! harness, when a campaign finds nothing or reports crashes that will not reproduce, or when the target API needs structured rather than raw input."

Writing Fuzzing Harnesses

A fuzzing harness is the entrypoint function that receives random data from the fuzzer and routes it to your system under test (SUT). The quality of your harness directly determines which code paths get exercised and whether critical bugs are found. A poorly written harness can miss entire subsystems or produce non-reproducible crashes.

Overview

The harness is the bridge between the fuzzer's random byte generation and your application's API. It must parse raw bytes into meaningful inputs, call target functions, and handle edge cases gracefully. The most important part of any fuzzing setup is the harness—if written poorly, critical parts of your application may not be covered.

Key Concepts

| Concept | Description | |---------|-------------| | **Harness** | Function that receives fuzzer input and calls target code under test | | **SUT** | System Under Test—the code being fuzzed | | **Entry point** | Function signature required by the fuzzer (e.g., `LLVMFuzzerTestOneInput`) | | **FuzzedDataProvider** | Helper class for structured extraction of typed data from raw bytes | | **Determinism** | Property that ensures same input always produces same behavior | | **Interleaved fuzzing** | Single harness that exercises multiple operations based on input |

When to Apply

**Apply this technique when:**

• Creating a new fuzz target for the first time
• Fuzz campaign has low code coverage or isn't finding bugs
• Crashes found during fuzzing are not reproducible
• Target API requires complex or structured inputs
• Multiple related functions should be tested together

**Skip this technique when:**

• Using existing well-tested harnesses from your project
• Tool provides automatic harness generation that meets your needs
• Target already has comprehensive fuzzing infrastructure

Quick Reference

| Task | Pattern | |------|---------| | Minimal C++ harness | `extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)` | | Minimal Rust harness | `fuzz_target!(|data: &[u8]| { ... })` | | Size validation | `if (size < MIN_SIZE) return 0;` | | Cast to integers | `uint32_t val = *(uint32_t*)(data);` | | Use FuzzedDataProvider | `FuzzedDataProvider fuzzed_data(data, size);` | | Extract typed data (C++) | `auto val = fuzzed_data.ConsumeIntegral<uint32_t>();` | | Extract string (C++) | `auto str = fuzzed_data.ConsumeBytesWithTerminator<char>(32, 0xFF);` |

Step-by-Step

Step 1: Identify Entry Points

Find functions in your codebase that:

• Accept external input (parsers, validators, protocol handlers)
• Parse complex data formats (JSON, XML, binary protocols)
• Perform security-critical operations (authentication, cryptography)
• Have high cyclomatic complexity or many branches

Good targets are typically:

• Protocol parsers
• File format parsers
• Serialization/deserialization functions
• Input validation routines

Step 2: Write Minimal Harness

Start with the simplest possible harness that calls your target function:

**C/C++:**

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

**Rust:**

#![no_main]
use libfuzzer_sys::fuzz_target;

fuzz_target!(|data: &[u8]| {
    target_function(data);
});

Step 3: Add Input Validation

Reject inputs that are too small or too large to be meaningful:

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
    // Ensure minimum size for meaningful input
    if (size < MIN_INPUT_SIZE || size > MAX_INPUT_SIZE) {
        return 0;
    }
    target_function(data, size);
    return 0;
}

**Rationale:** The fuzzer generates random inputs of all sizes. Your harness must handle empty, tiny, huge, or malformed inputs without causing unexpected issues in the harness itself (crashes in the SUT are fine—that's what we're looking for).

Step 4: Structure the Input

For APIs that require typed data (integers, strings, etc.), use casting or helpers like `FuzzedDataProvider`:

**Simple casting:**

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
    if (size != 2 * sizeof(uint32_t)) {
        return 0;
    }

    uint32_t numerator = *(uint32_t*)(data);
    uint32_t denominator = *(uint32_t*)(data + sizeof(uint32_t));

    divide(numerator, denominator);
    return 0;
}

**Using FuzzedDataProvider:**

#include "FuzzedDataProvider.h"

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
    FuzzedDataProvider fuzzed_data(data, size);

    size_t allocation_size = fuzzed_data.ConsumeIntegral<size_t>();
    std::vector<char> str1 = fuzzed_data.ConsumeBytesWithTerminator<char>(32, 0xFF);
    std::vector<char> str2 = fuzzed_data.ConsumeBytesWithTerminator<char>(32, 0xFF);

    concat(&str1[0], str1.size(), &str2[0], str2.size(), allocation_size);
    return 0;
}

Step 5: Test and Iterate

Run the fuzzer and monitor:

• Code coverage (are all interesting paths reached?)
• Executions per second (is it fast enough?)
• Crash reproducibility (can you reproduce crashes with saved inputs?)

Iterate on the harness to improve these metrics.

Common Patterns

Pattern: Beyond Byte Arrays—Casting to Integers

**Use Case:** When target expects primitive types like integers or floats

**Implementation:**

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
    // Ensure exactly 2 4-byte numbers
    if (size != 2 * sizeof(uint32_t)) {