Mutation Engine¶

The mutation engine is the core innovation of Crucible. Rather than treating GGUF files as opaque byte streams, it parses the binary structure and applies targeted mutations to specific fields, reaching deep code paths that generic fuzzers never touch.

Why Structure-Aware Beats Generic¶

Generic fuzzers like AFL and libFuzzer treat inputs as flat byte arrays. For a format like GGUF, this means the vast majority of mutations produce files rejected at the very first check — the 4-byte magic number.

Consider the difference:

Iteration 1: corrupt magic       → rejected at byte 0
Iteration 2: corrupt magic       → rejected at byte 0
Iteration 3: corrupt version     → rejected at byte 4
Iteration 4: corrupt magic       → rejected at byte 0
...
Iteration 10000: finally valid   → reaches metadata parser

Iteration 1: mutate metadata key → reaches metadata string handler
Iteration 2: corrupt tensor dims → reaches dimension validation
Iteration 3: poison alignment    → reaches padding calculator
Iteration 4: overflow dim product → reaches allocation logic
...
Every iteration reaches deep code paths

Mutation Pipeline¶

Each fuzzing iteration follows this pipeline:

flowchart LR
    A[Parse Seed] --> B[Select 1-3\nMutations]
    B --> C[Weighted Category\nSelection]
    C --> D[Strategy\nSelection]
    D --> E[Apply to\nGGUF Struct]
    E --> F[Serialize\nto Bytes]
    F --> G[Write to\nTarget]

1. Parse Seed — Load and deserialize a .gguf file from the corpus into a *gguf.File struct
2. Select Mutation Count — Randomly choose 1 to 3 mutations to apply per iteration
3. Weighted Category Selection — Pick a mutation category using the distribution below
4. Strategy Selection — Uniformly select a specific strategy within that category
5. Apply Mutation — Call Strategy.Mutate(*gguf.File, *rand.Rand) to modify the struct in place
6. Serialize — Re-encode the mutated struct back to valid GGUF binary
7. Write — Pass the bytes to the target binary via stdin or temp file

Category Weights¶

Mutation categories are weighted based on historical CVE density and code path coverage:

pie title Mutation Category Weights
    "Metadata + Model-Loader (35%)" : 35
    "TensorInfo (35%)" : 35
    "Header (10%)" : 10
    "Consistency (10%)" : 10
    "Alignment (5%)" : 5
    "Data (5%)" : 5

Why 70% Metadata + TensorInfo¶

The metadata and tensor info sections receive 70% of mutation budget for good reason. Analysis of historical CVEs in llama.cpp and related parsers shows these sections contain the most bug-dense code:

• Metadata parsing involves variable-length strings, nested arrays, and type dispatch — classic sources of buffer overflows and type confusion
• Tensor info parsing involves dimension arithmetic (multiplication of multiple uint64 values), offset calculations, and memory allocation sizing — classic sources of integer overflows
• Model-loader targeting (5 strategies in model_loader.go, weighted under the Metadata category) fuzzes architecture dispatch, hyperparameter handling, and tensor name schemas — exercising the llama_model_load() path that runs after GGUF parsing

Strategy Categories¶

Crucible implements 46 strategies across 6 weighted categories (7 strategy files). Every strategy implements the same interface:

type Strategy interface {
    Name() string                          // (1)!
    Mutate(f *gguf.File, rng *rand.Rand)   // (2)!
}

1. Returns a human-readable name for logging and crash reports
2. Modifies the GGUF file struct in place using the provided RNG for determinism

Header Strategies¶

Metadata Strategies¶

TensorInfo Strategies¶

Model-Loader Strategies¶

These target the model-loading path (llama_model_load) rather than raw GGUF parsing. They are registered under the Metadata category for weighting purposes.

Alignment Strategies¶

Data Strategies¶

Consistency Strategies¶

Critical Bug Patterns¶

The strategies above are designed to trigger specific classes of vulnerabilities:

Deterministic Reproduction¶

Every fuzzing run is seeded with a 64-bit integer from crypto/rand. This seed is:

1. Logged at the start of each run
2. Recorded in every crash report
3. Sufficient to reproduce the exact sequence of mutations

# Reproduce a crash with a known seed
crucible generate --seed 8827361950234 --count 1 --corpus ./corpus