heimdall.core package

Submodules

heimdall.core.access module

class heimdall.core.access.MemoryAccess(vmi: libvmi.Libvmi, pid: int)[source]

Bases: object

Provides methods for accessing and manipulating memory using Libvmi.

The MemoryAccess class allows reading and writing to a virtual machine’s memory space by utilizing the Libvmi library. It supports operations such as reading bytes, writing bytes, reading strings, and writing strings to specific memory addresses within a process.

__init__(vmi: libvmi.Libvmi, pid: int)[source]

Initialize the MemoryAccess with a Libvmi instance and PID.

Parameters:

vmi (Libvmi) – An instance of the Libvmi library initialized for the target virtual machine.
pid (int) – The process ID (PID) of the target process within the virtual machine.

read(address: int, size: int) → bytes[source]

Read bytes from a specific memory address.

Parameters:

address (int) – The memory address to read data from.
size (int) – The number of bytes to read.

Returns:

The bytes read from memory.

Return type:

bytes

read_str(address: int) → str[source]

Read a null-terminated string from a specific memory address.

Parameters:: address (int) – The memory address to read the string from.
Returns:: The string read from memory.
Return type:: str

read_ustr(address: int) → str[source]

Read a null-terminated string from a specific memory address.

Parameters:: address (int) – The memory address to read the string from.
Returns:: The string read from memory.
Return type:: str

write(address: int, data: bytes) → None[source]

Write bytes to a specific memory address.

Parameters:

address (int) – The memory address to write data to.
data (bytes) – The bytes data to write to memory.

write_str(address: int, data: str) → None[source]

Write a string to a specific memory address (with null termination).

Parameters:

address (int) – The memory address to write the string to.
data (str) – The string data to write to memory.

heimdall.core.context module

class heimdall.core.context.Context(vm_access: MemoryAccess, dwarf: Any | None = None, slide: int = 0)[source]

Bases: object

Represents the context in which Heimdall operates.

The Context class provides access to memory and symbol information, managing the virtual machine’s memory access, symbol profiles, and slide offsets.

__init__(vm_access: MemoryAccess, dwarf: Any | None = None, slide: int = 0)[source]

Initialize the Context with memory access, optional symbols file, and slide offset.

Parameters:

vm_access (MemoryAccess) – The memory access object used to read and write memory.
dwarf (Optional[Any], optional) – The path to the symbols file or an ISFFile object, by default None.
slide (int, optional) – The slide offset to adjust addresses, by default 0.

create_symbols_jar(dwarf)[source]

file_symbol(address: int, descriptor: Any | None = None) → Symbol[source]

Create a Symbol object adjusted by the slide offset.

Parameters:

address (int) – The file-relative memory address of the symbol.
descriptor (Optional[Any], optional) – The type descriptor of the symbol, by default None.

Returns:

The Symbol object representing the memory symbol, adjusted for the slide.

Return type:

Symbol

peek(address: int, size: int) → bytes[source]

Read bytes from a given address in the process’s memory.

Parameters:

address (int) – The memory address to read from.
size (int) – The number of bytes to read.

Returns:

The bytes read from memory.

Return type:

bytes

peek_str(address: int) → str[source]

Read a null-terminated string from a given address in the process’s memory.

Parameters:: address (int) – The memory address to read the string from.
Returns:: The string read from memory.
Return type:: str

peek_ustr(address: int) → str[source]

poke(address: int, data: bytes) → None[source]

Write bytes to a given address in the process’s memory.

Parameters:

address (int) – The memory address to write to.
data (bytes) – The data to write.

symbol(address: int, descriptor: Any | None = None) → Symbol[source]

Create a Symbol object based on the given address and descriptor.

Parameters:

address (int) – The memory address of the symbol.
descriptor (Optional[Any], optional) – The type descriptor of the symbol, by default None.

Returns:

The Symbol object representing the memory symbol.

Return type:

Symbol

heimdall.core.descriptors module

class heimdall.core.descriptors.ArrayKind(name: str, size: int, count: int, subtype: KindDescriptor)[source]

Bases: KindDescriptor

Represents a kind descriptor for arrays, including count and subtype.

__init__(name: str, size: int, count: int, subtype: KindDescriptor) → None

count: int

subtype: KindDescriptor

class heimdall.core.descriptors.BaseKind(name: str, size: int, fmt: str)[source]

Bases: KindDescriptor

Base class for specific kinds of descriptors with a format.

__init__(name: str, size: int, fmt: str) → None

fmt: str

class heimdall.core.descriptors.BitFieldKind(name: str, size: int, bit_length: int, bit_position: int, base_type: BaseKind)[source]

Bases: KindDescriptor

Represents a bit field kind descriptor with bit length and position.

__init__(name: str, size: int, bit_length: int, bit_position: int, base_type: BaseKind) → None

base_type: BaseKind

bit_length: int

bit_position: int

class heimdall.core.descriptors.ClassKind(name: str, size: int, fmt: str)[source]

Bases: BaseKind

Represents a kind descriptor specifically for classes.

__init__(name: str, size: int, fmt: str) → None

class heimdall.core.descriptors.ComplexKind(name: str, size: int, fields: Mapping[str, Field])[source]

Bases: KindDescriptor

Represents a composite kind descriptor with multiple fields.

__init__(name: str, size: int, fields: Mapping[str, Field]) → None

fields: Mapping[str, Field]

class heimdall.core.descriptors.Descriptor(name: str)[source]

Bases: object

Base class representing a descriptor with a name.

__init__(name: str) → None

name: str

class heimdall.core.descriptors.EnumKind(name: str, size: int, fmt: str, constants: dict[str, int])[source]

Bases: BaseKind

Represents a kind descriptor for enums, including constants.

__init__(name: str, size: int, fmt: str, constants: dict[str, int]) → None

constants: dict[str, int]

class heimdall.core.descriptors.Field(offset: int, type: KindDescriptor)[source]

Bases: object

Represents a field in a complex type with an offset and type.

__init__(offset: int, type: KindDescriptor) → None

offset: int

type: KindDescriptor

class heimdall.core.descriptors.FunctionKind(name: str, size: int, fmt: str)[source]

Bases: BaseKind

Represents a kind descriptor specifically for functions.

__init__(name: str, size: int, fmt: str) → None

class heimdall.core.descriptors.KindDescriptor(name: str, size: int)[source]

Bases: Descriptor

Represents a kind descriptor with a specific size.

__init__(name: str, size: int) → None

size: int

class heimdall.core.descriptors.PointerKind(name: str, size: int, fmt: str, subtype: KindDescriptor)[source]

Bases: BaseKind

Represents a kind descriptor for pointers, including a subtype.

__init__(name: str, size: int, fmt: str, subtype: KindDescriptor) → None

subtype: KindDescriptor

class heimdall.core.descriptors.StructKind(name: str, size: int, fields: Mapping[str, Field])[source]

Bases: ComplexKind

Represents a kind descriptor for structures.

__init__(name: str, size: int, fields: Mapping[str, Field]) → None

class heimdall.core.descriptors.SymbolDescriptor(name: str, address: int, kind: Descriptor)[source]

Bases: Descriptor

Represents a symbol with an address and a kind of descriptor.

__init__(name: str, address: int, kind: Descriptor) → None

address: int

kind: Descriptor

class heimdall.core.descriptors.UnionKind(name: str, size: int, fields: Mapping[str, Field])[source]

Bases: ComplexKind

Represents a kind descriptor for unions.

__init__(name: str, size: int, fields: Mapping[str, Field]) → None

class heimdall.core.descriptors.UnresolvedKind(name: str, size: int, data: Mapping)[source]

Bases: KindDescriptor

Represents a kind descriptor for unresolved kinds with data.

__init__(name: str, size: int, data: Mapping) → None

data: Mapping

heimdall.core.isf_file module

class heimdall.core.isf_file.ISFFile(path: Path)[source]

Bases: object

Manages and accesses symbol information from a JSON file in ISF (Intermediate Symbol File) format.

The ISFFile class provides methods to load and interact with symbol data extracted from a JSON file, typically used in volatility frameworks for memory forensics. It allows retrieval of types, symbols, enums, and metadata about the operating system.

__init__(path: Path) → None[source]

Initialize the ISFFile by loading data from the given JSON file.

Parameters:: path (str) – The file path to the ISF JSON file.
Raises:: SymbolsFileFormatError – If the JSON file cannot be loaded or is missing required keys.

get_enum(name: str) → Any[source]

Get an enum definition by name.

Parameters:: name (str) – The name of the enum to retrieve.
Returns:: The enum definition if found; otherwise, None.
Return type:: Any

get_os_type() → OSType[source]

Get the operating system type based on the metadata in the ISF file.

Returns:: The operating system type detected from the ISF metadata.
Return type:: OSType
Raises:: SymbolsFileFormatError – If the operating system type cannot be determined from the metadata.

get_symbol(name: str) → Any[source]

Get a symbol definition by name.

Parameters:: name (str) – The name of the symbol to retrieve.
Returns:: The symbol definition if found; otherwise, None.
Return type:: Any

get_type(name: str) → dict[str, Any] | None[source]

Get a type definition by name.

Parameters:: name (str) – The name of the type to retrieve.
Returns:: The type definition if found; otherwise, None.
Return type:: dict[str, Any] or None

validate_json() → None[source]

Validate that the JSON data contains all required keys.

Raises:: SymbolsFileFormatError – If the JSON data is missing any required keys.

class heimdall.core.isf_file.OSType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

LINUX = 3

MACOS = 1

WINDOWS = 2

heimdall.core.symbol module

Bases: object

Represents a memory-resident symbol with associated type information, providing methods for reading and writing values from memory.

The Symbol class acts as an abstraction for symbols in memory, offering type-aware memory access and manipulation. It supports handling complex types, arrays, pointers, and bitfields.

Notes

The class uses __getitem__ and __setitem__ to handle reading from and writing to memory based on the type descriptor:

This simplifies interaction with memory by providing type-safe, structured access to memory addresses.

Examples

Accessing an array element or dereferencing a pointer:

symbol = Symbol(ctx, address, descriptor)
value = symbol[0]      # Access an array element or dereference a pointer.
symbol[0] = 42         # Write a value to memory.

Parameters:

ctx (Context) – The context object managing memory access and symbol resolution.
address (int) – The memory address where the symbol is located.
descriptor (Optional[DescriptorType]) – The type descriptor associated with the symbol, determining how the memory should be interpreted.

cast(type_name: str) → Symbol[source]

Cast the symbol to another type.

Parameters:: type_name (str) – The name of the type to cast the symbol to.
Returns:: A new Symbol instance cast to the specified type.
Return type:: Symbol

disass(size: int = 40) → list[CsInsn][source]

Disassemble a number of bytes starting from the symbol’s address.

Parameters:: size (int, optional) – The number of bytes to disassemble (default is 40).
Returns:: A list of disassembled instructions.
Return type:: list of CsInsn

peek(size: int) → bytes[source]

Peek into memory at the symbol’s address and retrieve a specified number of bytes.

Parameters:: size (int) – The number of bytes to read from the symbol’s address.
Returns:: The bytes read from memory.
Return type:: bytes

peek_str() → str[source]

Peek into memory at the symbol’s address and retrieve a string.

Returns:: The string read from memory.
Return type:: str

peek_ustr() → str[source]

Peek into memory at the symbol’s address and retrieve a Unicode string.

Returns:: The Unicode string read from memory.
Return type:: str

poke(data: bytes) → None[source]

Write data to memory at the symbol’s address.

Parameters:: data (bytes) – The data to write to the symbol’s address.

heimdall.core.symbols_jar module

class heimdall.core.symbols_jar.SymbolsJar(profile: ISFFile)[source]

Bases: object

Represents a container for symbol and type information, responsible for resolving and storing symbols and types from a given context profile.

The SymbolsJar class provides methods to retrieve types, symbols, and enums by name. It initializes base types, user-defined types, enums, and symbols from the context’s profile.

__init__(profile: ISFFile)[source]

Initialize the SymbolsJar.

Parameters:: profile (ISFFile) – The symbols file used for populating types and symbols.

get_enum(name: str) → EnumKind[source]

Get an enum by its name.

Parameters:: name (str) – The name of the enum to retrieve.
Returns:: The enum descriptor corresponding to the given name, or None if not found.
Return type:: EnumKind

get_symbol(name: str) → SymbolDescriptor[source]

Get a symbol by its name.

Parameters:: name (str) – The name of the symbol to retrieve.
Returns:: The symbol descriptor corresponding to the given name.
Return type:: SymbolDescriptor

get_type(name: str) → KindDescriptor[source]

Get a type by its name.

Parameters:: name (str) – The name of the type to retrieve.
Returns:: The type descriptor corresponding to the given name.
Return type:: KindDescriptor
Raises:: ValueError – If the type with the given name is not found.

heimdall.core package

Submodules

heimdall.core.access module

heimdall.core.context module

heimdall.core.descriptors module

heimdall.core.isf_file module

heimdall.core.symbol module

heimdall.core.symbols_jar module

Module contents