Crate detour [−] [src]
A cross-platform detour library written in Rust.
Intro
This library provides a thread-safe, inline detouring functionality by disassembling and patching functions during runtime, using assembly opcodes allocated within executable memory. It modifies the target functions and replaces their prolog with an unconditional jump.
Beyond the basic functionality this library handles several different edge cases:
- Relative branches.
- RIP relative operands.
- Detects NOP-padding.
- Relay for large offsets (>2GB)
- Supports hot patching.
Detours
Three different types of detours are provided:
Generic: A type-safe interface — the same prototype is enforced for both the target and the detour.
It is also enforced when invoking the original target.Static: A static & type-safe interface. Thanks to its static nature it can accept a closure as its second argument, but on the other hand, it can only have one detour active at a time.
Raw: The underlying building block that the others types abstract upon. It has no type-safety and interacts with raw pointers.
It should be avoided unless the types used aren't known until runtime.
All detours implement the Detour trait, which exposes
several methods, and enforces Send + Sync
. Therefore you must also include
it into your scope whenever you are using a detour.
Features
- static: Enabled by default. Includes the static detour functionality, but requires the nightly features const_fn & unboxed_closures.
Procedure
To illustrate on an x86 platform:
0 int return_five() {
1 return 5;
00400020 [b8 05 00 00 00] mov eax, 5
00400025 [c3] ret
2 }
3
4 int detour_function() {
5 return 10;
00400040 [b8 0A 00 00 00] mov eax, 10
00400045 [c3] ret
6 }
To detour return_five
the library by default tries to replace five bytes
with a relative jump (the optimal scenario), which works in this case.
Executable memory will be allocated for the instruction and the function's
prolog will be replaced.
0 int return_five() {
1 return detour_function();
00400020 [e9 16 00 00 00] jmp 1b <detour_function>
00400025 [c3] ret
2 }
3
4 int detour_function() {
5 return 10;
00400040 [b8 0A 00 00 00] mov eax, 10
00400045 [c3] ret
6 }
Beyond what is shown here, a trampoline is also generated so the original function can be called regardless whether the function is hooked or not.
NOTE: Currently x86 & x64 is supported on all major platforms.
Modules
error |
Error types and utilities. |
Macros
static_detours |
A macro for defining type-safe detours. |
Structs
GenericDetour |
A type-safe wrapper around RawDetour. |
RawDetour |
A type-less detour. |
StaticDetour |
A type-safe static detour. |
StaticDetourController |
An instantiator for StaticDetour. |
Traits
Detour |
Generic trait exposing functionality shared between all detours. |
Function |
Trait representing a function that can be used as a target or detour for detouring. |
HookableWith |
Trait indicating that |