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:

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

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

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_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”)