zelos package¶
Subpackages¶
Submodules¶
- zelos.breakpoints module
- zelos.config_gen module
- zelos.engine module
- zelos.enums module
- zelos.exceptions module
- zelos.file_system module
- zelos.hooks module
- zelos.manager module
- zelos.memory module
- zelos.modules module
- zelos.processes module
- zelos.scheduler module
- zelos.state module
- zelos.symbol_manager module
- zelos.threads module
- zelos.triggers module
- zelos.util module
Module contents¶
A comprehensive binary emulation platform. <https://github.com/zeropointdynamics/zelos>
-
class
zelos.
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 # verbosity flag set to 1 z = Zelos( "binary_to_emulate" "ARG1", "ARG2", verbosity=1, )
-
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
(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 = 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) → 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 = Zelos("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) → 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 tostart()
.- 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
-
property
main_binary
¶ Returns the parsed main binary, if it exists, otherwise returns None.
-
class
zelos.
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.
-
class
zelos.
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.
-
property
-
class
zelos.
Engine
(config=None, api=None)¶ Bases:
object
-
STACK_SIZE
= 589824¶
-
set_log_level
(log_level)¶
-
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
(timeout=0, swap_threads=True) → Optional[dict]¶ Starts execution of the program at the given offset or entry point.
-
close
() → None¶ Handles the end of the run command
-
-
exception
zelos.
InvalidHookTypeException
¶
-
exception
zelos.
InvalidRegException
¶
-
exception
zelos.
UnsupportedBinaryError
¶
-
exception
zelos.
ZelosLoadException
¶
-
exception
zelos.
ZelosRuntimeException
¶
-
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
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
-
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.