zelos.api.memory_api module¶

class zelos.api.memory_api.MemoryApi(zelos)¶

Bases: object

read(addr: int, size: int) → bytearray¶

Copies specified region of memory. Requires that the specified address is mapped.

Parameters

addr – Address to start reading from.
size – Number of bytes to read.

Returns

Bytes corresponding to data held in memory.

write(addr: int, data: bytearray) → int¶

Writes specified bytes to memory. Requires that the specified address is mapped.

Parameters

addr – Address to start writing data to.
data – Bytes to write in memory.

read_int(addr: int, size: int = None, signed: bool = False) → int¶

Reads an integer value from the specified address. Can handle multiple sizes and representations of integers.

Parameters

addr – Address to begin reading int from.
size – Size (# of bytes) of integer representation. If None, uses the architecture to determine size (32 bit -> 4, 64bit -> 8). Default is None.
signed – If true, interpret bytes as signed integer. Default false.

Returns

Integer representation of bytes read.

write_int(addr: int, value: int, size: int = None, signed: bool = False) → int¶

Writes an integer value to the specified address. Can handle multiple sizes and representations of integers.

Parameters

addr – Address in memory to write integer to.
value – Integer to write into memory.
size – Size (# of bytes) to write into memory. If None, uses the architecture to determine size (32 bit -> 4, 64bit -> 8). Default is None.
signed – If true, write number as signed integer. Default false.

Returns

Number of bytes written to memory.

read_string(addr: int, size: int = 1024) → str¶

Reads a utf-8 string from memory. Stops at null terminator. Fails if a byte is uninterpretable.

Parameters

addr – Address in memory to start reading from.
size – Maximum size of string to read from memory.

Returns

String read from memory.

read_wstring(addr: int, size: int = 1024) → str¶

Reads a utf-16 string from memory. Stops at null terminator. Fails if a byte is uninterpretable.

Parameters

addr – Address in memory to start reading from.
size – Maximum size of string to read from memory.

Returns

String read from memory.

read_punicode_string(addr: int) → str¶

Given the address of a pointer to a unicode string, returns the string that was pointed to as a python string.

Parameters: addr – Address of the unicode string pointer
Returns: String read from memory

read_pansi_string(addr: int) → int¶

Given the address of a pointer to a ANSI string, returns the string that was pointed to as a python string.

Parameters: addr – Address of the ANSI string pointer
Returns: String read from memory

write_string(addr: int, value: str, terminal_null_byte: bool = True) → int¶

Writes a string to a specified address as utf-8. By default, adds a terminal null byte.

Parameters

addr – Address in memory to begin writing string to.
value – String to write to memory.
terminal_null_byte – If True, adds terminal null byte. Default True.

Returns

Number of bytes written.

write_wstring(addr: int, value: int, terminal_null_byte: bool = True) → int¶

Writes a string to a specified address as utf-16-le. By default, adds a terminal null byte.

Parameters

addr – Address in memory to begin writing string to.
value – String to write to memory.
terminal_null_byte – If True, adds terminal null byte. Default True.

Returns

Number of bytes written.

readstruct(addr: int, obj: _ctypes.Structure) → _ctypes.Structure¶

Reads a ctypes structure from memory.

Parameters

addr – Address in memory to begin reading structure from.
obj – An instance of the structure to create from memory.

Returns

Instance of structure read from memory.

Example

class SIGACTION(ctypes.Structure):
    _fields_ = [
        ("sa_handler", ctypes.c_uint64),
        ("sa_flags", ctypes.c_uint64),
        ("sa_restorer", ctypes.c_uint64),
        ("sa_mask", ctypes.c_uint64),
    ]

# Pointer to sigaction struct
pointer = 0xdeadbeef

sigaction = api.memory.readstruct(pointer, SIGACTION())
print(sigaction.sa_handler)

writestruct(address: int, structure: _ctypes.Structure) → int¶

Write a ctypes Structure to memory.

Parameters

addr – Address in memory to begin writing to.
structure – An instance of the structure to write to memory.

Returns

Number of bytes written to memory.

Example

class SIGACTION(ctypes.Structure):
    _fields_ = [
        ("sa_handler", ctypes.c_uint64),
        ("sa_flags", ctypes.c_uint64),
        ("sa_restorer", ctypes.c_uint64),
        ("sa_mask", ctypes.c_uint64),
    ]

sigaction = SIGACTION()
sigaction.handler = 0xdeadbeef

# Memory address to write struct to
destination = 0xb0bad00d

bytes_written = api.memory.writestruct(destination, sigaction)

map(address: int, size: int, name: str = '', kind: str = '', module_name: str = '', prot: int = <ProtType.RWX: 7>, reserve: bool = False) → None¶

Maps a region of memory at the specified address.

Parameters

address – Address to map.
size – # of bytes to map. This will be rounded up to the nearest 0x1000.
name – String used to identify mapped region. Used for debugging.
kind – String used to identify the purpose of the mapped region. Used for debugging.
module_name – String used to identify the module that mapped this region.
prot – An integer representing the RWX protection to be set on the mapped region.
reserve – Reserves memory to prepare for mapping. An option used in Windows.

get_region(address: int) → Optional[zelos.emulator.base.MemoryRegion]¶

Returns the memory region that the specified address is mapped in, if one exists, otherwise returns None.

Parameters: address – Address used to specify a region of memory.
Returns: A zelos.emulator.base.MemoryRegion containing the specified address, or None if the address is not mapped in any region.

get_regions() → List[zelos.emulator.base.MemoryRegion]¶

Returns a list of all mapped memory regions.

Returns: A list of zelos.emulator.base.MemoryRegion objects.

read_ptr(addr: int) → int¶: Reads a pointer at addr. The number of bytes read is dependent on the architecture of the binary.

read_size_t(addr: int) → int¶: Reads a value of type size_t at addr.

pack(x: int, bytes: int = None, little_endian: bool = None, signed: bool = False) → bytes¶: Unpacks an integer from a byte format. Defaults to the current architecture bytes and endianness.

unpack(x: bytes, bytes: int = None, little_endian: bool = None, signed: bool = False) → int¶: Unpacks an integer from a byte format. Defaults to the current architecture bytes and endianness.

read_int64(addr: int) → int¶

read_uint64(addr: int) → int¶

read_int32(addr: int) → int¶

read_uint32(addr: int) → int¶

read_int16(addr: int) → int¶

read_uint16(addr: int) → int¶

read_int8(addr: int) → int¶

read_uint8(addr: int) → int¶

write_ptr(addr: int, value: int) → int¶

write_size_t(addr: int, value: int) → int¶

write_int64(addr: int, value: int) → int¶

write_uint64(addr: int, value: int) → int¶

write_int32(addr: int, value: int) → int¶

write_uint32(addr: int, value: int) → int¶

write_int16(addr: int, value: int) → int¶

write_uint16(addr: int, value: int) → int¶

write_int8(addr: int, value: int) → int¶

write_uint8(addr: int, value: int) → int¶

search(value_to_search: bytes) → List[int]¶: Search for a sequence of bytes in memory. Returns a list of the starting address of all nonoverlapping matches.