LiteInst Binary Instrumentation
Use This Skill For
src/runtime.rs site discovery, registry, patch, hook, or fallback changes.
src/patch_alloc.rs allocation behavior.
liteinst API or pinned-revision updates.
- Bugs involving dynamic executable mappings, stale sites, text protections,
repeated SIGSYS traps, or hook recursion.
Execution Model
The seccomp SIGSYS event is a discovery mechanism, not the tool execution
context. On the first hit at a syscall instruction:
- Validate the trap and locate the actual syscall site.
- Claim the site in the fixed registry.
- Validate enough complete instructions for LiteInst's patch window.
- Install a replace-first hook and reachable trampoline, temporarily changing
text protections only as required.
- Redirect saved RIP to the hook trampoline and return from the handler.
- Dispatch the Reverie tool after sigreturn in normal guest context.
If the site cannot be patched safely, retain trap fallback. Never run tool code
or coordinator RPC from the signal handler.
Invariants Checklist
- One logical syscall produces one tool event on the first trap.
- Installed hooks enter
tool_trampoline; nested trusted syscalls bypass the
tool and cannot recursively patch or dispatch.
- Instruction validation covers the full patch window. Do not assume bytes
after a syscall are readable, executable, or part of the same mapping.
- Trampoline arenas are reachable from their mapping. A newly executable map
without a prepared arena must fall back safely.
- Text permissions are restored on every success and error path, and modified
instructions become visible to executing cores.
- Mapping-generation updates for
mmap, munmap, and mremap invalidate old
site assumptions. Stale sites are revalidated or rejected.
- Fixed registry and arena limits fail predictably. Do not allocate through the
guest allocator during signal-time installation.
- Patch installation uses the patch scope; normal tool dispatch uses the
reusable dispatch scope. Neither scope may block or reenter itself.
Investigation Workflow
- Reproduce with a single focused test and
--test-threads=1.
- Determine whether the event used the first-hit trap, installed hook, or trap
fallback. Use the exported trap/hook counters where possible.
- Inspect the containing executable mapping and instruction bytes before
changing scanner or patcher logic.
- Check mapping generation, site state, and arena reachability.
- Check trusted-syscall and allocator scope before blaming tool behavior.
- Add a regression that exercises repeated execution, mapping churn, boundary
bytes, or fallback as appropriate.
The core regression should preserve calls=32 traps=1 hooks=32. A changed
count needs a specific architectural reason and explicit review.
Validation
cargo test -p reverie-liteinst --test strace -- --test-threads=1
cargo test -p reverie-liteinst --test rpc_tool -- --test-threads=1
cargo test -p reverie-liteinst --all-features -- --test-threads=1
cargo clippy -p reverie-liteinst --all-targets --all-features
Run on Linux x86-64. Report a missing architecture, seccomp, or dynamic-loader
precondition as a limitation; do not weaken the regression to make it pass.
1---2name: liteinst-binary-instrumentation3description: "Use when changing LiteInst syscall discovery, text patching, trampolines, executable-map tracking, trap fallback, or allocator scopes."4metadata:5 source: https://skillmd.com/skills/facebookexperimental/liteinst-binary-instrumentation6---78# LiteInst Binary Instrumentation910## Use This Skill For1112- `src/runtime.rs` site discovery, registry, patch, hook, or fallback changes.13- `src/patch_alloc.rs` allocation behavior.14- `liteinst` API or pinned-revision updates.15- Bugs involving dynamic executable mappings, stale sites, text protections,16 repeated SIGSYS traps, or hook recursion.1718## Execution Model1920The seccomp SIGSYS event is a discovery mechanism, not the tool execution21context. On the first hit at a syscall instruction:22231. Validate the trap and locate the actual syscall site.242. Claim the site in the fixed registry.253. Validate enough complete instructions for LiteInst's patch window.264. Install a replace-first hook and reachable trampoline, temporarily changing27 text protections only as required.285. Redirect saved RIP to the hook trampoline and return from the handler.296. Dispatch the Reverie tool after sigreturn in normal guest context.3031If the site cannot be patched safely, retain trap fallback. Never run tool code32or coordinator RPC from the signal handler.3334## Invariants Checklist3536- One logical syscall produces one tool event on the first trap.37- Installed hooks enter `tool_trampoline`; nested trusted syscalls bypass the38 tool and cannot recursively patch or dispatch.39- Instruction validation covers the full patch window. Do not assume bytes40 after a syscall are readable, executable, or part of the same mapping.41- Trampoline arenas are reachable from their mapping. A newly executable map42 without a prepared arena must fall back safely.43- Text permissions are restored on every success and error path, and modified44 instructions become visible to executing cores.45- Mapping-generation updates for `mmap`, `munmap`, and `mremap` invalidate old46 site assumptions. Stale sites are revalidated or rejected.47- Fixed registry and arena limits fail predictably. Do not allocate through the48 guest allocator during signal-time installation.49- Patch installation uses the patch scope; normal tool dispatch uses the50 reusable dispatch scope. Neither scope may block or reenter itself.5152## Investigation Workflow53541. Reproduce with a single focused test and `--test-threads=1`.552. Determine whether the event used the first-hit trap, installed hook, or trap56 fallback. Use the exported trap/hook counters where possible.573. Inspect the containing executable mapping and instruction bytes before58 changing scanner or patcher logic.594. Check mapping generation, site state, and arena reachability.605. Check trusted-syscall and allocator scope before blaming tool behavior.616. Add a regression that exercises repeated execution, mapping churn, boundary62 bytes, or fallback as appropriate.6364The core regression should preserve `calls=32 traps=1 hooks=32`. A changed65count needs a specific architectural reason and explicit review.6667## Validation6869```bash70cargo test -p reverie-liteinst --test strace -- --test-threads=171cargo test -p reverie-liteinst --test rpc_tool -- --test-threads=172cargo test -p reverie-liteinst --all-features -- --test-threads=173cargo clippy -p reverie-liteinst --all-targets --all-features74```7576Run on Linux x86-64. Report a missing architecture, seccomp, or dynamic-loader77precondition as a limitation; do not weaken the regression to make it pass.