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}