Callback Mechanism

The whole interaction from tritondse with the user-written code is performed through the callback mechanism. Most callbacks does not expect return values but provides as argument all necessary variables which enable changing the state of the execution. Events that can be caught are:

address reached
instruction executed (all of them)
memory address read or written
register read or written
function reached (from its name)
end of an execution
thread context switch
specific instruction mnemonic (e.g: SYSENTER)
specific instruction bytes
new input creation (before it gets appended in the pool of seeds)
memory exception (access invalid memory map or with invalid permissions)

Only the new input creation, accept a modified input as return value. That enable post-processing an input just before it enter the pool of seeds. That is especially useful to recompute some fields etc.

CallbackManager

All callbacks are meant to be registered on the CallbackManager. That object managed by SymbolicExplorator will be transmitted to every SymbolicExecutor which will then be able to to catch all events. In such context, callbacks will be triggered indifferently from any execution. A user willing to do per-execution operation shall register an end of execution to catch to switch from on execution to the other.

class tritondse.callbacks.CallbackManager[source]

Class used to aggregate all callbacks that can be plugged inside a SymbolicExecutor running session. The internal structure ensure that check the presence of callback can be made in Log(N). All callbacks are designed to be read-only

bind_to(se: SymbolicExecutor) → None[source]

Bind callbacks on the given process state. That step is required to register callbacks on the Triton Context object. This is also used to keep a reference on the SymbolicExecutor object;

IMPORTANT You MUST call unbind once you finish using the SymbolicExecutor.

Parameters:: se (SymbolicExecutor) – SymbolicExecutor on which to bind callbacks

fork() → CallbackManager[source]

Fork the current CallbackManager in a new object instance (that will be unbinded). That method is used by the SymbolicExplorator to ensure each SymbolicExecutor running concurrently will have their own instance off the CallbackManager.

Returns:: Fresh instance of CallbackManager
Return type:: CallbackManager

get_address_callbacks(addr: tritondse.types.Addr) → Tuple[List[tritondse.callbacks.AddrCallback], List[tritondse.callbacks.AddrCallback]][source]

Get all the pre/post callbacks for a given address.

Parameters:: addr (tritondse.types.Addr) – Address where to trigger the callback
Returns:: tuple of lists containing callback functions for pre/post respectively

get_context_switch_callback() → List[tritondse.callbacks.ThreadCallback][source]

Get the list of all function callback to call when thread is being scheduled.

Returns:: List of callbacks defined when thread is being scheduled

get_execution_callbacks() → Tuple[List[tritondse.callbacks.SymExCallback], List[tritondse.callbacks.SymExCallback]][source]

Get all the pre/post callbacks for the current symbolic execution.

Returns:: tuple of lists containing callback functions for pre/post respectively

get_exploration_step_callbacks() → List[ExplorationStepCallback][source]

Get all the exploration step callbacks

Returns:: list containing callbacks

get_imported_routine_callbacks(routine_name: str) → Tuple[List[tritondse.callbacks.RtnCallback], List[tritondse.callbacks.RtnCallback]][source]

Get the list of all callbacks for an imported routine

Parameters:: routine_name – the routine name
Returns:: Tuple of list of callbacks (for pre and post)

get_instruction_callbacks() → Tuple[List[tritondse.callbacks.InstrCallback], List[tritondse.callbacks.InstrCallback]][source]

Get all the pre/post callbacks for instructions.

Returns:: tuple of lists containing callback functions for pre/post respectively

get_memory_violation_callbacks() → List[MemoryViolationCallback][source]

Get all memory violation callbacks.

Returns:: list of memory violation callbacks

get_mnemonic_callbacks(mnemonic: OPCODE) → Tuple[List[MnemonicCallback], List[MnemonicCallback]][source]

Get all the pre/post callbacks for a given mnemonic.

Parameters:: mnemonic (OPCODE) – Mnemonic where to trigger the callback
Returns:: tuple of lists containing callback functions for pre/post respectively

get_new_input_callback() → List[tritondse.callbacks.NewInputCallback][source]

Get the list of all function callback to call when a new input is generated by SMT.

Returns:: List of callbacks to call on input generation

get_on_branch_covered_callback() → List[BranchCoveredCallback][source]

Get the list of all function callbacks to call when a branch is about to be solved.

Returns:: List of callbacks to call on branch covered

get_on_solving_callback() → List[SymExSolvingCallback][source]

Get the list of all function callbacks to call when a branch is about to be solved.

Returns:: List of callbacks to call on branch solving

get_opcode_callbacks(opcode: bytes) → Tuple[List[OpcodeCallback], List[OpcodeCallback]][source]

Get all the pre/post callbacks for a given opcode.

Parameters:: opcode (bytes) – Opcode where to trigger the callback
Returns:: tuple of lists containing callback functions for pre/post respectively

is_binded() → bool[source]

Check if the callback manager has already been bound on a given process state.

Returns:: True if callbacks are bound on a process state

is_empty() → bool[source]

Check whether a callback has already been registered or not

Returns:: True if no callback were registered

register_addr_callback(pos: CbPos, addr: tritondse.types.Addr, callback: tritondse.callbacks.AddrCallback) → None[source]

Register a callback function on a given address before or after the execution of the associated instruction.

Parameters:

pos (CbPos) – When to trigger the callback (before or after) execution of the instruction
addr (tritondse.types.Addr) – Address where to trigger the callback
callback (tritondse.callbacks.AddrCallback) – callback function

register_exploration_step_callback(callback: ExplorationStepCallback) → None[source]

Register a callback executed before each exploration step. The object given in parameter is the SymbolicExplorator itself.

Parameters:: callback (tritondse.callbacks.ExplorationStepCallback) – Callback function to trigger

register_function_callback(func_name: str, callback: tritondse.callbacks.AddrCallback) → None[source]

Register a callback on the address of the given function name. The function name is only resolve when the callback manager is bound to a SymbolicExecutor.

Parameters:

func_name (str) – Function name
callback (tritondse.callbacks.AddrCallback) – callback function

register_instruction_callback(pos: CbPos, callback: tritondse.callbacks.InstrCallback) → None[source]

Register a callback triggered on each instruction executed, before or after its side effects have been applied to ProcessState.

Parameters:

pos (CbPos) – before, after execution of the instruction
callback (tritondse.callbacks.InstrCallback) – callback function to trigger

register_memory_read_callback(callback: tritondse.callbacks.MemReadCallback) → None[source]

Register a callback that will be triggered by any read in the concrete memory of the process state.

Parameters:: callback (tritondse.callbacks.MemCallback) – Callback function to be called

register_memory_violation_callback(callback: MemoryViolationCallback) → None[source]

Register a callback function called when a memory violation occurred during the emulation.

Parameters:: callback (tritondse.callbacks.MemoryViolationCallback) – callback function

register_memory_write_callback(callback: tritondse.callbacks.MemWriteCallback) → None[source]

Register a callback called on each write in the concrete memory state of the process.

Parameters:: callback (tritondse.callbacks.MemCallback) – Callback function to be called

register_mnemonic_callback(pos: CbPos, mnemonic: OPCODE, callback: MnemonicCallback) → None[source]

Register a callback function on a given mnemonic before or after the execution of the associated instruction.

Parameters:

pos (CbPos) – When to trigger the callback (before or after) execution of the instruction
mnemonic (OPCODE) – Mnemonic where to trigger the callback
callback (tritondse.callbacks.MnemonicCallback) – callback function

register_new_input_callback(callback: tritondse.callbacks.NewInputCallback) → None[source]

Register a callback function called when the SMT solver find a new model namely a new input. This callback is called before any treatment on the input (worklist, etc.). It thus allows to post-process the input before it getting put in the queue.

Parameters:: callback (tritondse.callbacks.NewInputCallback) – callback function

register_on_branch_covered_callback(callback: BranchCoveredCallback) → None[source]

Register a callback function called when a branch covered. This callback is called after the branch is solved.

Parameters:: callback (tritondse.callbacks.BranchCoveredCallback) – callback function

register_on_solving_callback(callback: SymExSolvingCallback) → None[source]

Register a callback function called when a branch is about to be solved. This callback is called before the branch is solved and will use the result of the callback to go ahead with the solving or skip it.

Parameters:: callback (tritondse.callbacks.BranchSolvingCallback) – callback function

register_opcode_callback(pos: CbPos, opcode: bytes, callback: OpcodeCallback) → None[source]

Register a callback function on a given opcode before or after the execution of the associated instruction.

Parameters:

pos (CbPos) – When to trigger the callback (before or after) execution of the instruction
opcode (bytes) – Opcode where to trigger the callback
callback (tritondse.callbacks.OpcodeCallback) – callback function

register_post_addr_callback(addr: tritondse.types.Addr, callback: tritondse.callbacks.AddrCallback) → None[source]

Register post-address callback. Equivalent to register a pre-address on the return site. (assume the function returns)

Parameters:

addr (tritondse.types.Addr) – Address where to trigger the callback
callback (tritondse.callbacks.AddrCallback) – callback function

register_post_execution_callback(callback: tritondse.callbacks.SymExCallback) → None[source]

Register a callback executed after program loading, registers and memory initialization. Thus, this callback is called after executing upon program exit (or crash)

Parameters:: callback (tritondse.callbacks.SymExCallback) – Callback function to trigger

register_post_imported_routine_callback(routine_name: str, callback: tritondse.callbacks.RtnCallback) → None[source]

Register a callback, called after the call to imported routines.

Parameters:

routine_name – the routine name
callback (tritondse.callbacks.RtnCallback) – callback function

register_post_instruction_callback(callback: tritondse.callbacks.InstrCallback) → None[source]

Register a post-execution callback on all instruction executed by the engine.

Parameters:: callback (tritondse.callbacks.InstrCallback) – callback function to trigger

register_post_mnemonic_callback(mnemonic: OPCODE, callback: MnemonicCallback) → None[source]

Register post-mnemonic callback.

Parameters:

mnemonic (OPCODE) – Mnemonic where to trigger the callback
callback (tritondse.callbacks.MnemonicCallback) – callback function

register_post_opcode_callback(opcode: bytes, callback: OpcodeCallback) → None[source]

Register post-opcode callback.

Parameters:

opcode (bytes) – Opcode where to trigger the callback
callback (tritondse.callbacks.OpcodeCallback) – callback function

register_pre_addr_callback(addr: tritondse.types.Addr, callback: tritondse.callbacks.AddrCallback) → None[source]

Register pre address callback

Parameters:

addr (tritondse.types.Addr) – Address where to trigger the callback
callback (tritondse.callbacks.AddrCallback) – callback function

register_pre_execution_callback(callback: tritondse.callbacks.SymExCallback) → None[source]

Register a callback executed after program loading, registers and memory initialization. Thus, this callback is called just before executing the first instruction.

Parameters:: callback (tritondse.callbacks.SymExCallback) – Callback function to trigger

register_pre_imported_routine_callback(routine_name: str, callback: tritondse.callbacks.RtnCallback) → None[source]

Register a callback before call to an imported routines

Parameters:

routine_name – the routine name
callback (tritondse.callbacks.RtnCallback) – callback function

register_pre_instruction_callback(callback: tritondse.callbacks.InstrCallback) → None[source]

Register a pre-execution callback on all instruction executed by the engine.

Parameters:: callback (tritondse.callbacks.InstrCallback) – callback function to trigger

register_pre_mnemonic_callback(mnemonic: OPCODE, callback: MnemonicCallback) → None[source]

Register pre-mnemonic callback.

Parameters:

mnemonic (OPCODE) – Mnemonic where to trigger the callback
callback (tritondse.callbacks.MnemonicCallback) – callback function

register_pre_opcode_callback(opcode: bytes, callback: OpcodeCallback) → None[source]

Register pre-opcode callback.

Parameters:

opcode (bytes) – Opcode where to trigger the callback
callback (tritondse.callbacks.OpcodeCallback) – callback function

register_probe(probe: ProbeInterface) → None[source]

Register a probe. That function will iterate the cbs attribute of the object, and will register each entry in self.

Warning

Does not implement all CbType

Parameters:: probe (ProbeInterface) – a probe interface

register_register_read_callback(callback: tritondse.callbacks.RegReadCallback) → None[source]

Register a callback on each register read during the symbolic execution.

Parameters:: callback (tritondse.callbacks.RegReadCallback) – Callback function to be called

register_register_write_callback(callback: tritondse.callbacks.RegWriteCallback) → None[source]

Register a callback on each register write during the symbolic execution.

Parameters:: callback (tritondse.callbacks.RegReadCallback) – Callback function to be called

register_thread_context_switch_callback(callback: tritondse.callbacks.ThreadCallback) → None[source]

Register a callback triggered upon each thread context switch during the execution.

Parameters:: callback (tritondse.callbacks.ThreadCallback) – Callback to be called

reset() → None[source]: Reset all callbacks :return:

unbind() → None[source]: Unbind callbacks from the current process state as well as from the Triton Context object.

unregister_callback(callback: Callable) → None[source]

Unregister the given callback from the manager.

Parameters:: callback – callback to remove
Returns:: None

Auxiliary enumerate:

class tritondse.callbacks.CbPos(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Enums representing callback position

AFTER = 2

BEFORE = 1

Probe Interface

The ProbeInteface is a very simple mechanism to register multiple callbacks all at once by subclassing the interface. This interface expect a local attriubte cbs containing callback related informations.

class tritondse.callbacks.ProbeInterface[source]

The Probe interface

property callbacks: List[Tuple[CbType, Callable, Any | None]]

Auxiliary enums:

class tritondse.callbacks.CbType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Enums representing all kind of callbacks

BRANCH_COV = 20

CTX_SWITCH = 1

EXPLORE_STEP = 15

MEMORY_READ = 2

MEMORY_WRITE = 3

MEM_VIOLATION = 22

NEW_INPUT = 14

POST_ADDR = 5

POST_EXEC = 6

POST_INST = 7

POST_MNEM = 17

POST_OPCODE = 19

POST_RTN = 4

PRE_ADDR = 8

PRE_EXEC = 9

PRE_INST = 10

PRE_MNEM = 16

PRE_OPCODE = 18

PRE_RTN = 11

REG_READ = 12

REG_WRITE = 13

SYMEX_SOLVING = 21

Callback signatures

tritondse.callbacks.AddrCallback: alias of Callable[[SymbolicExecutor, ProcessState, int], None]

tritondse.callbacks.BranchCoveredCallback: alias of Callable[[SymbolicExecutor, ProcessState, Tuple[int, int]], bool]

tritondse.callbacks.ExplorationStepCallback: alias of Callable[[SymbolicExplorator], None]

tritondse.callbacks.InstrCallback: alias of Callable[[SymbolicExecutor, ProcessState, Instruction], None]

tritondse.callbacks.MemoryViolationCallback: alias of Callable[[SymbolicExecutor, ProcessState, MemoryAccessViolation], None]

tritondse.callbacks.MemReadCallback: alias of Callable[[SymbolicExecutor, ProcessState, MemoryAccess], None]

tritondse.callbacks.MemWriteCallback: alias of Callable[[SymbolicExecutor, ProcessState, MemoryAccess, int], None]

tritondse.callbacks.MnemonicCallback: alias of Callable[[SymbolicExecutor, ProcessState, OPCODE], None]

tritondse.callbacks.NewInputCallback: alias of Callable[[SymbolicExecutor, ProcessState, Seed], Seed | None]

tritondse.callbacks.OpcodeCallback: alias of Callable[[SymbolicExecutor, ProcessState, bytes], None]

tritondse.callbacks.RegReadCallback: alias of Callable[[SymbolicExecutor, ProcessState, Register], None]

tritondse.callbacks.RegWriteCallback: alias of Callable[[SymbolicExecutor, ProcessState, Register, int], None]

tritondse.callbacks.RtnCallback: alias of Callable[[SymbolicExecutor, ProcessState, str, int], int | Expression | None]

tritondse.callbacks.SymExCallback: alias of Callable[[SymbolicExecutor, ProcessState], None]

tritondse.callbacks.SymExSolvingCallback: alias of Callable[[SymbolicExecutor, ProcessState, Tuple[int, int], SymExType, AstNode, List[AstNode]], bool]

tritondse.callbacks.ThreadCallback: alias of Callable[[SymbolicExecutor, ProcessState, ThreadContext], None]