procmod-hook

Inline function hooking and detouring for x86_64.

Example

Hook a game's damage calculation to make the player invincible:

use procmod_hook::Hook;use std::sync::atomic::{AtomicPtr,Ordering};staticTRAMPOLINE:AtomicPtr<u8> = AtomicPtr::new(std::ptr::null_mut());extern"C"fndamage_detour(entity_id:u32,amount:f32) -> f32{if entity_id == 1{return0.0;// player takes no damage}let original:extern"C"fn(u32,f32) -> f32 = unsafe{
std::mem::transmute(TRAMPOLINE.load(Ordering::SeqCst))};original(entity_id, amount)}// target_addr obtained via procmod-scan or manual inspectionlet hook = unsafe{Hook::install(target_addr as*constu8, damage_detour as*constu8)}?;TRAMPOLINE.store(hook.trampoline()as*mutu8,Ordering::SeqCst);// damage_detour is now called instead of the original function

API

• Hook::install(target, detour) - Redirect target to detour, returns a hook with a trampoline to the original.
• hook.trampoline() - Pointer to the original function's relocated entry point. Transmute to the original signature to call it.
• hook.unhook() - Remove the hook, restore original bytes, free the trampoline.

Hooks are automatically removed on drop.

How it works

1. Decode instructions at the target function's entry point using iced-x86
2. Allocate executable memory (trampoline) within 2GB of the target
3. Relocate stolen instructions into the trampoline, adjusting RIP-relative addressing
4. Append a jump from the trampoline back to the target (continuing original execution)
5. Overwrite the target's first bytes with a jump to the detour

The detour runs instead of the original. It can call the original at any point through the trampoline.

Platform support

Platform	Architecture	Status
Linux	x86_64	Supported
Windows	x86_64	Supported
macOS	x86_64	Supported

arm64 support is a future goal. The crate compiles on arm64 but exports no types.

Safety

Hook installation is inherently unsafe:

• No thread may be executing the target function's entry point during install/unhook
• The detour must have the same calling convention and signature as the target
• The hook must remain alive as long as the detour might call the trampoline

Part of the procmod ecosystem.