Using retrace.

1 · Install

git clone https://github.com/riboseinc/retrace
cd retrace
cmake -B build -G Ninja -DRETRACE_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

# release artifacts: .so / .dylib / .dll per platform
# install.sh detects OS + arch
curl -fsSL https://github.com/riboseinc/retrace/releases |
  sh -s -- download

2 · Five-minute quickstart

# one env var per platform — the library does the rest
LD_PRELOAD=build/src/v2/libretrace.so /bin/ls          # Linux/BSD
DYLD_INSERT_LIBRARIES=build/src/v2/libretrace.dylib /bin/id  # macOS
retrace-win-run --dll retrace.dll -- target.exe        # Windows

# now with a config: log + call_real on selected functions
cat > trace.json <<'EOF'
${ "intercept_scripts": [
  { "func_name": "open", "actions": [
    { "action_name": "log_params" },
    { "action_name": "call_real" } ] } ] }
EOF
RETRACE_JSON_CONFIG=trace.json LD_PRELOAD=build/src/v2/libretrace.so ./tool

macOS SIP blocks injection into system binaries — csrutil disable in Recovery, or copy the binary somewhere non-protected first.

3 · Config anatomy

{ "intercept_scripts": [
  { "func_name": "getenv",          // exact name, or "sqlite3_*"
    "actions": [
      { "action_name": "fuzz_str",
        "action_params": { "dict": "env.dict", "fuzz_seed": 42 } },
      { "action_name": "call_real" } ] } ] }

Comments are tolerated (parson's comment mode). Without a config you get the default: log_params + call_real for every intercepted function. Validate any config withretrace-profile validate or the on-site validator below.

4 · The action set

New behaviors are new actions — composable in any order, per script, per function.

5 · Live OTLP streaming

RETRACE_OTLP_ENDPOINT=http://collector:4318 \
RETRACE_LOGGER_DEF_ENA=1 RETRACE_LOGGER_DEF_STDOUT_ENA=0 \
LD_PRELOAD=build/src/v2/libretrace.so ./service

Spans per call on /v1/traces, jail denials and security events on /v1/logs, campaign/grading metrics on/v1/metrics. At exit: one stderr line with emitted/sent/dropped counters. Schema:docs/reports.md.

6 · Observe → jail → harden

retrace-profile capture -o p.json -- ./tool      # 1. observe
retrace-profile --libc p.json --kernel k.json    # 2. grade vs kernel truth
retrace-profile jail p.json -o jail.json         # 3. emit the jail config
retrace run --config jail.json -- ./tool         # 4. run confined
retrace-profile harden p.json -o strict.json     # 5. deny-by-default