zelos.hooks module¶
-
class
zelos.hooks.
HookInfo
(hook_type, callback, handle, name: str = '', start=None, end=None, end_condition=None)¶ Bases:
object
-
class
zelos.hooks.
HookManager
(z, api)¶ Bases:
object
Manages hooks that allow user code to execute at certain predefined events, such as the creation of threads/process, or the execution of a block of instructions.
-
register_mem_hook
(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.
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. Can be used for deletion.
-
register_exec_hook
(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.
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. Can be used for deletion.
-
register_interrupt_hook
(callback, intno=None, name=None, end_condition=None)¶
-
register_thread_hook
(hook_type, callback, name=None)¶
-
register_process_hook
(hook_type, callback, name=None)¶
-
register_inst_type_hook
(inst_type, callback, name='', start_addr=None, end_addr=None) → zelos.hooks.HookInfo¶
-
register_syscall_hook
(syscall_hook_type, callback, name=None, syscall_name=None) → zelos.hooks.HookInfo¶
-
setup_func_hooks
()¶ This function must be called before function hooks are enabled. It can only be called once the addresses of the imported functions are known.
-
on_entrypoint
(callback)¶ Run callback when the binary has reached it’s entrypoint for the first time.
-
on_main_module_load
(callback)¶ Run callback when the first part of the target module has been loaded into memory.
-
register_func_hook
(func_name: str, callback: Callable[[Zelos], Any], end_condition=None) → zelos.hooks.HookInfo¶ Registers a hook that should execute when an imported function is called.
There are multiple assumptions embedded in this hook. We assume that the pointers to the imported functions will be set at the time the entrypoint is reached. There are certain protections that can be put in place that will get around this, and we may have to update how function hooks are registered for those binaries.
-
register_exception_hook
(callback, name=None) → zelos.hooks.HookInfo¶
-
register_zml_hook
(zml_string: str, closure: Callable[[], Any], name=None) → zelos.hooks.HookInfo¶ Registers a hook that is triggered when a zml string is satisfied.
-
register_close_hook
(closure: Callable[[], Any], name=None) → zelos.hooks.HookInfo¶ Registers a closure that is called before Zelos benignly exits. If Zelos does not exist cleanly, there is no guarantee that hooks registered here will be called.
- Parameters
closure – Called before Zelos exits.
-
delete_hook
(hook_info: zelos.hooks.HookInfo) → None¶ Deletes a hook. Keep in mind that deletion is slightly delayed. If you delete a hook before it has run on the current address, the hook will still run.
- Parameters
hook_info –
-
is_internal_mem_hook
(hook_type)¶
-
-
class
zelos.hooks.
Hooks
(emu, scheduler)¶ Bases:
object
Keeps track of the hooks that are in action.
-
hook_mem_invalid
(uc, access, address, size, value, user_data)¶
-
add_hook
(zelos_hook_type, callback, handle, name=None, start_addr=None, end_addr=None) → None¶ Adds a hook to zebracorn. Depending on the hook type, the callback is triggered at different moments, such as on ever instruction or every basic block. In addition, if you specify an address region, the hook will only run on those addresses. Restricting the addresses that a hook can trigger can result in considerable speedups.
-
del_hook
(name)¶
-
print_active_hooks
()¶
-
-
class
zelos.hooks.
InterruptHooks
(hook_manager, z)¶ Bases:
object
Manages hooks that handle interrupts emitted by the cpu emulator
-
enable
() → None¶ Enables hooks for cpu interrupts across all processes.
-
disable
() → None¶ Disable hooks for cpu interrupts across all processes.
-
register_interrupt_handler
(interrupt_number, handler)¶
-
register_generic_interrupt_handler
(handler)¶
-
register_unhandled_interrupt_handler
(handler)¶
-