qbdi-rs

Rust bindings for QuarkslaB Dynamic binary Instrumentation (QBDI).

Introduction

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.

This crate provides Rust bindings to the QBDI C/C++ API, allowing Rust programs to use QBDI's powerful binary instrumentation capabilities.

Features

• Safe Rust wrappers around QBDI's API
• Ergonomic API design following Rust idioms
• Support for callbacks, memory instrumentation, and execution control
• Cross-platform and cross-architecture support:
  • Architectures: x86_64, AArch64, ARM
  • Platforms: Linux, macOS, Windows, Android, iOS

Supported Targets

Usage

Add this to your Cargo.toml:

[dependencies]
qbdi-rs = "0.1.0"

For specific architecture support, you can enable the corresponding features:

[dependencies]
qbdi-rs = { version = "0.1.0", features = ["android", "aarch64"] }

Available features:

• std (default): Use Rust's standard library
• x86_64: Enable x86_64 architecture specific optimizations
• aarch64: Enable AArch64 architecture specific optimizations
• arm: Enable ARM architecture specific optimizations
• android: Android platform support
• frida_binding: Enable Frida integration

Example

use qbdi::{VM, VMOptions, InstPosition, VMEvent};

fn main() {
    // Create a VM instance with default options
    let mut vm = VM::new(VMOptions::default());
    
    // Add a simple instruction callback
    vm.add_code_cb(InstPosition::PREINST, |vm_state| {
        println!("Executing instruction at 0x{:x}", vm_state.gpr().get_pc());
        VMEvent::CONTINUE
    });

    // Example buffer of code to execute (architecture-specific)
    // This example uses x86_64 machine code
    let code = vec![0x90, 0x90, 0x90, 0xc3]; // NOP, NOP, NOP, RET
    
    // Allocate and instrument the code
    let address = vm.allocate_and_instrument(&code);
    
    // Run the instrumented code
    vm.run(address, 0).expect("Execution failed");
}

Building for Different Architectures

The project includes helper scripts to build for different architectures:

For Android

# Setup environment variables
export NDK_HOME=/path/to/android/ndk
export ANDROID_API_LEVEL=21

# Build for different Android architectures
./build-multi-arch.sh --android  # Builds for all supported Android architectures
./build-multi-arch.sh --release  # Build release version

For iOS (requires macOS)

./build-multi-arch.sh --ios

For All Platforms

./build-multi-arch.sh --all

Documentation

For more detailed documentation, refer to:

• QBDI documentation
• API documentation: cargo doc --open

Development

Building from Source

# Clone the repository
git clone https://github.com/yourusername/qbdi-rs.git
cd qbdi-rs

# Build for the host platform
cargo build

# Run tests
cargo test

# Build and run examples
cargo run --example simple_test

Publishing to crates.io

Before publishing, make sure all tests pass on all supported platforms:

# Test on host platform
cargo test

# Test on different architectures if possible
./build-multi-arch.sh --all

# Publish to crates.io
cargo publish

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.