docs

ReFS Documentation

Reverse engineering documentation for the Resilient File System (ReFS), covering versions 3.4 through 3.14 and Insider build 29574. Based on a master thesis combining static analysis of refs.sys (4 builds with full PDB symbols) with raw disk analysis of 110+ parseable ReFS disk images across 5 production versions.

Knowledge Map — the single index from any topic to its authoritative sources (master-reference section, findings, evidence). · Directory indexes: structures · concepts · attributes · examples. How this was verified — the dual-evidence methodology, evidence levels, and how to trace any claim to its provenance. · Conventions for adding pages.

New to ReFS forensics? Start with the Forensic Analysis Workflow (end-to-end runbook), the Carrier categories (how the artifacts are organised), and What Survives (delete / format / upgrade).

Quick Start

1. Architecture -- two-layer driver model and three-tier IRP dispatch
2. Bootstrap Chain -- how to traverse from VBR to any table
3. Version Evolution -- what changed across v3.4 through Insider
4. How this was verified -- the dual-evidence method and how to trace any claim

Core Concepts

Page	Topic
Architecture	Refs*/Cms* two-layer model, three-tier IRP dispatch
Bootstrap Chain	GPT → VBR → SUPB → CHKP → Container Table → target
Virtual Addressing	VLCN-to-PLCN translation via Container Table
Cluster and Page Size	4 KiB vs 64 KiB clusters, page size derivation
Copy-on-Write	Fundamental update model and forensic implications
Checksum Architecture	CRC64/SHA-256 Merkle tree, page reference sizes
Resident Storage	Inline vs extent-based content storage
$STANDARD_INFORMATION	Timestamp fields and version-dependent layout
Timestomping Detection	Multi-source timestamp-tamper detection ($SI change-time + USN journal + volume bound)
Attributes	The ReFS attribute schemas — 12 on v3.4, 16 on v3.14 (18 distinct across all versions)
Version Evolution	v3.4 through Insider structural changes
Version Detection	Classifying upgrade state from CHKP flags
Deletion Recovery	Five recovery methods: Trash Table, checkpoint differential, orphan scan, stream-snapshot reconstruction, B+-tree node-slack carve
What Survives	Artifact-vs-event survival matrix (delete / format / upgrade / unmount / crash)
Carrier Categories	Carrier's five data categories applied to ReFS
Tool-to-Artifact Map	For each forensic goal, which forefst.py / refsanalysis.py invocation surfaces it
Hard Links	Multi-name files: shared FileId identity, why $SI+0x70 is a decoy
Snapshots and Versioning	$SNAPSHOT stream snapshots and prior-content recovery
Integrity Streams	Per-file opt-in block checksums (file_attrs & 0x8000)
WSL / Linux Metadata	$LXUID/$LXGID/$LXMOD/$LXDEV EAs and WSL device nodes
Artifact Timeline	Timestamp sources and super-timeline construction
Transactions / Crash Consistency	Redo-only MLog + checkpoint atomicity
Redundancy	Boot-sector, superblock, checkpoint copies
Object IDs and FileIds	The cross-table join key; OID vs per-directory ordinal
OID Allocation	Monotonic counter, gaps as deletion evidence
Space Allocation	Three-tier bitmap allocator (Medium / Container / Small)
Compression	Per-container 24H2 volume compression
Deduplication	Opt-in post-process block sharing
Tiered Storage	Fast/slow tier relocation and the heat engine
File Systems	General file system background
Windows File Systems	Windows I/O stack and driver model

On-Disk Structures

Bootstrap Chain

Page	Structure
VBR	Volume Boot Record (sector 0)
SUPB	Superblock (LCN 0x1E)
CHKP	Checkpoint (13 root pointers)

B+-Tree Engine

Page	Structure
Page Header	80-byte common metadata header
Page References	Three formats: 104B, 48B, 72B
B+-Tree Node	MSB+ page format, inner/leaf nodes

System Tables (13 Roots)

Page	Structure
Object Table	OID-to-LCN mapping (roots 0/5)
Schema Table	Key-comparison rules (roots 3/9)
Container Table	VLCN-to-PLCN translation (roots 7/8)
Parent-Child Table	Directory hierarchy (root 4)
Allocators	Three-tier allocation: Medium (1), Container (2), Small (12)
Block Refcount	Shared block counts (root 6)
Container Index	Container lookup by state (root 10)
Integrity State	Per-range integrity tracking (root 11)
System OIDs	All system object identifiers

Metadata Structures

Page	Structure
Directory Entries	Type 0x30 rows, resident/non-resident layouts
Reverse Index (Type 0x20)	Per-object FileId-resolution index (name ↔ FileId ↔ home dir)
Extent Descriptors	Type 0x40 rows, VLCN-to-PLCN mapping
Reparse Points	Global reparse-point index table (24-byte key, OID 0x540/0x541)
Security Descriptors	OID 0x530 single-table model (SecurityId → descriptor)
Upcase Table	Unicode case-folding
Volume Info	OID 0x500 (label, version, schema count)
Trash Table	Async deletion queue (OID 0x0D)

Recovery Structures

Page	Structure
MLog	Metadata log (redo-only journaling)
USN Journal	V3 format with 128-bit file IDs

Attributes

The Attributes — Forensic Reference is the entry point: the catalog of the real ReFS attributes, the NTFS attribute names that have no ReFS equivalent, the on-disk layout, and the forensically important elements.

Byte-level detail pages: $DATA · $STANDARD_INFORMATION · $OBJ_LINK · $I30_INDEX · $EA_INFORMATION / $EA · $EFS · $SNAPSHOT · $NAMED_DATA · $REPARSE_POINT · Reparse Index · $VOLUME_INFORMATION

Driver Internals

Page	Topic
Driver Interface	Import tables, embedded libraries, subsystem growth, IRP handlers

(The two-layer driver model is in Architecture, listed under Core Concepts.)

Research

Page	Topic
NTFS Comparison	Structural mapping for NTFS practitioners

Tools

Page	Tool
forefst.py	Unified forensic tool — timeline-ready listings, deleted/CoW recovery, and the forensic suite (USN, MLog, timeline, timestomp, extract, security, reparse, deleted, recyclebin, snapshots, dataruns, integrity, export, specials)
refsanalysis.py	Structure / lab tool — decode one on-disk structure at a time (VBR, SUPB, CHKP, object/schema/container tables, …)

Examples

Worked walkthroughs (step-by-step investigations)

Walkthrough	Goal
Decode the VBR by hand	Read every VBR field from a hexdump → version, cluster size, checksum algorithm, container size (no tool)
Find a deleted file	Run the deletion-recovery methods (Trash Table, orphan scan, OID density, CoW prior-content) on one image
Detect timestomping	Cross $SI change-time vs USN journal vs volume-creation bound to flag a tampered timestamp
Read a hard-link group	Resolve every name of one physical object via home-backref + child-ordinal + content fingerprint
Identify native vs upgraded	Classify volume state from CHKP flags (0x002 / 0x602 / 0x682) and the immutable VBR format-time fields

Raw tool dumps

File	Content
VBR Win10	VBR output from a v3.4 volume
VBR Win11	VBR output from a v3.14 volume
Summary Win10	Full volume summary (v3.4, 2 TB)
Summary Win11	Full volume summary (v3.14, 2 TB)
Schema Win11	Schema Table dump (v3.14)

Reference

Page	Content
Methodology	How every claim was verified; evidence levels; tracing provenance
Glossary	Key terms and definitions
Changelog	Release history