Trace a packaged app.

Every interception point the driver and the preload shim already implement emits one event per decision onto the bus — a JSON-lines stream, one object per line, robust to a crashed tail. Events name OS-level facts (paths, verdicts, errnos), never language-runtime facts, so every runtime is covered equally. Arm it with one environment variable:

Run a package under the record policy with the bus armed; when it exits, the capture is synthesized into a suggested manifest fragment — commented YAML on stdout (or --out), never applied. The process exits with the payload’s own exit code.

The draft it writes looks like this:

The draft extends the jail journal’s needs discovery to the axes a journal cannot see: host reads and writes become needs: grants (strongest-observed-op wins); an in-image file read through a raw host fd becomes a materialize: candidate; an in-image dlopen whose dependency closure resolved entirely in-image earns a closure-covered — nothing to declare note; a spawned host executable earns an entrypoint/runtime-dep note. Floor, store, and exec-cache paths are excluded. Then the human gate: you review, flip ro↔rw, delete noise, fill every why — a generated suggestion never edits a manifest by itself. Output representative; paths abbreviated.

Replay a capture — a finished file or a live run’s growing one — into the hop chain. The first hop whose verdict is red prints with its evidence; the signature table that maps stream shapes to hops lives in data, seeded from the incident corpus (a lost handoff env, the OS loader refusing a resolved closure, a jail denial, an exec-cache write failure) and extended as incidents teach new shapes.

A clean capture replays like this:

Output representative.

The inside stream can never prove its own completeness — an escape is invisible from inside by definition. "What isn’t tebako intercepting" is answerable only by subtracting the inside stream from an outside capture of the same run. Capture the run once per side, then correlate:

--prefix names the virtualized root as the outside capture spells it; an under-prefix touch the inside stream never saw is an escape. stdout is a machine contract — one escape <path> func=… tid=… pid=… class=… line per escape, or a JSON array with --json — byte-identical with retrace’s retrace-correlate on the shared golden fixtures (the parity is asserted in CI; the format is retrace’s, tebako never authors a competing one). The summary, the per-surface-class coverage percentages, and the producing layer go to stderr:

The remaining flags scope the correlation: --pid N considers only one process’s outside entries, --window SECS requires timestamps within the window for coverage (0, the default, is pure set-difference), and --exclude-probes drops probe-class escapes (an existence probe on an under-prefix path counts as an escape by default — a name-not-found answer is still information the VFS never served). The escape lines above are the toolkit’s golden fixture, verbatim.

On windows the outside capture that works today is Procmon’s CSV export — the kernel layer, normalized into the retrace JSON shape by an offline converter in the CLI (in-process, byte-parity with upstream’s procmon2retrace):

That verdict is the golden libsass-importer fixture, reproduced from the CSV end: a native importer probing partials with raw Win32 calls, below every libc hook — exactly the escape class only a kernel-layer capture can certify. One honest limitation: the libc-boundary alternative on windows (retrace’s inline-hook backends with live injection) is a documented absent prerequisite at retrace v2.14.0 — the win-run injector crashes inside the child’s engine boot — so the procmon chain carries windows coverage certification until that lands upstream. A probe leg in tebako’s CI pins the broken signature and fails on drift in either direction.

A coverage report is only as strong as its outside capture’s layer: a libc-boundary capture certifies libc-routed escapes only; certifying sub-libc escapes takes a kernel-layer capture. The report names the producing layer — pass --layer kernel when the outside capture is ptrace, eBPF, or procmon.

The 0/1 split for explain and cover exists so the verdicts are CI-gateable.

See also: Check a payload · Set a jail policy · Debug & logging