In Short 🔗

This project provides a current, byte-level reference for the ReFS 3.4-3.14 on-disk format, together with an open-source forensic implementation and the research material used to validate it:

• The ReFS format reference, xbpt.gitlab.io/forefst/, documenting the structures, attributes, main concepts like addressing or checksum mechanisms and version-specific changes (also as plain Markdown in the repository).
• The open-source forensic tool, forefst.py, for analysing ReFS volumes, including file metadata, deleted data, journals, hard links and special files.
• The reproducible research methodology and lab materials, combining reverse engineering of Microsoft’s refs.sys driver with analysis of more than 100 disk images to validate the documented structures and behaviours.

The goal is not simply to produce a ReFS parser. The goal is to make modern ReFS forensic analysis explainable and independently verifiable, and to provide a path towards forensically sound ReFS analysis. Important parser decisions should be traceable to observed structures, driver behaviour or reproducible experiments.

The reference makes the tool explainable, the tool makes the reference useful, and the underlying evidence makes both auditable.

Introduction 🔗

ReFS (Resilient File System) is Microsoft’s modern file system ¹. Introduced with Windows Server 2012 fourteen years ago, it remained for a long time relatively uncommon outside Storage Spaces on servers but this is changing: ReFS is now the default file system for Dev Drive on Windows 11, is increasingly used on Windows Server, and recent Windows Server Insider builds support booting directly from ReFS volumes ². I see this evolution, together with the rapid evolution of the ReFS driver itself, as pointing towards ReFS becoming Microsoft’s main file system and eventually succeeding NTFS. But even today, forensic investigators may encounter ReFS volumes in real investigations, making a solid understanding of its internals and reliable tools for forensic analysis essential now, not only in the future.

Unlike NTFS, ReFS has no Master File Table or in-place metadata updates; instead, it organizes metadata as a forest of B+-trees updated through copy-on-write, with checksummed metadata and optionally data, stream snapshots, and transactions recorded through a redo-only log. These concepts are not unique to ReFS: ReiserFS, ZFS, Btrfs, and APFS all implement variations of similar ideas. What distinguishes ReFS is Microsoft’s own implementation, split between the upper file-system layer and the lower Minstore key-value engine that produces the specific on-disk structures. These architectural choices make ReFS forensics fundamentally different from the better-established NTFS case.

However, the forensic literature has not followed the evolution of the file system. The most comprehensive public analysis remains the work of Prade, Groß, and Dewald on ReFS 3.4 from 2019 ³ ⁴. It provides a solid baseline, but describes the Windows 10 1803 era, while Microsoft has changed the format several times since. The tooling landscape faces a similar gap: open-source tools such as libfsrefs, refsprog, pyrefs, the Sleuth Kit extension by Prade et al., and journal parsers such as ARIN each cover only part of the format or an earlier version. Some commercial, closed-source tools also support ReFS, but the extent of that support is unclear and their results are difficult to independently audit. There is therefore a growing gap between the ReFS volumes encountered today and the publicly documented knowledge and tooling available to forensic examiners ⁵.

So I tried to close part of that gap by reverse engineering ReFS (the refs.sys driver), mainly versions 3.4 and 3.14, and systematically verifying the structures against a lab corpus of more than a hundred disk images. The result is the three parts mentioned above: the ReFS reference documentation (structures, attributes, concepts, and more), the ReFS forensic tool (forefst.py) and the ReFS lab materials (everything needed to reproduce and audit the structural analysis: hypervisor scripts, file-activity generators, tool output, some disk images and the refsanalysis.py tool)

This project started as my master’s thesis (Forensic Analysis of the Resilient File System (ReFS) Version 3.14, University of Mons, 2026). I chose ReFS forensics because it was both an interesting technical subject and an area where better forensic knowledge could be useful to others. The thesis provided a solid foundation, but the work was not quite finished. I therefore continued it beyond the thesis, consolidating the findings into a more complete and reproducible reference and further improving the practical tool for forensic analysis.

I hope I have built and documented a solid understanding of current ReFS and provided a forensic tool built on knowledge that others can inspect, verify, and improve.

From NTFS to ReFS 🔗

NTFS forensics has familiar entry points: $MFT, $UsnJrnl:$J, $LogFile, $SDS. ReFS has none of them. There is no fixed-location metadata file and no MFT-like table: metadata lives in B+-trees reached from the checkpoint, directories are addressed by Object ID rather than by record number, and files exist as rows in their parent’s tree, identified by a value unique within their creation directory. The layout of these rows is itself described by an on-disk Schema Table rather than by fixed structures.

Except for the bootstrap chain, every address on the volume is virtual (with two levels of indirection!), so nothing can be resolved until the Container Table is loaded, and the Container Table can only be reached by walking the whole chain of anchors first (Bootstrap Chain, Virtual Addressing). The links of that chain are version-dependent (see Version Evolution) and misinterpreting any one of them can result in completely wrong output or no output.

Some important differences between NTFS and ReFS are:

The full comparison, difference by difference with its forensic consequence, is on the NTFS vs ReFS page.

Supporting ReFS therefore does not mean writing a parser, it means decoding and implementing the file system because the real barrier is not parsing difficulty, but the lack of a recent public byte-level map of the current format to implement from.

The Reference 🔗

That study of the format is the biggest part of the work: the ReFS on-disk format from version 3.4 to the current 3.14, published as a browsable reference at xbpt.gitlab.io/forefst and as plain Markdown in the repository.

The scope covers the whole format: the bootstrap chain (VBR, superblock, checkpoint, Container Table), the B+-tree page engine, the system tables that map every object to its bytes, the directory entries, every attribute from $STANDARD_INFORMATION ($SI) to $SNAPSHOT, both journals, the security descriptors. In practice that means dozens of structure pages, the attribute set, the concept pages that give them a forensic reading (copy-on-write, what survives a delete / format / upgrade, version detection, etc), worked examples with real tool output. And it is not a compilation of existing knowledge: a large part of it did not exist in the literature.

Some of the main findings, each documented on its own page, are:

• The addressing chain, fully mapped. How ReFS locates data on disk: virtual cluster numbers resolved through the Container Table, in two hops instead of NTFS’s one. The container rows could only be partially decoded in 2019; every field now has a name — and the physical start cluster is not at the fixed offset prior work assumed, because the row grows from 160 to 224 bytes on 64 KiB-cluster or SHA-256 volumes, which shifts the field (Virtual Addressing, Container Table).
• The indirect root list. A checkpoint flag indicates whether CHKP+0x94 holds the thirteen root offsets directly or a single offset to that list elsewhere in the same page. A parser that misses the flag reads invalid data where the root list should be (Checkpoint).
• The page reference shrank. The structure that anchors every metadata page went from 104 bytes to 48, with a 72-byte variant when SHA-256 is in use. It is one of the changes most likely to break a 3.4-era parser (Page References). Resident files — two properties, not one. Prior work describes $DATA on ReFS 3.4 as always non-resident. That is correct for the format it studied: on volumes formatted ≤ 3.10 the main stream is never inline, whatever its size. From format 3.11 the driver stores a stream of fewer than 2 KiB inside the B+-tree row, and a tool that assumes every file’s content lives in external clusters will not find those files on a current volume. Two things had been conflated under the word resident: where a file’s record sits (embedded in its directory-entry row, or split out into its own record — which a move or a hard link forces) and where its bytes are (inline in the record, or in clusters — decided by the volume’s format version and the stream size, and never changed by a move or a link). The verdict on residency comes from the $DATA descriptor itself, not from the size of the row (Resident Storage).
• The attribute set, documented in full. Prior work sketched only a handful of attributes. ReFS stores them across two nested levels of B+-tree — the object’s own tree, then a mini-tree embedded inside a single value — and a parser that handles only the outer level reads a file’s name and timestamps but misses its data streams, its alternate data streams, its reparse target and its extended attributes entirely. Every attribute now has its own byte-level page, from $STANDARD_INFORMATION and $DATA to $SNAPSHOT, $EFS, $REPARSE_POINT and the EA records (Attributes).
• $STANDARD_INFORMATION changed. Eight new bytes in the one attribute every timestamp analysis depends on ($STANDARD_INFORMATION).
• The checksum architecture, mapped end to end. A four-level Merkle tree from the boot sector down to individual B+-tree pages, three checksum algorithms (a CRC-64/NVME polynomial (0xAD93D23594C93659, the one also used by NVMe), CRC32-C, SHA-256) plus three more checksum families that live outside that tree entirely (MLog record XOR-folds, per-compression-unit checksums, per-cluster integrity-stream CRC32-C) (Checksum Architecture).
• A native-format marker and a version echo. New checkpoint and boot-sector fields that an in-place upgrade can never set. They make it possible to classify a volume as original, upgraded or native (Version Detection, VBR).
• New system tables. A Candidate Table, a Heat Engine, a Session Activity Table that records mount sessions, and, on Insider builds, a TPM-bound attestation table (Version Evolution).
• Features that postdate the literature. Stream snapshots (point-in-time copies of a file’s content), WSL metadata, Dev Drive: each got its own page (Snapshots, WSL Metadata).
• Hard links. It is also a feature that postdates the literature because ReFS is often described as not supporting hard links but recent native volumes do. But nothing on disk records how many names a file has — the $SI field named HardLinkCount always reads 1 — so the count has to be reconstructed by joining directory entries back to the stream they share. Two by-products for the analyst: linking a file forces it out of resident storage, and every name carries a backref to the directory the file was first created in, a piece of provenance available nowhere else (Hard Links).
• Unique Directory ID and FileId. Object IDs (OID) are unique IDs for directories and system objects. They are monotonic and never reused, so a gap in the sequence is durable proof that a directory or system object existed and was deleted, even after a full overwrite. NTFS has nothing equivalent, since it recycles its MFT record numbers and erases this evidence over time (Deletion & Recovery, Object IDs). Another interesting finding was that ReFS also uses a unique ID (I named it FileRef) for files based on the OID of the directory in which the file was created and the file’s reference within that directory. And that ID is never reused either, so a gap in these IDs is also a proof of deletion. In the tools, the term ObjectRef is used for ObjectID and FileRef.
• Journals: MLog & USN. The MLog four-layer record format and new redo-opcodes are decoded (MLog). The USN Journal’s USN_RECORD_V3 structure is documented, including its 128-bit File IDs and their correlation with FileRefs (USN Journal).

To my knowledge, this is the most complete public documentation of the current format.

Everything in it is verified the same way. Each structural statement carries a graded evidence level, and a byte-level claim is accepted only when supported by two independent sources: the decompiled refs.sys driver and the lab corpus (100+ disk images covering multiple production versions, sizes, cluster sizes, targeted tests (hard links, wsl, reparse files, etc), checksum configurations, disk parameters, etc). Static analysis shows what the driver expects, raw-disk analysis shows what is actually written; and requiring the two to agree discarded several hypotheses that seemed plausible based on only one. And finally, the tools are regression-tested against that corpus after each new finding or functionality. The method has its own page (here for more details); if someone asks “how do you know this field is right?”, there is a written answer.

That evidence base also has edges, and they are worth stating. The corpus was produced under controlled laboratory conditions, so volumes with years of real activity, genuine crash recovery or petabyte-scale capacity may behave in ways it does not capture. Storage Spaces and tiered deployments — the production setting ReFS is most often paired with — were not exercised at all. Compression and deduplication were located in the driver and their supporting structures documented, but neither was exercised at scale: no compressed content was produced, and a single deduplication-enabled image is not a basis for dedup-aware content reconstruction. And ReFS keeps moving: the Insider build already shows a driver advertising a 3.15 format it does not yet write. None of this makes the documented layout wrong; it simply marks where it stops.

One honesty note, because I think it matters: the code was written with heavy LLM assistance. What makes the result useful is not how it was generated, but the methodology used to verify it and make its findings reproducible. That said, errors are obviously possible, so tell me if you find any errors or inconsistencies.

The Tools 🔗

Two tools were developed: forefst and refsanalysis. While forefst is the main forensic tool, refsanalysis played an important role in studying, validating, and improving the reference documentation, and remains useful for retrieving specific information.

forefst.py 🔗

If you only want a csv output like the one from MFTECmd for NTFS, use files; it outputs all the important information about the files. If you want more information about a targeted file, use details on that file. You can also directly read an ADS, export a snapshot, etc.

But there is a lot more:

• Volume triage — summary: version, cluster size, object counts, checksum state, upgraded status, etc.
• Enumerate and filter
  • File listing — files: every file and directory with ~40 metadata columns, in CSV, JSON, JSONL or body format.
  • File details — details dumps every attribute of one entry, addressed by path (or by OID, for a directory or system object).
  • File search — search: case-insensitive substring match on names across the whole volume.
• Inspect special artefacts
  • Special files — specials lists files carrying a special attribute: ADS, reparse points, WSL metadata, hard links, sparse, encrypted, compressed, integrity streams.
  • Security descriptors — security lists each security descriptor: owner, group, control flags, DACL/SACL ACEs.
  • Snapshotted files — snapshots lists and extracts a file’s own $SNAPSHOT attribute.
• Extract and Recover
  • Content extraction — extract writes out a single file’s content.
  • Deleted files — deleted is a command of its own, since the files listing covers the live tree only. It runs the Trash Table, the checkpoint diff and a B+-tree node-slack scan, with --full adding an orphan-page pass and carving; each remnant gets a recoverability verdict, and export deleted writes back what can be recovered. Copy-on-write leaves far more behind than an in-place file system does, and every run keeps a recovery log.
  • Recycle bin — recyclebin walks $RECYCLE.BIN/<SID>/ and decodes each $I metadata file — the original full path, deletion time, and logical size of a recycled item — and reports whether its $R payload still survives. If so, it can be exported.
• Journal analysis
  • MLog (Metadata Log) — mlog --parse does for ReFS what a $LogFile parser does for NTFS, promoting redo records into filesystem actions (CREATE, WRITE, RENAME, MOVE, DELETE).
  • Update Sequence Number (USN) — usn reads the change journal, the counterpart of $UsnJrnl:$J, but using V3 records.
• More Experimental/Informational Features
  • Super-timeline — timeline: ReFS scatters time across three different artefacts, the $SI MACB times, the USN journal and the MLog transaction log, and this merges them into one chronological output with names and paths resolved from the volume. Because the three are independent, they also cross-validate each other (Artifact Timeline).
  • Anti-forensics — timestomp: the replacement for the $SI-versus-$FN check that ReFS makes impossible, combining change-time heuristics, USN corroboration and hard-link $SI divergence, with a severity per finding (Timestomp Detection).

The output formats are csv, json, jsonl or body. Sample images are published with the repository, so the tool can be tried without a ReFS volume at hand:

python3 forefst.py sample.raw summary          # volume overview
python3 forefst.py sample.raw files --csv files.csv     # full file listing

summary is what you run first. It answers, in one screen, the questions that decide how everything else must be read — which format version, which checksum algorithm, and whether the volume was formatted natively or upgraded in place:

$ ./forefst.py /mnt/data/disks/step3b/win11refs2tmillionsofactionsv2.raw summary
[forefst v1.4.0] Opening win11refs2tmillionsofactionsv2.raw...
[forefst] ReFS 3.14 | 512 objects | cluster_size=4096
[forefst] Running summary...
[forefst] Walking directory tree for full summary...
Tip: `fastsummary` = quick volume metadata (no directory walk).
==============================================================================
ReFS Volume Fast Extended Summary
------------------------------------------------------------------------------
  Image:              win11refs2tmillionsofactionsv2.raw
  Image size:         2.0 TB
  ReFS version:       3.14
  Volume GUID:        29112745-cafb-4343-b36e-36153e1a68ba
  Volume serial:      0xaa2a19642a192f37
  Volume label:       win11refs2tmillionsofactionsv2
  Volume size:        2.0 TB
  Cluster size:       0x1000 (4.0 KB)
  Container size:     0x4000000 (64.0 MB)
  Checksum:           CRC64

------------------------------------------------------------------------------
Bootstrap structures
------------------------------------------------------------------------------
  VBR primary      LBA 0 (offset 0x0)  — checksum OK
      9a9e2d4f1ea196994ccf97b0abc8c1969bd0b6cc44b1a7edfb02fbad4b9fec10
  SUPB primary     LCN 0x1e (offset 0x1e000)  — checksum OK
      8ca0c86f8960cf1864ef09e9fbe2f5dca714ad30192bbb0358fa42297d886e65
  CHKP primary     LCN 0x51eb04 (offset 0x51eb04000)  — checksum OK, vclock=293
      69d14fd3621b26a6f32a675d43009065b6c9a409b34d2bb0c3d2c4d732daf647
------------------------------------------------------------------------------
  VBR backup       LBA 4294836223 (off 0x1fffbfffe00)  — = primary, checksum OK
      9a9e2d4f1ea196994ccf97b0abc8c1969bd0b6cc44b1a7edfb02fbad4b9fec10
  SUPB backup      LCN 0x1fffbffd (offset 0x1fffbffd000)  — checksum OK
      83fc320295a6c63b1039c227d650a966bd51263e37900aa7497efbbdcaf480fd
  SUPB backup      LCN 0x1fffbffe (offset 0x1fffbffe000)  — checksum OK
      97f1b2f06ffa5fc86aeb0525f6b0104f78292e6b73fb53b2995718609ab43df5
  CHKP secondary   LCN 0x3d702ac (offset 0x3d702ac000)  — checksum OK, vclock=292
      fd3c629c08cb584e4820ff63049fc7e88855851918abc0114688ffa88783d93c

note: the SUPB copies hash differently by design (each carries its own LCN +
self-checksum); their payload is identical — redundancy, not divergence.

------------------------------------------------------------------------------
Checkpoint
------------------------------------------------------------------------------
  Virtual clock:      293
  Flags:              0x682
                        · 0x002 = always-set
                        · 0x080 = native-Win11-format (v3.10+)
                        · 0x200 = indirect-root-list
                        · 0x400 = metadata-checksum (CRC64/SHA-256)

------------------------------------------------------------------------------
Global Root Tables
------------------------------------------------------------------------------
  Object ID Table                 512 rows
  Medium Allocator                 28 rows
  Container Allocator             165 rows
  Schema Table                     29 rows
  Parent-Child Table              500 rows
  Object ID Table dup             512 rows
  Block RefCount                  146 rows
  Container Table               32767 rows
  Container Table dup           32767 rows
  Schema Table dup                 29 rows
  Container Index                   0 rows
  Integrity State                   1 rows
  Small Allocator                   8 rows

------------------------------------------------------------------------------
Volume Detail
------------------------------------------------------------------------------
  Volume version:     3.14
  Driver version:     3.14
  Volume created:     2026-05-17 07:30:55.7358472
  Volume modified:    2026-05-17 08:20:27.0721968
  Volume state:       NATIVE v3.14
  Security descs:     14
  Reparse index:      33 entries
  Trash table:        0 entries
  Containers used:    32766 / 32767  (first maps to PLCN 0 = boot region)
  FS Metadata:        no child entries
  USN Journal:        Inactive

------------------------------------------------------------------------------
File System Content (from directory walk)
------------------------------------------------------------------------------
  Directories:        496
  Files:              334052 (331200 resident + 2852 non-resident)
  Total file size:    1.8 GB
  Oldest timestamp:   2021-05-18 07:16:04.9990009
  Newest timestamp:   2026-05-17 08:20:27.0980138
  Encrypted files:    0
  Integrity objects:  0
  Compressed files:   0
  Hard-linked:        27 files sharing 54 names
  Snapshot versions:  0 (across 0 files)
  ADS host files:     22

files produces the equivalent of an $MFT parse, 40 columns per entry. A file example in json format:

$ forefst.py win11refs15t64k.raw files --json files.json
[forefst v1.4.0] Opening win11refs15t64k.raw...
[forefst] ReFS 3.14 | 51 objects | cluster_size=65536
[forefst] Building security descriptor map...
[forefst] 14 security descriptors loaded
[forefst] Walking directory tree...
[forefst] 38 dirs, 265 files (9 resident + 256 non-resident)
[forefst] hard-linked: 1 files sharing 2 names · ADS: 2 · reparse: 3 
          · WSL: 0 · sparse: 0 · encrypted: 0 · compressed: 0 · integrity: 0 
          · EA: 0 · snapshots: 0
Wrote 303 entries to files2.json
[forefst] Done. 303 entries (0 deleted) -> JSON files.json
$
[...]
  {
    "oid": null,
    "file_ref": "0x723:0x3",
    "home_oid": "0x723",
    "file_id": "0x3",
    "creation_dir": "test/elvis_dir_india_800575",
    "file_name": "xbpt_tango_foxtrot_898933.txt",
    "parent_oid": "0x702",
    "parent_path": "test",
    "full_path": "test/xbpt_tango_foxtrot_898933.txt",
    "extension": ".txt",
    "file_size": 207263,
    "is_directory": false,
    "is_moved": true,
    "is_resident": false,
    "created": "2026-05-17 06:47:22.5638317",
    "modified": "2026-05-17 06:47:22.9646334",
    "changed": "2026-05-17 06:47:24.3386026",
    "accessed": "2026-05-17 06:47:22.9646334",
    "file_attributes": "Archive",
    "security_id": 5176748164,
    "owner_sid": "BUILTIN\\Administrators (S-1-5-32-544)",
    "usn": null,
    "has_ads": false,
    "ads_names": null,
    "is_encrypted": false,
    "is_compressed": false,
    "has_integrity": false,
    "has_ea": false,
    "reparse_target": null,
    "hard_link_count": 1,
    "hard_link_names": null,
    "snapshot_count": null,
    "snapshot_names": null,
    "timestomp_flags": null,
    "group_sid": "Domain Users (S-1-5-21-3829591975-2821165226-2477612932-513)",
    "dacl_summary": "4 ACE(s): ALLOWED:BUILTIN\\Administrators (S-1-5-32-544):FULL_CONTROL | 
                    ALLOWED:SYSTEM (S-1-5-18):FULL_CONTROL | 
                    ALLOWED:Authenticated Users (S-1-5-11):MODIFY | 
                    ALLOWED:BUILTIN\\Users (S-1-5-32-545):READ_EXECUTE",
    "allocated_size": 262144,
    "reparse_tag": null,
    "is_sparse": false,
    "internal_flags": null
  },
[...]

The complete subcommand reference is on the forefst page; the source is a single file, forefst.py. Python 3.7+, standard library only.

refsanalysis.py 🔗

refsanalysis is the companion of the reference. Where forefst answers “what happened on this volume?”, refsanalysis answers “what does this structure actually contain?”: it decodes one on-disk structure at a time — boot sector, superblock, checkpoint, Object Table, schemas, containers, allocators — and prints the fields with their offsets and raw bytes.

It is the tool the reference was written with, and it is published so the reference can be checked and continued. Three uses in particular:

• Verify a documented claim against your own image, instead of taking a page at face value.
• Extend the documentation where a structure is only partially decoded, working from the same output the reference was built on.
• Study a newer ReFS version: decode the same structures on a recent build, compare with the documented baseline, and see exactly what Microsoft moved.

That last point is the answer to the problem raised earlier, that an implementation correct for one version goes silently wrong on the next. The lab materials — formatting procedures, workload scripts, analysis outputs — are released for the same reason (reference page).

Forensic Soundness 🔗

Forensic soundness means using transparent, documented and repeatable methods, so that the evidence keeps its integrity and provenance and can be explained, assessed and challenged afterwards. In practice, the examiner must be able to say where an artefact comes from, how it was parsed, which assumptions were made, and an independent party must be able to review the same material and reach the same result. It also implies, as Carrier puts it, understanding the underlying structures rather than running tools as black boxes — which is precisely why open, inspectable tools matter in file-system forensics.

For NTFS these conditions are met: the structural knowledge is mature and public, several independent open tools can cross-validate each other, and the procedures are established. For ReFS none of these conditions were met. And it was the main goal of my thesis: contribute to the forensic soundness of ReFS analysis.

Hence the shape of the project, and the reason it is not just a tool: without verified structural knowledge, reliable tools cannot be built; without reliable tools, forensic soundness cannot be established. The reference is what makes the tool explainable, the tool is what makes the reference useful, and both had to be released together, with the lab materials that allow the work itself to be reproduced, verified and continued.

What matters is not that a tool now opens a ReFS volume, but that an examiner can say where each field came from, point to the evidence behind it — and that anyone who disagrees can check the reference, re-run the analysis on their own image, and say so.

I hope that will be useful. If you detect an error, if you have something to add or comment, you can contact me or open an issue on GitHub.