Skip to main content

Crate refs_forensic

Crate refs_forensic 

Source
Expand description

refs-forensic — anomaly auditor + CoW metadata-residue recovery for ReFS.

ReFS is a reverse-engineered, undocumented, allocate-on-write filesystem, and that CoW model is the forensic lever this crate pulls:

  • F-INTEGRITY (audit_image / audit_findings) emits graded forensicnomicon::report::Findings for structural anomalies: a bad boot VBR signature (REFS-BOOT-SIGNATURE-INVALID), a metadata block whose self-recorded block number disagrees with its location (REFS-SELF-BLOCK-MISMATCH — consistent with a relocated/tampered page), the two checkpoint copies disagreeing (REFS-CHECKPOINT-DIVERGENCE), a virtual reference that resolves nowhere (REFS-ORPHANED-OR-UNRESOLVED), and geometry beyond bounds (REFS-IMPOSSIBLE-GEOMETRY). A metadata CRC mismatch (REFS-METADATA-CRC-MISMATCH) is emitted only over a caller-supplied explicit coverage range via audit_crc_range — never auto-fabricated, because ReFS’s own whole-block checksum coverage range is undetermined in the reverse-engineered references (see refs_core’s metablock docs).
  • F-CARVE (recover_residue) exploits allocate-on-write: an updated directory page is written NEW and the object table re-points at it, leaving the OLD MSB+ page behind. This scans for MSB+ directory pages whose self-block-number is NOT the current object-table mapping (= stale/old versions) and carves the directory-entry rows found in them (REFS-STALE-METADATA-PAGE / REFS-CARVED-DIRECTORY-ENTRY).

Built on refs-core for valid-path reading (boot / superblock / Minstore / object table); where the audit must see the raw self-block / checkpoint bytes the reader normalizes away it parses those bytes directly (the reader/analyzer-split principle).

Each finding is an observation (“consistent with …”); the examiner draws the conclusions. Mirrors the fleet producer pattern (typed AnomalyKind + impl Observation + audit_* → Vec<Anomaly> + audit_findings → Vec<Finding>), as in xfs-forensic / btrfs-forensic / ntfs-forensic.

§Honest validation state (Tier-2)

ReFS has no official spec and no ground-truth corpus. F-INTEGRITY is validated on the real resident v3.14 metadata (a clean volume emits nothing false; crafted corruption is detected). F-CARVE’s stale-page recovery is validated on a real resident stale CoW 0x600 page (carrying System Volume Information) plus synthetic pages; the minted user-file bands are non-resident (beyond the oracle slice, source VHD lost), so their deleted-recovery end-to-end is oracle-blocked — surfaced as such, never fabricated. See docs/validation.md.

Structs§

Anomaly
A ReFS structural-integrity anomaly: an observation graded by severity, with a stable code and note derived from its AnomalyKind so they cannot drift.
StalePage
A recovered stale (old-CoW) metadata page: an MSB+ directory page whose self-block-number is NOT the current object-table mapping, so it is a superseded version left behind by allocate-on-write. Its carved directory entries are potential deleted / renamed / superseded names.

Enums§

AnomalyKind
Classification of a ReFS structural-integrity anomaly (F-INTEGRITY). Each variant carries the evidence needed to reproduce the observation.
Severity
Severity of a forensic finding (Info < Low < Medium < High < Critical).

Functions§

audit_crc_range
Audit a resident metadata block’s CRC over a caller-supplied, known coverage range [start..end] against stored, returning an AnomalyKind::MetadataCrcMismatch anomaly when it does not verify, or None when it verifies OR the range is out of bounds.
audit_findings
Audit an image and convert each F-INTEGRITY anomaly to a canonical Finding tagged with scope.
audit_image
Audit a whole ReFS image for structural-integrity anomalies (F-INTEGRITY): validate the boot VBR signature + geometry, check the superblock’s self-block, check the checkpoint set the superblock names, and sweep every resident MSB+ metadata page for a self-block-number that disagrees with its location.
recover_residue
Recover CoW metadata residue (F-CARVE): scan image for MSB+ directory pages whose self-block-number is NOT the current version (= stale/old versions left behind by allocate-on-write), and carve the directory-entry rows found in them.