Events module

Instrumenting the engine with event hooks.

Reference
- Classes
- Enums
- Functions

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::Event enum class.

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
event::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.

❱ Classes

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.

❱ Enums

enum class Event { EXEC, REG_R, REG_W, REG_RW, MEM_R, MEM_W, MEM_RW, BRANCH, PATH, NONE }: Events on which a hook can be triggered.
enum class When { BEFORE, AFTER }
enum class Action { CONTINUE, HALT, ERROR }: Action returned by hook callbacks for the execution engine.

❱ Functions

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.

Enumerators
EXEC	Executing an instruction in a given address range.
REG_R	Read a given register.
REG_W	Write a given register.
REG_RW	A combinaison of Event::REG_R and Event::REG_W.
MEM_R	Reading memory in a given address range.
MEM_W	Writing memory in a given address range.
MEM_RW	A combinaison of Event::MEM_R and Event::MEM_W.
BRANCH	Executing a branch operation (conditional or absolute)
PATH	Encountering a path constraint (conditional branch with symbolic/concolic condition)
NONE

enum class When

An enum indicating when callbacks must be triggered

Enumerators
BEFORE	Trigger callbacks before processing the associated event.
AFTER	Trigger callbacks after processing the associated event.

enum class Action

Action returned by hook callbacks for the execution engine.

Enumerators
CONTINUE	Continue execution.
HALT	Stop execution.
ERROR	An error occured within the callback.