vsc-forensic

Windows Volume Shadow Copy (VSS) forensics for Rust — a panic-free reader for the shadow-copy store/catalog structures, and a graded anomaly analyzer that turns each NTFS snapshot into evidence you can diff across time.

VSS is how Windows keeps point-in-time snapshots of an NTFS volume under System Volume Information: each shadow copy preserves the blocks that were about to change, so the live volume plus the VSS stores together encode the temporal cohort of the filesystem's past states. vsc-forensic is the [P^H] disk-history member of the forensic fleet — it navigates that VSS region by snapshot, enumerates the catalog of stores and their metadata, and surfaces shadow-copy timeline and integrity anomalies as fleet findings.

Quick start

Point the reader at a raw NTFS volume (offset 0 = the NTFS boot sector) and enumerate its shadow copies:

use std::fs::File;
use vsc::VssVolume;

let mut vol = VssVolume::open(File::open("ntfs_volume.raw")?)?;
println!("shadow copies: {}", vol.store_count());

for store in vol.stores() {
    println!(
        "{}  size {}  created FILETIME {}",
        store.store_id_string(), store.volume_size, store.creation_time,
    );
}

// Read a store's per-snapshot metadata (shadow-copy IDs, attribute flags, machine).
if vol.store_count() > 0 {
    let info = vol.store_info(0)?;
    println!("shadow copy {}", info.shadow_copy_id_string());

    // Reconstruct the volume as it was at the snapshot — copy-on-write blocks
    // overlaid on the live volume — and read any 16 KiB block back.
    let mut snap = vol.snapshot(0)?;
    let block = snap.read_block(0)?; // the NTFS boot sector as it was at snapshot time
    println!("snapshot boot sector: {:02x?}", &block[3..11]); // b"NTFS    "
}
# Ok::<(), vsc::error::VssError>(())

Then run the analyzer to get graded findings — no shadow copies where you expected some (consistent with MITRE T1490 deletion), a sequence gap, a non-persistent store:

use vsc_forensic::audit;

for anomaly in audit(&mut vol) {
    println!("[{:?}] {} — {}", anomaly.severity, anomaly.code, anomaly.note);
    // e.g. [Info] VSC-STORE-PRESENT — shadow copy 1afc8871-… created 2023-01-04T21:38:00Z
}

The two-crate split

Following the fleet reader/analyzer standard, the workspace ships two crates:

Crate	Role	Depends on	Emits
`vsc-core`	reader / decoder	`uuid`, `thiserror`	typed VSS catalog / store records
`vsc-forensic`	anomaly analyzer	`vsc-core`, `forensicnomicon`	graded `forensicnomicon::report::Finding`s

The reader stays pure — it decodes bytes and makes no judgments. All forensic meaning lives in the analyzer, a side-effect-free function of already-decoded records. That separation is why vsc-core is useful on its own and why vsc-forensic drops straight into a fleet Report next to every other analyzer.

Findings

Code	Meaning
`VSC-NO-SHADOW-COPIES`	a VSS volume header is present but the catalog holds zero stores — consistent with MITRE T1490 shadow-copy deletion or a volume that never had snapshots
`VSC-STORE-PRESENT`	one finding per enumerated shadow copy, carrying its GUID and creation time
`VSC-SEQUENCE-GAP`	non-contiguous catalog sequence numbers — consistent with a deleted intermediate store
`VSC-STORE-NON-PERSISTENT`	a store whose attribute flags mark it non-persistent

Findings are observations, not verdicts — the "consistent with" framing is deliberate; the analyst or tribunal draws the conclusion.

Capabilities

Capability	Status
VSS volume header + catalog enumeration (store GUID, size, sequence, creation time)	✅
Store metadata decode (shadow-copy IDs, attribute flags, originating machine)	✅
`vsc-forensic` anomaly auditor (`VSC-*` findings → `forensicnomicon::report`)	✅
Fuzzed (`fuzz_catalog` / `fuzz_store` / `fuzz_reconstruct`) + Tier-1 validated against `libvshadow`	✅
COW block-list reconstruction — materialize a snapshot's view of the volume, read any block back	✅

Trust but verify

Both crates enforce the fleet hardening contract: #![forbid(unsafe_code)], the Paranoid-Gatekeeper clippy set (unwrap_used/expect_used denied), bounds-checked readers that never panic on malformed input, cargo-deny supply-chain gating, and a 100%-line-coverage CI gate. Every parsed structure has a cargo-fuzz target whose invariant is "must not panic".

Correctness is proven against an independent third-party oracle — libvshadow (via pyvshadow) — run on a real public CTF disk image: vsc-core's catalog and store-metadata output matches the oracle field-for-field (store count, GUID, volume size, creation FILETIME, shadow-copy IDs), and its reconstruction reproduces the snapshot's bytes block-for-block across every path — passthrough, bitmap zero-fill, plain copy-on-write, and 512-byte overlay merge (validated over 1,415 blocks; the algorithm is documented in docs/RECONSTRUCTION.md). See tests/data/README.md and the env-gated oracle_pcmus001 / reconstruct_pcmus001 integration tests.

Documentation

The curated docs site is built with MkDocs and served from GitHub Pages. See docs/RESEARCH.md for the VSS on-disk format research behind the design.