test(fuzz): fuzz the guest-facing parsers, and fix what it found (#169)

Adds fuzzing for the parsers that read guest-controlled bytes — the control-channel frame decoder, the userspace vsock state machine, the split-virtqueue reader, and the 9P server together with the transport beneath it. Five `cargo fuzz` targets share their harness bodies with `tests/fuzz_corpus.rs`, which replays every committed seed and crash artifact on stable inside a plain `cargo test`. Only that replay blocks a merge: libFuzzer needs nightly and its search is non-deterministic, so a run that finds a bug says nothing about whether the change under review introduced it. Discovery runs weekly and on demand instead (ADR-0012).

The fuzzing found seven guest-reachable defects in shipped code, all fixed here. A guest could kill the VMM process for every sandbox it hosts with two MMIO writes — activating a virtqueue it never sized, so every ring index divided by zero. It could escape the 9P shared directory, because `Tlcreate` and `Tmkdir` validated the parent fid and then joined an unfiltered guest name onto it. It could hang the host in a descriptor cycle, size 4 GiB host allocations from a descriptor length or a `Tread` count, overflow ring-address arithmetic under `overflow-checks`, and desynchronize a 9P mount with `Rread`, `Rreaddir`, or `Rwalk` replies exceeding the negotiated `msize`. The same allocation and overflow bugs sat in the userspace vsock TX path, and neither device clamped `QueueNum` to the size it advertises.

**One wire-path behavior change:** a `Tversion` asking for less than 4 KiB is now refused with `Rerror`/`EINVAL` rather than served. The device derives its request-assembly budget from `msize`, and a budget that small starves every later request including the `Tversion` that would renegotiate. Raising the client's value instead would break the negotiation the other way, since the reply commits the server not to exceed what the client can receive. Linux's 9P client rejects `msize < 4096` at mount time, so a conforming mount never reaches it.

The gate checks that it is still covering something. Each harness reports the work it performed, and every seed must clear a floor — a harness that reaches none of its parser returns cleanly and replays green, which is exactly how the `nine_p_transport` target shipped inert in an earlier revision of this branch and was caught by review rather than by CI. The floor applies where a harness drives its parser from a loop over the fuzzer's bytes, since that is what a consumption bug can starve; the other two hand the raw input straight in and cannot go inert that way. Discovered inputs go to a gitignored `fuzz/corpus-run/`, so `fuzz/corpus/` stays the curated set the floor polices.

Every fix is verified by reverting it and requiring the gate to fail: nine of nine caught, five by the corpus and four by unit-test oracles, plus the floor's own check. Two fixes cannot be pinned by any input — a 4 GiB `alloc_zeroed` is mapped lazily and never faults, and an out-of-table descriptor index reads zeroed memory and ends the walk indistinguishably — so both carry oracles instead. Fuzzing pins crashes; everything else needs an assertion.

Validated on Linux at rustc 1.98: fmt, clippy, workspace tests, corpus replay, and all five targets clean with no artifacts.

Closes #155.

Author: cspinetta

.github/workflows/e2e.yml

@@ -253,7 +253,7 @@ jobs:
           # --no-fail-fast collects every result instead of stopping at the first
           # failure.
           #
-          # Two exclusions, both deliberate:
+          # The exclusions, each deliberate:
           #
           # pty_command_not_allowed asserts the guest rejects a non-allowlisted
           # program, but the allowlist loads at guest boot from a file only the

.github/workflows/fuzz.yml

@@ -0,0 +1,104 @@
+name: Fuzz
+
+# Coverage-guided fuzzing of the parsers that read guest-controlled bytes.
+#
+# Not a required status check, and deliberately not run on pull requests. A
+# fuzzer that finds a new bug on an unrelated change blocks that change, which
+# trains people to route around the gate; and libFuzzer needs a nightly
+# toolchain, which breaks on its own schedule and has no business on the path
+# that gates a merge. The pull-request gate instead replays every committed
+# corpus input and crash artifact through the same harnesses on stable, inside
+# `cargo test` (`tests/fuzz_corpus.rs`) — so anything found here is checked on
+# every change once its input is committed.
+#
+# When a run fails, download the `fuzz-artifacts` bundle, commit the crashing
+# input under `fuzz/artifacts/<target>/` together with the parser fix, and the
+# replay test keeps it fixed.
+
+on:
+  workflow_dispatch:
+    inputs:
+      max_total_time:
+        description: 'Seconds to fuzz each target'
+        required: false
+        default: '300'
+  schedule:
+    # Sundays 04:00 UTC. Fuzzing costs only runner minutes, so unlike the
+    # credentialed agent lane this one can run unattended; a weekly cadence is
+    # enough for a parser surface that changes rarely.
+    - cron: '0 4 * * 0'
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+permissions:
+  contents: read
+
+concurrency:
+  group: fuzz
+  cancel-in-progress: false
+
+jobs:
+  fuzz:
+    name: Fuzz ${{ matrix.target }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # One job per target so a crash in one still leaves the others' results
+        # readable, and so each gets the full budget rather than a share of it.
+        target: [vsock_frame, vsock_packet, virtqueue, nine_p, nine_p_transport]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # libFuzzer's `fuzz_target!` and the sanitizer instrumentation
+      # `cargo fuzz` passes are nightly-only. This is why fuzzing lives here and
+      # not in the stable lanes.
+      - name: Install Rust nightly
+        uses: dtolnay/rust-toolchain@nightly
+
+      - name: Install cargo-fuzz
+        uses: taiki-e/install-action@82cd3e7658a6f96c86c0234aeeda1748937cb0a1  # v2
+        with:
+          tool: cargo-fuzz
+
+      - name: Cache cargo registry + build
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4  # v2.9.1
+        with:
+          workspaces: |
+            .
+            fuzz
+          shared-key: fuzz-${{ matrix.target }}
+
+      - name: Fuzz ${{ matrix.target }}
+        run: |
+          # -rss_limit_mb bounds the harness's own footprint: an allocation
+          # sized from a guest-supplied length is exactly the class of bug this
+          # is looking for, so it must report rather than OOM the runner.
+          # -max_len keeps inputs in the range the parsers actually see on the
+          # wire, so the budget goes into structure rather than length.
+          # Two corpus directories: libFuzzer writes what it discovers to the
+          # first and reads the second without modifying it, so the committed
+          # seed set stays exactly what `tests/fuzz_corpus.rs` polices.
+          mkdir -p fuzz/corpus-run/${{ matrix.target }}
+          cargo fuzz run ${{ matrix.target }} \
+            fuzz/corpus-run/${{ matrix.target }} \
+            fuzz/corpus/${{ matrix.target }} -- \
+            -max_total_time=${{ github.event.inputs.max_total_time || '300' }} \
+            -rss_limit_mb=2048 \
+            -max_len=65536 \
+            -print_final_stats=1
+
+      # `if: failure()` on purpose: a crash is the only case with an artifact to
+      # collect, and it is the case where the reproducer must not be lost.
+      - name: Upload crash artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fuzz-artifacts-${{ matrix.target }}
+          path: fuzz/artifacts/
+          if-no-files-found: ignore

.gitignore

@@ -1,4 +1,15 @@
 /target
+# cargo-fuzz build output. `fuzz/corpus/` and `fuzz/artifacts/` are tracked on
+# purpose: the corpus is the curated seed set and the artifacts are crash
+# regressions that `tests/fuzz_corpus.rs` replays on every run.
+/fuzz/target
+/fuzz/coverage
+# Where a fuzz run accumulates what it discovers. libFuzzer writes new units to
+# the first corpus directory it is given, so runs are pointed here and
+# `fuzz/corpus/` stays exactly the seed set the replay gate polices — a
+# discovered input is kept for reaching new coverage, which is not the same
+# property the gate's work floor checks.
+/fuzz/corpus-run
 /artifacts
 /tmp
 package-lock.json

AGENTS.md

@@ -862,6 +862,40 @@ ANTHROPIC_API_KEY=... cargo test --test e2e_service_mode -- --ignored --test-thr
 ANTHROPIC_API_KEY=... cargo test --test e2e_agent_mcp -- --ignored --test-threads=1
 ```
 
+### Fuzzing the guest-facing parsers
+
+Several host-side parsers read bytes a guest chooses: the control-channel frame decoder (`void-box-protocol` framing plus the multiplex request-id prefix), the userspace vsock connection state machine, the split-virtqueue reader that walks descriptor chains out of guest memory, and the 9P server together with the transport beneath it. Their harnesses live in `src/fuzz.rs`, and two callers drive the same bodies — `cargo fuzz` and the replay gate.
+
+The merge gate replays them. `tests/fuzz_corpus.rs` runs every file under `fuzz/corpus/<target>/` and `fuzz/artifacts/<target>/` through its harness on stable, as part of a plain `cargo test`. It is deterministic and costs milliseconds, so it needs no special invocation.
+
+Discovery is out of band. `cargo fuzz` needs a nightly toolchain, and a search that finds a new bug on an unrelated change would block that change, so it runs weekly and on demand in `.github/workflows/fuzz.yml` — never on a pull request (ADR-0012). To run it locally:
+
+```bash
+rustup toolchain install nightly
+cargo install cargo-fuzz
+# libfuzzer-sys builds the libFuzzer runtime with cc, so a C++ compiler must be
+# on PATH as `c++` (Fedora: gcc-c++; Debian/Ubuntu: g++).
+# libFuzzer writes what it discovers to the first corpus directory and reads the
+# rest without modifying them, so runs go to `fuzz/corpus-run/` (gitignored) and
+# `fuzz/corpus/` stays the curated seed set.
+mkdir -p fuzz/corpus-run/vsock_frame
+cargo +nightly fuzz run vsock_frame fuzz/corpus-run/vsock_frame fuzz/corpus/vsock_frame \
+  -- -max_total_time=60 -rss_limit_mb=2048
+# targets: vsock_frame, vsock_packet, virtqueue, nine_p, nine_p_transport
+```
+
+Do not commit what a run accumulates in `fuzz/corpus-run/`. libFuzzer keeps an input because it reached new coverage, which is not the property the replay gate checks, so those inputs would be judged against a work floor written for curated seeds. Promote one deliberately when it covers a shape worth keeping: move it into `fuzz/corpus/<target>/` and give it a name that says what it covers.
+
+`nine_p` drives the 9P message parser directly; `nine_p_transport` drives the device through its MMIO registers and guest memory, covering the queue programming and descriptor walk beneath it. The split matters: the transport parses guest data of its own — descriptor lengths size host allocations and `next` indices steer the walk — and a harness aimed at the message parser never reaches it.
+
+When a run crashes, `cargo fuzz` writes the input under `fuzz/artifacts/<target>/`. Commit that file **together with the parser fix** — the replay test then keeps the bug fixed for everyone. Never commit a crashing input ahead of its fix: it reds the gate for every unrelated change.
+
+Adding a target means adding a `[[bin]]` to `fuzz/Cargo.toml`, a harness body in `src/fuzz.rs`, an arm in `tests/fuzz_corpus.rs`, at least one seed under `fuzz/corpus/<target>/`, and a work floor in `work_floor`. `every_fuzz_target_is_replayed` fails if any of the middle three is missing, so a target cannot end up fuzzed but unguarded.
+
+A harness returns the units of work it performed — frames decoded, packets routed, chains popped, requests dispatched, registers written — and the replay test holds every seed to that target's floor. Panic-freedom alone does not show a harness still reaches its parser: one that reaches nothing returns cleanly and replays green, so the count is what makes an inert target visible. A floor only bites where the harness drives its parser from a loop over the fuzzer's bytes, because that is what a consumption bug can starve; a harness that hands the raw input straight to its parser cannot go inert that way, and takes a floor of zero. Set a floor from what the seeds actually do, with enough margin that trimming one does not trip it, and check it against the negative-space seeds — an input written to prove the parser *rejects* something does zero units of successful work by construction. The floor applies to seeds only; a crash artifact may reach its bug before doing any countable work. Assert nothing about the count inside a harness body — under `cargo fuzz` an input that does no work is an ordinary outcome, and an assertion there would be reported as a crash.
+
+A harness parameterizes itself from the raw input through a hand-rolled byte reader rather than the `arbitrary` crate. The committed corpus is tied to the exact byte-consumption order, and a crate upgrade that reorders its reads would silently repoint every seed at a different scenario.
+
 ### Test initramfs and BusyBox
 
 `scripts/build_test_image.sh` builds a minimal initramfs with `guest-agent`