Expand description
Shared LD_PRELOAD + seccomp/SIGSYS instrumentation runtime for Reverie’s ld-preload backends (e9patch and liteinst).
This crate factors the primitives every ld-preload backend needs out of any one backend so they are written and reviewed once:
seccomp— the trap-everything-but-the-trusted-gate BPF filter;trap— the trusted syscall gate, theSIGSYShandler, and dispatcher registration;dispatch— theSyscallDispatcherseam and the shared fail-closedPassthroughDispatcher;fork— fork-following (the filter is inherited atomically; only per-process state must be reset);signal— signal multiplexing / reserved-signal policy;sync— the async-signal-safeSpinMutexthe in-guest tool hosts use for RPC and per-thread state;lifecycle— theLifecycleControllerseam that makes switching to a hybrid in-process-trap + ptrace backend an additive change rather than a rewrite;- [
rpc] (featurecoordinator-rpc) — a synchronous coordinator RPC client wire-compatible with the asyncreverie-rpc-transport; - [
tool_host] (featurecoordinator-rpc) — the backend-agnostic driver that polls an in-guest Reverie tool’sasynchandlers with a no-op waker and carries the sharedERESTARTSYSrestart protocol.
§Coverage boundaries
Established by the research-ldpreload-derisking task and enforced here:
this runtime is for trusted, dynamically linked, non-AT_SECURE, no-exec
x86-64 guests. It does not cover vDSO fast paths, the ~40 loader/startup
syscalls before the constructor runs, static binaries, or execve. fork
is fully covered because the kernel inherits the filter atomically.
§Two ways to use it
- As a library (
rlib): e9patch/liteinst embed the runtime, register a customSyscallDispatcher, and callinstall. - As a standalone
LD_PRELOAD(cdylib): setREVERIE_PRELOAD_TOOLand preloadlibreverie_preload.so; the constructor installs a built-in tool.
Modules§
- dispatch
- The dispatcher seam: how a backend or tool handles a trapped syscall.
- fmt
- Async-signal-safe line formatting.
- fork
- Fork-following.
- lifecycle
- The lifecycle-controller seam.
- seccomp
- Classic-BPF seccomp filter for LD_PRELOAD instrumentation.
- signal
- Signal multiplexing between the runtime and the guest.
- sync
- Async-signal-safe synchronization primitives for the in-guest tool hosts.
- trap
- The syscall trap: trusted gate, SIGSYS handler, and dispatcher registration.
Enums§
- Builtin
Tool - The built-in tools the standalone
LD_PRELOADcdylib can install.
Constants§
- LIB_ENV
- Environment variable overriding the located preload library path.
- SPOOF_
PID - The value
BuiltinTool::SpoofGetpidreturns forgetpid. - TOOL_
ENV - Environment variable selecting a built-in tool for the standalone cdylib.
Functions§
- configure_
command - Configure
commandto load the runtime and select a built-intool. - initialize_
from_ environment - Read
TOOL_ENVand, if it names a built-in tool, install the runtime. - install⚠
- Install the runtime with a caller-provided dispatcher and controller.
- install_
builtin ⚠ - Install a built-in tool with the default in-process controller.
- preload_
library_ path - Locate the preload cdylib beside the current executable, or via
LIB_ENV. - reverie_
preload_ ⚠initialize - Constructor entry point invoked by the dynamic loader for the cdylib.