dosh/fuzz/README.md

dosh fuzz targets

cargo-fuzz / libFuzzer harnesses for the dosh parsers and handshake verifiers (spec milestone 5 / §16: "Fuzz packet parsing, authorized-key parsing, known-host parsing, and handshake state", "Fuzz targets run in CI").

This is a standalone crate (its own [workspace]) so it never affects the main crate's cargo build / cargo test / cargo fmt --check.

Targets

Target	Parser(s) exercised
packet_decode	protocol::Header::parse, protocol::decode, protocol::decrypt_body
from_body	protocol::from_body::<T> for every protocol & native wire struct
authorized_keys	native::parse_authorized_keys, native::parse_ssh_ed25519_public_blob
known_hosts	native::parse_known_hosts, native::parse_host_public_key_line
handshake_structs	handshake struct decode + verify_server_hello, user_auth_transcript, verify_native_user_auth
attach_ticket	auth::open_attach_ticket, auth::verify_attach_ticket, auth::decode_bootstrap

Every target's objective is the same: no panics on any input (a panic on untrusted bytes is a robustness/DoS bug per threat model §5).

Prerequisites

rustup toolchain install nightly
cargo install cargo-fuzz

cargo-fuzz requires a nightly toolchain (it builds with -Z sanitizer=address).

Run

From the repository root:

# Run all targets for a short smoke pass
make fuzz-smoke

# Run all targets for the pre-launch deep pass (default: 300s each)
make fuzz-deep

# List targets
cargo +nightly fuzz list --fuzz-dir fuzz

# Run a single target indefinitely
cargo +nightly fuzz run --fuzz-dir fuzz packet_decode

# Short, CI-style smoke run of one target (10 seconds)
cargo +nightly fuzz run --fuzz-dir fuzz packet_decode -- -max_total_time=10

Or from inside fuzz/:

cd fuzz
cargo +nightly fuzz run packet_decode -- -max_total_time=10

CI

.github/workflows/ci.yml has a fuzz-smoke job that installs nightly + cargo-fuzz and runs each target. Push/PR runs use a short 20-second-per-target smoke pass. Weekly scheduled and manual workflow runs use a 300-second-per-target deep pass by default. The job is tolerant if the toolchain/tooling is unavailable so it never blocks the main test gate.