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 and JVM 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.
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.