refsanalysis.py#

ReFS structure and lab analysis tool — boot sector, superblock, checkpoint, object/schema/container tables, the upcase table, parent-child relationships, a lab-format file/attribute browser, and a boot-sector editor/repair subsystem. It imports its parsing layer from forefst.py and never modifies it.

Forensic commands moved to forefst. The file-level forensic commands — usn, mlog, timeline, timestomp, extract, security, reparse, deleted, snapshots, integrity, export, dataruns — now live in forefst.py. Running them here prints a one-line redirect — or reach them without leaving refsanalysis via the forefst passthrough (see Running forefst commands).

Invocation#

refsanalysis.py <image> <subcommand> [options]
refsanalysis.py <image>                       # no subcommand → summary
refsanalysis.py <image> summary++             # extended summary
refsanalysis.py <image> <cmd> --help          # detailed help + examples for one subcommand
refsanalysis.py help <cmd>                     # same, without needing an image
refsanalysis.py --list                         # list all subcommands
refsanalysis.py <image> forefst <cmd> [opts]   # run any forefst subcommand (passthrough — see below)

Every subcommand accepts --partition-start <offset> to override GPT/volume detection (decimal or 0x hex). The structure commands draw from a common verbosity vocabulary — not every command accepts every flag; each command’s row in the Subcommand Reference (and its --help) lists the ones it supports:

Running forefst commands via refsanalysis#

refsanalysis.py <image> forefst <cmd> [options] delegates to forefst.py, so every forefst subcommand is reachable without leaving refsanalysis — the file lister (files/summary/ search/details) and the full forensic suite (usn/mlog/timeline/timestomp/extract/security/ reparse/deleted/snapshots/integrity/export/dataruns). It re-uses forefst’s real dispatch (no code is duplicated), so the behaviour, options, and output are identical to running forefst.py directly.

refsanalysis.py disk.raw forefst usn --stats            # forefst's USN activity summary
refsanalysis.py disk.raw forefst files --filter ea --json   # forefst's file listing (EA-only) as JSON
refsanalysis.py disk.raw forefst timeline --fast            # forefst's super-timeline
refsanalysis.py disk.raw forefst --help                     # forefst's full subcommand list
refsanalysis.py disk.raw forefst usn --help                 # help for one forefst command

refsanalysis.py help forefst describes the passthrough itself. (This is a convenience bridge; forefst.py remains the single implementation of the forensic commands.)

Quick Start#

refsanalysis.py disk.raw summary                       # volume overview
refsanalysis.py disk.raw summary++ --json              # extended summary, JSON
refsanalysis.py disk.raw files -v                       # lab-format file listing
refsanalysis.py disk.raw attributes --filter wsl        # files carrying WSL metadata
refsanalysis.py disk.raw details /dir/file.txt          # full per-file record by path
refsanalysis.py disk.raw boot --verify                  # decode + check the VBR
refsanalysis.py disk.raw chkp -vv                       # checkpoint + container translation
refsanalysis.py disk.raw objects                        # object-ID table
refsanalysis.py disk.raw schema                         # schema table
refsanalysis.py disk.raw bootedit repair --dry-run      # diagnose fixboot damage (preview)
refsanalysis.py disk.raw all > structure_dump.txt       # run every structure tool

Subcommand Reference#

Volume overview#

File-system content (lab format)#

forefst’s files/details subcommands are the forensic-grade equivalents (38-column CSV/JSON, owner+group SID, hard-link names+counts, snapshot counts, reparse targets, FileId/HomeOid join keys, IsSparse). refsanalysis keeps a lighter, human-readable lab view.

Structure analysis#

Boot sector repair#

bootedit inspects or repairs the ReFS VBR. Writes go to a sparse copy unless --inplace is given; always preview with --dry-run first.

refsanalysis.py disk.raw bootedit read                                 # read-only display
refsanalysis.py disk.raw bootedit repair --dry-run                     # preview a fixboot repair
refsanalysis.py disk.raw bootedit set --field checksum_algo --value 2 --dry-run

--inplace modifies the original image (dangerous); without it, write actions target a sparse copy named by -o/--output.

Architecture#

refsanalysis.py imports its parsing layer from forefst.py and never modifies it. Each subcommand is a cmd_* function following one bootstrap pattern:

def cmd_example(image, remaining, partition_start):
    args = _parse_args(remaining, flags=["-v"], valued=["--oid"])
    try:
        f, ps, cs, tr, roots, obj_map, vmaj, vmin, chkp_lcns = bootstrap(image, partition_start)
    except (ValueError, OSError) as e:
        die(str(e))
    try:
        # ... analysis using f, ps, cs, tr, obj_map ...
        return 0
    finally:
        f.close()

bootstrap() (from forefst.py) locates the partition, parses the VBR/SUPB/both checkpoints, reads the 13 root pointers, builds the Container Table translator and the Object Table map. Afterwards any structure is reachable via obj_map[oid] and walk_bplus().

Relationship to forefst.py#

forefst.py is the forensic file lister and forensic suite; refsanalysis.py is the structure/lab tool. Both share the same bootstrap and parsing layer. SID and attribute rendering use the same canonical helpers in both tools (attribute strings are TitleCase, e.g. Archive, EA, ReparsePoint, joined with |).

Dependencies#

Python 3.7+ standard library only. No pip packages.

Cross-References#

• forefst.py — the forensic lister + forensic suite that provides the parsing library
• Bootstrap Chain — the volume initialization sequence
• Virtual Addressing — VLCN to PLCN translation