Impacket ntfs-read.py

Back to the category index / Back to the command index

Overview

Opens an NTFS volume or image read-only to browse directories and extract files.

Item	Details
Implementation	examples/ntfs-read.py
Category	Secrets / DPAPI / registry / file analysis
Size	1,455 lines
Distribution	Installed as a script through scripts=examples/*.py in setup.py

CLI and input

Run python examples/ntfs-read.py -h for the current option definitions.

Argument	Description
volume	NTFS volume to open (e.g. \.\C: or /dev/disk1s1)
-extract	Extract a pathname (for example, \windows\system32\config\sam)
-debug	Enable debug output
-ts	Add a timestamp to each log message

Detailed processing flow

The tool reads cluster and MFT geometry from the boot sector, then parses MFT record fixups, resident and non-resident attributes, data runs, and index roots and allocations. -extract saves a specified inode or stream; otherwise, MiniShell dispatches ls, cd, cat, hexdump, and get.

How it works

NTFS parsing starts at the boot sector. The tool reads sector and cluster sizes, the starting MFT cluster, and MFT record size, then converts them to byte offsets in the specified volume or image. NTFS.mountVolume() establishes this geometry and obtains data runs from the MFT’s own record to read later inodes.

Each MFT record applies update sequence fixups to check sector-end consistency and enumerates resident and non-resident attributes. Resident data sits in the record; non-resident data is read from clusters by following VCN-to-LCN data runs. Directories parse B-tree entries in INDEX_ROOT and INDEX_ALLOCATION, linking file names and MFT references to child inodes.

For files with an attribute list, extents span multiple MFT records, so NonResidentDataAttribute combines runs in logical order. Sparse, compressed, and encrypted flags do not imply a readable data stream. MiniShell resolves paths and runs ls, cat, hexdump, and get on this read-only model; writes to the host filesystem are limited to extracted files.

Disk images are untrusted input. Validate fixups, attribute and run lengths, index entry sizes, and recursive directory references to avoid integer overflows and infinite loops when changing the parser.

Key implementation elements

Symbol	Location	Where to trace its responsibility
NTFS_BPB	131	Structure or constant definition
NTFS_EXTENDED_BPB	146	Structure or constant definition
NTFS_BOOT_SECTOR	160	Structure or constant definition
NTFS_MFT_RECORD	170	Structure or constant definition
NTFS_ATTRIBUTE_RECORD	188	Structure or constant definition
NTFS_ATTRIBUTE_RECORD_NON_RESIDENT	200	Structure or constant definition
NTFS_ATTRIBUTE_RECORD_RESIDENT	213	Structure or constant definition
NTFS_FILE_NAME_ATTR	221	Structure or constant definition
NTFS_STANDARD_INFORMATION	238	Structure or constant definition
NTFS_INDEX_HEADER	247	Structure or constant definition
NTFS_INDEX_ROOT	256	Structure or constant definition
NTFS_INDEX_ALLOCATION	267	Structure or constant definition
NTFS_INDEX_ENTRY_HEADER	277	Structure or constant definition
NTFS_INDEX_ENTRY	286	Structure or constant definition
NTFS_DATA_RUN	296	Structure or constant definition
NTFS_ATTRIBUTE_LIST_ENTRY	304	Structure or constant definition
Attribute	321	__init__(), getFlags(), getName(), isNonResident(), dump(), getTotalSize(), getType()
AttributeResident	347	__init__(), dump(), getFlags(), getValue(), read(), getDataSize()
AttributeNonResident	370	__init__(), dump(), getDataSize(), getValue(), parseDataRuns(), readClusters(), readVCN(), read()
NonResidentDataAttribute	544	__init__()
AttributeStandardInfo	648	__init__(), getFileAttributes(), getFileTime(), dump()
AttributeFileName	666	__init__(), getFileNameType(), getFileAttributes(), getFileName(), getFileSize(), getFlags(), dump()
AttributeIndexAllocation	690	__init__(), dump(), read()
AttributeIndexRoot	704	__init__(), parseIndexEntries(), dump(), getType()
IndexEntry	729	__init__(), isSubNode(), isLastNode(), getVCN(), getSize(), getKey(), getINodeNumber(), dump()
AttributeListEntry	754	__init__()
AttributeList	771	__init__(), getEntries()
INODE	804	__init__(), isDirectory(), isCompressed(), isEncrypted(), isSparse(), displayName(), getPrintableAttributes(), parseAttributes(), searchAttribute(), PerformFixUp(), parseIndexBlocks(), walkSubNodes(), and others
NTFS	1138	__init__(), mountVolume(), readBootSector(), getINode()
MiniShell	1226	__init__(), emptyline(), onecmd(), do_exit(), do_shell(), do_help(), do_lcd(), do_cd(), findPathName(), do_pwd(), do_ls(), complete_cd(), and others
getUnixTime()	315	Module function
main()	1432	Module function

Dependencies

Within Impacket

Module	Main names used
impacket.examples	logger
impacket	version
impacket.structure	Structure, hexdump

External packages (used directly)

Import name	Distribution package	Import path and declaration status
six	six	Imported directly; declared

Output, side effects, and required privileges

• The main operation parses local files. Treat input as untrusted: validate offsets, lengths, and format identifiers before accessing data.
• Options may create or update local files. Check how existing files are handled and the permissions on output containing secrets.

Failure paths and cleanup

• Distinguish a missing input file, a damaged file, an incomplete read, and an unsupported format.

When changing the implementation

The code depends on impacket.structure and standard file I/O. NTFS, INODE, and each Attribute* class handle parsing; MiniShell handles the UI. Preserve boundary checks for offsets and lengths in untrusted images, sparse/compressed/encrypted attributes, and attribute-list extents.

Verification

• Syntax: python -m py_compile examples/ntfs-read.py
• CLI: python examples/ntfs-read.py -h
• Related test: tests/misc/test_ntfs_read.py
• Related test: tests/misc/test_structure.py