zfs-forensic

A from-scratch ZFS on-disk reader and a graded anomaly auditor — walk the vdev labels, uberblock ring, MOS, DMU dnodes, ZAP, and ZPL of a ZFS pool over any byte source, then turn its copy-on-write, self-checksumming Merkle structure into evidence: torn vdev labels, uberblock-rootbp checksum mismatches, dead metadata blocks, and files still carvable from a snapshot after they were deleted live.

Two crates, one workspace:

• zfs-forensic-core (imported as zfs_core) — the reader: four-label + XDR nvlist config bootstrap, endian-adaptive uberblock ring, block-pointer tree navigation with fletcher4 / SHA-256 checksums and LZ4 / gzip / zstd decompression, dnodes / objsets, ZAP (micro + fat), DSL datasets, and ZPL / SA file resolution — over any byte slice. #![forbid(unsafe_code)].
• zfs-forensic — the auditor: turns parsed ZFS structures into severity-graded forensicnomicon::report::Findings, and carves CoW-deleted files from snapshots, so a ZFS pool's anomalies aggregate uniformly with the partition and container layers.

Audit a ZFS image in 30 seconds

[dependencies]
zfs-forensic = "0.1"   # pulls in zfs-forensic-core

use zfs_forensic::audit_findings;

// Feed it the raw pool bytes; get back graded findings.
for finding in audit_findings(&image_bytes, "zfs") {
    println!("[{:?}] {} — {}", finding.severity, finding.code, finding.note);
    // e.g. [Some(High)] ZFS-UBERBLOCK-CHECKSUM-MISMATCH — active uberblock (txg 22 …
}

audit_findings parses the L0 vdev label, verifies the active uberblock's ub_rootbp checksum against the MOS block, reconciles the four vdev labels, and sweeps the reachable metadata tree — all in place. A structurally invalid image yields no findings, never a panic. For the typed form, audit_image(&image) returns Vec<Anomaly>; each anomaly.to_finding(source) converts to a report::Finding.

The anomaly codes

Each finding is an observation ("consistent with …"); the examiner draws the conclusions. Codes are a stable, published contract.

Deleted-file recovery is separate: recover_deleted(&image) walks the DSL snapshot chain, reads each snapshot's ZPL root directory, diffs it against the live filesystem's root, and carves each file present in a snapshot but absent live from the snapshot's pinned blocks — returning each RecoveredFile (ZFS-DELETED-FILE-CARVED: path, source snapshot, inode, size, content, and the content's sha256 recovery gate).

The reader: navigate a pool

zfs-forensic-core (imported as zfs_core) reads a ZFS pool over any byte slice:

use zfs_core::{VdevLabel, read_block};

// The L0 vdev label lives at physical offset 0; its active uberblock's rootbp
// points at the MOS objset block.
let label = VdevLabel::parse(&image[..zfs_core::LABEL_SIZE])?;
let rootbp = label.active_uberblock.rootbp_full();
let mos = read_block(&image, &rootbp)?; // fletcher4-checked, decompressed
# Ok::<(), zfs_core::ZfsError>(())

The bare crate name zfs (an abandoned 2016 stub) and zfs-core (a libzfs_core FFI wrapper) are both taken on crates.io, so this on-disk reader publishes as zfs-forensic-core with [lib] name = "zfs_core" — consumers still write use zfs_core::….

What makes this different from a general-purpose ZFS crate

Most ZFS tooling answers "what files are on this pool?" This workspace answers the questions a digital forensics examiner needs:

Trust but verify

• #![forbid(unsafe_code)] in both crates — no unsafe in our source. Pure-Rust, no C toolchain: every codec (including the batteries-included ruzstd zstd decoder) is pure Rust, so the reader builds as a single static binary with no C bindings.
• Panic-free — every integer / length / offset field is read through bounds-checked helpers; nvlist length / count fields are capped against allocation bombs; a malformed image degrades to an empty or typed result, never a panic.
• Fuzzed — one cargo-fuzz target per parsed structure (label, uberblock, blkptr, dnode, zap, dsl, sa, read_block) plus a fuzz_forensic target driving the full audit_image / recover_deleted pipeline. fuzz.yml builds every target on each push and deep-fuzzes each for 10 minutes weekly.
• Tier-1 validated (full read path) — the entire reader path (label → uberblock → MOS → DSL → ZPL → SA → file content) is checked against a real, vendor-authored FreeBSD 14.3 ZFS-root image whose pool is a single disk vdev (no RAIDZ). zpl_read_path reads genuine third-party file bytes whose sha256 matches two independent OpenZFS oracles — zdb and a live read-only kernel zfs mount.
• Tier-1 validated (bootstrap layer) — the vdev label + nvlist config + uberblock reader is additionally checked against the OpenZFS project's own zol-0.6.1 reference pool (openzfs/zfs-images), a third-party artifact whose ground truth comes from zdb -l / zdb -u, a wholly separate implementation.
• Tier-2 regression corpus — always-on, byte-exact self-mint fixtures (tpool / dtpool, zdb as the independent oracle) pin each layer's decode as a fast CI backstop under the Tier-1 gates. Reading the raidz zol-0.6.1 pool's data layers still needs RAIDZ parity reconstruction (deferred); the FreeBSD single-vdev pool is what carries those layers to Tier-1. See docs/validation.md.

Reader API (zfs-forensic-core)

Privacy Policy · Terms of Service · © 2026 Security Ronin Ltd