api_qbdipreload.rst

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 qbdi_preload_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 intro_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 intro_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

Return codes

QBDIPRELOAD_NO_ERROR

QBDIPRELOAD_NOT_HANDLED

QBDIPRELOAD_ERR_STARTUP_FAILED

User callbacks

qbdipreload_on_start

qbdipreload_on_premain

qbdipreload_on_main

qbdipreload_on_run

qbdipreload_on_exit

Helpers

qbdipreload_hook_main

qbdipreload_threadCtxToGPRState

qbdipreload_floatCtxToFPRState