Instrumenting the engine with event hooks.
The MaatEngine can instrument emulated code with event hooks. Hooks can be placed on events such as register access, memory access, branch operation, etc. The complete list of available events is given by the event::
Hooks can be placed either before or after the event occurs.
Event hooks usually come with one or several user defined callbacks: those are functions that are executed automatically everytime the hook is triggered. Callbacks must return an action for the engine:
- event::Action::CONTINUE: continue to execute code
- event::Action::HALT: stop executing code
Action:: ERROR: indicates that a fatal error happended in the callback and that the engine should abort execution
Note that hooks set with no callbacks at all will always halt execution, just as if they had a callback returning event::Action::HALT.
A hook is optionally identified by a unique name, which can be used to enable or disable it at will. Hooks can also belong to a "group" (also identified by a unique name) allowing to enable or disable multiple hooks simultaneously.
- class maat::event::EventCallback
- A callback to be executed on an event.
- class maat::event::AddrFilter
- Filter addresses to monitor.
- class maat::event::EventHook
- Generic hook base.
- class maat::event::EventManager
- The event manager holds all hooks that have been set in the engine. It allows to add/remove/enable/disable hooks. It also serves as an interface to check whether hooks should be triggered or not given the current executed instruction.
- auto is_reg_event(event::Event event) -> bool
- Return true if event is Event::REG_R, Event::REG_W, Event::REG_RW.
- auto is_mem_event(event::Event event) -> bool
- Return true if event is Event::MEM_R, Event::MEM_W, or Event::MEM_RW.
- auto is_simple_event(event::Event event) -> bool
- Return true if event neither a Event::REG_ nor a Event::MEM_ nor an Event::ADDR event.
- auto is_exec_event(event::Event event) -> bool
- Return true if event is Event::EXEC.
❱ Enum documentation
enum class Event
Events on which a hook can be triggered.
Executing an instruction in a given address range.
Read a given register.
Write a given register.
A combinaison of Event::REG_R and Event::REG_W.
Reading memory in a given address range.
Writing memory in a given address range.
A combinaison of Event::MEM_R and Event::MEM_W.
Executing a branch operation (conditional or absolute)
Encountering a path constraint (conditional branch with symbolic/concolic condition)