QBDIPreload API
Introduction
QBDIPreload is a small utility library that provides code injection capabilities using dynamic
library injection. It currently only works under Linux using the LD_PRELOAD mechanism and
macOS using the DYLD_INSERT_LIBRARIES mechanism. For other platforms please check out
Frida/QBDI API instead.
QBDIPreload exploits these library injection mechanisms to hijack the normal program startup.
During the hijacking process QBDIPreload will call your code allowing you to setup and start
your instrumentation. The compilation should produce a dynamic library (.so under Linux,
.dylib under macOS) which should then be added to the matching environment variable
(LD_PRELOAD under Linux and DYLD_INSERT_LIBRARIES under macOS) when running the
target binary.
You can look at Generate a template for a working example with build and usage instructions.
Note
QBDIPreload automatically takes care of blacklisting instrumentation of the C standard library and the OS loader as described in Limitations.
Note
Please note that QBDIPreload does not allow instrumenting a binary before the main function (inside the loader and the library constructors / init) as explained in Limitations.
Note
QBDIPreload is supposed to be used with LD_PRELOAD or DYLD_INSERT_LIBRARIES mechanisms to inject some code into the target
process. Hence, the limitations of these also affect QBDIPreload (cannot inject suid binary, …).
Initialisation
-
QBDIPRELOAD_INIT
A C pre-processor macro declaring a constructor.
Warning
QBDIPRELOAD_INITmust be used once in any project using QBDIPreload. It declares a constructor, so it must be placed like a function declaration on a single line.
Return codes
-
QBDIPRELOAD_NO_ERROR
No error.
-
QBDIPRELOAD_NOT_HANDLED
Startup step not handled by callback.
-
QBDIPRELOAD_ERR_STARTUP_FAILED
Error in the startup (preload) process.
User callbacks
-
int qbdipreload_on_start(void *main)
Function called when preload is on a program entry point (interposed start or an early constructor). It provides the main function address, that can be used to place a hook using the
qbdipreload_hook_mainAPI.- Parameters
main – [in] Address of the main function
- Returns
int QBDIPreload state
-
int qbdipreload_on_premain(void *gprCtx, void *fpuCtx)
Function called when preload hook on main function is triggered. It provides original (and platforms dependent) GPR and FPR contexts. They can be converted to QBDI states, using
qbdipreload_threadCtxToGPRStateandqbdipreload_floatCtxToFPRStateAPIs.- Parameters
gprCtx – [in] Original GPR context
fpuCtx – [in] Original FPU context
- Returns
int QBDIPreload state
-
int qbdipreload_on_main(int argc, char **argv)
Function called when preload has successfully hijacked the main thread and we are in place of the original main function (with the same thread state).
- Parameters
argc – [in] Original argc
argv – [in] Original argv
- Returns
int QBDIPreload state
-
int qbdipreload_on_run(VMInstanceRef vm, rword start, rword stop)
Function called when preload is done and we have a valid QBDI VM object on which we can call run (after some last initializations).
- Parameters
vm – [in] VM instance.
start – [in] Start address of the range (included).
stop – [in] End address of the range (excluded).
- Returns
int QBDIPreload state
-
int qbdipreload_on_exit(int status)
Function called when process is exiting (using
_exitorexit).- Parameters
status – [in] exit status
- Returns
int QBDIPreload state
Helpers
-
int qbdipreload_hook_main(void *main)
Enable QBDIPreload hook on the main function (using its address)
Warning
It MUST be used in
qbdipreload_on_startif you want to handle this step. The assumedmainaddress is provided as a callback argument.- Parameters
main – [in] Pointer to the main function