plthook-native
plthook-native is a pure-Rust engine for enumerating and transactionally replacing
imports in loaded native modules. It supports PE import address tables, ELF
PLT/GOT relocations, and Mach-O symbol pointers and chained fixups.
The crates.io package is named plthook-native to distinguish it from the existing
plthook package. The Rust library name intentionally remains plthook, so code
imports it as use plthook::....
This crate is the low-level engine used by hookfs. Use it directly for
instrumentation, compatibility shims, controlled native-library interposition,
or other cases where a specific loaded module's imports must be rebound.
Installation
[]
= "0.1.0"
use ;
The minimum supported Rust version is 1.96.
Basic workflow
Acquire a currently loaded module, describe one or more replacement pointers,
and keep the returned guard alive for as long as calls should be redirected.
Module::from_address accepts any code or data address inside the exact loaded
module to patch; an address of an export already resolved by the application is
usually the most convenient anchor:
use c_void;
use ;
extern "C"
The replacement function must exactly match the imported function's ABI and
signature. Casting an incompatible function or allowing the target module to
unload while its Module/HookGuard is in use can violate memory safety; these
contracts are necessarily the caller's responsibility.
Module acquisition and enumeration
Module represents a validated image that is already loaded in the current
process. It can be acquired from:
Module::from_addressfor a live code or data address in the image;Module::from_handlefor a live platform loader handle;Module::from_namewithout intentionally loading a new image; orModule::enumerateto inspect all supported loaded images.
Module::imports returns ImportSlot values with the provider name, symbol,
slot address, import kind, version where available, and protection metadata.
Replacement matching
Replacement::by_name(library, symbol, pointer) restricts a match to one
provider. This is normally preferred on Windows, where provider DLL names are
matched case-insensitively. Replacement::by_symbol(symbol, pointer) matches a
symbol regardless of provider and is useful on ELF and Mach-O. Append
.optional() when absence of a symbol should not abort the transaction.
By default a requested replacement is required. Installation resolves every target and every canonical original before changing memory. If any required symbol or original cannot be resolved, no slot is modified.
HookGuard::installed describes the slots that were changed, and
HookGuard::original exposes the canonical original pointer for a symbol.
Calling uninstall restores synchronously and reports conflicts; dropping the
guard performs best-effort restoration.
Transaction and concurrency behavior
- All install/uninstall operations are process-wide serialized.
- Protection changes are page-batched and restored to their prior values.
- Aligned pointer-width slot updates are atomic on supported architectures.
- A failed multi-symbol install rolls back already-written slots.
- Restoration uses compare-exchange and does not overwrite another component's later modification of the same slot.
- A disappeared module is not dereferenced during restoration.
These properties protect the patching transaction, but they cannot make an arbitrary replacement function ABI-safe or coordinate unrelated hooking libraries automatically.
Supported targets
| Operating system | Format and imports | Architectures |
|---|---|---|
| Windows | PE32+ standard and delay IAT | x86-64, aarch64 |
| Linux (glibc) | ELF64 JUMP_SLOT and GLOB_DAT |
x86-64, aarch64 |
| macOS | Mach-O symbol pointers/chained fixups | x86-64, arm64 |
| iOS/iPadOS | Mach-O symbol pointers/chained fixups | arm64 |
Only calls emitted through a patched import slot are affected. Direct calls, inlined code, direct syscalls, and static linkage are outside this mechanism. Authenticated arm64e PAC-signed slots are detected and rejected; writing an unsigned pointer to such a slot would be invalid.
Origin, license, and attribution
plthook-native is a Rust port derived from
kubo/plthook. The upstream implementation is
covered by Kubo Takehiro's platform-specific 2013-2024 copyright notices and
distributed under the BSD-2-Clause license. Its notices and disclaimer are
retained in LICENSE-BSD-2-Clause and NOTICE.
Original Rust work is available under either MIT or Apache-2.0, at your option.
Because the crate incorporates ported BSD-2-Clause work, redistribution must
also comply with the retained BSD notice. The package manifest expresses this
as (MIT OR Apache-2.0) AND BSD-2-Clause.