Frida/QBDI API

Introduction

We provide bindings for Frida, most C/C++ APIs are exported and available through them, but they are also backed up by plenty of helpers that fluidify the script writing.

Nevertheless, this API slightly differs from the C++ API:

Every callback must be created as a native function. The callback registration can be done through calling VM.newInstCallback(), VM.newVMCallback() and VM.newInstrRuleCallback().
The QBDI class is the equivalent of the VM class we have in the C++ API.

QBDI class

With Frida API, the QBDI object is the equivalent of the VM object in C++ API.

class VM(): Create a new instrumentation virtual machine using “new VM()”

Options

VM.getOptions()

Get the current options of the VM

Returns:: Options – The current option

VM.setOptions(options)

Set the options of the VM

Arguments:

options (Options) – The new options of the VM.

State management

VM.getGPRState()

Obtain the current general register state.

Returns:: GPRState – An object containing the General Purpose Registers state.

VM.getFPRState()

Obtain the current floating point register state.

Returns:: FPRState – An object containing the Floating point Purpose Registers state.

VM.getErrno()

Get the backuped value of errno.

Returns:: Integer – errno

VM.setGPRState(state)

Set the GPR state

Arguments:

state (GPRState) – Array of register values

VM.setFPRState(state)

Set the FPR state

Arguments:

state (FPRState) – Array of register values

VM.setErrno(errno)

Set the backuped value of errno

Arguments:

errno (Integer) – the value to set

Instrumentation range

Addition

VM.addInstrumentedRange(start, end)

Add an address range to the set of instrumented address ranges.

Arguments:

start (String|Number|NativePointer) – Start address of the range (included).
end (String|Number|NativePointer) – End address of the range (excluded).

VM.addInstrumentedModule(name)

Add the executable address ranges of a module to the set of instrumented address ranges.

Arguments:

name (String) – The module’s name.

Returns:

bool – True if at least one range was added to the instrumented ranges.

VM.addInstrumentedModuleFromAddr(addr)

Add the executable address ranges of a module to the set of instrumented address ranges. using an address belonging to the module.

Arguments:

addr (String|Number|NativePointer) – An address contained by module’s range.

Returns:

bool – True if at least one range was removed from the instrumented ranges.

VM.instrumentAllExecutableMaps()

Adds all the executable memory maps to the instrumented range set.

Returns:: bool – True if at least one range was added to the instrumented ranges.

Removal

VM.removeInstrumentedRange(start, end)

Remove an address range from the set of instrumented address ranges.

Arguments:

start (String|Number|NativePointer) – Start address of the range (included).
end (String|Number|NativePointer) – End address of the range (excluded).

VM.removeInstrumentedModule(name)

Remove the executable address ranges of a module from the set of instrumented address ranges.

Arguments:

name (String) – The module’s name.

Returns:

bool – True if at least one range was added to the instrumented ranges.

VM.removeInstrumentedModuleFromAddr(addr:)

Remove the executable address ranges of a module from the set of instrumented address ranges using an address belonging to the module.

Arguments:

addr: (String|Number|NativePointer) – An address contained by module’s range.

Returns:

bool – True if at least one range was added to the instrumented ranges.

VM.removeAllInstrumentedRanges(): Remove all instrumented ranges.

Callback management

Creation

VM.newInstCallback(cbk)

Create a native Instruction callback from a JS function.

Example:

>>> var icbk = vm.newInstCallback(function(vm, gpr, fpr, data) {
>>>   inst = vm.getInstAnalysis();
>>>   console.log("0x" + inst.address.toString(16) + " " + inst.disassembly);
>>>   return VMAction.CONTINUE;
>>> });

Arguments:

cbk (InstCallbackRaw) – an instruction callback (ex: function(vm, gpr, fpr, data) {};)

Returns:

an native InstCallback

VM.newInstrRuleCallback(cbk)

Create a native Instruction rule callback from a JS function.

Example:

>>> var icbk = vm.newInstrRuleCallback(function(vm, ana, data) {
>>>   console.log("0x" + ana.address.toString(16) + " " + ana.disassembly);
>>>   return [new InstrRuleDataCBK(InstPosition.POSTINST, printCB, ana.disassembly)];
>>> });

Arguments:

cbk (InstrRuleCallbackRaw) – an instruction callback (ex: function(vm, ana, data) {};)

Returns:

an native InstrRuleCallback

VM.newVMCallback(cbk)

Create a native VM callback from a JS function.

Example:

>>> var vcbk = vm.newVMCallback(function(vm, evt, gpr, fpr, data) {
>>>   if (evt.event & VMEvent.EXEC_TRANSFER_CALL) {
>>>     console.warn("[!] External call to 0x" + evt.basicBlockStart.toString(16));
>>>   }
>>>   return VMAction.CONTINUE;
>>> });

Arguments:

cbk (VMCallbackRaw) – a VM callback (ex: function(vm, state, gpr, fpr, data) {};)

Returns:

a native VMCallback

InstCallback

VM.addCodeCB(pos, cbk, data, priority)

Register a callback event for a specific instruction event.

Arguments:

pos (InstPosition) – Relative position of the callback (PreInst / PostInst).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.
priority (Int) – The priority of the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

VM.addCodeAddrCB(addr, pos, cbk, data, priority)

Register a callback for when a specific address is executed.

Arguments:

addr (String|Number|NativePointer) – Code address which will trigger the callback.
pos (InstPosition) – Relative position of the callback (PreInst / PostInst).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.
priority (Int) – The priority of the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

VM.addCodeRangeCB(start, end, pos, cbk, data, priority)

Register a callback for when a specific address range is executed.

Arguments:

start (String|Number|NativePointer) – Start of the address range which will trigger the callback.
end (String|Number|NativePointer) – End of the address range which will trigger the callback.
pos (InstPosition) – Relative position of the callback (PreInst / PostInst).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.
priority (Int) – The priority of the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

VM.addMnemonicCB(mnem, pos, cbk, data, priority)

Register a callback event if the instruction matches the mnemonic.

Arguments:

mnem (String) – Mnemonic to match.
pos (InstPosition) – Relative position of the callback (PreInst / PostInst).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.
priority (Int) – The priority of the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

VMEvent

VM.addVMEventCB(mask, cbk, data)

Register a callback event for a specific VM event.

Arguments:

mask (VMEvent) – A mask of VM event type which will trigger the callback.
cbk (VMCallback) – A native VMCallback returned by VM.newVMCallback().
data (Object|null) – User defined data passed to the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

MemoryAccess

VM.addMemAccessCB(type, cbk, data, priority)

Register a callback event for every memory access matching the type bitfield made by the instruction in the range codeStart to codeEnd.

Arguments:

type (MemoryAccessType) – A mode bitfield: either MEMORY_READ, MEMORY_WRITE or both (MEMORY_READ_WRITE).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.
priority (Int) – The priority of the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

VM.addMemAddrCB(addr, type, cbk, data)

Add a virtual callback which is triggered for any memory access at a specific address matching the access type. Virtual callbacks are called via callback forwarding by a gate callback triggered on every memory access. This incurs a high performance cost.

Arguments:

addr (String|Number|NativePointer) – Code address which will trigger the callback.
type (MemoryAccessType) – A mode bitfield: either MEMORY_READ, MEMORY_WRITE or both (MEMORY_READ_WRITE).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

VM.addMemRangeCB(start, end, type, cbk, data)

Add a virtual callback which is triggered for any memory access in a specific address range matching the access type. Virtual callbacks are called via callback forwarding by a gate callback triggered on every memory access. This incurs a high performance cost.

Arguments:

start (String|Number|NativePointer) – Start of the address range which will trigger the callback.
end (String|Number|NativePointer) – End of the address range which will trigger the callback.
type (MemoryAccessType) – A mode bitfield: either MEMORY_READ, MEMORY_WRITE or both (MEMORY_READ_WRITE).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

InstrRuleCallback

VM.addInstrRule(cbk, type, data)

Add a custom instrumentation rule to the VM.

Arguments:

cbk (InstrRuleCallback) – A native InstrRuleCallback returned by VM.newInstrRuleCallback().
type (AnalysisType) – Analyse type needed for this instruction function pointer to the callback
data (Object|null) – User defined data passed to the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

VM.addInstrRuleRange(start, end, cbk, type, data)

Add a custom instrumentation rule to the VM for a range of address.

Arguments:

start (String|Number|NativePointer) – Begin of the range of address where apply the rule
end (String|Number|NativePointer) – End of the range of address where apply the rule
cbk (InstrRuleCallback) – A native InstrRuleCallback returned by VM.newInstrRuleCallback().
type (AnalysisType) – Analyse type needed for this instruction function pointer to the callback
data (Object|null) – User defined data passed to the callback.

Returns:

Number – The id of the registered instrumentation (or VMError.INVALID_EVENTID in case of failure).

Removal

VM.deleteInstrumentation(id)

Remove an instrumentation.

Arguments:

id (Number) – The id of the instrumentation to remove.

Returns:

bool – True if instrumentation has been removed.

VM.deleteAllInstrumentations(): Remove all the registered instrumentations.

Memory management

Allocation

VM.alignedAlloc(size, align)

Allocate a block of memory of a specified sized with an aligned base address.

Arguments:

size (Number) – Allocation size in bytes.
align (Number) – Base address alignement in bytes.

Returns:

Pointer (rword) to the allocated memory or NULL in case an error was encountered.

VM.allocateVirtualStack(state, stackSize)

Allocate a new stack and setup the GPRState accordingly. The allocated stack needs to be freed with alignedFree().

Arguments:

state (GPRState) – Array of register values
stackSize (Number) – Size of the stack to be allocated.

Returns:

Pointer (rword) to the allocated memory or NULL in case an error was encountered.

VM.alignedFree(ptr)

Free a block of aligned memory allocated with alignedAlloc or allocateVirtualStack

Arguments:

ptr (NativePtr) – Pointer to the allocated memory.

Exploration

VM.getModuleNames()

Use QBDI engine to retrieve loaded modules.

Returns:: list of module names (ex: [“ls”, “libc”, “libz”])

Run

VM.run(start, stop)

Start the execution by the DBI from a given address (and stop when another is reached).

Arguments:

start (String|Number|NativePointer) – Address of the first instruction to execute.
stop (String|Number|NativePointer) – Stop the execution when this instruction is reached.

Returns:

bool – True if at least one block has been executed.

VM.call(address, args)

Call a function by its address (or through a Frida NativePointer).

Arguments can be provided, but their types need to be compatible with the .toRword() interface (like NativePointer or UInt64).

Example:

>>> var vm = new VM();
>>> var state = vm.getGPRState();
>>> var stackTopPtr = vm.allocateVirtualStack(state, 0x1000000);
>>> var aFunction = Module.findExportByName(null, "Secret");
>>> vm.addInstrumentedModuleFromAddr(aFunction);
>>> vm.call(aFunction, [42]);
>>> vm.alignedFree(stackTopPtr);

Arguments:

address (String|Number|NativePointer) – function address (or Frida NativePointer).
args (StringArray|NumberArray) – optional list of arguments

VM.switchStackAndCall(address, args, stackSize)

Call a function by its address (or through a Frida NativePointer). QBDI will allocate his one stack to run, while the instrumented code will use the top of the current stack.

Arguments can be provided, but their types need to be compatible with the .toRword() interface (like NativePointer or UInt64).

Example:

>>> var vm = new VM();
>>> var state = vm.getGPRState();
>>> var aFunction = Module.findExportByName(null, "Secret");
>>> vm.addInstrumentedModuleFromAddr(aFunction);
>>> vm.switchStackAndCall(aFunction, [42]);

Arguments:

address (String|Number|NativePointer) – function address (or Frida NativePointer).
args (StringArray|NumberArray) – optional list of arguments
stackSize (String|Number) – stack size for the engine.

VM.simulateCall(state, retAddr, args)

Simulate a call by modifying the stack and registers accordingly.

Arguments:

state (GPRState) – Array of register values
retAddr (String|Number|NativePointer) – Return address of the call to simulate.
args (StringArray|NumberArray) – A variadic list of arguments.

InstAnalysis

VM.getInstAnalysis(type)

Obtain the analysis of the current instruction. Analysis results are cached in the VM. The validity of the returned pointer is only guaranteed until the end of the callback, else a deepcopy of the structure is required.

Arguments:

type (AnalysisType) – Properties to retrieve during analysis (default to ANALYSIS_INSTRUCTION | ANALYSIS_DISASSEMBLY).

Returns:

InstAnalysis – A InstAnalysis() object containing the analysis result.

VM.getCachedInstAnalysis(addr, type)

Obtain the analysis of a cached instruction. Analysis results are cached in the VM. The validity of the returned pointer is only guaranteed until the end of the callback, else a deepcopy of the structure is required.

Arguments:

addr (String|Number|NativePointer) – The address of the instruction to analyse.
type (AnalysisType) – Properties to retrieve during analysis (default to ANALYSIS_INSTRUCTION | ANALYSIS_DISASSEMBLY).

Returns:

InstAnalysis – A InstAnalysis() object containing the analysis result. null if the instruction isn’t in the cache.

MemoryAccess

VM.getInstMemoryAccess()

Obtain the memory accesses made by the last executed instruction. Return NULL and a size of 0 if the instruction made no memory access.

Returns:: Array.<MemoryAccess> – An array of MemoryAccess() made by the instruction.

VM.getBBMemoryAccess()

Obtain the memory accesses made by the last executed sequence. Return NULL and a size of 0 if the basic block made no memory access.

Returns:: Array.<MemoryAccess> – An array of MemoryAccess() made by the sequence.

VM.recordMemoryAccess(type)

Obtain the memory accesses made by the last executed instruction. Return NULL and a size of 0 if the instruction made no memory access.

Arguments:

type (MemoryAccessType) – Memory mode bitfield to activate the logging for: either MEMORY_READ, MEMORY_WRITE or both (MEMORY_READ_WRITE).

Cache management

VM.precacheBasicBlock(pc)

Pre-cache a known basic block.

Arguments:

pc (String|Number|NativePointer) – Start address of a basic block

Returns:

bool – True if basic block has been inserted in cache.

VM.clearCache(start, end)

Clear a specific address range from the translation cache.

Arguments:

start (String|Number|NativePointer) – Start of the address range to clear from the cache.
end (String|Number|NativePointer) – End of the address range to clear from the cache.

VM.clearAllCache(): Clear the entire translation cache.

Register state

class GPRState()

General Purpose Register context

GPRState.dump(color)

Pretty print and log QBDI context.

Arguments:

color (bool) – Will print a colored version of the context if set.

GPRState.getRegister(rid)

This function is used to get the value of a specific register.

Arguments:

rid (String|Number) – Register (register name or ID can be used e.g : “RAX”, “rax”, 0)

Returns:

GPR value (ex: 0x42)

GPRState.getRegisters()

This function is used to get values of all registers.

Returns:: GPRs of current context (ex: {“RAX”:0x42, …})

GPRState.pp(color)

Pretty print QBDI context.

Arguments:

color (bool) – Will print a colored version of the context if set.

Returns:

dump of all GPRs in a pretty format

GPRState.setRegister(rid, value)

This function is used to set the value of a specific register.

Arguments:

rid (String|Number) – Register (register name or ID can be used e.g : “RAX”, “rax”, 0)
value (String|Number) – Register value (use strings for big integers)

GPRState.setRegisters(gprs)

This function is used to set values of all registers.

Arguments:

gprs – Array of register values

GPRState.synchronizeContext(FridaCtx, direction)

This function is used to synchronise context between Frida and QBDI.

Warning

Currently QBDI_TO_FRIDA is not implemented (due to Frida limitations).

Arguments:

FridaCtx – Frida context
direction (SyncDirection) – Synchronization direction. (FRIDA_TO_QBDI or QBDI_TO_FRIDA)

GPRState.synchronizeRegister(FridaCtx, rid, direction)

This function is used to synchronise a specific register between Frida and QBDI.

Warning

Currently QBDI_TO_FRIDA is experimental. (E.G : RIP cannot be synchronized)

Arguments:

FridaCtx – Frida context
rid (String|Number) – Register (register name or ID can be used e.g : “RAX”, “rax”, 0)
direction (SyncDirection) – Synchronization direction. (FRIDA_TO_QBDI or QBDI_TO_FRIDA)

class SyncDirection()

Synchronisation direction between Frida and QBDI GPR contexts

SyncDirection.QBDI_TO_FRIDA: Constant variable used to synchronize QBDI’s context to Frida’s.

Warning

This is currently not supported due to the lack of context updating in Frida.

SyncDirection.FRIDA_TO_QBDI: Constant variable used to synchronize Frida’s context to QBDI’s.

GPR_NAMES: An array holding register names.

REG_PC: String of the instruction pointer register.

REG_RETURN: A constant string representing the register carrying the return value of a function.

REG_SP: String of the stack pointer register.

Callback

InstCallback(vm, gpr, fpr, data)

This is the prototype of a function callback for:

VM.addCodeCB(), VM.addCodeAddrCB() and VM.addCodeRangeCB()
VM.addMnemonicCB()
VM.addMemAccessCB(), VM.addMemAddrCB() and VM.addMemRangeCB()
InstrRuleDataCBK().

The function must be registered with VM.newInstCallback().

Arguments:

vm (QBDI) – The current QBDI object
gpr (GPRState) – The current GPRState
fpr (FPRState) – The current FPRState
data (Object) – A user-defined object.

Returns:

the VMAction() to continue or stop the execution

VMCallback(vm, vmState, gpr, fpr, data)

This is the prototype of a function callback for VM.addVMEventCB(). The function must be registered with VM.newVMCallback().

Arguments:

vm (QBDI) – The current QBDI object
vmState (VMState) – A structure containing the current state of the VM.
gpr (GPRState) – The current GPRState
fpr (FPRState) – The current FPRState
data (Object) – A user-defined object

Returns:

the VMAction() to continue or stop the execution

InstrRuleCallback(vm, ana, data)

This is the prototype of a function callback for VM.addInstrRule() and VM.addInstrRuleRange(). The function must be registered with VM.newInstrRuleCallback().

Arguments:

vm (QBDI) – The current QBDI object
ana (InstAnalysis) – The current QBDI object
data (Object) – A user-defined object

Returns:

An Array of InstrRuleDataCBK()

class InstrRuleDataCBK(pos, cbk, data, priority)

Object to define an InstCallback() in an InstrRuleCallback()

Arguments:

pos (InstPosition) – Relative position of the callback (PreInst / PostInst).
cbk (InstCallback) – A native InstCallback returned by VM.newInstCallback().
data (Object|null) – User defined data passed to the callback.
priority (Int) – The priority of the callback.

class VMAction()

The callback results.

VMAction.CONTINUE: The execution of the basic block continues.

VMAction.SKIP_INST

Available only with PREINST InstCallback. The instruction and the remained PREINST callbacks are skip. The execution continue with the POSTINST instruction.

We recommand to used this result with a low priority PREINST callback in order to emulate the instruction without skipping the POSTINST callback.

VMAction.SKIP_PATCH

Available only with InstCallback. The current instruction and the reminding callback (PRE and POST) are skip. The execution continues to the next instruction.

For instruction that change the instruction pointer (jump/call/ret), BREAK_TO_VM must be used insted of SKIP.

SKIP can break the record of MemoryAccess for the current instruction.

VMAction.BREAK_TO_VM: The execution breaks and returns to the VM causing a complete reevaluation of the execution state. A VMAction.BREAK_TO_VM is needed to ensure that modifications of the Program Counter or the program code are taken into account.

VMAction.STOP: Stops the execution of the program. This causes the run function to return early.

class InstPosition()

Position relative to an instruction.

InstPosition.PREINST: Positioned before the instruction.

InstPosition.POSTINST: Positioned after the instruction.

class CallbackPriority()

Priority of callback

CallbackPriority.PRIORITY_DEFAULT: Default priority for callback.

CallbackPriority.PRIORITY_MEMACCESS_LIMIT: Maximum priority if getInstMemoryAccess is used in the callback.

InstAnalysis

class AnalysisType()

Properties to retrieve during an instruction analysis.

AnalysisType.ANALYSIS_INSTRUCTION: Instruction analysis (address, mnemonic, …).

AnalysisType.ANALYSIS_DISASSEMBLY: Instruction disassembly.

AnalysisType.ANALYSIS_OPERANDS: Instruction operands analysis.

AnalysisType.ANALYSIS_SYMBOL: Instruction nearest symbol (and offset).

class InstAnalysis()

Object that describes the analysis of an instruction

InstAnalysis.address: Instruction address (if ANALYSIS_INSTRUCTION)

InstAnalysis.affectControlFlow: True if instruction affects control flow (if ANALYSIS_INSTRUCTION)

InstAnalysis.disassembly: Instruction disassembly (if ANALYSIS_DISASSEMBLY)

InstAnalysis.instSize: Instruction size (in bytes) (if ANALYSIS_INSTRUCTION)

InstAnalysis.isBranch: True if instruction acts like a ‘jump’ (if ANALYSIS_INSTRUCTION)

InstAnalysis.isCall: True if instruction acts like a ‘call’ (if ANALYSIS_INSTRUCTION)

InstAnalysis.isCompare: True if instruction is a comparison (if ANALYSIS_INSTRUCTION)

InstAnalysis.isPredicable: True if instruction contains a predicate (~is conditional) (if ANALYSIS_INSTRUCTION)

InstAnalysis.isMoveImm: True if this instruction is a move immediate (including conditional moves) instruction (if ANALYSIS_INSTRUCTION)

InstAnalysis.isReturn: True if instruction acts like a ‘return’ (if ANALYSIS_INSTRUCTION)

InstAnalysis.mayLoad: True if QBDI detects a load for this instruction (if ANALYSIS_INSTRUCTION)

InstAnalysis.mayStore: True if QBDI detects a store for this instruction (if ANALYSIS_INSTRUCTION)

InstAnalysis.loadSize: size of the expected read access (if ANALYSIS_INSTRUCTION)

InstAnalysis.storeSize: size of the expected written access (if ANALYSIS_INSTRUCTION)

InstAnalysis.condition: Condition associated with the instruction (if ANALYSIS_INSTRUCTION)

InstAnalysis.mnemonic: LLVM mnemonic (if ANALYSIS_INSTRUCTION)

InstAnalysis.flagsAccess: Flag access type (noaccess, r, w, rw) (if ANALYSIS_OPERANDS)

InstAnalysis.operands: Structure containing analysis results of an operand provided by the VM (if ANALYSIS_OPERANDS)

InstAnalysis.moduleName: Instruction module name (if ANALYSIS_SYMBOL and found)

InstAnalysis.symbolName: Instruction symbol (if ANALYSIS_SYMBOL and found)

InstAnalysis.symbolOffset: Instruction symbol offset (if ANALYSIS_SYMBOL and found)

class ConditionType()

Instruction Condition

ConditionType.CONDITION_NONE: The instruction is unconditionnal

ConditionType.CONDITION_ALWAYS: The instruction is always true

ConditionType.CONDITION_NEVER: The instruction is always false

ConditionType.CONDITION_EQUALS: Equals ( ‘==’ )

ConditionType.CONDITION_NOT_EQUALS: Not Equals ( ‘!=’ )

ConditionType.CONDITION_ABOVE: Above ( ‘>’ unsigned )

ConditionType.CONDITION_BELOW_EQUALS: Below or Equals ( ‘<=’ unsigned )

ConditionType.CONDITION_ABOVE_EQUALS: Above or Equals ( ‘>=’ unsigned )

ConditionType.CONDITION_BELOW: Below ( ‘<’ unsigned )

ConditionType.CONDITION_GREAT: Great ( ‘>’ signed )

ConditionType.CONDITION_LESS_EQUALS: Less or Equals ( ‘<=’ signed )

ConditionType.CONDITION_GREAT_EQUALS: Great or Equals ( ‘>=’ signed )

ConditionType.CONDITION_LESS: Less ( ‘<’ signed )

ConditionType.CONDITION_EVEN: Even

ConditionType.CONDITION_ODD: Odd

ConditionType.CONDITION_OVERFLOW: Overflow

ConditionType.CONDITION_NOT_OVERFLOW: Not Overflow

ConditionType.CONDITION_SIGN: Sign

ConditionType.CONDITION_NOT_SIGN: Not Sign

class OperandAnalysis()

Structure containing analysis results of an operand provided by the VM.

OperandAnalysis.type: Operand type

OperandAnalysis.flag: Operand flag

OperandAnalysis.value: Operand value (if immediate), or register Id

OperandAnalysis.size: Operand size (in bytes)

OperandAnalysis.regOff: Sub-register offset in register (in bits)

OperandAnalysis.regCtxIdx: Register index in VM state

OperandAnalysis.regName: Register name

OperandAnalysis.regAccess: Register access type (r, w, rw)

class OperandType()

Register access type (read / write / rw)

OperandType.OPERAND_INVALID: Invalid operand.

OperandType.OPERAND_IMM: Immediate operand.

OperandType.OPERAND_GPR: General purpose register operand.

OperandType.OPERAND_PRED: Predicate special operand.

OperandType.OPERAND_FPR: Float register operand.

OperandType.OPERAND_SEG: Segment or unsupported register operand

class OperandFlag()

Operand flag

OperandFlag.OPERANDFLAG_NONE: No flag

OperandFlag.OPERANDFLAG_ADDR: The operand is used to compute an address

OperandFlag.OPERANDFLAG_PCREL: The value of the operand is PC relative

OperandFlag.OPERANDFLAG_UNDEFINED_EFFECT: The operand role isn’t fully defined

OperandFlag.OPERANDFLAG_IMPLICIT: The operand is implicit

class RegisterAccessType()

Register access type (read / write / rw)

RegisterAccessType.REGISTER_READ: Register is read.

RegisterAccessType.REGISTER_WRITE: Register is written.

RegisterAccessType.REGISTER_READ_WRITE: Register is read/written.

MemoryAccess

class MemoryAccess()

Object that describes a memory access

MemoryAccess.accessAddress: Address of accessed memory

MemoryAccess.instAddress: Address of instruction making the access

MemoryAccess.size: Size of memory access (in bytes)

MemoryAccess.type: Memory access type (READ / WRITE)

MemoryAccess.value: Value read from / written to memory

MemoryAccess.flags: Memory access flags

class MemoryAccessType()

Memory access type (read / write / …)

MemoryAccessType.MEMORY_READ: Memory read access.

MemoryAccessType.MEMORY_WRITE: Memory write access.

MemoryAccessType.MEMORY_READ_WRITE: Memory read/write access.

class MemoryAccessFlags()

Memory access flags

MemoryAccessFlags.MEMORY_NO_FLAGS: Empty flag.

MemoryAccessFlags.MEMORY_UNKNOWN_SIZE: The size of the access isn’t known.

MemoryAccessFlags.MEMORY_MINIMUM_SIZE: The given size is a minimum size.

MemoryAccessFlags.MEMORY_UNKNOWN_VALUE: The value of the access is unknown or hasn’t been retrived.

VMEvent

class VMEvent()

Events triggered by the virtual machine.

VMEvent.SEQUENCE_ENTRY: Triggered when the execution enters a sequence.

VMEvent.SEQUENCE_EXIT: Triggered when the execution exits from the current sequence.

VMEvent.BASIC_BLOCK_ENTRY: Triggered when the execution enters a basic block.

VMEvent.BASIC_BLOCK_EXIT: Triggered when the execution exits from the current basic block.

VMEvent.BASIC_BLOCK_NEW: Triggered when the execution enters a new (~unknown) basic block.

VMEvent.EXEC_TRANSFER_CALL: Triggered when the ExecBroker executes an execution transfer.

VMEvent.EXEC_TRANSFER_RETURN: Triggered when the ExecBroker returns from an execution transfer.

VMEvent.SYSCALL_ENTRY: Not implemented.

VMEvent.SYSCALL_EXIT: Not implemented.

VMEvent.SIGNAL: Not implemented.

class VMState()

Object that describes the current VM state

VMState.event: The event(s) which triggered the callback (must be checked using a mask: event & BASIC_BLOCK_ENTRY).

VMState.sequenceStart: The current basic block start address which can also be the execution transfer destination.

VMState.sequenceEnd: The current basic block end address which can also be the execution transfer destination.

VMState.basicBlockStart: The current sequence start address which can also be the execution transfer destination.

VMState.basicBlockEnd: The current sequence end address which can also be the execution transfer destination.

VMState.lastSignal: Not implemented.

Other globals

QBDI_LIB_FULLPATH: Fullpath of the QBDI library

class Options()

QBDI VM Options

Options.NO_OPT: Default value

Options.OPT_DISABLE_FPR: Disable all operation on FPU (SSE, AVX, SIMD). May break the execution if the target use the FPU.

Options.OPT_DISABLE_OPTIONAL_FPR: Disable context switch optimisation when the target execblock doesn’t used FPR.

Options.OPT_DISABLE_MEMORYACCESS_VALUE: Don’t load the value when perform memory access.

Options.OPT_DISABLE_ERRNO_BACKUP: Don’t save and restore errno.

Options.OPT_ATT_SYNTAX: Used the AT&T syntax for instruction disassembly (for X86 and X86_64)

Options.OPT_ENABLE_FS_GS: Enable Backup/Restore of FS/GS segment. This option uses the instructions (RD|WR)(FS|GS)BASE that must be supported by the operating system.

class VMError()

Error return by the QBDI VM

VMError.INVALID_EVENTID: Returned event is invalid.

Register values

The size of a general register depends of the architecture. QBDI uses a custom type (rword) to represent a register value.

This binding provides a common interface (.toRword()) to cast values into JS types compatible with the C rword type.

rword: An alias to Frida uint type with the size of general registers (uint64 or uint32)

NativePointer.prototype.toRword(): Convert a NativePointer into a type with the size of a register (Number or UInt64).

Number.prototype.toRword(): Convert a number into a type with the size of a register (Number or UInt64). Can’t be used for numbers > 32 bits would cause weird results due to IEEE-754.

UInt64.prototype.toRword(): An identity function (returning the same UInt64 object). It exists only to provide a unified toRword interface.

Helpers

Some functions helpful to interact with Frida’s interface and write scripts.

hexPointer(ptr)

This function is used to pretty print a pointer, padded with 0 to the size of a register.

Arguments:

ptr – Pointer you want to pad

Returns:

pointer value as padded string (ex: “0x00004242”)