AUDIENCES

One instrument, four professions.

retrace's actions compose differently for each audience. Pick your trail — every step is a command you can run today.

See

Security researchers & malware analysts

You reverse binaries without source. retrace maps every file, network, and process call in seconds — then lets you rewrite them mid-flight, jail them, and stream violations live to your collector.

Map the surface

$ retrace trace open,connect,system,getenv -- ./sample

One command, every libc touchpoint, JSON out.

Detonate under a jail

$ retrace-profile capture -o p.json -- ./sample

Profile the run, emit a jail config, re-run confined.

Watch violations live

$ RETRACE_OTLP_ENDPOINT=http://collector:4318 retrace ...

Denials stream as OTLP log records while it runs.

Live detonation workflow →id-redirection example →Cookbook: jail + harden →

Break

Fuzzing engineers & QA

Error paths hide bugs but need fixtures nobody writes. Inject OOM, short I/O, latency, and mutated strings straight into the target — deterministic seeds, reproducible runs, clustered crash reports.

Fail allocations deterministically

$ retrace fuzz malloc --rate 0.1 -- ./parser file

Same seed, same failures — every crash reproducible.

Run a corpus campaign

$ retrace-fuzz-report --config fuzz.json --seeds corpus/ -- ./target

Clusters, reproducers, minimized corpus, drift oracle.

Mutate strings by grammar

$ fuzz_str with @-template dictionaries

Template lines expand at load; %1..%9 reference tokens.

Fuzz campaign workflow →fuzz-workbench example →Cookbook: dictionary fuzzing →

Attest

Auditors & compliance teams

Claims need ground truth. retrace grades what a binary SAYS it touches against kernel-layer evidence (strace/dtrace/ktrace/procmon/ETW) and against the declared set of its packaging manifest.

Capture + grade

$ retrace-profile --libc t.json --kernel truth.json

libc_only/kernel_only counts: sub-libc access made visible.

Audit a package's declared set

$ retrace-profile --libc t.json --inside declared.json

Observed-but-not-granted paths are headline violations.

Diff behavior across versions

$ retrace-profile diff baseline.json candidate.json

Drift the baseline never saw — the supply-chain signal.

Continuous audit workflow →packaging-audit example →Output shapes reference →

Diagnose

SREs & backend developers

The 3am failure is environmental. Trace the exact libc calls of a misbehaving service — timings, env reads, DNS, connects — without redeploying instrumented builds.

Time every call

$ retrace trace 'sqlite3_*' --time -- ./migration

p99/max per function, honest aggregates.

Watch env + DNS behavior

$ retrace trace getenv,getaddrinfo,connect -- ./svc

Config drift and resolver paths, visible.

Replay deterministically

$ retrace replay session.json

Same calls, same mutations — bugs replay on your laptop.

OTLP observability →All examples →Docs: quickstart →

Debug

Developers & reverse engineers

retrace's root persona: the bug is in the boundary between your code and libc. Step through every call with arguments and returns, diff two runs, and pin the fault that only fires at 3am.

Trace with arguments

$ retrace trace open,malloc,getenv -- ./app

Dereferenced strings, sizes, returns — JSON per call.

Diff two runs

$ retrace-diff run1.json run2.json --threshold 5

Which calls appear, vanish, or slow down between builds.

Pin the 3am fault

$ RETRACE_REPLAY_OUT=run.rec ./flaky && RETRACE_REPLAY_IN=run.rec ./flaky

The time-seeded run records; the replay reproduces it exactly — or names its drift.

Cookbook: the debugging set →Recipe 27: replay a trace →Recipe 41: cross-arch samples →