1 unstable release

Uses new Rust 2021

0.9.0 Aug 26, 2022

#110 in Build Utils

Download history 34/week @ 2022-08-26 29/week @ 2022-09-02 33/week @ 2022-09-09 25/week @ 2022-09-16 28/week @ 2022-09-23 35/week @ 2022-09-30 29/week @ 2022-10-07 21/week @ 2022-10-14 24/week @ 2022-10-21 22/week @ 2022-10-28 28/week @ 2022-11-04 27/week @ 2022-11-11 25/week @ 2022-11-18 8/week @ 2022-11-25 8/week @ 2022-12-02

72 downloads per month
Used in crochet

BSD-2-Clause

78KB
1.5K SLoC

detour-rs

Azure build Status crates.io version Documentation Language (Rust)

This is a cross-platform detour library developed in Rust. Beyond the basic functionality, this library handles branch redirects, RIP-relative instructions, hot-patching, NOP-padded functions, and allows the original function to be called using a trampoline whilst hooked.

This is one of few cross-platform detour libraries that exists, and to maintain this feature, not all desired functionality can be supported due to lack of cross-platform APIs. Therefore EIP relocation is not supported.

NOTE: Nightly is currently required for static_detour! and is enabled by default.

Platforms

This library provides CI for these targets:

  • Linux
    • i686-unknown-linux-gnu
    • x86_64-unknown-linux-gnu
    • x86_64-unknown-linux-musl
  • Windows
    • i686-pc-windows-gnu
    • i686-pc-windows-msvc
    • x86_64-pc-windows-gnu
    • x86_64-pc-windows-msvc
  • macOS
    • i686-apple-darwin
    • x86_64-apple-darwin

Installation

Add this to your Cargo.toml:

[dependencies]
detour = "0.8.0"

Example

  • A static detour (one of three different detours):
use std::error::Error;
use detour::static_detour;

static_detour! {
  static Test: /* extern "X" */ fn(i32) -> i32;
}

fn add5(val: i32) -> i32 {
  val + 5
}

fn add10(val: i32) -> i32 {
  val + 10
}

fn main() -> Result<(), Box<dyn Error>> {
  // Reroute the 'add5' function to 'add10' (can also be a closure)
  unsafe { Test.initialize(add5, add10)? };

  assert_eq!(add5(1), 6);
  assert_eq!(Test.call(1), 6);

  // Hooks must be enabled to take effect
  unsafe { Test.enable()? };

  // The original function is detoured to 'add10'
  assert_eq!(add5(1), 11);

  // The original function can still be invoked using 'call'
  assert_eq!(Test.call(1), 6);

  // It is also possible to change the detour whilst hooked
  Test.set_detour(|val| val - 5);
  assert_eq!(add5(5), 0);

  unsafe { Test.disable()? };

  assert_eq!(add5(1), 6);
  Ok(())
}
  • A Windows API hooking example is available here; build it by running:
$ cargo build --example messageboxw_detour

Mentions

Part of the library's external user interface was inspired by minhook-rs, created by Jascha-N, and it contains derivative code of his work.

Appendix

  • EIP relocation

    Should be performed whenever a function's prolog instructions are being executed, simultaneously as the function itself is being detoured. This is done by halting all affected threads, copying the affected instructions and appending a JMP to return to the function. This is barely ever an issue, and never in single-threaded environments, but YMMV.

  • NOP-padding

    int function() { return 0; }
    // xor eax, eax
    // ret
    // nop
    // nop
    // ...
    

    Functions such as this one, lacking a hot-patching area, and too small to be hooked with a 5-byte jmp, are supported thanks to the detection of code padding (NOP/INT3 instructions). Therefore the required amount of trailing NOP instructions will be replaced, to make room for the detour.

Dependencies

~320–550KB
~13K SLoC