refs-forensic
A from-scratch, reverse-engineered reader and graded anomaly auditor for ReFS v3 (the Windows Resilient File System) — walk the boot region, checkpoint, object table, and Minstore B+tree over any byte source, resolve virtual→physical container addresses, and surface copy-on-write metadata residue as evidence.
refs-core parses the on-disk structures; refs-forensic grades ReFS-specific
anomalies as forensicnomicon::report::Findings and recovers copy-on-write
metadata residue.
ReFS is reverse-engineered. Microsoft publishes no official on-disk specification for ReFS. Every structural fact this crate encodes comes from third-party reverse engineering — primarily libyal
libfsrefsand Prade's academic work. There is no ground-truth forensic corpus. Structural metadata is therefore Tier-2 at best (self-minted on the live Windows driver + cross-checked against the reverse-engineered references); only file content can reach Tier-1, by hashing against the Windows driver. This crate does not claim Tier-1 for structural findings. Seedocs/validation.md.
What refs-core parses
- The boot Volume Boot Record (FS-recognition structure at offset 0):
ReFS/FSRSsignatures, sector/cluster geometry, volume serial, and the major/minor format version. - Version detection + fail-loud gate: targets ReFS v3.x; a v1 (or any non-v3) volume is rejected naming the real version bytes, never silently misparsed.
- The primary superblock (
SUPB, at cluster 30) and the checkpoint pair it names: block-signature validation, self-describing block number, and torn/zero-copy detection. - The object table and container layer: virtual→physical address resolution so metadata blocks are reachable by object id.
- Minstore B+tree (
MSB+) pages — node/leaf walking — and the directory entries they carry.
Validation is Tier-2 for structural metadata (no ReFS ground-truth corpus exists); deep non-resident directory recovery is oracle-blocked and surfaced as such — see the honest validation state below and
docs/validation.md.
use BootSector;
let boot = parse?; // image = bytes at the ReFS partition
boot.require_v3?; // fail loud on a non-v3 volume
println!;
let sb = parse_at?;
assert_eq!; // self-describing
Import path is refs_core (the bare refs crate name is held by an unrelated
third party on crates.io, so the import is not hijacked).
refs-forensic — the audit layer
Graded structural anomalies (F-INTEGRITY) and copy-on-write metadata-residue
recovery (F-CARVE), each finding an observation ("consistent with …"),
never a verdict. Full evidence + tiering in docs/validation.md.
// F-INTEGRITY — structural anomalies as graded forensicnomicon Findings.
let findings = audit_findings;
for f in &findings
// F-CARVE — recover directory-entry residue from stale copy-on-write pages.
for stale in recover_residue
| Code | Signal |
|---|---|
REFS-BOOT-SIGNATURE-INVALID |
boot VBR signature ≠ ReFS\0\0\0\0 (fail-loud value) |
REFS-SELF-BLOCK-MISMATCH |
metadata block self-block ≠ its location (relocated/tampered) |
REFS-METADATA-CRC-MISMATCH |
stored CRC fails over a known coverage range (via audit_crc_range; never auto-fabricated — ReFS's own range is undetermined) |
REFS-CHECKPOINT-DIVERGENCE |
the superblock names zero / torn checkpoint copies |
REFS-ORPHANED-OR-UNRESOLVED |
a child reference resolving to no resident page (directory-walk caller) |
REFS-IMPOSSIBLE-GEOMETRY |
cluster/geometry beyond bounds (allocation-bomb guard) |
REFS-STALE-METADATA-PAGE / REFS-CARVED-DIRECTORY-ENTRY |
an old CoW MSB+ directory page + the entries it still holds |
Honest validation state (Tier-2). F-INTEGRITY is validated on the real
resident v3.14 metadata (a clean volume emits nothing false) plus crafted
corruption. F-CARVE is validated on a real resident stale CoW 0x600 page
carrying System Volume Information. The minted user files live in a
non-resident band beyond the oracle slice (source VHD lost), so their
deleted-recovery end-to-end is oracle-blocked — surfaced as such, never
fabricated. File-content extraction and USN journal parsing are later phases.
Robustness
#![forbid(unsafe_code)], panic-free bounds-checked little-endian readers, and
saturating arithmetic — the crate parses untrusted, attacker-controllable disk
images and must never panic, read out of bounds, or trust a length field.
Privacy Policy · Terms of Service · © 2026 Security Ronin Ltd