Getting Started

exhume_filesystem provides one read-only interface for walking, inspecting, and reading files from forensic images and extracted folders. Callers use the same Filesystem, FileCommon, and DirectoryCommon APIs regardless of the filesystem that was detected.

The crate is used by exhume_indexer, exhume_artefacts, and other Exhume tools that must work with filesystem records without first exporting the files to the examiner's workstation.

Supported sources

Source	Implementation	Notes
Linux extended filesystems	ExtFS	Normalizes inode and directory records.
NTFS	NTFS	Supports ordinary NTFS and BitLocker volumes when an FVEK is supplied.
exFAT	ExFatFS	Normalizes exFAT records and directory entries.
APFS	ApfsFs	Reads APFS records, extended attributes, and supported decmpfs compressed content.
Extracted directory	FolderFS	Treats a host directory as a filesystem source.

Disk-image formats are opened by exhume_body. auto, raw, and ewf are the common choices; availability of other container formats depends on the installed exhume_body version.

Filesystem access is read-only. The CLI's --dump operation writes an exported copy to the current working directory but never changes the evidence source.

Install

Install the CLI from crates.io:

cargo install exhume_filesystem

From the Exhume workspace, replace exhume_filesystem in the examples below with:

cargo run -p exhume_filesystem --

Important units

For an image or forensic container, both --offset and --size are required:

• --offset is the filesystem start offset in bytes.
• --size is the filesystem length in sectors.
• Decimal and 0x-prefixed hexadecimal values are accepted.

The CLI gets the sector size from exhume_body and converts --size to bytes before filesystem detection. Folder sources do not require an offset or size.

CLI use cases

Inspect an extracted folder

Print normalized metadata for the folder-backed filesystem:

exhume_filesystem \
  --body /evidence/mobile-extraction \
  --metadata \
  --json

Enumerate every record as JSON:

exhume_filesystem \
  --body /evidence/mobile-extraction \
  --enum \
  --json > files.json

Without --json, enumeration prints a compact forensic listing containing the filesystem identifier, permissions, timestamp, owner, group, size, and path.

Inspect a filesystem inside an image

The following example opens a filesystem at byte offset 0x100000. Its length is 0x400000 sectors:

exhume_filesystem \
  --body /evidence/disk.raw \
  --format raw \
  --offset 0x100000 \
  --size 0x400000 \
  --metadata \
  --json

Partition discovery is intentionally outside this crate. Obtain the correct offset and sector count from a partition parser such as exhume_partitions.

Work with a record identifier

Filesystem identifiers are native record numbers: for example, an inode, NTFS MFT record, or APFS file ID.

Inspect record 42:

exhume_filesystem \
  --body /evidence/disk.raw \
  --format raw \
  --offset 0x100000 \
  --size 0x400000 \
  --record 42 \
  --json

List the children when that record is a directory:

exhume_filesystem \
  --body /evidence/disk.raw \
  --format raw \
  --offset 0x100000 \
  --size 0x400000 \
  --record 42 \
  --list \
  --json

Export a regular file. The output is named file_42.bin in the current directory:

exhume_filesystem \
  --body /evidence/disk.raw \
  --format raw \
  --offset 0x100000 \
  --size 0x400000 \
  --record 42 \
  --dump

--print currently performs a bounded read of the first 8 KiB and reports how many bytes were readable. Use --dump when the file content itself is needed.

Open a BitLocker-protected NTFS volume

Supply the Full Volume Encryption Key as hexadecimal. Do not include spaces or separators:

exhume_filesystem \
  --body /evidence/encrypted.raw \
  --format raw \
  --offset 0x100000 \
  --size 0x400000 \
  --fvek 00112233aabbccdd... \
  --metadata

Treat FVEKs as sensitive case material: avoid shell history and shared logs in production workflows.

CLI reference

Option	Meaning
-b, --body <PATH>	Required image, forensic container, or directory.
-f, --format <FORMAT>	Body format; defaults to auto.
-o, --offset <BYTES>	Filesystem start in bytes; required for non-directory sources.
-s, --size <SECTORS>	Filesystem length in sectors; required for non-directory sources.
-r, --record <ID>	Inspect a native filesystem record identifier.
-e, --enum	Walk all filesystem records.
--list	List children of the directory selected by --record.
--dump	Export the selected record to file_<ID>.bin.
--print	Read up to the first 8 KiB of the selected record and report the result.
--metadata	Print filesystem-level metadata.
-j, --json	Use structured JSON for compatible metadata and listing operations.
--fvek <HEX>	BitLocker FVEK used to open an encrypted NTFS volume.
-l, --log-level <LEVEL>	error, warn, info, debug, or trace.

--enum conflicts with record-oriented operations. --list, --dump, and --print require --record; run enumeration and record inspection as separate commands.

Relationship to other Exhume crates

• exhume_body opens raw and containerized evidence and provides bounded body slices.
• exhume_partitions discovers the offsets and sizes passed to this crate.
• exhume_indexer walks a Filesystem and persists normalized records to SQLite.
• exhume_artefacts consumes files through paths, bytes, or Read + Seek streams.