msl

Memory Slice (.msl) format parser.

Optional dependencies (lazy-imported when needed): - blake3: integrity chain verification - zstandard: zstd block decompression - lz4: lz4 block decompression

MSL file reader with mmap-backed, endianness-aware parsing.

class MslReader[source]

Bases: object

Memory-mapped MSL file reader (context manager).

__init__(path)[source]

Parameters:: path (Path)

open()[source]

Return type:: None

close()[source]

Return type:: None

property file_header: MslFileHeader

iter_blocks(merge_cont=True)[source]

Iterate blocks; merges continuation blocks when merge_cont is True.

Parameters:: merge_cont (bool)
Return type:: Iterator[Tuple[MslBlockHeader, bytes]]

read_bytes(offset, length)[source]

Read raw bytes from the mmap at given offset.

Parameters:

offset (int)
length (int)

Return type:

bytes

read_block_payload(hdr)[source]

Read and decompress a block’s payload bytes.

Parameters:: hdr (MslBlockHeader)
Return type:: bytes

collect_regions()[source]

Return type:: List[MslMemoryRegion]

collect_key_hints()[source]

Return type:: List[MslKeyHint]

collect_modules()[source]

Return type:: List[MslModuleEntry]

collect_process_identity()[source]

Return type:: List[MslProcessIdentity]

collect_vas_map()[source]

Return type:: List[MslVasMap]

collect_related_dumps()[source]

Return type:: List[MslRelatedDump]

collect_end_of_capture()[source]

Return type:: List[MslEndOfCapture]

collect_import_provenance()[source]

Return type:: List[MslImportProvenance]

collect_module_list_index()[source]

Return type:: List[MslModuleListIndex]

collect_processes()[source]

Return type:: List[MslProcessTable]

collect_connections()[source]

Return type:: List[MslConnectionTable]

collect_handles()[source]

Return type:: List[MslHandleTable]

collect_connectivity_tables()[source]

Return type:: List[MslConnectivityTable]

collect_thread_contexts()[source]

Return type:: list

collect_file_descriptors()[source]

Return type:: list

collect_network_connections()[source]

Return type:: list

collect_environment_blocks()[source]

Return type:: list

collect_security_tokens()[source]

Return type:: list

collect_system_context()[source]

Collect SYSTEM_CONTEXT (0x0050) blocks per spec §6.2 Table 20.

Return type:: list

MSL file writer for producing valid Memory Slice binary files.

All struct layouts must match the corresponding decoders.py decoder for roundtrip compatibility via MslReader.

class MslWriter[source]

Bases: object

Accumulate blocks and write a valid MSL file.

__init__(path, pid=0, os_type=OSType.UNKNOWN, arch_type=ArchType.UNKNOWN, imported=True)[source]

Parameters:

path (Path)
pid (int)
os_type (int)
arch_type (int)
imported (bool)

property dump_uuid: UUID

add_memory_region(base_addr, data, protection=0x03, region_type=0x05, page_size_log2=12, timestamp_ns=0)[source]

Add a memory region block. Returns block UUID.

Parameters:

base_addr (int)
data (bytes)
protection (int)
region_type (int)
page_size_log2 (int)
timestamp_ns (int)

Return type:

UUID

add_key_hint(region_uuid, offset, key_length, key_type, protocol, confidence=0x01, key_state=0, note='')[source]

Add a key hint block referencing a memory region.

Parameters:

region_uuid (UUID)
offset (int)
key_length (int)
key_type (int)
protocol (int)
confidence (int)
key_state (int)
note (str)

Return type:

None

add_import_provenance(source_format, tool_name, orig_file_size, note='', source_path=None)[source]

Add an import provenance block.

When source_path is provided and readable, its BLAKE3 digest is computed and written as source_hash. Otherwise source_hash is 32 zero bytes.

Parameters:

source_format (int)
tool_name (str)
orig_file_size (int)
note (str)
source_path (Path | None)

Return type:

None

add_related_dump(related_uuid, related_pid, relationship, target_path=None)[source]

Add a RELATED_DUMP block (type 0x0041).

When target_path is provided and readable, its BLAKE3 digest is computed and written as target_hash, pinning the cross-reference. Otherwise target_hash is 32 zero bytes.

Parameters:

related_uuid (UUID)
related_pid (int)
relationship (int)
target_path (Path | None)

Return type:

None

add_end_of_capture(reason=0)[source]

Add an end-of-capture block.

The 32-byte file_hash slot is left as zeros here; write() finalizes it with a digest covering the file header and every preceding encoded block.

Parameters:: reason (int)
Return type:: None

write()[source]

Write all accumulated blocks to the output file.

END_OF_CAPTURE blocks have their file_hash finalized over the file header plus every prior encoded block, so the EoC pins the full file contents.

Return type:: None

Raw-to-MSL import: convert .dump files to .msl format.

class ImportResult[source]

Bases: object

Result of importing a single raw dump to MSL format.

source_path: Path

output_path: Path

regions_written: int

key_hints_written: int

total_bytes: int

__init__(source_path, output_path, regions_written, key_hints_written, total_bytes)

Parameters:

source_path (Path)
output_path (Path)
regions_written (int)
key_hints_written (int)
total_bytes (int)

Return type:

None

import_raw_dump(raw_path, output_path, pid=0, secrets=None, os_type=OSType.UNKNOWN, arch_type=ArchType.UNKNOWN, page_size_log2=12)[source]

Convert a raw .dump file to .msl format.

Parameters:

raw_path (Path)
output_path (Path)
pid (int)
secrets (List[CryptoSecret] | None)
os_type (int)
arch_type (int)
page_size_log2 (int)

Return type:

ImportResult

import_run_directory(run_dir, output_dir, keylog_filename='keylog.csv')[source]

Import all .dump files in a run directory to .msl format.

Parameters:

run_dir (Path)
output_dir (Path)
keylog_filename (str)

Return type:

List[ImportResult]

MSL format constants and enumerations (Memory Slice spec v1.1.0).

Magic bytes and all IntEnum/IntFlag types from the specification tables.

class Endianness[source]

Bases: IntEnum

LITTLE = 1

BIG = 2

__new__(value)

class HeaderFlag[source]

Bases: IntFlag

IMPORTED = 1

INVESTIGATION = 2

ENCRYPTED = 4

__new__(value)

class BlockType[source]

Bases: IntEnum

Block type registry (spec Table 9).

INVALID = 0

MEMORY_REGION = 1

MODULE_ENTRY = 2

MODULE_LIST_INDEX = 16

THREAD_CONTEXT = 17

FILE_DESCRIPTOR = 18

NETWORK_CONNECTION = 19

ENVIRONMENT_BLOCK = 20

SECURITY_TOKEN = 21

KEY_HINT = 32

IMPORT_PROVENANCE = 48

PROCESS_IDENTITY = 64

RELATED_DUMP = 65

SYSTEM_CONTEXT = 80

PROCESS_TABLE = 81

CONNECTION_TABLE = 82

HANDLE_TABLE = 83

CONNECTIVITY_TABLE = 85

END_OF_CAPTURE = 4095

VAS_MAP = 4097

POINTER_GRAPH = 4099

__new__(value)

class BlockFlag[source]

Bases: IntFlag

Per-block flags (spec Table 7).

COMPRESSED = 1

COMP_ZSTD = 2

COMP_LZ4 = 4

HAS_KEY_HINTS = 8

HAS_CHILDREN = 16

CONTINUATION = 32

__new__(value)

class CompAlgo[source]

Bases: IntEnum

NONE = 0

ZSTD = 1

LZ4 = 2

__new__(value)

class PageState[source]

Bases: IntEnum

Three-state page acquisition model (spec Table 22).

CAPTURED = 0

FAILED = 1

UNMAPPED = 2

RESERVED = 3

__new__(value)

class Protection[source]

Bases: IntFlag

Memory region protection flags (spec Section 5.1).

READ = 1

WRITE = 2

EXECUTE = 4

GUARD = 8

COW = 16

__new__(value)

class RegionType[source]

Bases: IntEnum

Memory region types (spec Section 5.1).

UNKNOWN = 0

HEAP = 1

STACK = 2

IMAGE = 3

MAPPED_FILE = 4

ANONYMOUS = 5

SHARED_MEM = 6

OTHER = 255

__new__(value)

class OSType[source]

Bases: IntEnum

WINDOWS = 0

LINUX = 1

MACOS = 2

ANDROID = 3

IOS = 4

FREEBSD = 5

UNKNOWN = 65535

__new__(value)

class ArchType[source]

Bases: IntEnum

X86 = 0

X86_64 = 1

ARM64 = 2

ARM32 = 3

UNKNOWN = 65535

__new__(value)

class MslKeyType[source]

Bases: IntEnum

Crypto key type codes (spec Table 17).

UNKNOWN = 0

PRE_MASTER_SECRET = 1

MASTER_SECRET = 2

SESSION_KEY = 3

HANDSHAKE_SECRET = 4

APP_TRAFFIC_SECRET = 5

RSA_PRIVATE_KEY = 6

ECDH_PRIVATE_KEY = 7

IKE_SA_KEY = 8

ESP_AH_KEY = 9

SSH_SESSION_KEY = 10

WIREGUARD_KEY = 11

ML_KEM_PRIVATE_KEY = 12

OTHER = 65535

__new__(value)

class MslProtocol[source]

Bases: IntEnum

Protocol codes (spec Table 17).

UNKNOWN = 0

TLS_12 = 1

TLS_13 = 2

DTLS_12 = 3

DTLS_13 = 4

QUIC = 5

IKEV2_IPSEC = 6

SSH = 7

WIREGUARD = 8

PQ_TLS = 9

OTHER = 65535

__new__(value)

class Confidence[source]

Bases: IntEnum

Key hint confidence levels (spec Section 5.6).

SPECULATIVE = 0

HEURISTIC = 1

CONFIRMED = 2

__new__(value)

class KeyState[source]

Bases: IntEnum

Key lifecycle state (spec Section 5.6).

UNKNOWN = 0

ACTIVE = 1

EXPIRED = 2

__new__(value)

class HandleType[source]

Bases: IntEnum

Handle Table entry type discriminator (spec Table 24, uint16).

UNKNOWN = 0

FILE = 1

DIR = 2

SOCKET = 3

PIPE = 4

MUTEX = 5

TIMER = 6

OTHER = 7

__new__(value)

class ConnRowType[source]

Bases: IntEnum

Connectivity Table row-type discriminator (spec Table 26, uint8).

IPV4_ROUTE = 1

IPV6_ROUTE = 2

ARP_ENTRY = 3

PACKET_SOCKET = 4

IFACE_STATS = 5

SOCKET_FAMILY_AGG = 6

MIB_COUNTER = 7

__new__(value)