Corpus Management¶

A fuzzer is only as good as its seed corpus. Crucible takes a synthetic-first approach: generate seeds that exercise every parser path before supplementing with real-world models.

Synthetic-First Philosophy¶

Real-world GGUF models exercise the happy path — standard architectures, common quantization types, typical vocabulary sizes. But bugs hide in the corners: unusual value types, rare tensor configurations, extreme alignment values. Synthetic seeds fill those gaps.

flowchart TD
    A[Corpus Strategy] --> B[Synthetic Seeds]
    A --> C[Real Model Seeds]
    B --> D[crucible-gen]
    D --> E[Minimal Valid Files]
    D --> F[Per-Value-Type Seeds]
    D --> G[Per-Tensor-Type Seeds]
    D --> H[Edge Case Seeds]
    C --> I[HuggingFace Downloads]
    I --> J[Small Quantized Models]
    E --> K[Corpus Directory]
    F --> K
    G --> K
    H --> K
    J --> K

What crucible-gen Produces¶

The crucible-gen tool creates a comprehensive set of synthetic GGUF files. Each seed is minimal — just large enough to exercise its target code path.

Minimal Valid Files¶

The baseline: the smallest possible valid GGUF file (seed_000.gguf). Contains only the GGUF header with zero metadata keys and zero tensors. Every fuzzing run starts from a structurally valid file.

Per-Value-Type Seeds¶

One seed for each of the 14 metadata value types (seed_003.gguf through seed_016.gguf), ensuring the parser's type dispatch is fully covered:

Per-Tensor-Type Seeds¶

One seed for each common GGML quantization type (seed_017.gguf through seed_021.gguf), exercising the data size calculations for each block format:

Edge Case Seeds¶

Seeds designed to push boundary conditions:

Real Model Seeds¶

Synthetic seeds cover structure. Real models cover semantics — actual vocabulary sizes, real architecture metadata, production tensor shapes.

# Example: download a small quantized model
huggingface-cli download TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF \
    tinyllama-1.1b-chat-v1.0.Q2_K.gguf \
    --local-dir ./corpus/seeds/

Larger models are slower to parse, mutate, and serialize on every iteration. Keep real model seeds as small as possible.

CVE-Targeted Seeds¶

The --talos flag generates reconstruction seeds based on known vulnerability patterns from Cisco Talos and other researchers. These are written to corpus/reconstructed/:

crucible-gen --talos

These seeds prime the fuzzer to explore code paths around known bug patterns, increasing the chance of finding regressions or variants of previously patched vulnerabilities.

Corpus Loading¶

The LoadCorpus function scans a directory for .gguf files and provides thread-safe random selection:

corpus, err := corpus.LoadCorpus("./corpus/seeds/")  // (1)!
if err != nil {
    log.Fatal(err)
}

seed := corpus.Random(rng)  // (2)!

1. Recursively loads all .gguf files from the directory into memory
2. Thread-safe random selection using the provided *rand.Rand instance

The Corpus struct holds parsed GGUF files in memory for fast access. Random selection is performed with the fuzzer's seeded RNG to maintain deterministic reproducibility.

Minimization¶

Hash-Based Deduplication¶

Every file in the corpus is identified by its SHA-256 hash. When new crash inputs are added back to the corpus, duplicates are detected and skipped automatically.

corpus/
├── seeds/
│   ├── seed_000.gguf
│   ├── seed_012.gguf
│   └── tinyllama-q2.gguf
└── crashes/
    ├── abc123de.gguf      ← named by hash prefix
    └── f9871a02.gguf

Coverage-Guided Minimization¶

MinimizeWithCoverage uses an LLVM-instrumented harness to collect per-seed edge coverage and then applies a greedy set-cover algorithm to select the smallest seed set that covers all observed edges. Seeds that produce zero coverage (e.g. due to early crashes or instrumentation gaps) are preserved after hash-based dedup rather than silently dropped.

result, err := corpus.MinimizeWithCoverage(seeds, "./harness-binary")

Falls back to hash-based dedup when no harness is provided.

Fuzzer Dictionary¶

The file corpus/gguf.dict contains 260+ known-interesting byte patterns organized into categories that the mutation engine can insert into string fields and raw data sections:

# Magic and structural patterns
"GGUF"
"\x46\x55\x47\x47"

# Common metadata keys (60+ entries)
"general.architecture"
"general.alignment"
"general.name"
"tokenizer.ggml.model"
"tokenizer.ggml.tokens"
"llama.attention.head_count"
"llama.rope.freq_base"

# Architecture values (106+ entries)
"llama"
"falcon"
"gpt2"
"mpt"
"phi3"
"qwen2"
"gemma"
"command-r"

# ggml_type enum values (26 entries)
"\x00\x00\x00\x00"  # GGML_TYPE_F32
"\x01\x00\x00\x00"  # GGML_TYPE_F16
"\x02\x00\x00\x00"  # GGML_TYPE_Q4_0
"\x1e\x00\x00\x00"  # GGML_TYPE_COUNT (sentinel)

# Boundary values
"\xff\xff\xff\xff"
"\xff\xff\xff\xff\xff\xff\xff\xff"

The dictionary categories include:

The dictionary supplements random mutation with targeted patterns known to trigger specific bug classes — type confusion from invalid enum values, parsing errors from unexpected architecture strings, and integer boundary conditions in tensor size calculations.

Additional Dictionaries¶

Crucible includes format-specific dictionaries for non-GGUF attack surfaces:

Each dictionary is automatically selected by the --dict flag when the harness name or corpus directory matches the target surface.