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 gradedforensicnomicon::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 viaaudit_crc_range— never auto-fabricated, because ReFS’s own whole-block checksum coverage range is undetermined in the reverse-engineered references (seerefs_core’smetablockdocs). - 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 OLDMSB+page behind. This scans forMSB+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
AnomalyKindso they cannot drift. - Stale
Page - 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§
- Anomaly
Kind - 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]againststored, returning anAnomalyKind::MetadataCrcMismatchanomaly when it does not verify, orNonewhen it verifies OR the range is out of bounds. - audit_
findings - Audit an image and convert each F-INTEGRITY anomaly to a canonical
Findingtagged withscope. - 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
imageforMSB+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.