QBDI Documentation

QuarkslaB Dynamic binary Instrumentation (QBDI) is a modular, cross-platform and cross-architecture DBI framework. It aims to support Linux, macOS, Android, iOS and Windows operating systems running on x86, x86-64, ARM and AArch64 architectures. Information about what is a DBI framework and how QBDI works can be found in the user documentation introduction (Introduction).

QBDI modularity means it doesn’t contain a preferred injection method and it is designed to be used in conjunction with an external injection tool. QBDI includes a tiny (LD_PRELOAD based) Linux and macOS injector for dynamic executables (QBDIPreload), which acts as the foundation for our Python bindings (pyQBDI). QBDI is also fully integrated with Frida, a reference dynamic instrumentation toolkit, allowing anybody to use their combined powers.

x86-64 support is mature (even if SIMD memory access are not yet reported). ARM architecture is a work in progress but already sufficient to execute simple CLI program like ls or cat. x86 and AArch64 are planned, but currently unsupported.

A current limitation is that QBDI doesn’t handle signals, multithreading (it doesn’t deal with new threads creation) and C++ exception mechanisms. However, those system-dependent features will probably not be part of the core library (KISS), and should be integrated as a new layer (to be determined how).

CPU Operating Systems Execution Memory Access Information
x86-64 Linux, macOS, Windows Supported Partial (only non SIMD)
ARM Linux, Android, iOS Partial Unsupported
AArch64 Linux, Android Unsupported Unsupported
x86 Linux, macOS, Windows Unsupported Unsupported

Changelog

2017-12-22 Cedric TESSIER <ctessier@quarkslab.com>

  • Version 0.5
  • Official public release!

2017-12-10 Cedric TESSIER <ctessier@quarkslab.com>

  • Version 0.5 RC3
  • Introducing pyqbdi, full featured python bindings based on QBDIPreload library
  • Revising variadic API to include more friendly prototypes
  • Various bug, compilation and documentation fixes

2017-10-30 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.5 RC2
  • Apache 2 licensing
  • New QBDIPreload library for easier dynamic injection under linux and macOS
  • Various bug, compilation and documentation fixes
  • Big tree cleanup

2017-10-09 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.5 RC1
  • New Frida bindings
  • Upgrade to LLVM 5.0
  • Support for AVX registers
  • New callback helpers on mnemonics and memory accesses
  • Basic block precaching API
  • Automatic cache invalidation when a new instrumentation is added
  • Instruction and sequence level cache avoids needless retranslation
  • Upgrade of the validator which now supports Linux and macOS

2017-01-06 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.4
  • Basic Instruction Shadows concept
  • Memory access PatchDSL statements with support under X86_64 (non SIMD memory access only)
  • Shadow based memory access API and instrumentation
  • C and C++ API stabilization
  • Out-of-tree build and SDK
  • Overhaul of the entire documentation with a complete PatchDSL explanation and a split between user and developper documentation.

2016-04-29 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.3
  • Partial ARM support, sufficient to run simple program e.g cat, ls, …
  • Instrumentation filtering system, ExecBroker, allowing the engine to switch between non instrumented and instrumented execution
  • Complex execution validation system under linux which allows to do instruction per instruction compared execution between a non instrumented and an instrumented instance of a program
  • New callback system for Engine related event e.g basic block entry / exit, ExecBroker transfer / return.
  • New (internal) logging system, LogSys, which allows to do priority and tag based filtering of the debug logs.

2016-01-29 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.2
  • Upgrade to LLVM 3.7
  • Complete X86_64 patching support
  • Support of Windows X86_64
  • Basic callback based instrumentation
  • Usable C++ and C API
  • User documentation with examples
  • Uniformisation of PatchDSL

2015-10-09 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.1
  • Ported the PatchDSL from the minijit PoC
  • Corrected several design flaws in the PatchDSL
  • Implemented a comparated execution test setup to prove the execution via the JIT yields the same registers and stack state as a normal execution
  • Basic patching working for ARM and X86_64 architectures as shown by the compared execution tests

2015-09-17 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.0
  • Working dependency system for LLVM and Google Test
  • ExecBlock working and tested on linux-X86_64, linux-ARM, android-ARM and macOS-X86_64
  • Deployed buildbot infrastructure for automated build and test on linux-X86_64 and linux-ARM

Indices and Tables