`mozz.mutator`

Byte-level mutation operators for fuzzing.

Seven shipped mutators plus a weighted MutatorChain that picks one at random. All mutators take a Span[UInt8, _] input and return a new List[UInt8] — they never mutate in place.

Use default_mutator() to get the standard weighted chain used by fuzz().

Example: mojo var rng = Xoshiro256(seed=1) var chain = default_mutator() var input = List[UInt8](0x48, 0x65, 0x6C, 0x6C, 0x6F) # "Hello" var mutated = chain.mutate(Span[UInt8, _](input), rng)

Structs

`MutatorId`

struct MutatorId

Integer IDs for each built-in mutator (used by MutatorChain).

Implements Movable

comptime BIT_FLIP = Int(0)

comptime BYTE_SUBSTITUTION = Int(1)

comptime BYTE_INSERTION = Int(2)

comptime BYTE_DELETION = Int(3)

comptime BLOCK_DUPLICATION = Int(4)

comptime SPLICE = Int(5)

comptime BOUNDARY_INT = Int(6)

`BitFlip`

struct BitFlip

Flip 1–4 random bits at random positions.

Effective for discovering off-by-one errors and flag-dependent branches.

Implements Movable

`init`

def __init__(out self)

Create a BitFlip mutator.

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Flip 1–4 random bits in a copy of input.

Args: input: The input bytes to mutate.; rng: PRNG state (advanced in-place).

`ByteSubstitution`

struct ByteSubstitution

Replace 1–4 bytes with random or boundary values.

Boundary values (0x00, 0x7F, 0x80, 0xFF, etc.) are chosen with 30% probability to hit common parser edge cases.

Implements Movable

`init`

def __init__(out self)

Create a ByteSubstitution mutator.

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Replace 1–4 bytes with random or boundary values.

Args: input: The input bytes to mutate.; rng: PRNG state (advanced in-place).

`ByteInsertion`

struct ByteInsertion

Insert 1–8 random bytes at a random position.

Exercises length-parsing code paths that may assume fixed-size fields.

Implements Movable

`init`

def __init__(out self)

Create a ByteInsertion mutator.

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Insert 1–8 random bytes at a random position.

Args: input: The input bytes to mutate.; rng: PRNG state (advanced in-place).

`ByteDeletion`

struct ByteDeletion

Delete 1–8 bytes at a random position.

Exercises length checks and under-read recovery paths.

Implements Movable

`init`

def __init__(out self)

Create a ByteDeletion mutator.

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Delete 1–8 bytes starting at a random position.

Args: input: The input bytes to mutate.; rng: PRNG state (advanced in-place).

`BlockDuplication`

struct BlockDuplication

Duplicate a random 1–32 byte slice and insert it elsewhere.

Useful for exercising repeated-field parsers and length-prefix bugs.

Implements Movable

`init`

def __init__(out self)

Create a BlockDuplication mutator.

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Copy a random block and insert it at a random position.

Args: input: The input bytes to mutate.; rng: PRNG state (advanced in-place).

`Splice`

struct Splice

Splice the tail of a second corpus entry onto the current input.

Cross-pollination across corpus seeds can expose stateful interaction bugs that single-input mutation misses.

When no second seed is available the input is returned unchanged.

Implements Movable

`init`

def __init__(out self, corpus: List[List[UInt8]])

Create a Splice mutator with a snapshot of the corpus.

Args: corpus: Current corpus seeds (copied for safety).

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Splice a random corpus entry onto the first half of input.

Args: input: The primary input bytes.; rng: PRNG state (advanced in-place).

`BoundaryInt`

struct BoundaryInt

Replace a 1–2 byte run with an interesting integer boundary value.

Targets off-by-one errors on integer boundaries commonly exploitable in binary protocol parsers (e.g. payload-length fields).

Implements Movable

`init`

def __init__(out self)

Create a BoundaryInt mutator.

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Replace 1 or 2 bytes at a random position with a boundary value.

Args: input: The input bytes to mutate.; rng: PRNG state (advanced in-place).

`MutatorChain`

struct MutatorChain

Randomly selects one mutator from a weighted list and applies it.

Weights are cumulative; selection is O(n) weighted-random using the total weight sum.

Example:

var chain = default_mutator()
var out = chain.mutate(Span[UInt8, _](input), rng)

Implements Movable

`init`

def __init__(out self, ids: List[Int], weights: List[UInt32], corpus: List[List[UInt8]] = List())

Construct a chain with the given mutator IDs and weights.

Args: ids: List of MutatorId.* constants.; weights: Parallel list of positive integer weights.; corpus: Optional corpus snapshot for Splice (may be empty).

`update_corpus`

def update_corpus(mut self, corpus: List[List[UInt8]])

Refresh the corpus snapshot used by the Splice mutator.

Args: corpus: Updated corpus seeds.

`mutate`

def mutate(self, input: Span[UInt8], mut rng: Xoshiro256) -> List[UInt8]

Pick a mutator by weighted random draw and apply it.

Args: input: Input bytes to mutate.; rng: PRNG state (advanced in-place).

Functions

`default_mutator`

def default_mutator() -> MutatorChain

Return the standard weighted mutator chain used by fuzz().

Default weights:

BitFlip: 30
ByteSubstitution: 25
ByteInsertion: 15
ByteDeletion: 10
BlockDuplication: 10
Splice: 5
BoundaryInt: 5