alksocks/docs/research/fuzzing.md

# Fuzzing alksocks: Research and Plan

**Status:** adopted; wave-1 targets (`datagram_codec`, `rfc1928_codec`,
`params_parse`) implemented, seeds committed, campaigns run clean (§7).
Wave 2 (`session_pumps`) deferred to post-0.1 (§4). Campaigns run via the
detached runner (§6): **never as a foreground child of an agent
session** (§5).
**Date:** 2026-09-28
**Upstream precedent:** `/workspace/@alkdev/alkcall/docs/research/fuzzing.md`
(one real finding: the duplicate adopt/open destroying the live channel,
fixed in 0.8.1) and
`/workspace/@alkdev/alktunnels/docs/research/fuzzing.md` (wave-1/wave-2
adopted, six harness-model findings, no crate bugs). Tooling, corpus
policy, runner, and the no-hosted-CI posture are inherited from those
docs wholesale; this doc does not re-litigate them. It scopes them to
this crate.

---

## 1. Should this crate be fuzzed?

**Yes, and alkcall's fuzz doc already assigned this to us.** Three
lines, all pointing the same way:

1. **alkcall's fuzz doc §5 named this crate's surfaces as downstream
   targets.** Its "non-surfaces (deliberately)" note ends: *the channels
   layer carries opaque `Bytes` and the handler owns sub-stream framing
   (ADR-035); those downstream parsers are downstream crates' fuzz
   targets. Our `src/wire.rs` datagram codec **is** that named
   downstream target (shaped on alktunnels' codec, which alktunnels
   fuzzed as its wave-1 first target; the same assignment, landed
   here). Fuzzing it completes the upstream scope rather than
   duplicating it.

2. **We own an entire RFC handshake state machine fed by arbitrary
   peers, on both sides.** The targeted fork (`src/rfc1928/`, ADR-013)
   is fully owned code with project conventions applying unconditionally
   (convention 17). Its parse surfaces, namely `read_address` (the address
   codec), `negotiate_auth` (method negotiation), `read_command` (the
   command encoding), `read_username_password` (RFC 1929) and the client's
   `read_request_reply`, are fed bytes produced by **arbitrary peers**
   in both directions: the producer drives the server typestate against
   consumer bytes, and the consumer sessions + front doors drive the
   client path against producer bytes. An RFC state machine is exactly
   the shape the quinn-proto CVE class (RUSTSEC-2026-0037, remote DoS
   via `unwrap()` in parsing, the upstream doc §1's strongest
   datapoint) lives in: hand-rolled state transitions, length arithmetic,
   and boundary handling. One fork-carried correction is already of this
   class: upstream's `ReplyError::from_u8` ended in `unreachable!()`
   for unassigned reply codes; the fork made it a typed catch-all (the
   review's F-1) precisely because the value comes off the wire. A fuzz
   target is how that posture is *demonstrated* across the whole codec,
   not believed spotwise.

3. **The differential suite's blind spot is exactly fuzzing's
   strength.** `tests/rfc1928-differential.rs` pins our fork's behavior
   against the reference checkout on *valid* RFC edge cases, curated
   inputs a human thought of. What no example-based suite provides:
   random *malformed* input exploration (the panic-on-attacker-bytes
   class), stateful interleavings, and resource-bound assertions under
   adversarial sequences. The fork is about to be published (0.1) as
   wire-stable; after that, targets are regression protection for a
   frozen surface (cheapest now).

**The honest caveat** (mirroring both upstream docs): the crate has no
`unsafe` (checked at the crate root), the codec's decode direction is
infallible by contract (oversize rejected at frame time; the decoder
buffers, bounded by the u16 declared length), the RFC 1929 length
fields are one byte each (the attacker-controlled byte cannot ask for
more than 255), and the fork's error vocabulary is typed end-to-end
(the `unreachable!()`/`unwrap` sweep already ran in review 001).
Expected yield is therefore not memory-safety bugs; it is (a) the
demonstration that the infallibility/no-panic contracts hold on
adversarial input, (b) the decoder-state bound assertion (alktunnels
§1.3's finding class: a peer chunk amplifying into unbounded state),
and (c) regression protection for the published wire surface. If the
campaigns find nothing, that is the successful-negative-result posture
alkcall's §1 codified.

## 2. Toolchain (inherited, not re-decided)

Identical to both upstream docs: **cargo-fuzz 0.13.2 + `arbitrary`
1.4.x**, nightly confined to the `fuzz/` subtree via
`fuzz/rust-toolchain.toml`, the crate itself stays stable at MSRV 1.88.
AFL optional/deferred; bolero deferred (the async-friction argument);
libafl/honggfuzz/OSS-Fuzz not adopted. Sanitizer: `--sanitizer=address`
with debug assertions (cargo-fuzz defaults); no MSAN (no `unsafe` in
this crate).

**Layout (the upstream pattern, load-bearing):**

```
fuzz/
├── Cargo.toml            alksocks-fuzz (nightly-only bins; own [workspace])
├── rust-toolchain.toml   pins nightly for this subtree only
├── fuzz_targets/         thin fuzz_target! wrappers (3-line each)
│   ├── datagram_codec.rs
│   ├── rfc1928_codec.rs
│   └── params_parse.rs
├── shared/               alksocks-fuzz-shared (STABLE-toolchain library)
│   └── src/…             invariant logic + corpus replay (§3)
├── corpus/<target>/      committed hand-made seeds (§3)
├── gen_fuzz_seeds.py     deterministic seed generator (quiche pattern)
├── run-detached.sh       §6 detached runner (CWD-independent)
└── README.md
```

- **Invariant logic lives in `fuzz/shared/`**, not inline in the target
  binaries: the stable-toolchain corpus replay
  (`cargo test --manifest-path fuzz/shared/Cargo.toml`) runs the SAME
  invariant functions the fuzzer runs, on stable, in the release
  verification checklist. This is alkcall §7.2 tier-3's deliverable
  minus automation; per alkcall §7.9 (adopted here identically) this
  repo has no hosted CI and will not get one. Corpus replay as plain
  `cargo test` is the fuzz gate.
- **Root `Cargo.toml` needs the explicit `[workspace]` table**
  (`members = ["."]`, `exclude = ["fuzz"]`) and `"fuzz/"` on the
  publish exclude list; without it cargo auto-discovers `fuzz/shared/`
  into the main workspace and the MSRV toolchain tries to build the
  nightly-consumed dev-deps (the exact failure alkcall hit).
- **Corpus policy:** commit hand-made seeds, gitignore grown corpora
  (quinn/h2 model). Seeds per target listed in §3.

## 3. Invariants by target

### 3.1 `datagram_codec` (the ASSOCIATE frame codec, `src/wire.rs`)

Input: raw `&[u8]`. Drives `DatagramReader::feed` + `frame` /
`frame_inner` / `addr_encoding_len`. This is the alktunnels wave-1
`datagram_codec` target's shape, scoped to this crate's codec (the
frame carries `addr + data` inner bytes and decodes to
`(TargetAddr, payload)`, not opaque datagrams; the invariants follow
the inner structure). Invariants:

- **no-panic on any byte sequence** (the baseline).
- **infallible reassembly**: `feed` never errors at the reassembly
  layer; every frame completes as `Ok` or as one of the four
  *decode-garbage* `WireError` variants (`EmptyFrame` / `BadAtyp` /
  `ShortAddress` / `DomainNotUtf8`); `Oversize`/`Address` are
  unreachable from `feed` (they are frame-time errors; a shape
  assertion pins the partition).
- **empty-payload F-2 layering**: a decoded `(addr, empty)` pair comes
  only from a real `[len][addr]` frame whose payload region is empty,
  never invented by the codec; a `len == 0` frame (zero inner bytes)
  always surfaces as `EmptyFrame`, never as an empty datagram.
- **bad-ATYP loudness**: every `BadAtyp` error's byte is the actual
  first inner byte of its frame, and it is not one of the three
  RFC ATYPs (the post-reply control-byte semantic: any non-ATYP
  control byte must fail loud, never guess).
- **consumption accounting / splitting transparency**: feeding in
  3-byte slices yields exactly the datagram sequence the whole-input
  feed yields (both directions' framing is transparent to splitting).
- **round-trip**: every decoded datagram re-frames via `frame` (or
  `frame_inner` over its inner bytes) and re-decodes to itself;
  well-framed input re-frames byte-for-byte.
- **joint bound**: `frame` rejects iff
  `addr_encoding_len(addr) + payload.len() > MAX_INNER_LEN`, echoing
  `(total, max)` exactly, including the max-domain case where a legal
  RFC payload (65507 to a 255-char domain = 65766) must reject (the
  joint-bound reason the codec exists); `frame_inner` rejects iff
  `inner.len() > MAX_INNER_LEN`. The `checked_add` path (payload
  overflow wrapping the u16) rejects, never wraps.
- **decoder-state bound**: `buf` + in-flight `current` stay bounded by
  the fed chunk size plus one frame (header + `MAX_INNER_LEN`) on any
  adversarial input, the alktunnels §1.3 finding-class assertion
  (state must never grow with input). The crate's `DatagramReader`
  exposes this via `is_mid_frame()` + a new `retained_bytes()`
  diagnostic (the alktunnels `retained_bytes()` posture).

Seeds: valid frames (all three ATYPs), truncation at every prefix
length, `len = 0` / `len = MAX` / `len = MAX+1`, empty payloads,
batched frames, split frames, garbage ATYP, non-UTF-8 domains, the
65766 joint-bound shape, deep batch/split mixes.

### 3.2 `rfc1928_codec` (the forked RFC 1928 core, `src/rfc1928/`)

Input: raw `&[u8]`. Drives the fork's byte-level parsers over tokio
duplex streams (the in-tree test shape, mock bytes, no sockets):

- **`read_address`** (the address codec, both directions consume it):
  no-panic on any ATYP/bytes; every failure is a typed `AddrError`
  (`IncorrectAddressType` for unknown ATYP, the F-1 class, already
  fixed; never a panic); round-trip for every well-formed address
  (`to_be_bytes` → parse → equal).
- **the server handshake** (`negotiate_auth` → `read_command` over a
  duplex, `accept_no_auth` + `read_command`): no-panic on any byte
  sequence; every malformed shape is a typed `SocksServerError`
  (version mismatch, unacceptable method, unknown command, bad addr);
  a well-formed negotiation + CONNECT request parses to the exact
  command + target.
- **the client reply path** (`read_request_reply`): no-panic on any
  server byte sequence; unassigned reply codes map to the
  `GeneralFailure` catch-all (the F-1 pin, never `unreachable!()`);
  version mismatches are typed errors.
- **`parse_udp_request`** (the RFC UDP header codec, front doors only
  but still wire-reachable): no-panic; garbage RSV / unknown ATYP /
  truncation are typed `UdpHeaderError`s; round-trip with
  `new_udp_header`.
- **auth sub-handshakes** (`read_username_password`, RFC 1929):
  no-panic; the u8 length fields bound allocations structurally
  (≤ 255 bytes, asserted); empty username/password are typed errors;
  round-trip accept/reject status bytes.
- **`ReplyError::from_u8`** full-domain table: every `u8` maps, no
  panic, unassigned → catch-all (the direct probe of the F-1 class).

This is the wave-1 target of highest value: it is the entire RFC 1928
byte surface, fed attacker bytes from both protocol directions, and the
fork is owned code whose behavior the differential suite pins only on
valid inputs.

Seeds: valid handshakes (no-auth / password), version mismatches,
truncations at every prefix length of each message shape, unknown
methods/commands/ATYPs, empty and 255-byte domains, non-UTF-8 domains,
unassigned reply codes, RSV garbage.

### 3.3 `params_parse` (the open-op params, `src/params.rs`)

Input: raw bytes → `serde_json` (alkcall's bounded `arbitrary_value`
generator) → `Socks5Params` deserialization + `socks5_open_spec()` +
`SocksEstablishmentReason::parse` / `establishment_reason`. Invariants:

- **no-panic on any JSON-shaped input** (`deny_unknown_fields`
  dispatch, the registry-spec builder).
- **the trivial-params pin**: `{}` parses, `Socks5Params::as_json()` ==
  `{}`, and unknown fields always reject (the loud-rejection posture:
  the serde pin and the schema's `additionalProperties: false` agree).
- **the spec is a constant**: `socks5_open_spec()`'s wire-visible
  fields (op id, ALPN, scopes, schemas) are identical on every
  execution; the open-op surface is wire-stable (ADR-001); the
  reason-enum table equals the typed parse table (the schema/typed-view
  drift guard, mirrored from the in-suite test).
- **the reason surface is a pass-through extraction, not a validated
  table**: `establishment_reason` yields `Some(details.reason)` iff the
  code is `channel:open_failed` and the reason is a string; any string
  is surfaced as-is (the alktunnels harness-model finding #2, adopted
  here as the modeled contract); `SocksEstablishmentReason::parse`
  never panics and is total.

### 3.4 What is deliberately NOT a target (yet)

- **The producer pump (`serve_socks5_over`) / consumer sessions as
  stateful op-sequence targets**: wave 2, deferred (§4). The
  handshake-level target (§3.2) covers the byte surface; the
  session-level interleavings (associate stage select-shape, BIND quiet
  wait, the two-pump CONNECT plane) are stateful shapes over a live
  channels stack (the alktunnels wave-2 pattern), worth its own session
  post-0.1.
- **The doors (`door.rs`, `local/`, `composed/`)** are feature-gated
  assembly; their RFC-codec boundary (`parse_udp_request` /
  `new_udp_header`) is covered by the §3.2 target. The rest is I/O
  plumbing over the fuzzed cores, not parse surfaces.
- **`front_door` RFC 1929 negotiation**: covered by §3.2's auth
  sub-handshake invariants (the door drives the same forked parsers).

## 4. Scope: two waves

**Wave 1 (this session):** the three targets above. All drive
already-`pub` APIs; no `#[cfg(fuzzing)]` exposure needed (matching
both upstream docs' experience across all eight targets to date). One
diagnostic addition to the crate: `DatagramReader::retained_bytes()`
(the decoder-state byte count §3.1's bound asserts against, in
alktunnels' `retained_bytes()` style).

**Wave 2 (deferred to post-0.1):** `session_pumps`, the stateful
op-sequence target over the producer pump + consumer sessions in the
alkcall `manager_routing` / alktunnels `session_pumps` style (live
channels stack; ops over CONNECT/ASSOCIATE/BIND interleavings; the
two-pump shutdown-on-completion contract, the egress readiness
contract, and the datagram-stage exit matrix as invariants). Deferred
because wave 1 covers the wire byte surface completely, the session
harness is a large build, and the crate is one commit from its first
publish. The alktunnels sequencing (wave 1 at 0.2.0's fuzz adoption,
wave 2 the same session) was possible there because its session shape
was the crate's whole surface; here the byte-level targets carry the
attacker-reachable load and the stateful session target is a separate
planning unit.

Sequencing mirrors the upstream docs: init + wave-1 targets → 10–30
min campaigns per target via the detached runner → fix anything found →
wave 2 when scheduled.

## 5. Operational isolation: campaigns never share fate with the agent session

**Adopted verbatim from the upstream docs (alkcall §7.6, alktunnels
§5)**: an environment constraint, not a nice-to-have. Agent sessions
run fuzzer builds/campaigns through a bash tool that spawns the fuzzer
as a child of the session's own process tree and cgroup; an OOM in a
fuzz target must cost the fuzzer, never the session. Three layers, all
mandatory: (1) libFuzzer soft limits (`-rss_limit_mb=2048`
`-malloc_limit_mb=2048`); never `ulimit -v` under ASAN; (2) fork mode
(`-fork=1`) as blast-radius containment (crash/timeout/OOM kills only
the short-lived child; the harness survives and persists the artifact;
also the deadlock answer); (3) process detachment: the runner script
wraps `cargo fuzz run` in `setsid` + `nohup` + full redirection to a
log file; poll, never `wait`.

Also inherited: the operational note that `cargo fuzz run` returns
before its last fork-mode children fully exit; prefer `pgrep -af` to
LIST, kill by explicit pid from the runner's echoed `pid=`, and never
pattern-kill-and-recheck in one call.

## 6. No hosted CI

Per alkcall §7.9 / alktunnels §6, the standing policy applies to this
repo identically: no hosted CI will exist; do not add Actions/Gitea
Actions workflow files. **Corpus replay is the fuzz gate as plain
`cargo test`**: `cargo test --manifest-path fuzz/shared/Cargo.toml`
replays every committed seed through the invariant functions, so add it
to the release verification checklist (AGENTS.md). Campaigns run
manually via the detached runner (§6); e.g. before a release, or after
touching `src/wire.rs`, `src/rfc1928/`, or `src/params.rs`.

## 7. Implementation log

- **2026-09-28: proposal adopted** (this doc). Wave-1 targets
  `datagram_codec` + `rfc1928_codec` + `params_parse`; wave 2 deferred
  (§4).
- **2026-09-28: `alkcall` bumped 0.8.0 → 0.8.1,
  `alktunnels` 0.2.0 → 0.2.1.** Bug-fix releases, no API/wire change;
  alkcall's fix (the duplicate adopt/open destroying the live channel)
  is directly relevant to this crate's consumer sessions: every
  session's teardown reaps via the manager, and the
  open-op-response-replayed scenario alkcall's changelog names is the
  consumer open path. Verification: full suite (default + all-features)
  green, clippy, fmt, wasm check (§8 commands).
- **2026-09-28: wave-1 implemented.** The `fuzz/` workspace laid out
  per §2 (nightly-pinned subtree, stable `fuzz/shared` library, runner,
  dict, generator); the three targets over already-`pub` APIs, with no
  `#[cfg(fuzzing)]` exposure needed (the upstream docs' experience,
  now across eleven targets). One diagnostic addition to the crate:
  `DatagramReader::retained_bytes()` (§3.1's bound target). Seeds
  committed: 45 + 65 + 19 generated (fuzz/gen_fuzz_seeds.py) + 2
  campaign-found crash inputs promoted (`datagram_codec/seed-900`,
  `seed-901`, the §7 harness findings below).
- **2026-09-28: two harness-model defects caught by corpus replay
  pre-campaign** (the alkcall §7.7 fuzzer-as-harness-checker pattern):
  1. **A `len == 0` frame is well-framed but decodes to
     `Err(EmptyFrame)`**: the re-frame round-trip first expected every
     well-framed frame to decode `Ok`. The frame count still holds over
     every frame; the byte-for-byte re-frame holds over the decodable
     ones; `EmptyFrame` is pinned as the only zero-inner-byte shape.
     The same arm widened for `ShortAddress`/`DomainNotUtf8`/
     `BadAtyp`: a well-framed frame can carry any addr-garbage shape;
     the decode refuses the addr, and the raw frame is the only
     re-frame possible.
  2. **A fieldless `deny_unknown_fields` struct deserializes from ANY
     empty JSON composite** (the serde seq form `[]` included), not
     only `{}`. Not wire-reachable (the registry's `type: object`
     input schema is the gate that keeps non-object forms from ever
     reaching the type), but the harness must model the serde reality:
     the trivial-params invariant is now "an empty composite parses,
     everything non-empty rejects, the canonical round-trip is `{}`."
- **2026-09-28: first campaign finding, fork-mode containment as
  designed (a third harness-model defect).** The `datagram_codec`
  campaign crashed at ~35 s on input `0005 0301 1203 03bb 00`
  (`BadAtyp(0)` shape); the re-frame walk's `Err` arm (fixed in the
  replay pass above) still omitted `BadAtyp`. Fixed; the crash input is
  committed as `seed-900`; the campaign relaunched clean.
- **2026-09-28: second campaign finding (also harness, fork-mode
  containment); the count walk's `declared >= 7` gate excluded short
  domains.** Input `0005 0301 1203 03bb 00`, a domain frame with a
  1-byte domain (`addr_len = 5`) is a legal empty-payload frame, but
  the walk's `declared >= 7` gate (meant to skip addr-less frames)
  rejected it; the per-ATYP `addr_len` computation already does that
  job. The gate lowered to `>= 4` (the minimum ATYP + length-byte
  prefix the walk reads); the crash input is committed as `seed-901`;
  the campaign relaunched clean.
- **2026-09-28: wave-1 campaigns run (10-min detached runs, §6
  runner; `-fork=1 -rss_limit_mb=2048 -malloc_limit_mb=2048
  -timeout=25`; codec `-max_len=65536`, rfc1928
  `-max_len=4096 -use_value_profile=1`, params
  `-dict=json.dict -use_value_profile=1). All three exited 0 with
  empty artifact directories: no crashes, hangs, OOMs, or leaks.**
  - `datagram_codec` (post-harness-fixes), ~1.9M execs (~3k exec/s),
    33 fork jobs, `oom/timeout/crash: 0/0/0` throughout. Coverage
    saturated at 481 edges (ft 2222, corp 209); the 2-byte-header
    state machine is fully enumerated (the alktunnels wave-1
    saturation profile).
  - `rfc1928_codec`, ~2.0M execs (~3.6k exec/s), 33 fork jobs,
    `oom/timeout/crash: 0/0/0` throughout. Coverage saturated at 1429
    edges (ft 7987, corp 704); the handshake state machines'
    byte-level shape space is fully enumerated; both protocol
    directions held across every adversarial sequence.
  - `params_parse`, ~3.1M execs (~5.5k exec/s), 33 fork jobs,
    `oom/timeout/crash: 0/0/0` throughout. Coverage 1512 edges (ft
    12970, in-memory corpus 2981 from the 19 committed seeds); the
    serde/untagged shape space was still expanding at budget end; the
    spec-constant and pass-through-reason invariants held everywhere.
  - The decoder-state bound (§3.1) held everywhere:
    `retained_bytes()` never exceeded fed + one frame on any
    adversarial input. Grown corpora were **not** merged into the
    committed seeds (the §2 policy).
- **NO crate bugs found by wave 1.** All three findings this session
  were harness-model defects, each invisible to example-based review
  and caught by fuzzing/replay: the upstream "fuzzer as a
  harness-checker" pattern, confirmed a third time (alkcall §7.7,
  alktunnels §7, here §7). The codec's contracts (infallible
  reassembly, the F-2 layering, the joint bound, the retained-bytes
  bound) and the RFC core's no-panic posture held across every
  adversarial input the campaigns generated.
- (progress appended as implementation proceeds; see git log)

## 8. Verification commands

```bash
cargo test                                    # main suite (stable)
cargo test --all-features                     # the feature-gated suite
cargo test --manifest-path fuzz/shared/Cargo.toml   # corpus replay (fuzz gate)
cargo fuzz build                              # in fuzz/ (nightly, ASAN)
fuzz/run-detached.sh <target>                 # campaigns (never foreground)
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo clippy --manifest-path fuzz/shared/Cargo.toml --all-targets -- -D warnings
cargo fmt --manifest-path fuzz/shared/Cargo.toml --check
cargo check --target wasm32-unknown-unknown   # default crate stays wasm-clean
```

Campaign flags per target: `datagram_codec -max_len=65536`;
`rfc1928_codec -max_len=4096 -use_value_profile=1`;
`params_parse -dict=json.dict -use_value_profile=1`.

## 9. References

- Upstream campaigns + operational model (authoritative for tooling,
  runner, corpus policy, no-CI posture):
  `/workspace/@alkdev/alkcall/docs/research/fuzzing.md`,
  `/workspace/@alkdev/alktunnels/docs/research/fuzzing.md`
- alkcall 0.8.1 changelog, the finding our consumer open/adopt paths
  are exposed to
- This crate: ADR-001 (op/params), ADR-003 (the frame codec), ADR-013
  (the targeted fork), `docs/architecture/wire.md`,
  `docs/architecture/rfc1928.md`
- External: RUSTSEC-2026-0037 (quinn-proto, the maintainers'
  fuzzing-coverage statement), rust-fuzz trophy case, cargo-fuzz Rust
  Fuzz Book (all linked from the upstream doc's §9)