Coverage Analysis

Overview

1. Assessing harness effectiveness: Understand which parts of your application are actually executed by your fuzzing harnesses
2. Tracking fuzzing progress: Monitor how coverage changes when updating harnesses, fuzzers, or the system under test (SUT)

Key Concepts

When to Apply

• Starting a new fuzzing campaign to establish a baseline
• Fuzzer appears to plateau without finding new paths
• After harness modifications to verify improvements
• When migrating between different fuzzers
• Identifying areas requiring dictionary entries or seed inputs
• Debugging why certain code paths aren't reached

• Fuzzing campaign is actively finding crashes
• Coverage infrastructure isn't set up yet
• Working with extremely large codebases where full coverage reports are impractical
• Fuzzer's internal coverage metrics are sufficient for your needs

Quick Reference

Ideal Coverage Workflow

Copy
[Fuzzing Campaign]
       |
       v
[Generate Corpus]
       |
       v
[Coverage Analysis]
       |
       +---> Coverage Increased? --> Continue fuzzing with larger corpus
       |
       +---> Coverage Decreased? --> Fix harness or investigate SUT changes
       |
       +---> Coverage Plateaued? --> Add dictionary entries or seed inputs

Step-by-Step

Step 1: Build with Coverage Instrumentation

Copy
clang++ -fprofile-instr-generate -fcoverage-mapping \
  -O2 -DNO_MAIN \
  main.cc harness.cc execute-rt.cc -o fuzz_exec
`**GCC (C/C++):**`
g++ -ftest-coverage -fprofile-arcs \
  -O2 -DNO_MAIN \
  main.cc harness.cc execute-rt.cc -o fuzz_exec_gcov
`**Rust:**`
rustup toolchain install nightly --component llvm-tools-preview
cargo +nightly fuzz coverage fuzz_target_1

Step 2: Create Execution Runtime (C/C++ only)

Copy
// execute-rt.cc
#include <stdio.h>
#include <stdlib.h>
#include <dirent.h>
#include <stdint.h>

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

void load_file_and_test(const char *filename) {
    FILE *file = fopen(filename, "rb");
    if (file == NULL) {
        printf("Failed to open file: %s\n", filename);
        return;
    }

    fseek(file, 0, SEEK_END);
    long filesize = ftell(file);
    rewind(file);

    uint8_t *buffer = (uint8_t*) malloc(filesize);
    if (buffer == NULL) {
        printf("Failed to allocate memory for file: %s\n", filename);
        fclose(file);
        return;
    }

    long read_size = (long) fread(buffer, 1, filesize, file);
    if (read_size != filesize) {
        printf("Failed to read file: %s\n", filename);
        free(buffer);
        fclose(file);
        return;
    }

    LLVMFuzzerTestOneInput(buffer, filesize);

    free(buffer);
    fclose(file);
}

int main(int argc, char **argv) {
    if (argc != 2) {
        printf("Usage: %s <directory>\n", argv[0]);
        return 1;
    }

    DIR *dir = opendir(argv[1]);
    if (dir == NULL) {
        printf("Failed to open directory: %s\n", argv[1]);
        return 1;
    }

    struct dirent *entry;
    while ((entry = readdir(dir)) != NULL) {
        if (entry->d_type == DT_REG) {
            char filepath[1024];
            snprintf(filepath, sizeof(filepath), "%s/%s", argv[1], entry->d_name);
            load_file_and_test(filepath);
        }
    }

    closedir(dir);
    return 0;
}

Step 3: Execute on Corpus

Step 4: Process Coverage Data

Copy
# Merge raw profile data
llvm-profdata merge -sparse fuzz.profraw -o fuzz.profdata

# Generate text report
llvm-cov report ./fuzz_exec \
  -instr-profile=fuzz.profdata \
  -ignore-filename-regex='harness.cc|execute-rt.cc'

# Generate HTML report
llvm-cov show ./fuzz_exec \
  -instr-profile=fuzz.profdata \
  -ignore-filename-regex='harness.cc|execute-rt.cc' \
  -format=html -output-dir fuzz_html/
`**GCC with gcovr:**`
# Install gcovr (via pip for latest version)
python3 -m venv venv
source venv/bin/activate
pip3 install gcovr

# Generate report
gcovr --gcov-executable "llvm-cov gcov" \
  --exclude harness.cc --exclude execute-rt.cc \
  --root . --html-details -o coverage.html
`**Rust:**`
# Install required tools
cargo install cargo-binutils rustfilt

# Create HTML generation script
cat <<'EOF' > ./generate_html
#!/bin/sh
if [ $# -lt 1 ]; then
    echo "Error: Name of fuzz target is required."
    echo "Usage: $0 fuzz_target [sources...]"
    exit 1
fi
FUZZ_TARGET="$1"
shift
SRC_FILTER="$@"
TARGET=$(rustc -vV | sed -n 's|host: ||p')
cargo +nightly cov -- show -Xdemangler=rustfilt \
  "target/$TARGET/coverage/$TARGET/release/$FUZZ_TARGET" \
  -instr-profile="fuzz/coverage/$FUZZ_TARGET/coverage.profdata" \
  -show-line-counts-or-regions -show-instantiations \
  -format=html -o fuzz_html/ $SRC_FILTER
EOF
chmod +x ./generate_html

# Generate HTML report
./generate_html fuzz_target_1 src/lib.rs

Step 5: Analyze Results

• Uncovered code blocks: Areas that may need better seed inputs or dictionary entries
• Magic value checks: Conditional statements with hardcoded values that block progress
• Dead code: Functions that may not be reachable through your harness
• Coverage changes: Compare against baseline to track improvements or regressions

Common Patterns

Pattern: Identifying Magic Values

Copy
// Coverage shows this block is never executed
if (buf == 0x7F454C46) {  // ELF magic number
    // start parsing buf
}
`**Solution**: Add magic values to dictionary file:`
# magic.dict
"\x7F\x45\x4C\x46"

Pattern: Handling Crashing Inputs

Copy
// Fork before executing to isolate crashes
int main(int argc, char **argv) {
    // ... directory opening code ...

    while ((entry = readdir(dir)) != NULL) {
        if (entry->d_type == DT_REG) {
            pid_t pid = fork();
            if (pid == 0) {
                // Child process - crash won't affect parent
                char filepath[1024];
                snprintf(filepath, sizeof(filepath), "%s/%s", argv[1], entry->d_name);
                load_file_and_test(filepath);
                exit(0);
            } else {
                // Parent waits for child
                waitpid(pid, NULL, 0);
            }
        }
    }
}

Pattern: CMake Integration

Copy
project(FuzzingProject)
cmake_minimum_required(VERSION 3.0)

# Main binary
add_executable(program main.cc)

# Fuzzing binary
add_executable(fuzz main.cc harness.cc)
target_compile_definitions(fuzz PRIVATE NO_MAIN=1)
target_compile_options(fuzz PRIVATE -g -O2 -fsanitize=fuzzer)
target_link_libraries(fuzz -fsanitize=fuzzer)

# Coverage execution binary
add_executable(fuzz_exec main.cc harness.cc execute-rt.cc)
target_compile_definitions(fuzz_exec PRIVATE NO_MAIN)
target_compile_options(fuzz_exec PRIVATE -O2 -fprofile-instr-generate -fcoverage-mapping)
target_link_libraries(fuzz_exec -fprofile-instr-generate)
`Build:`
cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .
cmake --build . --target fuzz_exec

Advanced Usage

Tips and Tricks

Incremental Coverage Updates

Copy
# First run
./fuzz_exec_gcov corpus_batch_1/
gcovr --html coverage_v1.html

# Second run (adds to existing coverage)
./fuzz_exec_gcov corpus_batch_2/
gcovr --html coverage_v2.html

# Start fresh
gcovr --delete  # Remove .gcda files
./fuzz_exec_gcov corpus/

Handling Large Codebases

1. Filter by prefix: Only generate reports for relevant directories
   llvm-cov show ./fuzz_exec -instr-profile=fuzz.profdata /path/to/src/
2. Use directory coverage: Group by directory to reduce clutter (LLVM 18+)
   llvm-cov show -show-directory-coverage -format=html -output-dir html/
3. Generate JSON for programmatic analysis:
   llvm-cov export -format=lcov > coverage.json

Differential Coverage

Copy
# Campaign 1
LLVM_PROFILE_FILE=campaign1.profraw ./fuzz_exec corpus1/
llvm-profdata merge -sparse campaign1.profraw -o campaign1.profdata

# Campaign 2
LLVM_PROFILE_FILE=campaign2.profraw ./fuzz_exec corpus2/
llvm-profdata merge -sparse campaign2.profraw -o campaign2.profdata

# Compare
llvm-cov show ./fuzz_exec \
  -instr-profile=campaign2.profdata \
  -instr-profile=campaign1.profdata \
  -show-line-counts-or-regions

Anti-Patterns

Tool-Specific Guidance

libFuzzer

Copy
clang++ -fprofile-instr-generate -fcoverage-mapping \
  -O2 -DNO_MAIN \
  main.cc harness.cc execute-rt.cc -o fuzz_exec
`**Execute corpus and generate report:**`
LLVM_PROFILE_FILE=fuzz.profraw ./fuzz_exec corpus/
llvm-profdata merge -sparse fuzz.profraw -o fuzz.profdata
llvm-cov show ./fuzz_exec -instr-profile=fuzz.profdata -format=html -output-dir html/

• Don't use -fsanitize=fuzzer for coverage builds (it conflicts with profile instrumentation)
• Reuse the same harness function (LLVMFuzzerTestOneInput) with a different main function
• Use the -ignore-filename-regex flag to exclude harness code from coverage reports
• Consider using llvm-cov's -show-instantiation flag for template-heavy C++ code

AFL++

Copy
clang++ -fprofile-instr-generate -fcoverage-mapping \
  -O2 main.cc harness.cc execute-rt.cc -o fuzz_exec
`**Build for coverage with GCC:**`
AFL_USE_ASAN=0 afl-gcc -ftest-coverage -fprofile-arcs \
  main.cc harness.cc execute-rt.cc -o fuzz_exec_gcov
`**Execute and generate report:**`
# LLVM approach
LLVM_PROFILE_FILE=fuzz.profraw ./fuzz_exec afl_output/queue/
llvm-profdata merge -sparse fuzz.profraw -o fuzz.profdata
llvm-cov report ./fuzz_exec -instr-profile=fuzz.profdata

# GCC approach
./fuzz_exec_gcov afl_output/queue/
gcovr --html-details -o coverage.html

• Don't use AFL++'s instrumentation (afl-clang-fast) for coverage builds
• Use standard compilers with coverage flags instead
• AFL++'s queue/ directory contains your corpus
• AFL++'s built-in coverage statistics are useful for real-time monitoring but not for detailed analysis

cargo-fuzz (Rust)

Copy
rustup toolchain install nightly --component llvm-tools-preview
cargo install cargo-binutils rustfilt
`**Generate coverage data:**`
cargo +nightly fuzz coverage fuzz_target_1
`**Create HTML report script:**`
cat <<'EOF' > ./generate_html
#!/bin/sh
FUZZ_TARGET="$1"
shift
SRC_FILTER="$@"
TARGET=$(rustc -vV | sed -n 's|host: ||p')
cargo +nightly cov -- show -Xdemangler=rustfilt \
  "target/$TARGET/coverage/$TARGET/release/$FUZZ_TARGET" \
  -instr-profile="fuzz/coverage/$FUZZ_TARGET/coverage.profdata" \
  -show-line-counts-or-regions -show-instantiations \
  -format=html -o fuzz_html/ $SRC_FILTER
EOF
chmod +x ./generate_html
`**Generate report:**`
./generate_html fuzz_target_1 src/lib.rs

• Always use the nightly toolchain for coverage
• The -Xdemangler=rustfilt flag makes function names readable
• Filter by source files (e.g., src/lib.rs) to focus on crate code
• Use -show-line-counts-or-regions and -show-instantiations for better Rust-specific output
• Corpus is located in fuzz/corpus/<target>/

honggfuzz

Copy
# Use standard compiler, not honggfuzz compiler
clang -fprofile-instr-generate -fcoverage-mapping \
  -O2 harness.c execute-rt.c -o fuzz_exec
`**Execute corpus:**`
LLVM_PROFILE_FILE=fuzz.profraw ./fuzz_exec honggfuzz_workspace/

• Don't use hfuzz-clang for coverage builds
• honggfuzz corpus is typically in a workspace directory
• Use the same LLVM workflow as libFuzzer

Troubleshooting

Related Skills

Tools That Use This Technique

Related Techniques

Resources

Key External Resources

Video Resources