Skip to main content

Crate running_process_probe

Crate running_process_probe 

Source
Expand description

Sidecar / file-hook tier for running-process — #539 follow-up #551.

This crate implements the fourth column of #539’s per-platform acceptance matrix: streaming file-activity events (FileOpen/FileWrite/FileClose/FileUnlink/FileRename) intercepted in the target process’s address space via library-function detours, complementing the snapshot tier (read_process_file_handles) that already shipped under #539.

§Architecture (off-by-default opt-in)

The injector and per-OS interposer code live in this crate, behind the embed-helper Cargo feature, and ship via the bundled running-process-probe-agent binary embedded at build time and extracted to a per-user cache directory at first use. The main [running_process] crate stays completely clean of injection symbols (CreateRemoteThread, dlopen of interposers, etc.) so that static AV / EDR analysis of consumers that don’t opt in sees no hooking surface at all. Precedent: Frida’s frida-helper-{32,64}, Sysmon, VS Profiler.

Per-OS injection vehicles land in slices 4–6 of #551:

  • Windows: DLL injection + retour-rs function detours.
  • Linux: LD_PRELOAD of a shared object that shadows libc symbols via dlsym(RTLD_NEXT, ...). Env-var propagation through execve() re-injects descendants for free.
  • macOS: DYLD_INSERT_LIBRARIES — same shape as LD_PRELOAD, with SIP/hardened-runtime caveats documented per-call-site.

§Slice 1 scope (this scaffold)

  • HookConfig type for caller opt-in (always exists; off by default if embed-helper is disabled).
  • [HookCapability] negotiation that reports honestly whether the embedded helper is available for this build (feature_enabled) and whether the host has the per-OS injection vehicle (filled in by slices 4–6).
  • Placeholder running-process-probe-agent binary that prints a version banner and exits — proves the workspace plumbing.

No injection, no IPC, no events. Slice 2 adds the embed-and-extract machinery; slice 3 adds the IPC event stream; slices 4–6 add the actual interposer payloads.

Modules§

crash
Default-on crash interception and fixed-size pre-registration spool. Default-on crash capture (#636).
probe_diag
The running_process.probe_diag.v1 wire schema (#630).
snapshot
Cooperative all-thread stack capture (#635, S6).

Structs§

HookConfig
Opt-in configuration that turns the file-hook tier on for a single spawned process (and its descendants, on Linux + macOS where env-var inheritance handles re-injection automatically; Windows uses per-process injection — see slice 6 of #551).

Enums§

HookSupport
Per-OS support level the hook tier reports back to consumers.

Functions§

negotiate_hook_support
Negotiate the hook tier’s per-OS support level on this host with this build.