ABOUT
A userspace libc interceptor
that answers questions.
retrace began as a debugging tool and became an instrument: observe every libc call, rewrite it, break it, jail it — without source, without recompiling, on thirteen platforms. One shared library, one JSON config language, BSD-2-Clause.
What it is
The engine
A per-arch assembly trampoline funnels every intercepted call into one engine, which runs a JSON script of composable actions — log, mutate, inject failure, deny, decode, capture. Prototypes (parameter metadata) live in tables; new functions are an inventory line plus a prototype entry, conformance-tested.
The backends
Preload backends for ELF, Mach-O, and the BSDs; inline-hooking backends for Windows (MSVC + MinGW, x64 + arm64, including static-CRT binaries through the ntdll layer); ptrace for Linux static binaries. All one engine behind them.
The truth layer
libc-level claims are graded against kernel truth: strace, dtrace, truss, ktrace, procmon, and raw ETW all convert into the retrace shape, so "what it touched" has evidence behind it.
The observability bridge
Live OTLP streaming (spans, security events, metrics) and a documented attribute schema — retrace feeds the pipeline you already run instead of inventing another one.
The supervisor (v2.38, native on both worlds since v2.62)
A per-host daemon (retraced) owns every traced process: registry, versioned policy, a hash-chained journal, and a fleet CLI over TLS 1.3 with certificate claim scopes — plus kernel enforcement on Linux (Landlock + seccomp), macOS (Seatbelt), and Windows (AppContainer), each exec bound to a signed audit trail. The fleet CLI is control and evidence in one seat: it pushes policy, shows the session tree, and pulls the journal with the hash-chain verdict riding the reply. On Windows the whole plane speaks named pipes natively — daemon, fleet CLI, and every agent — and the daemon installs as an SCM service with one binary, two launches.
License & provenance
- retrace — BSD-2-Clause, by Ribose. Source of truth: the LICENSE file; no CLA required, contributions are inbound BSD-2.
- otlp-c (vendored,
third_party/otlp-c) — BSD-3-Clause. The pure-C OTLP client behind the streaming waves; see THIRD_PARTY_NOTICES. - parson (vendored) — MIT. The tolerant JSON parser behind configs and traces.
Every release ships a THIRD_PARTY_NOTICES with the license text of each vendored dependency and its pin.
Shipped: the supervisor arc
The supervisor is here: retraced runs per host behind a formally-versioned control protocol — fleets under central policy, freeze and thaw of live specimens, hash-chained journals, and a fleet CLI over mutual-TLS where each certificate carries its own claim scopes. Observation now runs on three lanes (libc, kernel via eBPF/ETW, runtime via Python, JVM, and Go agents) with drift graded live, and declared-sets compile into kernel enforcement on every desktop OS — each exec leaving a signed, verifiable audit record. The CLI's launch arm completes the lifecycle: spawn forks a workload that joins the daemon itself, and every departure — killed, crashed, or a clean exit — lands in the journal as its own record. The arc closed where it pointed: the engine's frame verbs are a polymorphic seam (the same JSON scripts run at libc dispatch or at syscall stops), the journal rotates and seals, campaigns fan out over the control plane, and the preload backends span ten architectures — x86-64, arm64, mips64, rv64, ppc64le, and Android's bionic end to end.
Contributing
Pull requests, issues, and cookbook recipes are all contributions. The development guide covers the build, the test pyramid, and the one-line test registration; CI runs the full 13-platform matrix on every PR, and checkpatch holds the kernel style.