whfmt.Fuzz 1.1.1

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
• Compound mutations — apply N independent mutations per variant for deeper coverage
• Mutation log — every applied mutation recorded (MutationLogEntry: type + field)
• Optionally recomputes checksums after mutation so parsers see plausible-looking corrupt data
• FuzzSession — reproducible multi-generation corpus with manifest.json save/load
• FuzzReport — field coverage, strategy distribution, and untested fields analysis
• Weighted random strategy picker ensures coverage of the most dangerous fields first

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

Full documentation: whfmt-Fuzz-guide.md — API reference, architecture, integration guides, and usage examples.

What's New

v1.1.1 — Catalog 1.3.2 alignment + extended mutations

• Catalog bump to whfmt.FileFormatCatalog 1.3.2 (Phase B audit + 2 bug fixes, 799 definitions, schema v3 canonical).
• FuzzMutation enum extended (Lot 4) with byte_swap / truncate / duplicate mutations.
• No Fuzz API changes — drop-in upgrade from 1.1.0.

v1.1.0 — Sessions, reports, compound mutations

• FuzzSession — multi-generation reproducible corpus with manifest.json save/restore (SaveCorpusAsync / LoadCorpusAsync)
• FuzzReport — coverage analysis: FieldCoverage, StrategyDistribution, UntestedFields, AverageMutationsPerVariant
• Compound mutations — compound: N parameter applies N independent mutations per variant
• MutationLog — every applied mutation recorded as MutationLogEntry (type + field)
• 3 new mutation strategies — InsertBytes, SliceRepeat, NegateField (12 total)
• Async overloads — GenerateAsync(string file, …) and GenerateAsync(Stream stream, …)
• GenerateWithReport() — single call returns (variants, report) with one Resolve pass
• Random.Shared replaces new Random() for stronger weak seeding

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,
    int compound = 1)   // NEW: mutations per variant

// 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,
    int compound = 1)

// Async overloads (from file path or stream)
Task<IReadOnlyList<FuzzVariant>> GenerateAsync(string inputFile, ...)
Task<IReadOnlyList<FuzzVariant>> GenerateAsync(Stream stream, string fileName, ...)

FormatFuzzer.GenerateWithReport()

// Returns variants + coverage report in one call
(IReadOnlyList<FuzzVariant>, FuzzReport) GenerateWithReport(
    IEmbeddedFormatCatalog catalog,
    string inputFile,
    int count = 10,
    string? forcedFormat = null,
    int? seed = null,
    int compound = 1)

FuzzSession — multi-generation corpus

var session = new FuzzSession(catalog, seed: 42);

// Generate batches iteratively
session.NextGeneration("sample.png", count: 50);
session.NextGeneration("sample.png", count: 50, compound: 3);

Console.WriteLine($"Corpus: {session.Corpus.Count} variants");

// Save with manifest.json
await session.SaveCorpusAsync("corpus/");

// Restore from disk
var restored = await FuzzSession.LoadCorpusAsync(catalog, "corpus/", seed: 42);

FuzzReport — coverage analysis

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);

Compound mutations (deeper coverage)

// Apply 3 independent mutations per variant
var variants = FormatFuzzer.Generate(catalog, "sample.png", count: 50, compound: 3);
foreach (var v in variants)
    Console.WriteLine($"  {v.MutationCount} mutations: {string.Join(", ", v.MutationLog.Select(m => m.Mutation))}");

Coverage-aware generation with report

var (variants, report) = FormatFuzzer.GenerateWithReport(catalog, "sample.zip", count: 200, seed: 42);
Console.WriteLine($"Untested fields: {string.Join(", ", report.UntestedFields)}");

Multi-generation session with save/restore

var session = new FuzzSession(catalog, seed: 42);
session.NextGeneration("sample.zip", count: 50);
session.NextGeneration("sample.zip", count: 50, compound: 2);
await session.SaveCorpusAsync("corpus/");
// corpus/ contains variant files + manifest.json

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, compound mutation engine
├── FuzzSession        — multi-generation reproducible corpus with manifest.json
├── FuzzVariant        — immutable result record with MutationLog
├── FuzzReport         — field coverage, strategy distribution, untested fields
├── MutationType       — enum of 12 mutation strategies
└── MutationLogEntry   — per-mutation type + field record

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

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

Related Packages

License

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