dissect.ntfs

Submodules

• dissect.ntfs.attr
• dissect.ntfs.c_ntfs
• dissect.ntfs.exceptions
• dissect.ntfs.index
• dissect.ntfs.mft
• dissect.ntfs.ntfs
• dissect.ntfs.secure
• dissect.ntfs.stream
• dissect.ntfs.usnjrnl
• dissect.ntfs.util

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

ATTRIBUTE_TYPE_CODE
NTFS_SIGNATURE

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.

is_symlink() → bool

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_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