Runtime Trace Bom

Runtime-traced BOM

tracebom runs a command under the @cdxgen/safer-exec sandbox and records what it actually does: which shared libraries it dlopens, which HTTP URLs it reaches, which crypto primitives it exercises, which children it spawns, and which files it mutates. The output is a CycloneDX BOM with library components and enumerated services.

This is observation of real execution, not static inference. It complements sbom-generate rather than replacing it: a trace shows only what the traced run exercised, so it under-reports by design.

Read reference/safety.md first.

Confirm before executing

tracebom executes the user's command. Treat every invocation as a confirm-first action:

1. Show the user the exact --cmd you intend to run and the sandbox limits.
2. Confirm the command is one they want executed now.
3. Never trace a command whose source you have not seen, and never trace something the user has described as untrusted without saying plainly what the sandbox does and does not contain.

The sandbox restricts filesystem, network, and process behaviour. It is a containment boundary, not a guarantee against malicious code.

Basic use

tracebom --cmd "node app.js" -o /absolute/path/to/bom.json

Aliases as a project type: -t dynamic / -t trace.

Evidence recorded on traced components uses technique=instrumentation, scope=required, confidence 0.8/0.5, plus hashes and OS package attribution.

Sandbox limits

Use --trace-period for long-running or persistent commands — a server will otherwise run until --timeout. Use --strict in CI so a degraded sandbox fails loudly instead of silently tracing less.

Filesystem access

--diff is the flag to reach for when the user's question is "what did this installer/build script change?"

Network

Network is off by default, and --trace-http-urls turns it on. Say that out loud when enabling it — the user is choosing to let the traced process reach the network.

tracebom --cmd "node app.js" \
  --trace-http-urls \
  --allow-host api.example.com --allow-port 443 \
  -o /absolute/path/to/bom.json

Keep the allowlist narrow, consistent with the host-allowlist rule in reference/safety.md.

Platform constraint: eBPF HTTP URL tracing is Linux-only, needs kernel

= 5.8, and requires CAP_BPF. On macOS or Windows it will not work — do not present its absence as a cdxgen failure.

Crypto tracing

tracebom --cmd "node app.js" \
  --trace-crypto --crypto-probe-mode operations \
  -o /absolute/path/to/bom.json

Also Linux-only with kernel >= 5.8. Use operations when the user wants observed cryptographic operations rather than just negotiated TLS; pair it with crypto-bom for the static side of the same question.

Process execution

--trace-exec is valuable for build scripts and postinstall hooks, where the interesting behaviour is what gets spawned.

--allow-envs passes host environment variables into the sandbox. Do not pass credential-bearing variables unless the user explicitly asks and understands they will be available to the traced process.

Output

Interpreting a trace

• A trace records one execution path. A library not loaded during the trace may still be loaded on a different input. Never present a trace as a complete dependency inventory.
• Conversely, everything in a trace was genuinely loaded — that is stronger evidence than a manifest entry.
• Compare a trace against a static SBOM to find declared-but-unloaded dependencies. Combine with bom-evidence for reachability before concluding a dependency is unused.
• In cdxi, .instrumented isolates the trace-derived components.

Reference

• tracebom: https://cdxgen.github.io/cdxgen/#/TRACEBOM
• Project types: https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES