alktunnels/fuzz

alktunnels fuzzing

libFuzzer targets for alktunnels' untrusted-input surfaces (see docs/research/fuzzing.md for the full rationale, scope decision, and campaign plan; the tooling/corpus/runner/no-CI posture is inherited from alkcall's docs/research/fuzzing.md).

Layout

• fuzz_targets/ — one binary per target; thin fuzz_target! wrappers.
• shared/ — the invariant logic, as a plain library so normal cargo test (stable toolchain) can replay the committed corpora through the same invariants (fuzz/shared/src/*.rs #[cfg(test)] modules; quinn's CI pattern). The fuzz binaries are nightly-only; the shared crate is stable-clean.
• corpus/<target>/ — committed hand-made seeds (regenerate with python3 fuzz/gen_fuzz_seeds.py from the repo root). Grown corpora and artifacts are gitignored.
• run-detached.sh — mandatory runner for agent sessions: wraps cargo fuzz run in setsid + nohup + log redirection so an OOM in a target can never take down the agent host (fuzzing.md §5).
• json.dict — JSON token dictionary for the params target (transferred from alkcall).

Targets

Target	Drives	Invariants
datagram_codec	DatagramReader::feed / frame_datagram (src/wire.rs)	no-panic; infallible decode; yielded datagrams ≤ MAX_DATAGRAM_LEN; F-2 sentinel layering (empty datagram ≠ EOF, only from [00 00] headers); splitting transparency (3-byte slices == whole-input feed); re-frame round-trip; oversize rejection exactly at the bound; is_mid_datagram tracks framing; decoder-state retained-bytes bound
params_parse	TunnelParams / TunnelDirectParams / TunnelForwardedParams / SubstrateAddr serde parses + parse_listen_reply / listen_reply_fields / establishment_reason (src/params.rs)	no-panic on raw bytes and structured Values; clean typed failure only; round-trip for valid params; listen: 0 pin; loud/lenient projection-pair agreement; pinned establishment-reason table
session_pumps	op sequences (SessionSequence) over one live channels stack per exec (MuxRunner → real demux → ChannelManager per side; the TunnelSession data-plane mirrors — codec plane + pump_bidi stream planes)	no-panic / no-wedge (5 s reconcile bound); two-pump shutdown-on-completion; lossless p2c copy count; EOF-sentinel teardown semantics (drain-before-EOF, map empties); FIFO datagram reconciliation (framing-walk model); pending backlog ≤ routed-batch remainder (the §1.3 bound); decoder-state retained-bytes bound re-asserted per op; monotonic counters

Commands

cargo fuzz build and cargo fuzz run must be executed with fuzz/ (or deeper) as the working directory so rustup selects the pinned nightly toolchain — the detached runner handles that itself.

# build (nightly, pinned by rust-toolchain.toml inside fuzz/; run from fuzz/)
cargo fuzz build

# agent sessions: detached campaign (never foreground; CWD-independent)
FUZZ_RUNTIME_SECS=600 fuzz/run-detached.sh datagram_codec -max_len=65536
FUZZ_RUNTIME_SECS=600 fuzz/run-detached.sh params_parse -dict=json.dict -use_value_profile=1
FUZZ_RUNTIME_SECS=600 fuzz/run-detached.sh session_pumps -max_len=4096 -use_value_profile=1

# corpus replay through the invariants (stable toolchain, no nightly)
cargo test --manifest-path fuzz/shared/Cargo.toml

# coverage
cargo fuzz coverage <target>

The fuzz workspace is excluded from the main workspace and from the published package (exclude in the root Cargo.toml); it pins its own nightly toolchain via rust-toolchain.toml and does not affect the crate's stable MSRV.