zelos.emulator.base module

class zelos.emulator.base.MemoryRegion(emu, address: int, size: int, prot: int, name: str, kind: str, module_name: str, shared: bool = False, reserve: bool = False, host_address: int = None, managed_object: any = None)

Bases: object

Represents a region of guest memory.

property start

property end

shrink(address: int, size: int)

get_data() → bytearray

Returns all data in the region.

Returns

Data from the region.

class zelos.emulator.base.PageTable

Bases: object

Maps host system pages to guest system pages. Enables directly reading and writing emulated memory without using the emulator memory API.

PAGE_MASK = 18446744073709547520

reset()

add(section) → None

Add or replace pages from the given section to the page table.

Parameters

section – the memory region to add.

remove(section) → None

Remove pages from the given section from the page table

Parameters

section – the memory region to remove.

exists(address: int) → bool

Checks if the address exists in the page table.

Parameters

address – The address of the page to check.

Returns

True if the address exists in the page table, False

otherwise.

read(address: int, size: int) → bytearray

Reads size bytes of guest memory from address.

Parameters

• address – The address to read.

• size – The size of the data to fetch in bytes.

Returns

The data at the specified address.

write(address: int, data: bytes) → None

Writes data to guest memory at address.

Parameters

• address – The address to read.

• size – The size of the data to fetch in bytes.

class zelos.emulator.base.IEmuHelper(unicorn_engine, state)

Bases: object

This is a class that serves as a wrapper around Unicorn, providing some additional functionality surrounding stacks and commonly used registers. Each architecture will need to implement their own subclass to provide the additional register information that is needed.

Because there may be multiple threads sharing a single emu instance, prefer to access these methods through the Thread class.

We chose to use string names for registers rather than an enum for quality of life reasons.

property regmap

property bytes

property is_running

getstack(idx: int) → int

setstack(idx: int, val: int) → None

popstack() → int

pushstack(data: int) → None

setSP(val: int) → None

getSP() → int

setFP(val: int)

getFP() → int

get_reg(reg_name: str) → int

set_reg(reg_name: str, val: int) → None

setIP(val: int) → None

getIP() → int

get_all_regs() → List[str]

Gets all registers for this architecture. Order of returned values is consistent between calls.

get_all_reg_vals() → Dict[str, int]

Returns a dict of {reg_name:reg_val} for all regs for the current architecture.

get_regs(regs: Iterable[str] = None) → Dict[str, int]

Returns a dictionary of registers and their values. Defaults to important regs for the current architecture

dumpregs(regs: Iterable[str] = None) → str

context_restore(context)

context_save()

emu_start(begin, until, timeout=0, count=0)

emu_stop()

hook_add(htype, callback, user_data=None, begin=1, end=0, arg1=0)

hook_del(h)

mem_map(address: int, size: int, name: str = '', kind: str = '', module_name: str = '', prot: int = <ProtType.RWX: 7>, shared: bool = False, reserve: bool = False)

mem_map_file(address: int, filename: str, offset: int = 0, size: int = 0, prot: int = <ProtType.RW: 3>, shared: bool = False)

map_shared(mr: zelos.emulator.base.MemoryRegion)

mem_unmap(address: int, size: int)

mem_protect(address: int, size: int, prot: int = <ProtType.RWX: 7>)

mem_region(address: int)

mem_regions()

mem_read(address: int, size: int)

mem_write(address: int, data)

bb_count()

inst_count()

to_signed(x, bytes=None)

pack(x: int, bytes: int = None, little_endian: bool = None, signed: bool = False) → <property object at 0x7ff2d678f778>

Unpacks an integer from a byte format. Defaults to the current architecture bytes and endianness.

unpack(x: <property object at 0x7ff2d678f778>, 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.

zelos.emulator.base.create_emulator(arch, mode, state) → zelos.emulator.base.IEmuHelper

Factory method for constructing the appropriate IEmuHelper