Security tests & how to help

Regression suite, fuzzing harnesses, audit rounds, and concrete contribution paths for external researchers.

LUKSbox is a young codebase. The cryptography is built on standardised primitives (NIST FIPS 203, RFC 8452, RFC 5869, RFC 9106), and mature Rust libraries (RustCrypto, libfido2, tss-esapi), but the integration layer, and the on-disk format are ours. This page lists every automated check that runs before a release and tells you how to push the project past where our imagination stops.

If you find a way to make LUKSbox misbehave on a crafted input, a malicious peer, or a surprising filesystem state, even if it isn't a classical vulnerability, please tell us. Open a GitHub issue with reproduction steps. We respond.

Regression suites

Every commit runs the workspace test suite plus a dedicated "security-regressions" CI gate that fails if any of the historic-bug guards trip.

Run them locally:

cargo test --workspace

The full test taxonomy is in TESTING.md.

Fuzzing campaigns

Every parser that touches attacker-controlled bytes has a libFuzzer harness in fuzz/ and an AFL++ harness in fuzz-afl/. PR CI runs each libFuzzer target for 5 minutes on the persistent corpus; a dedicated server runs the AFL++ campaigns for hours per release.

Total fuzz iterations across all targets at the time of writing: 30 million plus. Bugs that these harnesses originally found and helped fix (Argon2id DoS, cred_id OOM, postcard-decode OOM) are pinned down by the regression suites listed above.

Run fuzz locally:

cargo install cargo-fuzz
cd fuzz
cargo +nightly fuzz run header_parse -- -max_total_time=300

# Round 12 multi-slot deniable envelope opacity target
cargo +nightly fuzz run deniable_envelope_multi_slot -- -max_total_time=300

The full fuzz taxonomy and per-target invariants are in FUZZING.md.

Constant-time benches (dudect)

Statistical timing tests run on demand (cargo bench, not part of the default CI run) over four production code paths plus one known-leaky control for t-stat calibration.

The acceptance bar is |t| < 3.0 sustained across 5 K - 50 K samples. dudect_deniable_envelope was added in Round 12 as the regression gate for R12-01 (the deniable envelope discovery loop's timing leak). It is expected to PASS on current main now that the constant- time fix (always-allocate fixed scratch + subtle::Choice-driven byte selection + single-shot SlotPayload::decode on the chosen slot) has shipped. See docs/SECURITY_AUDIT_ROUND_12.md.

Internal audit rounds

Thirteen rounds of internal audit have shipped to date. Each round focuses on a specific surface; the per-round notes (vulnerabilities found, mitigations, regression tests added) are in the audit history on the website and the recent ground-truth snapshot is at the architecture page on the website.

What we still want to test (and how you can help)

External eyes find what internal eyes miss. We deliberately publish the open gaps so external researchers know where to push first. The honest list lives in our internal ground-truth catalogue (available on request to [email protected]); the highlights are below, with the contribution path for each.

Contribute a corpus seed

The fastest way to push fuzzing further is to add a real-world input file to a target's corpus. Drop it under fuzz/corpus/<target_name>/ and open a PR. Examples that would help today:

• Real headers from old vault layouts (V1 / V2) for header_parse.
• Authenticator-specific cred IDs (Google Titan, SoloKey stateless, Trezor) for keyslot_parse.
• Edge-case Windows paths (UNC, network share, long path with device-namespace prefix) for winfsp_path_parse.
• Truncated / extended .hybrid sidecars for hybrid_sidecar_parse.

Add a fuzz target

If a parser doesn't have a harness yet and you can imagine an attacker shaping its input, please add one. See the harness template in FUZZING.md.

Suggest a regression test

If you spot a code path where invariants aren't tested but feel like they should be, file an issue with the invariant in plain English. We write the test and credit the suggestion in the changelog.

Run the AFL++ campaign

The scripts/fuzz_server.sh script in the repository runs an AFL++ campaign indefinitely against any target. If you have spare cycles and want to find something the libFuzzer 5-minute PR run misses, this is the lever. Any crash you find folds into the regression suite.

Audit the CLI / GUI / mount surface

Most audit rounds have focused on the cryptographic core. The CLI argument-parsing layer, GUI worker threads, and FUSE / WinFsp adapters have had less attention.

Where to send findings