zelos.api.zelos_api module

class zelos.api.zelos_api.Zelos(filename, *cmdline_args, **flags)

Bases: object

Class that provides access to the core APIs. These core APIs are event hooking, debugging, memory access, register access, and emulation context.

Parameters
  • filename – Specifies the name of the file to emulate.

  • cmdline_args – Arguments that are passed to the emulated binary.

  • flags – Parameters for zelos. To see the list of all flags, refer to Flags

Example

from zelos import Zelos

# initialize zelos with binary name, 2 cmdline args, and
# turn on the inst feed to print instructions.
z = Zelos(
    "binary_to_emulate"
    "ARG1",
    "ARG2",
    inst=True,
)
property memory

Returns the MemoryApi object.

property regs

Returns the RegsApi object.

property logger

Returns a logger that will behave in accordance to the –log config/cmdline option.

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.

  • ip_low – If specified, only executes callback if the event occurs at an address greater than or equal to this.

  • ip_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 = Zelos("binary_to_emulate")
z.hook_execution(
    HookType.EXEC.BLOCK, exec_hook
)
z.start()
hook_close(callback: Callable[[], Any]) → zelos.hooks.HookInfo

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

Parameters

callback – Called when zelos is closed. Does not take any arguments. The return value of callback 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 = Zelos("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, syscall_name: str = None) → zelos.hooks.HookInfo

Registers a callback 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.

  • syscall_name – Restricts calls of the hook to syscalls that match the given name.

  • 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 = Zelos("binary_to_emulate")
z.hook_syscalls(
    HookType.SYSCALL.AFTER, syscall_hook
)
z.start()
hook_zml(zml_string: str, callback: Callable[[], Any]) → zelos.hooks.HookInfo

Register a callback that triggers when a given ZML string is satisfied. For more information on ZML, view zelos.zml.ZmlParser.

Parameters
  • zml_string – Specifies condition to call callback.

  • callback – The code that should be executed when the specified event occurs.

delete_hook(hook_info: zelos.hooks.HookInfo) → None
start(timeout: float = 0) → Optional[dict]

Begin emulation. When called for the first time, begins execution at the binary entry point. If the emulation is stopped (for example, after calling stop()) this will resume execution from the current IP.

Parameters

timeout – Stops execution after timeout seconds.

Example

from zelos import Zelos

z = Zelos("binary_to_emulate")

# Start execution from the entry point
z.start()
step(count=1) → None

Begin emulation, stopping after executing count instructions.

Parameters

count – Maximum number of instructions to execute before stopping

next(count=1) → None

Begin emulation, executing count instructions not including instructions inside function calls.

Parameters

count – Maximum number of instructions to execute before stopping.

stop(reason: str = 'plugin')

Stop the Zelos run loop. After a call to stop(), execution can be resumed from the current IP with a call to start().

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()

End the current thread. Marks current thread as successfully completed and swaps to the next available thread, if one exists.

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 = Zelos("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 = Zelos("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 = Zelos("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 = Zelos("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 = Zelos("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 = Zelos("binary_to_emulate")

z.set_watchpoint(0xdeadbeef, True, True)

z.remove_watchpoint(0xdeadbeef)

z.start()
property date

Returns the date string used internally during emulation. The date string format is YYYY-MM-DD.

Getter

Returns the date string in YYYY-MM-DD format.

Setter

Sets the date string. Input must be YYYY-MM-DD format.

Type

str

property process

Returns the currently active process.

Type

Process

property thread

Returns the currently active thread.

Type

Thread

property main_binary

Returns the parsed main binary, if it exists, otherwise returns None. Note that the “main” binary denotes the binary that is loaded by Zelos during emulation, not necessarily the binary that is specified as input (the “target” binary). When the specified input binary (“target”) is statically linked, it is also the “main” binary. However, when the specified input binary (“target”) is dynamically linked, the “main” binary instead refers to the dynamic linker/loader.

Type

zelos.plugin.ParsedBinary

property main_binary_path

Returns the absolute path to the main binary, if it exists, otherwise returns None. Note that the “main” binary denotes the binary that is loaded by Zelos during emulation, not necessarily the binary that is specified as input (the “target” binary). When the specified input binary (“target”) is statically linked, it is also the “main” binary. However, when the specified input binary (“target”) is dynamically linked, the “main” binary instead refers to the dynamic linker/loader.

Type

str

property target_binary_path

Returns the absolute path to the target binary, if it exists, otherwise returns None. Note that the “target” binary denotes the binary specified as input to Zelos.

Type

str

class zelos.api.zelos_api.ZelosCmdline(cmdline_args)

Bases: zelos.api.zelos_api.Zelos

A workaround for allowing Zelos to be initialized with a commandline string while also allowing the main Zelos to maintain its simple/intuitive constructor based on commandline arguments and flags.