whfmt.Fuzz 1.1.0

whfmt.Fuzz

Format-aware binary fuzzer that generates structured mutant files for testing parsers, decoders, and file readers.

Unlike naive byte-flippers, whfmt.Fuzz understands the structure of binary files:

• Targets semantically significant fields (magic bytes, size fields, enum values, checksums)
• Applies format-specific mutation strategies declared in .whfmt definitions
• Optionally recomputes checksums after mutation so parsers see plausible-looking corrupt data
• Weighted random strategy picker ensures coverage of the most dangerous fields first

Powered by 790+ whfmt format definitions with dedicated fuzz blocks for ZIP, PNG, PE/EXE, PDF, MP3, SQLite, and more.

Install

dotnet add package whfmt.Fuzz

Quick Start

using WhfmtFuzz;
using WpfHexEditor.Core.Definitions;

var catalog = EmbeddedFormatCatalog.Instance;

// Generate 20 mutant variants of a PNG file
var variants = FormatFuzzer.Generate(catalog, "sample.png", count: 20);

foreach (var v in variants)
{
    if (v.IsError) { Console.Error.WriteLine(v.Error); continue; }

    File.WriteAllBytes($"corpus/{v.SuggestedFileName}", v.Data);
    Console.WriteLine($"  [{v.Index:D4}] {v.Strategy} on '{v.Field}' — {v.Description}");
}

API Reference

FormatFuzzer.Generate()

// From a file — format auto-detected
IReadOnlyList<FuzzVariant> Generate(
    IEmbeddedFormatCatalog catalog,
    string inputFile,
    int count = 10,
    string? forcedFormat = null,
    int? seed = null)

// From raw bytes — format detected from extension
IReadOnlyList<FuzzVariant> Generate(
    IEmbeddedFormatCatalog catalog,
    byte[] inputData,
    string fileName,
    int count = 10,
    string? forcedFormat = null,
    int? seed = null)

FuzzVariant

Mutation Strategies

Strategies are selected by weighted random pick using weights declared in the .whfmt definition. Rate controls per-strategy acceptance probability.

Format-Specific Strategies

ZIP

PNG

PE/EXE

Examples

Reproducible corpus generation

// Fixed seed — same corpus every CI run
var variants = FormatFuzzer.Generate(catalog, "test.zip", count: 100, seed: 42);

Force format detection

// File has no extension — force format
var variants = FormatFuzzer.Generate(catalog, rawBytes, "mystery_file", forcedFormat: "SQLite");

Save full corpus

var variants = FormatFuzzer.Generate(catalog, "sample.pdf", count: 500);
Directory.CreateDirectory("corpus");
foreach (var v in variants.Where(v => !v.IsError))
    File.WriteAllBytes(Path.Combine("corpus", v.SuggestedFileName), v.Data);

Console.WriteLine($"Generated {variants.Count(v => !v.IsError)} variants");

Integration with libFuzzer / AFL

// whfmt.Fuzz generates the initial seed corpus
// libFuzzer takes over for coverage-guided evolution
var seeds = FormatFuzzer.Generate(catalog, "golden.mp3", count: 1000, seed: 0);
foreach (var s in seeds.Where(v => !v.IsError))
    File.WriteAllBytes($"seeds/{s.SuggestedFileName}", s.Data);

// Then: afl-fuzz -i seeds/ -o findings/ -- ./my_parser @@

CI Integration

# .github/workflows/fuzz-corpus.yml
- name: Generate fuzz corpus
  run: dotnet run --project FuzzRunner -- --input golden/ --output corpus/ --count 200 --seed 42
- name: Run parser against corpus
  run: find corpus/ -name "*.png" | xargs -I{} ./tests/run_parser {}

Architecture

whfmt.Fuzz
├── FormatFuzzer       — entry point, strategy picker, mutation engine
├── FuzzVariant        — immutable result record
├── MutationType       — enum of 9 mutation strategies
└── FuzzStrategy       — internal weighted strategy record

Checksum recomputation: CRC32 (poly 0xEDB88320), MD5, SHA1, SHA256 — all built-in, zero external dependencies.

Depends on: whfmt.FileFormatCatalog 1.3.0+ — cross-platform net8.0.

Related Packages

License

GNU AGPL v3.0 — © 2016–2026 Derek Tremblay / Pulsar Informatique