dissect.ntfs#

Submodules#

Package Contents#

Classes#

Attribute

Parse and interact with MFT attributes.

AttributeHeader

Parse attribute headers.

AttributeRecord

Parse attribute records.

Index

Open an index with he given name on the given MFT record.

IndexEntry

Parse and interact with index entries.

Mft

Interact with the $MFT (Master File Table).

MftRecord

MFT record parsing and interaction.

NTFS

Implementation for Microsoft NTFS.

ACE

Parse an ACE from a file-like object.

ACL

Parse an ACL from a file-like object.

Secure

Lookup security descriptors from the $Secure file, or optionally just a file-like object of the $SDS.

SecurityDescriptor

Parse a security descriptor from a file-like object.

UsnJrnl

Parse the USN journal from a file-like object of the $UsnJrnl:$J stream.

UsnRecord

Parse a USN record from a file-like object and offset.

Attributes#

class dissect.ntfs.Attribute(header: AttributeHeader, record: dissect.ntfs.mft.MftRecord | None = None)#

Parse and interact with MFT attributes.

Wrapper for an AttributeHeader and AttributeRecord combination.

Parameters:
  • record – The MFT record this attribute belongs to.

  • header – The AttributeHeader for this Attribute.

property type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE#

Return the attribute type.

property resident: bool#

Return whether this attribute is resident or not.

property name: str#

Return the name of this attribute.

__slots__ = ('record', 'header', 'attribute')#
__getattr__(attr: str) Any#
__repr__() str#

Return repr(self).

classmethod from_fh(fh: BinaryIO, record: dissect.ntfs.mft.MftRecord | None = None) Attribute#

Parse an attribute from a file-like object.

Parameters:
  • fh – The file-like object to parse an attribute from.

  • record – The MFT record this attribute belongs to.

classmethod from_bytes(data: bytes, record: dissect.ntfs.mft.MftRecord | None = None) Attribute#

Parse an attribute from bytes.

Parameters:
  • data – The bytes to parse.

  • record – The MFT record this attribute belongs to.

dataruns() list[tuple[int, int]]#

Return the dataruns of this attribute, if non-resident.

Raises:

TypeError – If attribute is resident.

open() BinaryIO#

Open a file-like object for this attribute’s data.

Raises:

VolumeNotAvailableError – If no volume is available.

data() bytes#

Read and return all the data of this attribute.

Raises:

VolumeNotAvailableError – If no volume is available.

class dissect.ntfs.AttributeHeader(fh: BinaryIO, offset: int, record: dissect.ntfs.mft.MftRecord | None = None)#

Parse attribute headers.

Parameters:
  • record – The MFT record this attribute belongs to.

  • fh – The file-like object to parse an attribute header from.

  • offset – The offset in the file-like object to parse an attribute header from.

property type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE#

Return the attribute type.

property resident: bool#

Return whether this attribute is resident or not.

property record_length: int#

Return the record length of this attribute.

property name: str#

Return the name of this attribute.

property flags: int#

Return the attribute flags.

property size: int#

Return the data size of this attribute.

property allocated_size: int | None#

Return the allocated size if non-resident, else None.

property lowest_vcn: int | None#

Return the lowest VCN if non-resident, else None.

property highest_vcn: int | None#

Return the highest VCN if non-resident, else None.

property compression_unit: int | None#

Return the compression unit if non-resident, else None.

__slots__ = ('record', 'fh', 'offset', 'header')#
__repr__() str#

Return repr(self).

classmethod from_bytes(data: bytes, record: dissect.ntfs.mft.MftRecord | None = None) AttributeHeader#

Parse an attribute header from bytes.

Parameters:
  • data – The bytes to parse.

  • record – The MFT record this attribute belongs to.

dataruns() list[tuple[int, int]]#

Return the dataruns of this attribute, if non-resident.

Raises:

TypeError – If attribute is resident.

open() BinaryIO#

Open a file-like object for this attribute’s data.

Raises:

VolumeNotAvailableError – If no volume is available.

data() bytes#

Read and return all the data of this attribute.

Raises:

VolumeNotAvailableError – If no volume is available.

class dissect.ntfs.AttributeRecord(fh: BinaryIO, record: dissect.ntfs.mft.MftRecord | None = None)#

Parse attribute records.

Parameters:
  • record – The MFT record this attribute belongs to.

  • fh – The file-like object to parse an attribute record from.

__slots__ = ('record',)#
classmethod from_fh(fh: BinaryIO, attr_type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE, record: dissect.ntfs.mft.MftRecord | None = None) AttributeRecord#

Parse an attribute from a file-like object.

Selects a more specific AttributeRecord class if one is available for the given attribute type.

Parameters:
  • fh – The file-like object to parse an attribute from.

  • attr_type – The attribute type to parse.

  • record – The MFT record this attribute belongs to.

dissect.ntfs.ATTRIBUTE_TYPE_CODE#
dissect.ntfs.NTFS_SIGNATURE = b'NTFS    '#
class dissect.ntfs.Index(record: dissect.ntfs.mft.MftRecord, name: str)#

Open an index with he given name on the given MFT record.

Parameters:

name – The index to open.

Raises:

FileNotFoundError – If no index with that name can be found.

__iter__() Iterator[IndexEntry]#
index_buffer(vcn: int) IndexBuffer#

Return the IndexBuffer at the specified cluster number.

Parameters:

vcn – The virtual cluster number within the index allocation to read.

Raises:

FileNotFoundError – If this index has no index allocation.

search(value: Any, exact: bool = True, cmp: Callable[[IndexEntry, Any], Match] | None = None) IndexEntry#

Perform a binary search on this index.

Returns the matching node if performing an exact search. Otherwise return the first match that is greater than the search value.

Parameters:
  • value – The key to search.

  • exact – Result must be an exact match.

  • cmp – Optional custom comparator function.

Raises:
  • NotImplementedError – If there is no collation (comparator) function for the collation rule of this index.

  • KeyError – If an exact match was requested but not found.

entries() Iterator[IndexEntry]#

Yield all IndexEntry’s in this Index.

class dissect.ntfs.IndexEntry(index: Index, fh: BinaryIO, offset: int)#

Parse and interact with index entries.

Parameters:
  • index – The Index class instance this IndexEntry belongs to.

  • fh – The file-like object to parse an index entry on.

  • offset – The offset in the file-like object to parse an index entry at.

property is_end: bool#

Return whether this entry marks the end.

property is_node: bool#

Return whether this entry is a node.

property node_vcn: int#

Return the node VCN if this entry is a node.

property length: int#

Return the length of this index entry.

property key_length: int#

Return the length of this index entry.

dereference() dissect.ntfs.mft.MftRecord#

Dereference this IndexEntry to the MFT record it points to.

Note that the file reference is a union with the data part so only access this if you know the entry has a file reference and not a data part.

Raises:

MftNotAvailableError – If no MFT is available.

key() bytes#

Return the index key of this entry.

data() bytes#

Return the data part of this entry.

Note that the data part is a union with the file reference, so only access this if you know the entry has data and not a file reference.

attribute() dissect.ntfs.attr.AttributeRecord | None#

Return the dissect.ntfs.attr.AttributeRecord of the attribute contained in this entry.

class dissect.ntfs.Mft(fh: BinaryIO, ntfs: dissect.ntfs.ntfs.NTFS | None = None)#

Interact with the $MFT (Master File Table).

Parameters:
  • fh – A file-like object of the $MFT file.

  • ntfs – An optional NTFS class instance.

__call__(ref, *args, **kwargs) MftRecord#
root() MftRecord#

Return the root directory MFT record.

get(ref: int | str | dissect.cstruct.Instance, root: MftRecord | None = None) MftRecord#

Retrieve an MFT record using a variety of methods.

Supported references are:
  • _MFT_SEGMENT_REFERENCE cstruct instance

  • integer segment number

  • string file path

Parameters:
  • ref – Reference to retrieve the record by.

  • root – Optional root record to start resolving from. Useful for relative path lookups.

Raises:

TypeError – If the reference is of an unsupported type.

segments() Iterator[MftRecord]#

Yield all valid MFT records, regardless if they’re allocated or not.

class dissect.ntfs.MftRecord#

MFT record parsing and interaction.

Use the from_fh() or from_bytes() class methods to instantiate.

__hash__#
__repr__() str#

Return repr(self).

__eq__(other: Any) bool#

Return self==value.

classmethod from_fh(fh: BinaryIO, offset: int, ntfs: dissect.ntfs.ntfs.NTFS | None = None) MftRecord#

Parse an MFT record from a file-like object.

Parameters:
  • fh – The file-like object to parse an MFT record from.

  • offset – The offset in the file-like object to parse the MFT record from.

  • ntfs – An optional NTFS class instance.

classmethod from_bytes(data: bytes, ntfs: dissect.ntfs.ntfs.NTFS | None = None) MftRecord#

Parse an MFT record from bytes.

Parameters:
  • data – The bytes object to parse an MFT record from.

  • ntfs – An optional NTFS class instance.

Raises:

BrokenMftError – If the MFT record signature is invalid.

get(path: str) MftRecord#

Retrieve a MftRecord relative to this one.

Parameters:

path – The path to lookup.

Raises:

MftNotAvailableError – If no MFT is available.

attributes() dissect.ntfs.util.AttributeMap#

Parse and return the attributes in this MFT record.

$ATTRIBUTE_LIST’s are only parsed if there’s an MFT available on the NTFS object.

Raises:

BrokenMftError – If an error occurred parsing the attributes.

resident() bool#

Return whether this record’s default $DATA attribute is resident.

filename() str | None#

Return the first file name, or None if this record has no file names.

filenames(ignore_dos: bool = False) list[str]#

Return all file names of this record.

Parameters:

ignore_dos – Ignore DOS file name entries.

full_path(ignore_dos: bool = False) str | None#

Return the first full path, or None if this record has no file names.

Parameters:

ignore_dos – Ignore DOS file name entries.

full_paths(ignore_dos: bool = False) list[str]#

Return all full paths of this record.

Parameters:

ignore_dos – Ignore DOS file name entries.

is_dir() bool#

Return whether this record is a directory.

is_file() bool#

Return whether this record is a file.

is_reparse_point() bool#

Return whether this record is a reparse point.

Return whether this record is a symlink reparse point.

is_mount_point() bool#

Return whether this record is a mount point reparse point.

reparse_point_name() str#

Return the (printable) name of this reparse point.

reparse_point_substitute_name() str#

Return the substitute name of this reparse point.

reparse_point_record() MftRecord#

Resolve a reparse point and return the target record.

Note: absolute links (such as directory junctions) will always fail in the context of a single filesystem. Absolute links include the drive letter, of which we have no knowledge here.

open(name: str = '', attr_type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE = ATTRIBUTE_TYPE_CODE.DATA, allocated: bool = False) BinaryIO#

Open a stream on the given stream name and type.

Parameters:
  • name – The stream name, an empty string for the “default” data stream.

  • attr_type – The attribute type to open a stream on.

  • allocated – Whether to use the real stream size or the allocated stream size (i.e. include slack space).

Raises:

FileNotFoundError – If there are no attributes with the given name and type.

size(name: str = '', attr_type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE = ATTRIBUTE_TYPE_CODE.DATA, allocated: bool = False) int#

Return the stream size of the given stream name and type.

Parameters:
  • name – The stream name, an empty string for the “default” data stream.

  • attr_type – The attribute type to find the stream size of.

  • allocated – Whether to use the real stream size or the allocated stream size (i.e. include slack space).

Raises:

FileNotFoundError – If there are no attributes with the given name and type.

dataruns(name: str = '', attr_type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE = ATTRIBUTE_TYPE_CODE.DATA) list[tuple[int, int]]#

Return the dataruns of the given stream name and type.

Parameters:
  • name – The stream name, an empty string for the “default” data stream.

  • attr_type – The attribute type to get the dataruns of.

Raises:

FileNotFoundError – If there are no attributes with the given name and type.

has_stream(name: str = '', attr_type: dissect.ntfs.c_ntfs.ATTRIBUTE_TYPE_CODE = ATTRIBUTE_TYPE_CODE.DATA) bool#

Return whether or not this record has attributes with the given name and type.

index(name: str) dissect.ntfs.index.Index#

Open an index on this record.

Parameters:

name – The index name to open. For example, "$I30".

iterdir(dereference: bool = False, ignore_dos: bool = False) Iterator[dissect.ntfs.index.IndexEntry | MftRecord]#

Yield directory entries of this record.

Parameters:
  • dereference – Determines whether to resolve the IndexEntry’s to MftRecord’s. This impacts performance.

  • ignore_dos – Ignore DOS file name entries.

Raises:

NotADirectoryError – If this record is not a directory.

listdir(dereference: bool = False, ignore_dos: bool = False) dict[str, dissect.ntfs.index.IndexEntry | MftRecord]#

Return a dictionary of the directory entries of this record.

Parameters:
  • dereference – Determines whether to resolve the IndexEntry’s to MftRecord’s. This impacts performance.

  • ignore_dos – Ignore DOS file name entries.

Raises:

NotADirectoryError – If this record is not a directory.

class dissect.ntfs.NTFS(fh: BinaryIO | None = None, boot: BinaryIO | None = None, mft: BinaryIO | None = None, usnjrnl: BinaryIO | None = None, sds: BinaryIO | None = None)#

Implementation for Microsoft NTFS.

This implementation supports parsing NTFS from either a full NTFS volume or from separate files. If you have a file-like object of an NTFS volume, simply pass it as the fh argument. If you have separate file-like objects for things like $BOOT or $MFT, pass those as the boot and mft arguments. The separate arguments take precedence over parsing from the volume file-like object.

Parameters:
  • fh – A file-like object for the volume to use for parsing NTFS. This is where “data on disk” is read from.

  • boot – A file-like object for the $BOOT file.

  • mft – A file-like object for the $MFT file.

  • usnjrnl – A file-like object for the $Extend/$Usnjrnl:$J file.

  • sds – A file-like object for the $Secure:$SDS file.

serial() int | None#
volume_name() str | None#
class dissect.ntfs.ACE(fh: BinaryIO)#

Parse an ACE from a file-like object.

Parameters:

fh – The file-like object to parse an ACE from.

property type: dissect.ntfs.c_ntfs.ACE_TYPE#

Return the ACE type.

property is_standard_ace: bool#

Return whether this ACE is a standard ACE.

property is_compound_ace: bool#

Return whether this ACE is a compound ACE.

property is_object_ace: bool#

Return whether this ACE is an object ACE.

__repr__() str#

Return repr(self).

class dissect.ntfs.ACL(fh: BinaryIO)#

Parse an ACL from a file-like object.

Parameters:

fh – The file-like object to parse an ACL from.

class dissect.ntfs.Secure(record: dissect.ntfs.mft.MftRecord = None, sds: BinaryIO = None)#

Lookup security descriptors from the $Secure file, or optionally just a file-like object of the $SDS.

Only one the record or sds arguments needs to be provided.

Parameters:
  • record – The MFT record of the $Secure file, used when opening from a full NTFS volume.

  • sds – A file-like object of the $SDS stream, used when opening from separate system files.

lookup(security_id: int) SecurityDescriptor#

Lookup a security descriptor by the security ID.

An index is used if available ($SII), otherwise we iterate all entries until we find the correct one.

Parameters:

security_id – The security ID to lookup.

Raises:

KeyError – If the security ID can’t be found.

descriptors() Iterator[SecurityDescriptor]#

Return all security descriptors.

class dissect.ntfs.SecurityDescriptor(fh: BinaryIO)#

Parse a security descriptor from a file-like object.

Parameters:

fh – The file-like object to parse a security descriptor from.

class dissect.ntfs.UsnJrnl(fh: BinaryIO, ntfs: dissect.ntfs.ntfs.NTFS | None = None)#

Parse the USN journal from a file-like object of the $UsnJrnl:$J stream.

Parameters:
  • fh – A file-like object of the $UsnJrnl:$J stream.

  • ntfs – An optional NTFS class instance, used for resolving file paths.

records() Iterator[UsnRecord]#

Yield all parsed USN records.

Only yields version 2 USN records, other record versions are ignored.

class dissect.ntfs.UsnRecord(usnjrnl: UsnJrnl, fh: BinaryIO, offset: int)#

Parse a USN record from a file-like object and offset.

Parameters:
  • usnjrnl – The UsnJrnl class this record is parsed from.

  • fh – The file-like object to parse a USN record from.

  • offset – The offset to parse a USN record at.

property timestamp: datetime.datetime#
property timestamp_ns: int#
__repr__() str#

Return repr(self).

__getattr__(attr: str) Any#
file() dissect.ntfs.mft.MftRecord | None#
parent() dissect.ntfs.mft.MftRecord | None#
full_path() str#