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

Status

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

stable

https://travis-ci.com/QBDI/QBDI.svg?branch=master https://ci.appveyor.com/api/projects/status/s2qvpu8k8yiau647/branch/master?svg=true

dev

https://travis-ci.com/QBDI/QBDI.svg?branch=dev-next https://ci.appveyor.com/api/projects/status/s2qvpu8k8yiau647/branch/dev-next?svg=true

Changelog

2018-10-19 Cedric TESSIER <ctessier@quarkslab.com>

  • Version 0.6.2
  • Add support for a public CI (based on Travis and AppVeyor)
  • Fix instruction operands analysis (#57, #59)
  • Add missing MEMORY_READ enum value in Python bindings (#61)
  • Fix cache misbehavior on corner cases (#49, #51)
  • Add missing memory access instructions on x86_64 (#45, #47, #72)
  • Enable asserts in Debug builds (#48)

2018-03-22 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.6.1
  • Fixing a performance regression with the addCodeAddrCB (#42): Since 0.6, this API would trigger a complete cache flush forcing the engine to regenerate all the instrumented code after each call. Since this API is used inside VM:run(), this had the effect of completely canceling precaching optimization where used.
  • Fixing support for AVX host without AVX2 support (#19): Context switching was wrongly using AVX2 instructions instead of AVX instructions causing segfaults under hosts supporting AVX but not AVX2.

2018-03-02 Charles HUBAIN <chubain@quarkslab.com>

  • Version 0.6
  • Important performance improvement in the core engine (#30) This slightly changes the behavior of VMEvents.
  • Fix the addCodeAddrCB API (#37)
  • atexit and getCurrentProcessMap in python bindings (#35)
  • Fix getInstAnalysis on BASIC_BLOCK_ENTRY (#28)
  • Various documentation improvements (#34, #37, #38, #40) and an API uniformisation (#29)

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