nim-fuzzing

Files (4)

• SKILL.md
• protocol_fuzzer.md · references/
• simple_byte_target.md · references/
• structure_aware_fuzzing.md · references/

SKILL.md (first lines)

# 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:

```nim
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
0. Use `raises: []` — any uncaught exception will crash the fuzzer process,
which is treated as a finding.

## Minimum working example

```nim
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:

| Target format          | Extraction code |
|------------------------|-----------------|
| raw byte buffer        | `data.toOpenArray(0, len-1)` |
| string                 | `var s = newString(len); if len > 0: copyMem(addr s[0], data, len)` |
| seq[T] via copyMem     | `let n = len div sizeof(T); var s = newSeq[T](n); if n > 0: copyMem(addr s[0], data, n * sizeof(T))` |
| plain fixed-layout type | `if len >= sizeof(T): var value: T; copyMem(addr value, data, sizeof(T))` |

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`.

```nim
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`.

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

| Flag                   | Purpose |
|------------------------|---------|
| `--cc: clang`          | libFuzzer requires Clang. |
| `--panics: on`         | Defects crash the process immediately. |
| `--noMain: on`         | libFuzzer provides its own `main`. |
| `--define: noSignalHandler` | Prevents Nim's signal handler from masking crashes before ASan. |
| `--define: useMalloc`  | Uses C malloc so ASan tracks all allocations. |
| `--passC:"-fsanitize=fuzzer,address,undefined"` | Enables libFuzzer + ASan + UBSan. |
| `--passL:"-fsanitize=fuzzer,address,undefined"` | Links the sanitizer runtimes. |
| `--debugger: native`   | Embeds DWARF debug info in crash reports. |

## Corpus management

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

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template