/runtime-trace-bom

name: runtime-trace-bom
description: Produces a dynamic CycloneDX BOM by executing a command under the cdxgen safer-exec sandbox with tracebom, tracing dlopen shared-library loads, eBPF HTTP URL access, cryptographic library and cipher-suite usage, child process execution, and filesystem mutations. Use when asked what a program actually loads or calls at runtime, for a dynamic or runtime SBOM, to observe a binary's real behaviour, or to trace network and crypto usage of a process.

Runtime-traced BOM

`tracebom` runs a command under the `@cdxgen/safer-exec` sandbox and records what it actually does: which shared libraries it `dlopen`s, 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](../../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

| Flag | Default | Purpose | | --------------------- | -------------- | ---------------------------------------------- | | `-d, --working-dir` | cwd | Working directory for the traced process | | `--timeout` | `60000` ms | Trace timeout | | `--trace-period` | — | Stop tracing after N seconds | | `--max-memory` | `512` MB | Memory ceiling | | `--max-cpu` | — | CPU cores, fractional (`0.5` = half a core) | | `--max-processes` | `64` | Process count ceiling | | `--strict` | `false` | Treat sandbox setup warnings as hard errors |

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

| Flag | Default | Purpose | | ----------------- | ------------ | ------------------------------------------------ | | `--read-paths` | — | Extra read paths, comma-separated | | `--write-paths` | OS tmpdir | Sandbox write paths | | `--allow-hidden` | `true` | Allow hidden files and directories | | `--diff` | `false` | Track files created, modified, or deleted |

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

Network

| Flag | Default | Purpose | | ------------------- | -------- | -------------------------------------------------------------- | | `--disable-network` | `true` | Network off inside the sandbox | | `--trace-http-urls` | `false` | eBPF HTTP URL tracing; **automatically enables network** | | `--allow-host` | — | Hostnames the process may reach | | `--allow-port` | — | TCP ports allowed | | `--allow-url` | — | Fine-grained URL allow rules | | `--allow-listen` | — | IPs or `ip:port` the process may bind |

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](../../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

| Flag | Default | Purpose | | --------------------- | ----------- | ------------------------------------------------------------- | | `--trace-crypto` | `true` | eBPF crypto library and cipher-suite tracing | | `--crypto-probe-mode` | `tls-only` | `tls-only`, or `operations` for digest, encrypt, sign |

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

| Flag | Default | Purpose