clearly describe how to perform fuzzing, and make a single workspace

- add publish = false to fuzz subcrates

Author: cosmicexplorer

Cargo.toml

@@ -13,20 +13,34 @@ keywords = ["zip", "archive", "compression"]
 # Any change to rust-version must be reflected also in `README.md` and `.github/workflows/ci.yaml`.
 # The MSRV policy is documented in `README.md`.
 rust-version = "1.83.0"
+categories = ["compression", "filesystem", "parser-implementations"]
 description = """
 Library to support the reading and writing of zip files.
 """
-edition = "2021"
+edition.workspace = true
 exclude = ["tests/**", "examples/**", ".github/**", "fuzz_read/**", "fuzz_write/**"]
 
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
+[workspace]
+members = [".", "fuzz_read", "fuzz_write"]
+default-members = ["."]
+resolver = "2"
+
+[workspace.package]
+edition = "2021"
+
 [workspace.dependencies]
+afl = "0.15"
+arbitrary = { version = "1.4.1" }
+tikv-jemallocator = "0.6.0"
 time = { version = "0.3.37", default-features = false }
+zip = { path = ".", default-features = false }
 
 [dependencies]
+arbitrary = { workspace = true, features = ["derive"], optional = true }
 aes = { version = "0.8", optional = true }
 bzip2 = { version = "0.6.0", optional = true }
 chrono = { version = "^0.4.27", optional = true }
@@ -52,9 +66,6 @@ deflate64 = { version = "0.1.9", optional = true }
 lzma-rust2 = { version = "0.13", optional = true, default-features = false, features = ["std", "encoder", "optimization", "xz"] }
 bitstream-io =  { version = "4.5.0", optional = true }
 
-[target.'cfg(fuzzing)'.dependencies]
-arbitrary = { version = "1.4.1", features = ["derive"] }
-
 [dev-dependencies]
 bencher = "0.1.5"
 getrandom = { version = "0.3.1", features = ["wasm_js", "std"] }
@@ -65,6 +76,7 @@ clap = { version = "=4.4.18", features = ["derive"] }
 tempfile = "3.15"
 
 [features]
+arbitrary = ["dep:arbitrary"]
 aes-crypto = ["dep:aes", "dep:constant_time_eq", "hmac", "pbkdf2", "sha1", "getrandom", "zeroize"]
 chrono = ["dep:chrono"]
 _deflate-any = []

README.md

@@ -1,14 +1,12 @@
 zip
-========
+===
 
 [![Build Status](https://github.com/zip-rs/zip2/actions/workflows/ci.yaml/badge.svg)](https://github.com/Pr0methean/zip/actions?query=branch%3Amaster+workflow%3ACI)
 [![Crates.io version](https://img.shields.io/crates/v/zip.svg)](https://crates.io/crates/zip)
 
 [Documentation](https://docs.rs/zip/latest/zip/)
 
-Info
-----
-
+# Info
 
 A zip library for rust which supports reading and writing of simple ZIP files. Formerly hosted at
 https://github.com/zip-rs/zip2.
@@ -28,8 +26,7 @@ Currently unsupported zip extensions:
 
 * Multi-disk
 
-Features
---------
+# Features
 
 The features available are:
 
@@ -53,17 +50,15 @@ The features available are:
 
 By default `aes-crypto`, `bzip2`, `deflate`, `deflate64`, `lzma`, `ppmd`, `time`, `xz` and `zstd` are enabled.
 
-MSRV
-----
+# MSRV
 
 Our current Minimum Supported Rust Version is **1.83**. When adding features,
 we will follow these guidelines:
 
 - We will always support a minor Rust version that has been stable for at least 6 months.
 - Any change to the MSRV will be accompanied with a **minor** version bump.
 
-Examples
---------
+# Examples
 
 See the [examples directory](examples) for:
 
@@ -74,10 +69,9 @@ See the [examples directory](examples) for:
 * How to read a zip from the standard input.
 * How to append a directory to an existing archive
 
-Fuzzing
--------
+# Fuzzing
 
-Fuzzing support is through [cargo afl](https://rust-fuzz.github.io/book/afl.html). To install cargo afl:
+Fuzzing support is through [`cargo afl`](https://rust-fuzz.github.io/book/afl/tutorial.html). To install `cargo afl`:
 
 ```bash
 cargo install cargo-afl
@@ -86,13 +80,65 @@ cargo install cargo-afl
 To start fuzzing zip extraction:
 
 ```bash
-cargo +nightly afl build --all-features --manifest-path fuzz_read/Cargo.toml
-cargo +nightly afl run fuzz_read/target/debug/fuzz_read
+mkdir -vp fuzz-read-out
+cargo afl build --all-features -p fuzz_read
+# Curated input corpus:
+cargo afl fuzz -i fuzz_read/in -o fuzz-read-out target/debug/fuzz_read
+# Test data files:
+cargo afl fuzz -i tests/data -e zip -o fuzz-read-out target/debug/fuzz_read
 ```
 
 To start fuzzing zip creation:
 
 ```bash
-cargo +nightly afl build --all-features --manifest-path fuzz_write/Cargo.toml
-cargo +nightly afl run fuzz_write/target/debug/fuzz_write
+mkdir -vp fuzz-write-out
+cargo afl build --all-features -p fuzz_write
+# Curated input corpus and dictionary schema:
+cargo afl fuzz -x fuzz_write/fuzz.dict -i fuzz_write/in -o fuzz-write-out target/debug/fuzz_write
+```
+
+## Fuzzing stdio
+
+The read and write fuzzers can also receive input over stdin for one-off validation. Note here that the fuzzers can be configured to build in support for DEFLATE, or not:
+```bash
+# Success, no output:
+cargo run --quiet --all-features -p fuzz_read <tests/data/deflate64.zip
+# Error, without deflate64 support:
+cargo run --quiet -p fuzz_read <tests/data/deflate64.zip
+
+thread 'main' (537304) panicked at fuzz_read/src/main.rs:40:36:
+called `Result::unwrap()` on an `Err` value: UnsupportedArchive("Compression method not supported")
+note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+```
+
+The zip creation fuzzer will try to print out a description of the kind of input it translated the input bytes into:
+```bash
+# This is an empty input case:
+<fuzz_write/in/id-000000,time-0,execs-0,orig-0011743621118ab6c5278ffbb8fd14bddd8369ee.min \
+  cargo run --quiet --all-features -p fuzz_write
+# This input was translated into one or more test cases:
+<fuzz_write/in/id-000000,time-0,execs-0,orig-0011743621118ab6c5278ffbb8fd14bddd8369ee.min \
+  cargo run --quiet -p fuzz_write
+writer.start_file_from_path("", FileOptions { compression_method: Stored, compression_level: None, last_modified_time: DateTime::from_date_and_time(2048, 1, 1, 0, 0, 0)?, permissions: None, large_file: false, encrypt_with: None, extended_options: ExtendedFileOptions {extra_data: vec![].into(), central_extra_data: vec![].into()}, alignment: 0 })?;
+writer.write_all(&[])?;
+writer
+let _ = writer.finish_into_readable()?;
+```
+
+The zip creation fuzzer uses [`arbitrary::Unstructured`](https://docs.rs/arbitrary/latest/arbitrary/struct.Unstructured.html) to convert bytes over stdin to random inputs, so it can be triggered with other sources of random input:
+```bash
+# Usually, the random input is translated into zero test cases:
+head -c50 /dev/random | cargo run --quiet --all-features -p fuzz_write
+# Sometimes, one or more test cases are generated and successfully evaluated:
+head -c50 /dev/random | cargo run --quiet --all-features -p fuzz_write
+writer.set_raw_comment([20, 202])?;
+let mut writer = ZipWriter::new_append(writer.finish()?)?;
+let sub_writer = {
+let mut initial_junk = Cursor::new(vec![106]);
+initial_junk.seek(SeekFrom::End(0))?;
+                          let mut writer = ZipWriter::new(initial_junk);
+writer
+};
+writer.merge_archive(sub_writer.finish_into_readable()?)?;
+let mut writer = ZipWriter::new_append(writer.finish()?)?;
 ```

fuzz_read/Cargo.toml

@@ -1,17 +1,15 @@
 [package]
 name = "fuzz_read"
 version = "0.1.0"
-edition = "2021"
+edition.workspace = true
+publish = false
 
 [dependencies]
-afl = "0.15"
-tikv-jemallocator = "0.6.0"
+afl.workspace = true
+zip.workspace = true
 
-[dependencies.zip]
-path = ".."
-default-features = false
+[target.'cfg(fuzzing)'.dependencies]
+tikv-jemallocator.workspace = true
 
 [features]
 zip-default = ["zip/default"]
-
-[workspace]

fuzz_read/src/main.rs

@@ -1,15 +1,19 @@
+#![allow(unexpected_cfgs)] // Needed for cfg(fuzzing) on nightly as of 2024-05-06
+
+#[cfg(fuzzing)]
 use afl::fuzz;
 use std::io::{Read, Seek, SeekFrom};
+#[cfg(fuzzing)]
 use tikv_jemallocator::Jemalloc;
 use zip::read::read_zipfile_from_stream;
 
 const MAX_BYTES_TO_READ: u64 = 1 << 24;
 
+#[cfg(fuzzing)]
 #[global_allocator]
 static GLOBAL: Jemalloc = Jemalloc;
 
-fn decompress_all(data: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
-    let reader = std::io::Cursor::new(data);
+fn decompress_all(reader: impl Read + Seek) -> Result<(), Box<dyn std::error::Error>> {
     let mut zip = zip::ZipArchive::new(reader)?;
 
     for i in 0..zip.len() {
@@ -25,7 +29,17 @@ fn decompress_all(data: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
 }
 
 fn main() {
+    #[cfg(fuzzing)]
     fuzz!(|data: &[u8]| {
-        let _ = decompress_all(data);
+        let reader = std::io::Cursor::new(data);
+        let _ = decompress_all(reader);
     });
+
+    #[cfg(not(fuzzing))]
+    {
+        let mut v = Vec::new();
+        std::io::stdin().read_to_end(&mut v).unwrap();
+        let reader = std::io::Cursor::new(v);
+        decompress_all(reader).unwrap();
+    }
 }

fuzz_write/Cargo.toml

@@ -1,19 +1,17 @@
 [package]
 name = "fuzz_write"
 version = "0.1.0"
-edition = "2021"
+edition.workspace = true
+publish = false
 
 [dependencies]
-afl = "0.15"
-arbitrary = { version = "1.3.2", features = ["derive"] }
+afl.workspace = true
+arbitrary = { workspace = true, features = ["derive"] }
 replace_with = "0.1.7"
-tikv-jemallocator = "0.6.0"
+zip = { workspace = true, features = ["arbitrary"] }
 
-[dependencies.zip]
-path = ".."
-default-features = false
+[target.'cfg(fuzzing)'.dependencies]
+tikv-jemallocator.workspace = true
 
 [features]
 zip-default = ["zip/default"]
-
-[workspace]