wgcloak/docs/FUZZING.md

Fuzzing

The repository includes an isolated cargo-fuzz crate under fuzz/. It depends on the public wgcloak library by path and does not open sockets, read files, or start async runtimes. Each target limits the input passed to a parser to 64 KiB; payload/frame/datagram copies are limited to 16 KiB where the API supports a bound.

Install and run

Install cargo-fuzz once, then run a short smoke fuzzing session from the repository root:

cargo install cargo-fuzz
cargo fuzz run fuzz_direct_packet -- -max_total_time=30
cargo fuzz run fuzz_tls_frame -- -max_total_time=30
cargo fuzz run fuzz_http3_parser -- -max_total_time=30
cargo fuzz run fuzz_config_toml -- -max_total_time=30

The corpus directories under fuzz/corpus/ contain minimal and malformed seeds. Add minimized findings there with the target that discovered them.

For a compile-only check when cargo-fuzz is unavailable:

cargo check --manifest-path fuzz/Cargo.toml

cargo-fuzz uses libFuzzer and sanitizer instrumentation for fuzz builds. For an explicit sanitizer run, set the sanitizer supported by the local LLVM toolchain, for example:

RUSTFLAGS="-Zsanitizer=address" cargo fuzz run fuzz_direct_packet --sanitizer address -- -max_total_time=60

Target invariants

• Direct packet parsing rejects malformed/truncated/oversized input without panicking and checks the DATA bound before copying its payload.
• TLS/TCP framing handles arbitrary incremental chunks, rejects oversized length headers, and reports truncated final frames without panicking.
• HTTP/3 capsule, context-ID, and authentication message parsers reject malformed varints, capsule lengths, contexts, and auth payloads safely.
• TOML parsing accepts only valid UTF-8 input and performs structural parsing in memory; the target deliberately does not call validation that could load file-backed secrets.