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()
andVM.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
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.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:
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 (likeNativePointer
orUInt64
).- 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 (likeNativePointer
orUInt64
).- 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
orQBDI_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
orQBDI_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 withVM.newVMCallback()
.- Arguments:
- Returns:
the
VMAction()
to continue or stop the execution
- InstrRuleCallback(vm, ana, data)
This is the prototype of a function callback for
VM.addInstrRule()
andVM.addInstrRuleRange()
. The function must be registered withVM.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 anInstrRuleCallback()
- 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.
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
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.
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
orUInt64
).
- Number.prototype.toRword()
Convert a number into a type with the size of a register (
Number
orUInt64
). 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”)