Skip to main content

refs_forensic/
lib.rs

1//! `refs-forensic` — anomaly auditor + CoW metadata-residue recovery for ReFS.
2//!
3//! ReFS is a reverse-engineered, undocumented, **allocate-on-write** filesystem,
4//! and that CoW model is the forensic lever this crate pulls:
5//!
6//! - **F-INTEGRITY** ([`audit_image`] / [`audit_findings`]) emits graded
7//!   [`forensicnomicon::report::Finding`]s for structural anomalies: a bad boot
8//!   VBR signature (`REFS-BOOT-SIGNATURE-INVALID`), a metadata block whose
9//!   self-recorded block number disagrees with its location
10//!   (`REFS-SELF-BLOCK-MISMATCH` — consistent with a relocated/tampered page),
11//!   the two checkpoint copies disagreeing (`REFS-CHECKPOINT-DIVERGENCE`), a
12//!   virtual reference that resolves nowhere (`REFS-ORPHANED-OR-UNRESOLVED`), and
13//!   geometry beyond bounds (`REFS-IMPOSSIBLE-GEOMETRY`). A metadata CRC mismatch
14//!   (`REFS-METADATA-CRC-MISMATCH`) is emitted **only** over a caller-supplied
15//!   explicit coverage range via [`audit_crc_range`] — never auto-fabricated,
16//!   because ReFS's own whole-block checksum coverage range is undetermined in
17//!   the reverse-engineered references (see [`refs_core`]'s `metablock` docs).
18//! - **F-CARVE** ([`recover_residue`]) exploits allocate-on-write: an updated
19//!   directory page is written NEW and the object table re-points at it, leaving
20//!   the OLD `MSB+` page behind. This scans for `MSB+` directory pages whose
21//!   self-block-number is NOT the current object-table mapping (= stale/old
22//!   versions) and carves the directory-entry rows found in them
23//!   (`REFS-STALE-METADATA-PAGE` / `REFS-CARVED-DIRECTORY-ENTRY`).
24//!
25//! Built on `refs-core` for valid-path reading (boot / superblock / Minstore /
26//! object table); where the audit must see the raw self-block / checkpoint bytes
27//! the reader normalizes away it parses those bytes directly (the
28//! reader/analyzer-split principle).
29//!
30//! Each finding is an **observation** ("consistent with …"); the examiner draws
31//! the conclusions. Mirrors the fleet producer pattern (typed `AnomalyKind` +
32//! `impl Observation` + `audit_*` → `Vec<Anomaly>` + `audit_findings` →
33//! `Vec<Finding>`), as in `xfs-forensic` / `btrfs-forensic` / `ntfs-forensic`.
34//!
35//! # Honest validation state (Tier-2)
36//!
37//! ReFS has no official spec and no ground-truth corpus. F-INTEGRITY is validated
38//! on the **real resident v3.14 metadata** (a clean volume emits nothing false;
39//! crafted corruption is detected). F-CARVE's stale-page recovery is validated on
40//! a **real resident stale CoW `0x600` page** (carrying `System Volume
41//! Information`) plus synthetic pages; the minted user-file bands are
42//! non-resident (beyond the oracle slice, source VHD lost), so their
43//! deleted-recovery end-to-end is **oracle-blocked** — surfaced as such, never
44//! fabricated. See `docs/validation.md`.
45
46#![forbid(unsafe_code)]
47#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
48
49pub use forensicnomicon::report::Severity;
50use forensicnomicon::report::{Evidence, Finding, Location, Observation, Source};
51
52use refs_core::{BootSector, Checkpoint, MetaBlock, REFS_METADATA_PAGE_SIZE};
53
54// ── ReFS on-disk constants the analyzer parses below `-core` ──────────────────
55
56/// The `MSB+` Minstore metadata-page signature every resident directory / table
57/// page starts with.
58const MSB_SIGNATURE: &[u8; 4] = b"MSB+";
59
60/// Header offset of a metadata page's self (first) block number.
61const SELF_BLOCK_OFFSET: usize = 0x20;
62
63/// Header offset of a metadata page's table identifier.
64const TABLE_ID_OFFSET: usize = 72;
65
66/// ReFS cluster size in bytes (4 KiB — verified on the v3.14 oracle). Metadata
67/// pages sit on cluster boundaries.
68const CLUSTER_SIZE: usize = 4096;
69
70/// The well-known ReFS root-directory object identifier / directory table id.
71const REFS_ROOT_DIRECTORY_TABLE_ID: u64 = 0x600;
72
73/// Byte offset of the SUPB block within the boot+SB image region (cluster 30).
74const SUPERBLOCK_BLOCK_NUMBER: u64 = 30;
75
76/// A sane upper bound on the ReFS cluster size (bytes-per-sector ×
77/// sectors-per-cluster). Real ReFS clusters are 4 KiB–64 KiB; a value beyond this
78/// is a corrupt/hostile geometry field (allocation-bomb guard).
79const MAX_SANE_CLUSTER_SIZE: u64 = 1 << 20; // 1 MiB
80
81// ── F-INTEGRITY: structural-integrity anomaly kinds ───────────────────────────
82
83/// Classification of a ReFS structural-integrity anomaly (F-INTEGRITY). Each
84/// variant carries the evidence needed to reproduce the observation.
85#[derive(Debug, Clone, PartialEq, Eq)]
86#[non_exhaustive]
87pub enum AnomalyKind {
88    /// The boot VBR file-system signature at offset 3 is not `"ReFS\0\0\0\0"` —
89    /// the fail-loud offending bytes are carried so the examiner sees what the
90    /// image really is.
91    BootSignatureInvalid {
92        /// The eight raw bytes found at boot offset 3.
93        found: [u8; 8],
94    },
95    /// A resident metadata block whose stored CRC does not verify over a
96    /// **known/derivable** coverage range. Emitted only via [`audit_crc_range`];
97    /// never auto-fabricated (ReFS's own coverage range is undetermined).
98    MetadataCrcMismatch {
99        /// Which metadata structure failed (`SUPB` / `CHKP` / `MSB+` / caller).
100        structure: &'static str,
101        /// Absolute byte offset of the block in the image.
102        offset: u64,
103        /// The CRC checksum type (`1` = CRC-32C, `2` = CRC64-ECMA-182).
104        checksum_type: u8,
105    },
106    /// A metadata block whose self-recorded block number does not equal the block
107    /// number its actual location decodes to — consistent with a relocated,
108    /// tampered, or misparsed page.
109    SelfBlockMismatch {
110        /// The metadata structure (`SUPB`, `MSB+`, …).
111        structure: &'static str,
112        /// The block number recorded inside the block (header offset `0x20`).
113        recorded: u64,
114        /// The block number the block's location implies.
115        expected: u64,
116        /// Absolute byte offset of the block in the image.
117        offset: u64,
118    },
119    /// The two checkpoint copies the superblock names disagree (or it names none)
120    /// — a torn / tampered checkpoint.
121    CheckpointDivergence {
122        /// Human-readable reason (which invariant the checkpoint set broke).
123        reason: &'static str,
124        /// The checkpoint block numbers the superblock named.
125        checkpoints: Vec<u64>,
126    },
127    /// An object-table entry or directory child that references a virtual block
128    /// that resolves to no resident physical page — a dangling / corrupt
129    /// reference (a recovery lead).
130    ///
131    /// Reserved for a **directory-walk** caller that resolves a specific child
132    /// reference and finds it unresolvable ([`refs_core::RefsError::UnresolvedVirtualBlock`]):
133    /// `audit_image` does **not** emit this over a partial/sliced image, where
134    /// most blocks are legitimately non-resident (a container-table band beyond
135    /// the slice), because doing so would false-positive on every normal ReFS
136    /// slice. It is part of the public vocabulary so a caller that walks the tree
137    /// (and can tell a genuine dangling reference from a not-yet-materialized
138    /// band) can raise it.
139    OrphanedOrUnresolved {
140        /// The unresolved virtual block number.
141        block: u64,
142        /// What referenced it (`object-table entry`, `directory child`, …).
143        referrer: &'static str,
144    },
145    /// A cluster/sector/page geometry field beyond sane bounds — a corruption /
146    /// allocation-bomb guard.
147    ImpossibleGeometry {
148        /// The offending field name.
149        field: &'static str,
150        /// The value read from the structure.
151        value: u64,
152        /// The sane upper bound derived from the image size / spec.
153        limit: u64,
154    },
155}
156
157impl AnomalyKind {
158    /// Severity — the single source of truth for this kind.
159    #[must_use]
160    pub fn severity(&self) -> Severity {
161        match self {
162            AnomalyKind::BootSignatureInvalid { .. }
163            | AnomalyKind::MetadataCrcMismatch { .. }
164            | AnomalyKind::SelfBlockMismatch { .. }
165            | AnomalyKind::CheckpointDivergence { .. }
166            | AnomalyKind::ImpossibleGeometry { .. } => Severity::High,
167            AnomalyKind::OrphanedOrUnresolved { .. } => Severity::Medium,
168        }
169    }
170
171    /// Stable machine-readable, scheme-prefixed code.
172    #[must_use]
173    pub fn code(&self) -> &'static str {
174        match self {
175            AnomalyKind::BootSignatureInvalid { .. } => "REFS-BOOT-SIGNATURE-INVALID",
176            AnomalyKind::MetadataCrcMismatch { .. } => "REFS-METADATA-CRC-MISMATCH",
177            AnomalyKind::SelfBlockMismatch { .. } => "REFS-SELF-BLOCK-MISMATCH",
178            AnomalyKind::CheckpointDivergence { .. } => "REFS-CHECKPOINT-DIVERGENCE",
179            AnomalyKind::OrphanedOrUnresolved { .. } => "REFS-ORPHANED-OR-UNRESOLVED",
180            AnomalyKind::ImpossibleGeometry { .. } => "REFS-IMPOSSIBLE-GEOMETRY",
181        }
182    }
183
184    /// Human-readable, "consistent with" note.
185    #[must_use]
186    pub fn note(&self) -> String {
187        match self {
188            AnomalyKind::BootSignatureInvalid { found } => format!(
189                "boot VBR signature at offset 3 = {found:02x?} is not \"ReFS\\0\\0\\0\\0\" — the volume is not ReFS or the boot record was overwritten"
190            ),
191            AnomalyKind::MetadataCrcMismatch {
192                structure,
193                offset,
194                checksum_type,
195            } => format!(
196                "{structure} at byte {offset}: stored CRC (type {checksum_type}) does not verify over its known coverage range — consistent with corruption or post-write tampering"
197            ),
198            AnomalyKind::SelfBlockMismatch {
199                structure,
200                recorded,
201                expected,
202                offset,
203            } => format!(
204                "{structure} at byte {offset}: self-recorded block number {recorded} does not equal its location's block number {expected} — consistent with a relocated, tampered, or misparsed page"
205            ),
206            AnomalyKind::CheckpointDivergence {
207                reason,
208                checkpoints,
209            } => format!(
210                "checkpoint set {checkpoints:?}: {reason} — consistent with a torn or tampered checkpoint"
211            ),
212            AnomalyKind::OrphanedOrUnresolved { block, referrer } => format!(
213                "{referrer} references virtual block {block} which resolves to no resident physical page — a dangling or corrupt reference (recovery lead)"
214            ),
215            AnomalyKind::ImpossibleGeometry {
216                field,
217                value,
218                limit,
219            } => format!(
220                "geometry field {field} = {value} exceeds the sane bound {limit} for this image — consistent with corruption or an allocation-bomb"
221            ),
222        }
223    }
224
225    fn evidence(&self) -> Vec<Evidence> {
226        match self {
227            AnomalyKind::BootSignatureInvalid { found } => vec![Evidence {
228                field: "boot_signature".to_string(),
229                value: format!("{found:02x?}"),
230                location: Some(Location::ByteOffset(3)),
231            }],
232            AnomalyKind::MetadataCrcMismatch {
233                structure,
234                offset,
235                checksum_type,
236            } => vec![Evidence {
237                field: "metadata_crc".to_string(),
238                value: format!("{structure} checksum type {checksum_type}"),
239                location: Some(Location::ByteOffset(*offset)),
240            }],
241            AnomalyKind::SelfBlockMismatch {
242                structure,
243                recorded,
244                expected,
245                offset,
246            } => vec![Evidence {
247                field: "self_block_number".to_string(),
248                value: format!("{structure} recorded={recorded} expected={expected}"),
249                location: Some(Location::ByteOffset(*offset)),
250            }],
251            AnomalyKind::CheckpointDivergence {
252                reason,
253                checkpoints,
254            } => vec![Evidence {
255                field: "checkpoints".to_string(),
256                value: format!("{checkpoints:?}: {reason}"),
257                location: None,
258            }],
259            AnomalyKind::OrphanedOrUnresolved { block, referrer } => vec![Evidence {
260                field: "unresolved_block".to_string(),
261                value: format!("{referrer} -> {block}"),
262                location: Some(Location::Other {
263                    space: "refs:vblock".to_string(),
264                    value: *block,
265                }),
266            }],
267            AnomalyKind::ImpossibleGeometry {
268                field,
269                value,
270                limit,
271            } => vec![Evidence {
272                field: (*field).to_string(),
273                value: format!("{value} (limit {limit})"),
274                location: None,
275            }],
276        }
277    }
278}
279
280/// A ReFS structural-integrity anomaly: an observation graded by severity, with a
281/// stable code and note derived from its [`AnomalyKind`] so they cannot drift.
282#[derive(Debug, Clone, PartialEq, Eq)]
283pub struct Anomaly {
284    /// Severity, derived from `kind`.
285    pub severity: Severity,
286    /// Stable machine-readable code, derived from `kind`.
287    pub code: &'static str,
288    /// The classified anomaly with its evidence.
289    pub kind: AnomalyKind,
290    /// Human-readable note, derived from `kind`.
291    pub note: String,
292}
293
294impl Anomaly {
295    /// Build an [`Anomaly`], deriving severity/code/note from `kind`.
296    #[must_use]
297    pub fn new(kind: AnomalyKind) -> Self {
298        Anomaly {
299            severity: kind.severity(),
300            code: kind.code(),
301            note: kind.note(),
302            kind,
303        }
304    }
305}
306
307impl Observation for Anomaly {
308    fn severity(&self) -> Option<Severity> {
309        Some(self.severity)
310    }
311    fn code(&self) -> &'static str {
312        self.code
313    }
314    fn note(&self) -> String {
315        self.note.clone()
316    }
317    fn evidence(&self) -> Vec<Evidence> {
318        self.kind.evidence()
319    }
320}
321
322// ── F-INTEGRITY: the image auditor ────────────────────────────────────────────
323
324/// Audit a whole ReFS image for structural-integrity anomalies (F-INTEGRITY):
325/// validate the boot VBR signature + geometry, check the superblock's self-block,
326/// check the checkpoint set the superblock names, and sweep every resident
327/// `MSB+` metadata page for a self-block-number that disagrees with its location.
328///
329/// A clean image yields an empty vector. Malformed input never panics. A metadata
330/// CRC mismatch is **not** emitted here (ReFS's coverage range is undetermined) —
331/// use [`audit_crc_range`] with an explicit, known range.
332#[must_use]
333pub fn audit_image(image: &[u8]) -> Vec<Anomaly> {
334    let mut out = Vec::new();
335
336    // Boot VBR: a bad signature is the fail-loud front door. Everything downstream
337    // (geometry, superblock, checkpoint) depends on a real ReFS boot record, so a
338    // bad signature short-circuits — parsing SUPB/geometry off a non-ReFS image
339    // would fabricate anomalies from noise.
340    let Ok(boot) = BootSector::parse(image) else {
341        // Extract the offending signature bytes for the fail-loud value.
342        let mut found = [0u8; 8];
343        if let Some(s) = image.get(3..11) {
344            found.copy_from_slice(s);
345        }
346        if &found != refs_core::REFS_SIGNATURE {
347            out.push(Anomaly::new(AnomalyKind::BootSignatureInvalid { found }));
348        }
349        // A truncated-but-valid-signature image simply has nothing more to audit.
350        return out;
351    };
352
353    // Impossible geometry: an absurd cluster size (bytes/sector × sectors/cluster)
354    // is a corruption / allocation-bomb guard.
355    let cluster = boot.cluster_size();
356    if cluster == 0 || cluster > MAX_SANE_CLUSTER_SIZE {
357        out.push(Anomaly::new(AnomalyKind::ImpossibleGeometry {
358            field: "cluster_size",
359            value: cluster,
360            limit: MAX_SANE_CLUSTER_SIZE,
361        }));
362        // A broken cluster size makes every downstream offset meaningless; stop
363        // here rather than sweep off a corrupt geometry.
364        return out;
365    }
366
367    // Superblock self-block check: the SUPB at cluster 30 self-records block 30.
368    // Use an open-ended header slice (not a full 16 KiB page) so the check works
369    // even on the 128 KiB boot+SB fixture where the SUPB page is the tail.
370    let sb_off = boot.superblock_offset();
371    if let Some(page) = header_at(image, sb_off) {
372        if page.get(0..4) == Some(refs_core::SUPB_SIGNATURE.as_slice()) {
373            let recorded = le_u64(page, SELF_BLOCK_OFFSET);
374            if recorded != SUPERBLOCK_BLOCK_NUMBER {
375                out.push(Anomaly::new(AnomalyKind::SelfBlockMismatch {
376                    structure: "SUPB",
377                    recorded,
378                    expected: SUPERBLOCK_BLOCK_NUMBER,
379                    offset: sb_off,
380                }));
381            }
382
383            // Checkpoint set: the superblock names its checkpoint block numbers; a
384            // live volume always keeps at least one. Zero named (or a torn set)
385            // is a checkpoint divergence.
386            check_checkpoints(&mut out, page);
387        }
388    }
389
390    // Resident MSB+ self-block sweep: every resident Minstore page carries its own
391    // (virtual) self-block-number. A page whose self-block decodes to a *resident*
392    // low block (block == cluster) but disagrees with its physical cluster is
393    // relocated/tampered. High-band virtual blocks (self-block far beyond the
394    // slice) are the normal ReFS virtual-addressing regime and are NOT flagged
395    // (they need the container table to place, not a tamper signal).
396    sweep_resident_self_blocks(&mut out, image, cluster as usize);
397
398    out
399}
400
401/// Flag a superblock whose checkpoint set is torn (names zero checkpoints — a
402/// live volume always keeps at least one).
403fn check_checkpoints(out: &mut Vec<Anomaly>, superblock_page: &[u8]) {
404    // A superblock too short to hold the checkpoint header is a truncation, not a
405    // divergence — the `Err` case is left alone (no fabricated verdict from a
406    // short buffer); only a successfully parsed, EMPTY checkpoint set is torn.
407    if let Ok(checkpoints) = Checkpoint::locations_from_superblock(superblock_page) {
408        if checkpoints.is_empty() {
409            out.push(Anomaly::new(AnomalyKind::CheckpointDivergence {
410                reason: "the superblock names zero checkpoint copies (a live volume keeps at least one)",
411                checkpoints,
412            }));
413        }
414    }
415}
416
417/// Sweep every physically resident `MSB+` page and flag any whose self-block
418/// number decodes to a *resident low block* (block < resident cluster count) that
419/// disagrees with the page's actual physical cluster — consistent with a
420/// relocated/tampered page. Virtual (high-band) self-blocks are the normal ReFS
421/// addressing regime and are not flagged.
422fn sweep_resident_self_blocks(out: &mut Vec<Anomaly>, image: &[u8], cluster_size: usize) {
423    if cluster_size == 0 {
424        return; // cov:unreachable: audit_image rejects a zero cluster size before calling
425    }
426    let clusters = image.len() / cluster_size;
427    let resident_ceiling = clusters as u64;
428    for c in 0..clusters {
429        let off = c * cluster_size;
430        let Some(page) = block_at(image, off as u64) else {
431            break; // cov:unreachable: c < clusters bounds off + page within image
432        };
433        if page.get(0..4) != Some(MSB_SIGNATURE.as_slice()) {
434            continue;
435        }
436        let self_block = le_u64(page, SELF_BLOCK_OFFSET);
437        // Only a self-block that CLAIMS to be a low resident block (below the
438        // image's own cluster count) can be checked against its physical cluster.
439        // A high-band virtual self-block is placed by the container table, not by
440        // block==cluster, so comparing it here would false-positive on every
441        // normal ReFS page.
442        if self_block < resident_ceiling && self_block != c as u64 {
443            out.push(Anomaly::new(AnomalyKind::SelfBlockMismatch {
444                structure: "MSB+",
445                recorded: self_block,
446                expected: c as u64,
447                offset: off as u64,
448            }));
449        }
450    }
451}
452
453/// Audit a resident metadata block's CRC over a **caller-supplied, known**
454/// coverage range `[start..end]` against `stored`, returning an
455/// [`AnomalyKind::MetadataCrcMismatch`] anomaly when it does not verify, or
456/// `None` when it verifies OR the range is out of bounds.
457///
458/// This is the **only** path that emits `REFS-METADATA-CRC-MISMATCH`. ReFS's own
459/// whole-block checksum coverage range is undetermined in the reverse-engineered
460/// references (see [`refs_core`]'s `metablock` docs), so this crate never guesses
461/// it and never auto-fabricates a corruption verdict on a clean block (the
462/// LZNT1-trap the fleet standards warn against). A future phase that pins ReFS's
463/// range calls this with the confirmed bounds.
464///
465/// `offset` is the block's absolute byte position (for the finding location).
466/// This checks CRC-32C (ReFS checksum type `1`).
467#[must_use]
468pub fn audit_crc_range(
469    block: &[u8],
470    offset: u64,
471    start: usize,
472    end: usize,
473    stored: u32,
474) -> Option<Anomaly> {
475    match MetaBlock::verify_crc32c(block, start, end, stored) {
476        Some(true) | None => None,
477        Some(false) => Some(Anomaly::new(AnomalyKind::MetadataCrcMismatch {
478            structure: "caller-supplied range",
479            offset,
480            checksum_type: 1,
481        })),
482    }
483}
484
485/// Audit an image and convert each F-INTEGRITY anomaly to a canonical [`Finding`]
486/// tagged with `scope`.
487#[must_use]
488pub fn audit_findings(image: &[u8], scope: &str) -> Vec<Finding> {
489    let source = Source {
490        analyzer: "refs-forensic".to_string(),
491        scope: scope.to_string(),
492        version: None,
493    };
494    audit_image(image)
495        .iter()
496        .map(|a| a.to_finding(source.clone()))
497        .collect()
498}
499
500// ── F-CARVE: CoW metadata-residue recovery ────────────────────────────────────
501
502/// A recovered stale (old-CoW) metadata page: an `MSB+` directory page whose
503/// self-block-number is NOT the current object-table mapping, so it is a
504/// superseded version left behind by allocate-on-write. Its carved directory
505/// entries are potential deleted / renamed / superseded names.
506#[derive(Debug, Clone, PartialEq, Eq)]
507#[non_exhaustive]
508pub struct StalePage {
509    /// The page's self-recorded (virtual) block number.
510    pub self_block: u64,
511    /// The page's table identifier (`0x600` = root directory).
512    pub table_id: u64,
513    /// Absolute byte offset of the stale page in the image.
514    pub offset: u64,
515    /// The carved directory-entry names found in the stale page.
516    pub entries: Vec<String>,
517}
518
519/// Recover CoW metadata residue (F-CARVE): scan `image` for `MSB+` directory
520/// pages whose self-block-number is NOT the current version (= stale/old versions
521/// left behind by allocate-on-write), and carve the directory-entry rows found in
522/// them.
523///
524/// **The current-version discriminator (grounded in allocate-on-write).** ReFS
525/// never overwrites a metadata page in place: an update writes a NEW page at a
526/// NEW (monotonically higher) block number and re-points the tree at it, leaving
527/// the OLD page behind. So among all resident pages sharing a table identifier,
528/// the one with the **highest self-block-number is the current version** and every
529/// lower-numbered copy is stale residue. This is corroborated by the object table
530/// on the real oracle (its resolvable view maps `0x600` to the highest resident
531/// `0x600` block, `80_384`, not the stale `70_656`) — but the highest-block rule
532/// needs no single "current" object table (the oracle keeps several CoW copies of
533/// the object table itself, which disagree), so it is the robust signal.
534///
535/// Only page copies that (a) are not the highest self-block for their table id AND
536/// (b) carry carvable directory-entry rows the current version does not are
537/// surfaced — a stale page whose entries all survive in the current version is not
538/// actionable residue.
539///
540/// Returns what IS found. The minted user-file bands are non-resident in the
541/// available oracle (beyond the slice, source VHD gone), so their deleted-recovery
542/// end-to-end cannot be reproduced here — this returns the resident stale pages
543/// only and NEVER fabricates absent files. Malformed input never panics.
544#[must_use]
545pub fn recover_residue(image: &[u8]) -> Vec<StalePage> {
546    // Pass 1: for each directory table id, find the highest self-block (= current
547    // CoW version) and the carved entries of that current page.
548    let mut current: Vec<(u64, u64, Vec<String>)> = Vec::new(); // (table_id, self_block, entries)
549    for (off, page) in resident_msb_pages(image) {
550        let table_id = le_u64(page, TABLE_ID_OFFSET);
551        if table_id != REFS_ROOT_DIRECTORY_TABLE_ID {
552            continue;
553        }
554        let self_block = le_u64(page, SELF_BLOCK_OFFSET);
555        let _ = off;
556        match current.iter_mut().find(|(t, _, _)| *t == table_id) {
557            Some(entry) if self_block > entry.1 => {
558                entry.1 = self_block;
559                entry.2 = carve_directory_entries(page);
560            }
561            Some(_) => {}
562            None => current.push((table_id, self_block, carve_directory_entries(page))),
563        }
564    }
565
566    // Pass 2: surface every lower-than-current directory page whose carved entries
567    // include a name the current version no longer holds (deleted/renamed/
568    // superseded).
569    let mut out = Vec::new();
570    for (off, page) in resident_msb_pages(image) {
571        let table_id = le_u64(page, TABLE_ID_OFFSET);
572        if table_id != REFS_ROOT_DIRECTORY_TABLE_ID {
573            continue;
574        }
575        let self_block = le_u64(page, SELF_BLOCK_OFFSET);
576        let Some((_, cur_block, cur_entries)) = current.iter().find(|(t, _, _)| *t == table_id)
577        else {
578            continue; // cov:unreachable: pass 1 recorded a current entry for every table id seen here
579        };
580        // The current version itself is live, not stale.
581        if self_block >= *cur_block {
582            continue;
583        }
584        // Carve the stale page's entries and keep only those the current version
585        // dropped — a name still present in the current directory is not residue.
586        let dropped: Vec<String> = carve_directory_entries(page)
587            .into_iter()
588            .filter(|name| !cur_entries.contains(name))
589            .collect();
590        if dropped.is_empty() {
591            continue;
592        }
593        out.push(StalePage {
594            self_block,
595            table_id,
596            offset: off,
597            entries: dropped,
598        });
599    }
600    out
601}
602
603/// Iterate every physically resident `MSB+` metadata page as `(byte_offset,
604/// page_bytes)`, skipping any cluster that is not a full in-bounds `MSB+` page.
605fn resident_msb_pages(image: &[u8]) -> impl Iterator<Item = (u64, &[u8])> + '_ {
606    let clusters = image.len() / CLUSTER_SIZE;
607    (0..clusters).filter_map(move |c| {
608        let off = c * CLUSTER_SIZE;
609        let page = block_at(image, off as u64)?;
610        if page.get(0..4) == Some(MSB_SIGNATURE.as_slice()) {
611            Some((off as u64, page))
612        } else {
613            None
614        }
615    })
616}
617
618/// Carve the directory-entry names from a Minstore directory page: the `0x30`
619/// entry records' keys carry the UTF-16LE name at key offset `4`.
620fn carve_directory_entries(page: &[u8]) -> Vec<String> {
621    let Ok(node) = refs_core::parse_directory(page) else {
622        return Vec::new(); // cov:unreachable: a page that reached here already parsed its node header in the caller's ObjectTable path; guarded for a page that is MSB+ but has a malformed node header
623    };
624    node.into_iter().map(|e| e.name).collect()
625}
626
627// ── shared private helpers ────────────────────────────────────────────────────
628
629/// The 16 KiB metadata page at absolute byte `offset`, or `None` if it does not
630/// fully fit within the image (never over-reads / panics).
631fn block_at(image: &[u8], offset: u64) -> Option<&[u8]> {
632    let start = usize::try_from(offset).ok()?;
633    let end = start.checked_add(REFS_METADATA_PAGE_SIZE)?;
634    image.get(start..end)
635}
636
637/// The open-ended metadata-block header slice from absolute byte `offset` to the
638/// end of the image, or `None` if `offset` lies past the end. Used for the
639/// superblock's header-region checks (self-block, checkpoint fields), which live
640/// in the first ~200 bytes, so a partial tail page (the 128 KiB boot+SB fixture)
641/// is enough — the bounds-checked field reads below never over-read.
642fn header_at(image: &[u8], offset: u64) -> Option<&[u8]> {
643    let start = usize::try_from(offset).ok()?;
644    image.get(start..)
645}
646
647/// Bounds-checked little-endian `u64` read (yields `0` out of range). The
648/// analyzer parses raw page bytes directly (the reader/analyzer split), so it
649/// carries its own panic-free reader.
650fn le_u64(d: &[u8], o: usize) -> u64 {
651    d.get(o..o.saturating_add(8))
652        .and_then(|b| <[u8; 8]>::try_from(b).ok())
653        .map_or(0, u64::from_le_bytes)
654}
655
656#[cfg(test)]
657mod unit {
658    use super::{block_at, le_u64, Anomaly, AnomalyKind};
659    use crate::Severity;
660    use forensicnomicon::report::{Observation, Source};
661    use refs_core::REFS_METADATA_PAGE_SIZE;
662
663    /// Every `AnomalyKind` variant maps to a stable code, a graded severity, a
664    /// non-empty observational note, and non-empty backing evidence — and each
665    /// converts to a `forensicnomicon` Finding. This exercises the whole
666    /// vocabulary (including `OrphanedOrUnresolved`, reserved for a directory-walk
667    /// caller, and `MetadataCrcMismatch`, emitted only via `audit_crc_range`), so
668    /// the observation surface is proven without fabricating a false-positive
669    /// emission path in `audit_image`.
670    #[test]
671    fn every_anomaly_kind_has_code_severity_note_evidence_and_finding() {
672        let kinds = [
673            AnomalyKind::BootSignatureInvalid { found: [0u8; 8] },
674            AnomalyKind::MetadataCrcMismatch {
675                structure: "SUPB",
676                offset: 0x1e000,
677                checksum_type: 2,
678            },
679            AnomalyKind::SelfBlockMismatch {
680                structure: "MSB+",
681                recorded: 999,
682                expected: 3,
683                offset: 12288,
684            },
685            AnomalyKind::CheckpointDivergence {
686                reason: "torn",
687                checkpoints: vec![157_156, 1_885_500],
688            },
689            AnomalyKind::OrphanedOrUnresolved {
690                block: 34_494_087_168,
691                referrer: "directory child",
692            },
693            AnomalyKind::ImpossibleGeometry {
694                field: "cluster_size",
695                value: u64::MAX,
696                limit: 1 << 20,
697            },
698        ];
699        let source = Source {
700            analyzer: "refs-forensic".to_string(),
701            scope: "unit".to_string(),
702            version: None,
703        };
704        for kind in kinds {
705            let a = Anomaly::new(kind);
706            assert!(
707                a.code.starts_with("REFS-"),
708                "code is scheme-prefixed: {}",
709                a.code
710            );
711            assert!(!a.note.is_empty(), "note is non-empty for {}", a.code);
712            assert!(
713                !a.kind.evidence().is_empty(),
714                "evidence is non-empty for {}",
715                a.code
716            );
717            // Severity is graded (High for structural, Medium for the orphan lead).
718            let sev = a.severity;
719            assert!(matches!(sev, Severity::High | Severity::Medium));
720            // Converts to a canonical Finding carrying the code + source.
721            let f = a.to_finding(source.clone());
722            assert_eq!(f.code, a.code);
723            assert_eq!(f.source.analyzer, "refs-forensic");
724            assert_eq!(f.severity, Some(sev));
725        }
726    }
727
728    #[test]
729    fn le_u64_yields_zero_out_of_range() {
730        assert_eq!(le_u64(&[0, 0, 0], 0), 0);
731        assert_eq!(le_u64(&[1, 0, 0, 0, 0, 0, 0, 0], 0), 1);
732    }
733
734    #[test]
735    fn block_at_requires_a_full_page() {
736        let short = vec![0u8; REFS_METADATA_PAGE_SIZE - 1];
737        assert!(block_at(&short, 0).is_none());
738        let full = vec![0u8; REFS_METADATA_PAGE_SIZE];
739        assert!(block_at(&full, 0).is_some());
740        // An offset past the end yields None (no over-read).
741        assert!(block_at(&full, 1).is_none());
742    }
743}