core.models

Data structures for memory dump analysis.

deprecated_kwarg(cls, old_name, new_name)

Patch a dataclass __init__ to accept a deprecated kwarg name.

When callers pass old_name as a keyword argument, it is silently mapped to new_name (unless new_name is also provided).

Parameters:

• old_name (str)

• new_name (str)

class CryptoSecret

Bases: object

A parsed cryptographic secret from a keylog file.

secret_type: str

identifier: bytes

secret_value: bytes

protocol: str = 'TLS'

property client_random: bytes

Backward-compatible alias for identifier.

__init__(secret_type, identifier, secret_value, protocol='TLS')

Parameters:

• secret_type (str)

• identifier (bytes)

• secret_value (bytes)

• protocol (str)

Return type:

None

TLSSecret

alias of CryptoSecret

class KeyOccurrence

Bases: object

A found key occurrence in a dump file.

offset: int

secret: CryptoSecret

context_before: bytes

key_bytes: bytes

context_after: bytes

property context_start_offset: int

__init__(offset, secret, context_before, key_bytes, context_after)

Parameters:

• offset (int)

• secret (CryptoSecret)

• context_before (bytes)

• key_bytes (bytes)

• context_after (bytes)

Return type:

None

class DumpFile

Bases: object

Metadata for a single dump file.

kind tags the dump flavour so downstream code (discovery, API responses, UI) can branch without re-sniffing magic bytes. Valid values: "msl", "gdb_raw", "lldb_raw", "gcore", "raw".

path: Path

timestamp: str

phase_prefix: str

phase_name: str

canonical_phase: str | None = None

kind: str = 'raw'

property full_phase: str

property canonical_or_raw: str

__init__(path, timestamp, phase_prefix, phase_name, canonical_phase=None, kind='raw')

Parameters:

• path (Path)

• timestamp (str)

• phase_prefix (str)

• phase_name (str)

• canonical_phase (str | None)

• kind (str)

Return type:

None

class RunDirectory

Bases: object

A single run directory containing dumps and keylog.

meta is populated from meta.json when present (see core.dataset_metadata.load_run_meta()). Legacy runs without a meta.json leave it None — discovery code must tolerate both.

path: Path

library: str

protocol_version: str

run_number: int

dumps: List[DumpFile]

secrets: List[CryptoSecret]

secret_source: str = 'none'

phase_mappings: Dict[str, str]

meta: 'DatasetMeta' | None = None

property tls_version: str

Backward-compatible alias for protocol_version.

get_dump_for_phase(phase)

Parameters:

phase (str)

Return type:

DumpFile | None

available_phases()

Return type:

List[str]

__init__(path, library, protocol_version, run_number, dumps=<factory>, secrets=<factory>, secret_source='none', phase_mappings=<factory>, meta=None)

Parameters:

• path (Path)

• library (str)

• protocol_version (str)

• run_number (int)

• dumps (List[DumpFile])

• secrets (List[CryptoSecret])

• secret_source (str)

• phase_mappings (Dict[str, str])

• meta (Optional['DatasetMeta'])

Return type:

None

class ComparisonRegion

Bases: object

Aligned regions across dumps for multi-run comparison.

secret_type: str

key_length: int

context_size: int

run_data: List[Tuple[bytes, bytes, bytes]]

__init__(secret_type, key_length, context_size, run_data=<factory>, run_labels=<factory>, run_offsets=<factory>)

Parameters:

• secret_type (str)

• key_length (int)

• context_size (int)

• run_data (List[Tuple[bytes, bytes, bytes]])

• run_labels (List[str])

• run_offsets (List[int])

Return type:

None

run_labels: List[str]

run_offsets: List[int]