planetis-m/skills/nim-fuzzing

Nim Fuzzing

This skill covers wiring code to libFuzzer — harness structure, compilation, corpus, mutators, and crash triage. It does NOT cover writing the code under test.

Rules

Harness structure: the two required procs

Every Nim fuzz target needs these two exported procs:

proc initialize(): cint {.cdecl, exportc: "LLVMFuzzerInitialize".} =
  {.emit: "N_CDECL(void, NimMain)(void); NimMain();".}
 
proc testOneInput(data: ptr UncheckedArray[byte], len: int): cint {.
    cdecl, exportc: "LLVMFuzzerTestOneInput", raises: [].} =
  result = 0
  # exercise code under test with data[0..<len]

initialize is called once at startup. It bootstraps Nim's runtime via NimMain(). Without it the target will segfault before any inputs are tested.

testOneInput is called by libFuzzer with a raw byte buffer. It must return

1. Use raises: [] — any uncaught exception will crash the fuzzer process,

which is treated as a finding.

Minimum working example

proc fuzzMe(data: openArray[byte]): bool =
  result = data.len >= 3 and
    data[0].char == 'F' and
    data[1].char == 'U' and
    data[2].char == 'Z' and
    data[3].char == 'Z' # out-of-bounds when data.len == 3
 
proc initialize(): cint {.cdecl, exportc: "LLVMFuzzerInitialize".} =
  {.emit: "N_CDECL(void, NimMain)(void); NimMain();".}
 
proc testOneInput(data: ptr UncheckedArray[byte], len: int): cint {.
    cdecl, exportc: "LLVMFuzzerTestOneInput", raises: [].} =
  result = 0
  discard fuzzMe(data.toOpenArray(0, len-1))

Data extraction patterns

How to convert ptr UncheckedArray[byte] + len to Nim types:

For the copyMem patterns, the fuzzer-provided buffer is a flat byte array. Check the length before taking element addresses or copying bytes.

Error handling in the harness

Compile fuzz targets with --panics:on. This turns Defect subtypes (IndexDefect, OverflowDefect, AssertionDefect, etc.) into non-catchable panics that immediately crash the process — which libFuzzer interprets as a finding. You don't need a manual except Defect block.

testOneInput must have raises: []. Catch only specific expected error types (e.g., except ValueError) and let everything else crash. Never use except Exception — it catches Defect even with panics off, masking real bugs. Bare except is equivalent to except CatchableError and does not catch Defect.

proc testOneInput(data: ptr UncheckedArray[byte], len: int): cint {.
    cdecl, exportc: "LLVMFuzzerTestOneInput", raises: [].} =
  result = 0
  if len > 0:
    var input = newString(len)
    copyMem(addr input[0], data, len)
    try:
      parseMyFormat(input)
    except ValueError:
      discard          # expected rejection
  # Defects crash the process — no catch needed with --panics:on

Compilation

Build config file (recommended)

Name the config file <harnessname>.nims (e.g. my_fuzzer.nims for my_fuzzer.nim) or config.nims.

--cc: clang
--panics: on
--define: noSignalHandler
--define: useMalloc
--noMain: on
--passC: "-fsanitize=fuzzer,address,undefined"
--passL: "-fsanitize=fuzzer,address,undefined"
--debugger: native

Corpus management

libFuzzer needs a corpus directory. Start with at least one seed input:

mkdir corpus
echo "GET / HTTP/1.1" > corpus/seed_01

The fuzzer stores new coverage-discovering inputs into the corpus automatically. When restarting, pass the corpus directory to retain progress:

./my_fuzzer corpus/

Seed quality

Provide 1–5 small, valid inputs. Invalid seeds waste cycles. For protocol fuzzers, seed with minimal valid examples. For binary formats, use small well-formed files. Seeds should exercise the main code path, not degenerate cases.

Running the fuzzer

Basic run:

./my_fuzzer corpus/

Useful flags (passed as CLI args to the compiled binary, not to nim c):

Example:

./my_fuzzer -fork=4 -ignore_crashes=1 -max_len=65536 corpus/

Standalone mode: reproduce crashes without libFuzzer

Build a standalone binary that replays inputs from files instead of linking libFuzzer. Add this at the bottom of the harness file:

when defined(fuzzStandalone):
  import std/[cmdline, syncio]
  stderr.write "StandaloneFuzzTarget: running " & $paramCount() & " inputs\n"
  for i in 1..paramCount():
    var buf = readFile(paramStr(i))
    discard testOneInput(cast[ptr UncheckedArray[byte]](cstring(buf)), buf.len)

Compile:

nim c -d:fuzzStandalone my_fuzzer.nim

Run against a crash input:

./my_fuzzer crash_input

The standalone binary reads each command-line argument as a file path, feeds its contents to testOneInput, and prints progress to stderr. Use this to reproduce findings without the full fuzzer engine.

Structure-aware fuzzing with custom mutators

For structured formats (protocols, serialized types, typed data), raw byte mutation is inefficient — most mutations produce invalid inputs rejected early. Add customMutator and optionally customCrossOver to mutate at the domain level.

customMutator signature

proc customMutator(data: ptr UncheckedArray[byte], len, maxLen: int,
    seed: int64): int {.
    cdecl, exportc: "LLVMFuzzerCustomMutator", raises: [].}

Called by libFuzzer to mutate data in-place. Must:

• Read the typed structure from data[0..<len]
• Apply a type-aware mutation (change/add/delete element, shuffle, flip bit)
• Write the result back into data[0..<maxLen]
• Return the new byte length (≤ maxLen)

Use the seed for deterministic randomness. On failure, return the original len.

Defining customMutator replaces libFuzzer's built-in mutations. Include operations that change, add, and remove data.

customCrossOver signature

proc customCrossOver(data1: ptr UncheckedArray[byte], len1: int,
    data2: ptr UncheckedArray[byte], len2: int,
    res: ptr UncheckedArray[byte], maxResLen: int,
    seed: int64): int {.
    cdecl, exportc: "LLVMFuzzerCustomCrossOver", raises: [].}

Combines two inputs into res. Same constraints as customMutator.

When to add custom mutators

Add a custom mutator when:

• The format has a clear structural boundary (fields, chunks, typed elements)
• Raw byte mutation mostly produces invalid inputs
• Coverage stalls despite a good seed corpus

Start without one. Add only when the fuzzer fails to make progress.

See references/structure_aware_fuzzing.md for a worked example.

Crash triage workflow

1. Save the artifact. libFuzzer writes crash inputs as files named

crash-<hash>, slow-unit-<hash>, etc. Copy them to a permanent location.

1. Reproduce with the standalone binary. Compile with -d:fuzzStandalone and

feed the crash input. Confirm the crash is deterministic.

1. Minimize the input. Run the fuzzer with -minimize_crash=1:

``bash ./my_fuzzer -minimize_crash=1 crash_input ``

This produces a smaller, still-crashing input.

1. Isolate with sanitizers. Rebuild with only one sanitizer at a time

to understand the bug type:

```bash # ASan only nim c --cc:clang -d:noSignalHandler -d:useMalloc --noMain:on \ --passC:"-fsanitize=fuzzer,address" \ --passL:"-fsanitize=fuzzer,address" -g my_fuzzer.nim

# UBSan only nim c --cc:clang -d:noSignalHandler -d:useMalloc --noMain:on \ --passC:"-fsanitize=fuzzer,undefined" \ --passL:"-fsanitize=fuzzer,undefined" -g my_fuzzer.nim ```

1. Write a minimal Nim reproducer. Extract the failing operation into a

standalone .nim file with a doAssert-based test. Keep the original crash input and sanitizer report as evidence.

1. Classify findings using the framework from the nim-defect-analysis

skill. A fuzzer finding with an artifact and sanitizer report is CONFIRMED.

Coverage reporting

Build with Clang source-based coverage:

nim c --cc:clang --panics:on --noMain:on \
  -d:noSignalHandler -d:useMalloc \
  --passC:"-fsanitize=fuzzer -fprofile-instr-generate -fcoverage-mapping" \
  --passL:"-fsanitize=fuzzer -fprofile-instr-generate -fcoverage-mapping" \
  my_fuzzer.nim
 
LLVM_PROFILE_FILE="fuzz.profraw" ./my_fuzzer -runs=10000 corpus/
llvm-profdata merge -sparse fuzz.profraw -o fuzz.profdata
llvm-cov show ./my_fuzzer -instr-profile=fuzz.profdata --format=html \
  --output-dir=coverage_report

Workflow

1. Identify the fuzz target. Pick a function or module that parses,

deserializes, or processes untrusted byte input. It must be callable from a single entry point.

1. Set up project files. Create the harness .nim file with

initialize and testOneInput. Create a <harnessname>.nims config with the fuzzer flags. Optionally add the fuzzStandalone replay block at the bottom of the harness.

1. Create a seed corpus. Provide 1–5 minimal valid inputs in corpus/.

1. Build and smoke-test. Compile with the fuzzer config. Run with

-runs=1 to verify the harness starts and processes a seed.

1. Start fuzzing. Run with -fork=N for parallel workers. Let it run.

Check ls corpus/ periodically to see new coverage-discovering inputs.

1. Inspect for slow units. Files named slow-unit-* indicate inputs

that take unusually long. Review whether the code has algorithmic complexity issues.

1. Triage crashes. For each crash artifact, follow the crash triage

steps above: confirm, minimize, isolate sanitizer, write reproducer.

1. Iterate. If coverage stalls and the format is structured, add a

custom mutator. If the harness rejects too many inputs, relax validation in the fuzz path.

Common Mistakes