Events module

Instrumenting the engine with event hooks.

Contents

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.