zelos.memory module

class zelos.memory.Section(emu, address, size, name, kind, module_name, reserve=False, ptr=None)

Bases: object

Represents a region of memory that has been mapped.

get_data() → bytearray

Returns all data in the region.

Returns

Data from the region.

entropy() → float

Calculates the entropy of data contained within the section.

Returns

Entropy of this section.

get_strings(min_len: int = 5) → List[str]

Returns all strings found in the region’s memory.

Parameters

min_len – The minimum length a string must be to be included in the output.

Returns

List of strings found within this section’s data.

class zelos.memory.Memory(emu, state, lowest_addr: int = 0, max_addr: int = 18446744073709551615, disableNX: bool = False)

Bases: object

Responsbile for interactions with emulated memory.

HEAP_BASE = 2415919104

HEAP_MAX_SIZE = 104857600

VALLOC_BASE = 12910592

MAX_UINT64 = 18446744073709551615

copy(other_memory: zelos.memory.Memory) → None

Creates the same state in other_memory.

Parameters

other_memory – Memory that will contain a copy of self.

clear() → None

Clears all of memory

get_sections() → List[zelos.memory.Section]

Gets meaningful sections from Zelos in memory. Reserved sections are not guaranteed to be written into Zelos, so memory operations on these addresses may not be meaningful.

Returns

Sections present in memory.

record_initial_memory_state() → None

We record the initial memory state in order to use it to tell what memory has changed.

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: bytes) → None

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, sz: 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.

• sz – Size (# of bytes) of integer representation.

• signed – If true, interpret bytes as signed integer. Default false.

Returns

Integer represntation of bytes read.

write_int(addr: int, value: int, sz: 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.

• sz – Size (# of bytes) to write into memory.

• 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.

get_punicode_string(addr: int) → str

get_pansi_string(addr: int) → int

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.

readstructarray(addr: int, count: int, obj: _ctypes.Structure) → List[_ctypes.Structure]

Read an array of ctypes structure from memory.

Parameters

• addr – Address in memory to begin reading structure from.

• count – number of instances of the object to read.

• obj – An instance of the structure to create from memory.

Returns

List of structures read from memory.

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.

dumpstruct(structure: _ctypes.Structure, indent_level: int = 0) → None

Prints a string representing the data held in a struct.

Parameters

• structure – The structure to print out.

• indent_level – Number of indents when printing output. Makes for easier reading. Defaults to no indentation.

map_anywhere(size: int, name: str = '', kind: str = '', min_addr: int = 0, max_addr: int = 18446744073709551615, alignment: int = 4096, prot: int = <ProtType.RWX: 7>) → int

Maps a region of memory with requested size, within the addresses specified. The size and start address will respect the alignment.

Parameters

• size – # of bytes to map. This will be rounded up to match the alignment.

• name – String used to identify mapped region. Used for debugging.

• kind – String used to identify the purpose of the mapped region. Used for debugging.

• min_addr – The lowest address that could be mapped.

• max_addr – The highest address that could be mapped.

• alignment – Ensures the size and start address are multiples of this. Must be a multiple of 0x1000. Default 0x1000.

• prot – RWX permissions of the mapped region. Defaults to granting all permissions.

Returns

Start address of mapped region.

map(address: int, size: int, name: str = '', kind: str = '', module_name: str = '', prot: int = <ProtType.RWX: 7>, ptr: Optional[_ctypes.POINTER] = None, 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.

• ptr – If specified, creates a memory map from the pointer.

• reserve – Reserves memory to prepare for mapping. An option used in Windows.

copy_section(section: zelos.memory.Section, other_memory: zelos.memory.Memory) → None

Copies a section from this instance of memory into another instance of memory.

Parameters

• section – The section to copy. Must correspond to a section within this memory object.

• other_memory – An instance of memory to copy the specified section to.

protect(address: int, size: int, prot: int) → None

Sets memory permissions on the specified memory region. Respects alignment of 0x1000.

Parameters

• address – Address of memory region to modify permissions. Rounds down to nearest 0x1000.

• size – Size of region to protect. Rounds up to nearest 0x1000.

• prot – Desired RWX permissions.

unmap(address, size) → None

Unmaps a memory region, allowing it to be mapped again.

Parameters

• address – Address of section to be unmapped.

• size – Number of bytes to unmap.

get_base(address: int) → Optional[int]

Returns the base address of the memory region that contains this address.

Returns

The base address of the containing region, or None if address is not contained within any region.

get_perms(address: int) → int

Returns the permissions of the section containg the given address.

Parameters

address – Used to pick the containing section.

Returns

Permissions of the containing section.

get_size(address: int) → int

Returns the size of the section containg the given address.

Parameters

address – Used to pick the containing section.

Returns

Size of the containing section.

hook_first_read(region_addr, hook)

get_region(address)

Gets the region that this address belongs to.

get_initial_region(address)

Returns the initial region that contained this address, along with the memory at that time.

get_region_hash()

Used for determining whether a memory region has changed

read_ptr(addr: int) → int

read_size_t(addr: int) → int

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

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.

class zelos.memory.Heap(memory, emu, heap_start, heap_max_size)

Bases: object

Helper class to manage heap allocation.

dealloc(size: int) → int

Returns memory from the heap.

Parameters

size – # of bytes to return from the heap.

Returns

Address of the new heap boundary.

alloc(size: int, name: str = None, align: int = 4) → int

Allocates memory to the heap. These are rounded up to the size of the alignment.

Parameters

• size – Number of bytes to allocate.

• name – Used to keep track of what information was allocated. Used for debugging

• align – Ensures that the memory allocated is a multiple of this value. Defaults to 4.

Returns

Address of the new heap boundary

allocstr(s, terminal_null_byte=True, is_wide=False, alloc_name='allocstr')

Allocates a string to the heap. These are rounded up to the size of the alignment.

Parameters

• size – Number of bytes to allocate.

• name – Used to keep track of what information was allocated. Used for debugging

• align – Ensures that the memory allocated is a multiple of this value. Defaults to 4.

Returns

Address of the new heap boundary