zelos package¶

Submodules¶

Module contents¶

A comprehensive binary emulation platform. <https://github.com/zeropointdynamics/zelos>

class zelos.Zelos(filename, *cmdline_args, **flags)¶

Bases: object

API class that provides access to interal api wrappers.

hook_memory(hook_type: zelos.enums.HookType.MEMORY, callback: Callable[[Zelos, int, int, int, int], Any], mem_low: Optional[int] = None, mem_high: Optional[int] = None, name: Optional[str] = None, end_condition: Optional[Callable[[], bool]] = None) → zelos.hooks.HookInfo¶

Registers a hook on memory. Executes callback every time the specified event happens in memory.

The hook will only trigger when the event occurs at an address between mem_low and mem_high, if either of them are specified.

The hook will continue to trigger until the end_condition specified evaluates to True.

Parameters

hook_type – Specifies the event in memory that should trigger the callback to be executed. Options can be found in zelos.HookType.MEMORY
callback – The code that should be executed when the specified event occurs. The function should accept the following inputs: (zelos, access, address, size, value). The return value of “callback” is ignored.
mem_low – If specified, only executes callback if the event occurs at an address greater than or equal to this.
mem_high – If specified, only executes callback if the event occurs at an address less than or equal to this.
name – An identifier for this hook. Used for debugging.
end_condition – If specified, executes after the callback. If the function returns True, this hook is deleted.

Returns

Information regarding the hook.

Example

from zelos import Zelos, HookType

# Print every write to memory
def memory_hook(zelos, access, address, size, value):
    print(value)

z = Zelos("binary_to_emulate")
z.hook_memory(
    HookType.MEMORY.WRITE,
    memory_hook
)
z.start()

hook_execution(hook_type: zelos.enums.HookType.EXEC, callback: Callable[[Zelos, int, int], Any], ip_low: Optional[int] = None, ip_high: Optional[int] = None, name: Optional[str] = None, end_condition: Optional[Callable[[], bool]] = None) → zelos.hooks.HookInfo¶

Registers a hook that executes when code is executed. This is either for every instruction that is executed, or every block.

The hook will only trigger when the event occurs at an address between ip_low and ip_high, if either of them are specified.

The hook will continue to trigger until the end_condition specified evaluates to True.

Parameters

hook_type – Specifies whether the callback should be triggered every instruction, or every block. Options can be found in zelos.HookType.EXEC
callback – The code that should be executed when the specified event occurs. The function should accept the following inputs: (zelos, address, size). The return value of “callback” is ignored.
mem_low – If specified, only executes callback if the event occurs at an address greater than or equal to this.
mem_high – If specified, only executes callback if the event occurs at an address less than or equal to this.
name – An identifier for this hook. Used for debugging.
end_condition – If specified, executes after the callback. If the function returns True, this hook is deleted.

Returns

Information regarding the hook.

Example

from zelos import Zelos, HookType

# Print the first address of every block
def exec_hook(zelos, address, size):
    print(address)

z = ("binary_to_emulate")
z.hook_execution(
    HookType.EXEC.BLOCK, exec_hook
)
z.start()

hook_close(closure: Callable[[], Any]) → zelos.hooks.HookInfo¶

Registers a closure that is called when zelos.Engine.close() is called.

Parameters: closure – Called when zelos is closed. Does not take any arguments. The return value of closure is ignored

Example

from zelos import Zelos

# Close a file you are using with zelos
file = open("testfile", "r")
def close_cleanup():
    file.close()

z = ("binary_to_emulate")
z.hook_close(close_cleanup)
z.start()

# Hooks are run at this point
z.close()

hook_syscalls(syscall_hook_type: zelos.enums.HookType.SYSCALL, callback: Callable[[Zelos, str, Args, int], Any], name: str = None) → zelos.hooks.HookInfo¶

Registers a closure that is called when a syscall is invoked.

Parameters

syscall_hook_type – Decides when the hook should be triggered in relation to the execution of the syscall. Options can be found in zelos.HookType.SYSCALL
callback – The code that should be executed when the specified event occurs. The function should accept the following inputs: (zelos, syscall_name, args, return_value) The return value of “callback” is ignored.
name – An identifier for this hook. Used for debugging.

Example

from zelos import Zelos, HookType

# Keep track of the syscall return values
syscall_return_values = []
def syscall_hook(zelos, sys_name, args, ret_val):
    syscall_return_values.append((sys_name, ret_val))

z = ("binary_to_emulate")
z.hook_syscalls(
    HookType.SYSCALL.AFTER, syscall_hook
)
z.start()

delete_hook(hook_info: zelos.hooks.HookInfo) → None¶

start(timeout: float = 0) → None¶

Begin emulation, starting execution at the IP.

Parameters: timeout – Stops execution after timeout seconds.

Example

from zelos import Zelos

z = ("binary_to_emulate")

z.start()

step(count=1) → None¶

Begin emulation, stopping after executing count instructions.

Parameters: count – Maximum number of instructions to execute before stopping

stop(reason: str = 'plugin')¶

Stop the Zelos run loop and end execution.

Parameters: reason – An optional identifier that specifies a reason for stopping execution. Upon calling stop, the reason will be printed to stdout after Zelos exits the run loop. This is useful for debugging when log level is set to ‘debug’ or ‘spam’.

close()¶: Closes Zelos and runs cleanup functions.

end_thread()¶: Stop the current thread. Mark as successfully completed.

swap_thread(reason: str = 'thread swap')¶

Swap the running thread with the next scheduled thread.

Parameters: reason – An optional identifier that specifies a reason for swapping threads. Upon calling swap_thread, the reason will be printed to stdout after Zelos has successfully swapped to the next scheduled thread. This is useful for debugging when log level is set to ‘spam’.

set_breakpoint(address: int, temporary: bool = False)¶

Set a breakpoint at a particular address.

Parameters

address – Target address of breakpoint.
temporary – Determines whether or not the breakpoint is temporary. A temporary breakpoint will be automatically removed after use.

Example

from zelos import Zelos

z = ("binary_to_emulate")

z.set_breakpoint(0xdeadbeef)

z.start()

remove_breakpoint(address: int)¶

Remove a previously set breakpoint.

Parameters: address – Target address of breakpoint to remove.

Example

from zelos import Zelos

z = ("binary_to_emulate")

z.set_breakpoint(0xdeadbeef)

z.remove_breakpoint(0xdeadbeef)

z.start()

set_syscall_breakpoint(syscall_name: str)¶

Set a breakpoint at all syscalls of a specified name.

Parameters: syscall_name – Target syscall set breakpoint at.

Example

from zelos import Zelos

z = ("binary_to_emulate")

z.set_syscall_breakpoint("write")

z.start()

remove_syscall_breakpoint(syscall_name: str)¶

Remove a previously set syscall breakpoint specified by name.

Parameters: syscall_name – Target syscall to remove breakpoints from.

Example

from zelos import Zelos

z = ("binary_to_emulate")

z.set_syscall_breakpoint("write")

z.remove_syscall_breakpoint("write")

z.start()

set_watchpoint(address: int, read: bool, write: bool, temporary: bool = False)¶

Set a watchpoint on a particular memory address.

Parameters

address – Target address of watchpoint.
read – Determines whether to watch for reads to the target memory address.
write – Determines whether to watch for writes to the target memory address.

Example

from zelos import Zelos

z = ("binary_to_emulate")

# Break at any read or write to memory address 0xdeadbeef
z.set_watchpoint(0xdeadbeef, True, True)

# Break only at writes to memory address 0xfeedf00d
z.set_watchpoint(0xfeedf00d, False, True)

# Break only at reads to memory address 0xb0bad00d
z.set_watchpoint(0xb0bad00d, True, False)

z.start()

remove_watchpoint(address: int)¶

Remove a previously set watchpoint.

Parameters: address – Target address of watchpoint to remove.

Example

from zelos import Zelos

z = ("binary_to_emulate")

z.set_watchpoint(0xdeadbeef, True, True)

z.remove_watchpoint(0xdeadbeef)

z.start()

property date¶: Returns the date used internally during emulation.

property process¶: Returns the active process

property thread¶: Returns the active thread

class zelos.Engine(config=None, api=None)¶

Bases: object

STACK_SIZE = 589824¶

set_log_level(log_level)¶

log_api(args, isNative=False)¶

log_api_dbg(args)¶

hexdump(address: int, size: int) → None¶

property current_process¶

property emu¶

property memory¶

property scheduler¶

property thread_manager¶

property current_thread¶

property loader¶

property modules¶

property handles¶

set_mem_limit(limit_in_mb: int) → None¶

set_writetrace(target)¶

parse_file(filename)¶

load_executable(module_path, entrypoint_override=None)¶: This method simply loads the executable, without starting the emulation

property helpers¶: Helpers are the first layer in the components hierarchy, which mainly deal with providing help to developers.

load_library(module_name)¶

disas(address: int, size: int)¶: Disassemble code at the given address, for up to size bytes

step(count: int = 1) → None¶: Steps one assembly level instruction

step_over(count: int = 1) → None¶: Steps on assembly level instruction up to count instructions

start(count=0, timeout=0, swap_threads=True) → None¶: Starts execution of the program at the given offset or entry point.

close() → None¶: Handles the end of the run command

set_trace_on(val)¶

set_verbose(should_set_verbose: bool) → None¶

Used to set the verbosity level, and change the hooks. This prevents two types of issues:

Running block hooks when printing individual instructions
This will cause the annotations that are printed to be the values at the end of the block’s execution
Running instruction hooks when not printing instructions
This will slow down the emulation (sometimes considerably)

set_hook_granularity(granularity: zelos.enums.HookType.EXEC)¶

exception zelos.InvalidHookTypeException¶: Bases: zelos.exceptions.ZelosException

exception zelos.InvalidRegException¶: Bases: zelos.exceptions.ZelosException

exception zelos.OutOfMemoryException¶: Bases: Exception

exception zelos.UnsupportedBinaryError¶: Bases: zelos.exceptions.ZelosException

exception zelos.ZelosException¶: Bases: Exception

exception zelos.ZelosLoadException¶: Bases: zelos.exceptions.ZelosException

exception zelos.ZelosRuntimeException¶: Bases: zelos.exceptions.ZelosException

class zelos.HookType¶

Bases: object

class MEMORY¶

Bases: enum.Enum

Used by zelos.Zelos.hook_memory() to specify the memory event to hook on. View the registration function for more details.

READ = 1¶

WRITE = 2¶

READ_UNMAPPED = 3¶

WRITE_UNMAPPED = 4¶

READ_PROT = 5¶

WRITE_PROT = 6¶

READ_AFTER = 7¶

UNMAPPED = 8¶

PROT = 9¶

READ_INVALID = 10¶

WRITE_INVALID = 11¶

INVALID = 12¶

VALID = 13¶

class EXEC¶

Bases: enum.Enum

Used by zelos.Zelos.hook_execution(). If INST is chosen, the registered hook will be executed every time a single instruction is executed.

If BLOCK is chosen, the registered hook will be executed after every block of instructions is executed. A block is interpreted as a contiguous sequence of code where only the last instruction can modify control flow, typically a branch or return instruction.

View the registration function for more details.

INST = 1¶

BLOCK = 2¶

class THREAD¶

Bases: enum.Enum

Not usable yet through Zelos API

CREATE = 1¶

SWAP = 2¶

DESTROY = 3¶

class PROCESS¶

Bases: enum.Enum

Not usable yet through Zelos API

CREATE = 1¶

SWAP = 2¶

DESTROY = 3¶

class SYSCALL¶

Bases: enum.Enum

Used by zelos.Zelos.hook_syscalls().

If AFTER is chosen, the hook will be triggered after the syscall hass been executed.

View the registration function for more details.

AFTER = 1¶

class zelos.ProtType¶

Bases: enum.IntEnum

An enumeration.

NONE = 0¶

READ = 1¶

WRITE = 2¶

EXEC = 4¶

RWX = 7¶

RX = 5¶

RW = 3¶

class zelos.CommandLineOption(name, **kwargs)¶

Bases: object

Registers a command line option for Zelos. The kwargs are those recognized by the argparse library

class zelos.IPlugin(zelos)¶

Bases: zelos.manager.IManager

Base class for Plugins that provides an api for interacting with zelos objects.

class zelos.ISubcommand(argparser)¶: Bases: object

zelos package¶

Subpackages¶

Submodules¶

Module contents¶