Threat Model

This document describes the threat model for cdxgen — a polyglot CycloneDX BOM generator that produces SBOM, CBOM, HBOM, OBOM, SaaSBOM, CDXA, and VDR documents. It identifies threat actors, attack surfaces, trust boundaries, and mitigations across cdxgen's components: CLI, library, HTTP server, REPL, CI/CD infrastructure, container images, dependencies, the optional pure-ESM @cdxgen/cdx-hbom host collector, and the optional native helper binaries supplied through cdxgen-plugins-bin.

System Overview

cdxgen generates CycloneDX Bill-of-Materials (BOM) documents — including SBOM, CBOM, HBOM, OBOM, SaaSBOM, CDXA, and VDR — by parsing project manifests/lockfiles and optionally invoking external build tools. It also opportunistically uses the optional pure-ESM @cdxgen/cdx-hbom package for live hardware inventory on supported hosts, plus optional helper binaries from cdxgen-plugins-bin such as Trivy (container/rootfs OS inventory), osquery (live-OS OBOM), trustinspector (filesystem/signing/trust inventory), SourceKitten, and dosai. It operates in six modes:

1. CLI (bin/cdxgen.js) — Command-line invocation on local projects
2. Library (lib/cli/index.js) — Programmatic use via createBom(path, options)
3. HTTP Server (lib/server/server.js) — REST API accepting scan requests, optionally with Git clone
4. REPL (bin/repl.js) — Interactive shell for ad-hoc BOM operations
5. Evinse (bin/evinse.js) — Evidence generation for SBOM verification (analyzes call stacks, data flows, and usages)
6. Verify (bin/verify.js) — BOM signature verification using JWS

Trust Boundaries

┌─────────────────────────────────────────────────────────────────────┐
│                        User Environment                             │
│  ┌───────────┐  ┌────────────┐  ┌──────────────┐  ┌─────────────┐   │
│  │ CLI / REPL│  │ Library    │  │ HTTP Server  │  │ CI Runner   │   │
│  └─────┬─────┘  └─────┬──────┘  └──────┬───────┘  └──────┬──────┘   │
│        │              │                │                 │          │
│  ══════╪══════════════╪════════════════╪═════════════════╪══════    │
│  Trust boundary 1: cdxgen code ←→ external build tools              │
│        │               │                │                │          │
│  ┌─────▼─────────────────────────────────────────────────────────┐  │
│  │          External Build Tools and Helper Binaries             │  │
│  │  npm, maven, gradle, pip, go, cargo, dotnet, trivy, osquery…  │  │
│  └─────┬─────────────────────────────────────────────────────────┘  │
│        │                                                            │
│  ══════╪════════════════════════════════════════════════════════════│
│  Trust boundary 2: local system ←→ remote registries/hosts          │
│        │                                                            │
│  ┌─────▼─────────────────────────────────────────────────────────┐  │
│  │              Package Registries & Remote Hosts                │  │
│  │  npmjs.org, maven.org, pypi.org, crates.io, ...               │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Trust boundary 3: HTTP server ←→ external HTTP clients
Trust boundary 4: cdxgen process ←→ host operating system / filesystem
Trust boundary 5: cdxgen container ←→ container host

Threat Actors

Actor	Capability	Motivation
Malicious project author	Controls manifest files, lockfiles, build scripts, .npmrc, .mvn/, setup.py, etc.	Supply-chain attack: execute code on machines that scan their project
Network attacker (MITM)	Intercepts HTTP traffic between cdxgen/build tools and registries	Inject malicious package metadata, steal credentials, tamper with SBOMs
Malicious HTTP client	Sends crafted requests to the cdxgen server	Path traversal, SSRF, denial of service, Git clone exploits
Environment manipulator	Controls environment variables in the cdxgen process	Command injection via NODE_OPTIONS, credential theft, behavior alteration
Compromised dependency	A direct or transitive npm dependency of cdxgen is compromised	Arbitrary code execution in the cdxgen process at import time
Compromised helper binary	Controls or replaces an auxiliary native binary executed by cdxgen	Tamper with scan results, execute unexpected code, exfiltrate host data
Compromised CI/CD	Access to GitHub Actions workflows or self-hosted runners	Tamper with releases, inject malicious code into published artifacts

Threats and Mitigations by Component

1. CLI and Library (bin/cdxgen.js, lib/cli/index.js)

T1.1 — Command injection via project files

Threat: Attacker-controlled values from manifests or lockfiles (package names, versions, URLs) are passed to safeSpawnSync in a way that escapes command boundaries.

Mitigations:

• safeSpawnSync uses array-based arguments (not shell strings) via spawnSync, preventing shell metacharacter injection
• safeSpawnSync blocks shell: true invocations when the command or direct argument values contain shell metacharacters
• Dry-run/debug activity summaries flag discovered direct paths containing shell metacharacters so operators can review suspicious repository-controlled names before invoking external build tools
• Command allowlisting via CDXGEN_ALLOWED_COMMANDS — only explicitly permitted commands can execute
• In secure mode, automatic package installations are disabled, reducing the set of commands invoked
• commandsExecuted tracks all invoked commands for post-run audit

Scope note: These mitigations cover commands, options, and path values that cdxgen itself passes to external processes through safeSpawnSync. They do not sanitize every nested project path, module name, or generated path that an external build tool later discovers and interprets inside its own process. That behavior belongs to the separate cdxgen ↔ external build tool trust boundary.

Residual risk: Medium — cdxgen invokes many different commands with project-derived arguments, and external build tools may further interpret project-controlled files and paths after cdxgen has safely crossed its own process boundary. Continuous review is needed as new language support is added.

T1.2 — Arbitrary code execution via build tools

Threat: cdxgen invokes npm install, mvn, pip install, gradle, etc. These tools execute code from project files (postinstall scripts, setup.py, Gradle build scripts).

Mitigations:

• Secure mode (CDXGEN_SECURE_MODE=true) disables automatic package installation
• safeSpawnSync warns when pip/uv install is invoked without --only-binary=:all: (prevents setup.py execution during wheel builds)
• safeSpawnSync warns when Python is invoked without -S flag
• Users are advised to run in sandboxed environments for untrusted projects

Residual risk: High — this is a fundamental tension. Accurate dependency resolution often requires invoking build tools that may execute untrusted code. Secure mode trades accuracy for safety.

T1.3 — Environment variable poisoning

Threat: Attacker sets NODE_OPTIONS with --require or --eval to inject code, or manipulates JAVA_TOOL_OPTIONS, NODE_PATH, proxy variables, or TLS settings.

Mitigations:

• auditEnvironment() runs at startup and detects:
  • Code execution patterns in NODE_OPTIONS (--require, --eval, --import, --loader, --inspect)
  • JVM agent injection in MVN_ARGS, GRADLE_ARGS, JAVA_TOOL_OPTIONS
  • Module resolution poisoning via NODE_PATH
  • Disabled TLS verification (NODE_TLS_REJECT_UNAUTHORIZED=0)
  • Credential-like variables
  • Debug mode exposure
  • Running as root outside containers
  • Proxy interception variables
• Findings are reported with severity ratings and remediation guidance

Residual risk: Medium — auditEnvironment is pattern-based and may not catch novel obfuscation. An attacker who can set environment variables often already has significant access.

T1.4 — Path traversal via file inputs

Threat: Attacker crafts file paths with ../, Unicode tricks, or Windows device names to read or write outside the intended project directory.

Mitigations:

• hasDangerousUnicode() detects bidirectional control characters, zero-width characters, and other obfuscation
• isValidDriveRoot() prevents Unicode lookalike drive letters on Windows (CVE-2025-27210 mitigation)
• Node.js --permission model (in secure mode) restricts filesystem access to explicitly allowed paths
• safeExistsSync and safeMkdirSync check permissions before operations

Residual risk: Low in secure mode, Medium in default mode.

T1.5 — Remote source scanning via git URL and purl inputs

Threat: A user (or wrapper tool) supplies a malicious git URL or purl that resolves to an unsafe repository.

Mitigations:

• CLI and server both use shared source validation (validateAndRejectGitSource()) and hardened clone behavior
• Protocol allowlisting via GIT_ALLOW_PROTOCOL / CDXGEN_GIT_ALLOW_PROTOCOL
• Host allowlisting via CDXGEN_GIT_ALLOWED_HOSTS (or CDXGEN_SERVER_ALLOWED_HOSTS in server mode)
• Temporary clone directories are removed after scan completion
• purl resolution emits an explicit warning that registry metadata may be untrusted

Residual risk: Medium — trust is delegated to external registry metadata and remote repository hosting unless strict allowlists are configured.

T1.6 — User-controlled pattern complexity in CLI options

Threat: An operator supplies highly complex glob or regular-expression patterns through CLI/configuration options such as --exclude, --include-regex, --exclude-regex, ASTGEN_IGNORE_FILE_PATTERN, or related ignore-pattern environment variables, causing excessive CPU use during local matching or downstream frontend filtering.

Security boundary: These patterns are considered trusted operator input in CLI, REPL, and library usage. ReDoS or other algorithmic-complexity behavior that depends on a user intentionally supplying pathological command-line arguments or environment variables is not treated as a cdxgen security vulnerability. This scope note does not apply to regexes or patterns derived from untrusted remote clients, registry metadata, manifests, lockfiles, or scanned project content without explicit operator opt-in.

Mitigations:

• cdxgen avoids shell interpretation for these values and treats them as filtering patterns only
• Directory-oriented excludes are additionally forwarded as literal directory names for performance where supported by Atom and astgen
• Server deployments should validate or constrain request options at the API boundary if untrusted clients can submit scans

Residual risk: Low for intended local/CI usage where the operator controls CLI arguments. Medium for wrappers or server deployments that expose pattern options to untrusted users without additional validation.

T1.7 — Malicious archive metadata in packaged release artifacts

Threat: An attacker ships a crafted ASAR archive with malformed header data, path-like entry names, integrity mismatches, or unpacked/native payloads intended to confuse inventory, trigger unsafe extraction behavior, or hide high-risk runtime capabilities.

Mitigations:

• Native ASAR parsing validates header structure before walking entries
• Entry names containing path separators or traversal markers are rejected during header validation
• Archive inventory records both declared integrity metadata and computed SHA-256 hashes for file components
• .asar.unpacked extraction only writes within a temp directory created through safe wrappers
• --dry-run still blocks temp extraction even for ASAR scans, while allowing in-memory header and file-content analysis
• JavaScript capability analysis highlights eval/code generation, dynamic fetch/import, network, filesystem, hardware, and child-process indicators in packaged source files

Residual risk: Medium — cdxgen can inventory and verify what is present, but a trusted-looking packaged archive may still contain malicious application logic that requires human review or runtime sandboxing to fully assess.

T1.8 — Compromised or substituted helper binary

Threat: cdxgen executes optional native helpers from cdxgen-plugins-bin (for example Trivy, osquery, and trustinspector). A compromised, replaced, or unexpected binary could tamper with scan output or execute malicious logic. Separately, a forged plugins-manifest.json could attempt to spoof helper metadata recorded in metadata.tools.

Mitigations:

• Helper execution still flows through safeSpawnSync, command allowlisting, and the general secure-mode guardrails
• Optional helper package versions are pinned in package.json, and the companion repository generates post-build metadata/SBOMs for shipped binaries
• plugins-manifest.json is treated as data only: cdxgen does not execute commands, paths, or scripts from the manifest
• Manifest ingestion is constrained to the real plugins-manifest.json file under CDXGEN_PLUGINS_DIR, requires a regular file, enforces a size bound, and sanitizes accepted fields before merging them into metadata.tools
• Docker/rootfs tests assert non-cdxgen tool identity evidence and container/rootfs result parity, making silent helper-behavior drift easier to detect in CI
• macOS osquery execution uses one-shot shell mode with the persistent database disabled, reducing the need for helper-managed state under privileged host paths such as /var/osquery

Residual risk: Medium — helper binaries remain executable third-party/native code and expand the trusted computing base for deep OS/container inventory. A malicious actor who can replace the plugin directory can still spoof helper metadata or swap binaries, but that is a local integrity problem rather than a new command-injection path through manifest parsing.

T1.9 — Malicious rootfs repository or trusted-key metadata

Threat: A crafted image or root filesystem plants misleading repository source files or trusted key material so that the BOM reflects false trust relationships or reviewer-confusing crypto inventory.

Mitigations:

• Repository source entries are modeled as type: data with explicit cdx:os:repo:* provenance properties including source path and URL
• Trusted key files are modeled as type: cryptographic-asset with hashes, source paths, trust-domain properties, and schema-valid cryptoProperties
• When repo config explicitly references a key (signed-by, gpgkey), cdxgen emits a dependency edge from the repository component to the corresponding key asset instead of flattening the relationship away
• Docker/rootfs regression tests compare archive and reconstructed-rootfs signatures so repo/key inventory drift is caught during CI

Residual risk: Medium — cdxgen inventories what exists on disk and can preserve trust relationships, but it cannot prove that the configured repositories or keys are themselves benign or organization-approved.

T1.10 — Over-privileged HBOM live collection on managed hosts

Threat: An operator grants broader privileges than necessary to collect HBOM data on Linux, or assumes that every partial HBOM requires root access, increasing the blast radius of the scanning process on production hosts.

Mitigations:

• HBOM collection defaults to unprivileged mode and relies first on /proc, /sys, and other low-risk local sources where possible
• --privileged is explicit opt-in and only enables the documented permission-sensitive command paths exposed by @cdxgen/cdx-hbom
• @cdxgen/cdx-hbom 0.4.0 records missing-command and permission-denied diagnostics directly in the BOM root and collector trace instead of silently hiding partial evidence gaps
• cdxgen derives compact cdx:hbom:analysis:* summary properties and exposes hbom diagnostics so operators can distinguish "install a package" from "rerun with --privileged" without guessing
• In secure mode, cdxgen reuses the HBOM dry-run declaration as a preflight plan and aborts live HBOM collection when the declared commands fall outside CDXGEN_ALLOWED_COMMANDS or the declared local paths fall outside CDXGEN_ALLOWED_PATHS; for @cdxgen/cdx-hbom this also covers explicit sudo -n retry paths declared for permission-sensitive commands
• The Linux privileged path uses non-interactive sudo -n, avoiding interactive password prompts that would otherwise encourage ad hoc operator workarounds

Residual risk: Medium — HBOM still runs on the target host and may require elevated access for richer firmware or graphics detail. Users remain responsible for applying least privilege and deciding whether the additional evidence is worth the extra permissions.

T1.11 — Untrusted AI metadata from remote model registries and local model artifacts

Threat: A remote model repository (for example on Hugging Face) or a local AI artifact (for example GGUF) exposes misleading, oversized, or secret-bearing metadata that cdxgen could mirror into the BOM, confusing downstream review or leaking sensitive content.

Mitigations:

• Hugging Face remote resolution sanitizes URLs, strips userinfo/query/fragment components, and emits bounded revision-aware references instead of mirroring raw request contexts
• AI-BOM prefers CycloneDX-first structures such as modelCard, pedigree, externalReferences, services, dependencies, and data components over dumping opaque metadata blobs into ad-hoc properties
• GGUF parsing intentionally avoids copying raw tokenizer vocabularies, raw Hugging Face tokenizer JSON payloads, and raw chat templates; it emits safe derivatives such as counts, booleans, and token IDs instead
• Hugging Face model-card parsing avoids copying raw gated-access prompts, widget conversations, and other unbounded prompt-like payloads into top-level BOM properties; it emits bounded booleans, counts, task/I-O hints, and stable links instead
• Remote Hugging Face Spaces are modeled as application components with explicit model/dataset dependency edges so reviewer-relevant relationships survive without copying large runtime payloads

Residual risk: Medium — cdxgen can sanitize and bound what it emits, but it still trusts remote and artifact-provided metadata enough to model lineage, datasets, and popularity/runtime hints. Human review is still required for policy decisions on untrusted third-party models.

2. HTTP Server (lib/server/server.js)

T2.1 — Path traversal via scan requests

Threat: A client sends a scan request with a path like /app/../../../etc/passwd to scan or access files outside allowed directories.

Mitigations:

• isAllowedPath() resolves paths and checks they are within CDXGEN_SERVER_ALLOWED_PATHS
• Uses path.relative() to detect .. traversal
• hasDangerousUnicode() blocks Unicode obfuscation in paths
• isAllowedWinPath() blocks Windows device names, UNC paths, and invalid drive roots
• Body parser has 1MB request size limit

Residual risk: Low when CDXGEN_SERVER_ALLOWED_PATHS is configured. Medium when unconfigured (any path is scannable).

T2.2 — Git clone exploits

Threat: A client sends a Git URL that exploits Git features to execute code during clone (e.g., ext:: protocol, fd:: protocol, malicious submodules).

Mitigations:

• validateAndRejectGitSource() rejects dangerous protocols (ext::, fd::)
• Validates URL format and hostname against CDXGEN_SERVER_ALLOWED_HOSTS
• Git clone uses hardened configuration:
  • core.fsmonitor=false — disables filesystem monitor hooks
  • safe.bareRepository=explicit — prevents bare repo attacks
  • -c alias.clone= — prevents alias abuse
  • core.hooksPath=/dev/null — disables hook execution entirely
  • --template= — prevents OS hook templates from being copied into the new repo
  • GIT_CONFIG_NOSYSTEM=1 and GIT_CONFIG_GLOBAL=/dev/null in secure mode — prevents reading system/user configs including Git 2.54 hook.<name>.command entries
  • GIT_TERMINAL_PROMPT=0 — prevents interactive prompts
  • --depth 1 — limits history to reduce attack surface
• GIT_ALLOW_PROTOCOL defaults to https:ssh in secure mode

Residual risk: Low — multiple layers of Git hardening are applied.

T2.3 — Server-Side Request Forgery (SSRF)

Threat: A client triggers cdxgen to make HTTP requests to internal hosts via package registry lookups or Git clone URLs.

Mitigations:

• CDXGEN_ALLOWED_HOSTS restricts cdxgenAgent outbound connections
• CDXGEN_SERVER_ALLOWED_HOSTS restricts Git clone target hosts
• Server-side Dependency-Track submission host checks require exact matches or real subdomain matches for wildcard entries (for example, *.example.com matches api.example.com but not evil-example.com)
• Dependency-Track submission redirects are disabled so an allowlisted host cannot bounce uploads to a different destination
• Secure mode enforces HTTPS-only
• Redirect following is disabled in secure mode

Residual risk: Medium — build tools invoked by cdxgen make their own HTTP requests that are not controlled by CDXGEN_ALLOWED_HOSTS.

T2.6 — Registry metadata poisoning for purl requests

Threat: A purl request resolves through registry metadata (repository, homepage, or similar fields) to attacker-controlled repositories.

Mitigations:

• purl-to-repository resolution is restricted to known ecosystems and then validated with git protocol + host allowlists
• Host allowlists can block unexpected repository hosts even when metadata is poisoned
• cdxgen logs warnings when using registry-derived repository URLs

Residual risk: Medium — poisoned metadata can still redirect scans if allowlists are broad or unset.

T2.4 — Denial of service

Threat: A client sends many concurrent requests, very large bodies, or requests for enormous projects to exhaust server resources.

Mitigations:

• Body parser limit: 1MB
• Server timeout: 10 minutes (configurable via CDXGEN_SERVER_TIMEOUT_MS)
• Spawn timeout: 20 minutes (configurable via CDXGEN_TIMEOUT_MS)
• Max buffer: 100MB (configurable via CDXGEN_MAX_BUFFER)

Residual risk: Medium — no built-in rate limiting or concurrent request limits. The server is designed for trusted internal use. Deploy behind a reverse proxy for production exposure.

T2.5 — No authentication or authorization

Threat: Any client that can reach the server can trigger scans, potentially accessing the host filesystem.

Mitigations:

• CDXGEN_SERVER_ALLOWED_PATHS restricts scannable directories
• Users are expected to deploy behind a reverse proxy with authentication
• The server is intended for internal/CI use, not public exposure

Residual risk: High if exposed without access controls. Low in intended deployment behind a reverse proxy.

3. Dependencies

T3.1 — Compromised npm dependency

Threat: A direct or transitive dependency publishes a malicious update that executes code when imported.

Mitigations:

• pnpm-lock.yaml provides reproducible installs with integrity hashes
• pnpm.onlyBuiltDependencies restricts which packages can run install scripts
• Renovate provides automated dependency updates with CI testing
• CodeQL scanning runs on the codebase
• npm provenance attestation on published packages
• Optional heavy dependencies (atom, server middleware) are in optionalDependencies to reduce the attack surface of minimal installs

Residual risk: Medium — supply-chain attacks on npm packages are an industry-wide threat. cdxgen has a moderate dependency tree.

T3.2 — Dependency confusion

Threat: An attacker publishes a malicious package with the same name as a private dependency to a public registry.

Mitigations:

• cdxgen uses only public npm packages; no private registry dependencies
• All dependencies are explicitly versioned in package.json
• pnpm-lock.yaml pins exact versions with integrity hashes

Residual risk: Low.

4. CI/CD Infrastructure

T4.1 — GitHub Actions supply-chain attack

Threat: A compromised GitHub Action or workflow modification injects malicious code into cdxgen releases.

Mitigations:

• All GitHub Actions are pinned to full SHA digests (not mutable tags)
• permissions: {} default (no permissions) at workflow level; explicit per-job grants
• persist-credentials: false on all checkout steps
• npm provenance (NPM_CONFIG_PROVENANCE=true) provides verifiable build attestation
• Concurrency controls prevent parallel release workflows

Residual risk: Low — strong workflow hardening practices are in place.

T4.2 — Self-hosted runner compromise

Threat: A self-hosted CI runner is compromised, allowing an attacker to tamper with builds or access secrets.

Mitigations:

• Self-hosted runners are used only for specific heavy jobs (e.g., depscan analysis)
• Workflow permissions are scoped to specific jobs
• persist-credentials: false limits credential exposure
• Jobs on self-hosted runners do not have release/publish permissions

Residual risk: Medium — self-hosted runners inherently have a larger trust boundary than GitHub-hosted runners.

T4.3 — Release integrity

Threat: An attacker modifies the npm package or container image between build and publish.

Mitigations:

• npm provenance attestation links published packages to specific GitHub Actions runs
• Container base images are pinned to SHA digests
• Multi-platform container builds use consistent base images
• CodeQL analysis runs on PRs and pushes

Residual risk: Low.

5. Container Images

T5.1 — Container escape

Threat: A vulnerability in the container runtime or cdxgen's container configuration allows escaping to the host.

Mitigations:

• cdxgen-secure image runs as non-root user (cyclonedx)
• Node.js --permission model restricts filesystem and child process access within the container
• Limited --allow-fs-write to temp and output directories only
• COMPOSER_ALLOW_SUPERUSER=0 prevents accidental root operations

Residual risk: Low for cdxgen-specific vectors. Container runtime vulnerabilities are the responsibility of the runtime vendor.

T5.2 — Vulnerable base image

Threat: The base container image contains known vulnerabilities.

Mitigations:

• Base images are pinned to SHA digests for reproducibility
• Images are regularly rebuilt with updated dependencies
• CI builds test images before publishing

Residual risk: Low — regular rebuilds reduce the window of vulnerability.

6. SBOM Output

T6.1 — Sensitive data in SBOM

Threat: Generated SBOMs contain sensitive information (file paths, emails, secrets, internal hostnames) that is inadvertently shared.

Mitigations:

• thoughtLog performs limited log normalization (for example, replacing the literal '.' with '<project dir>'), but logs may still include direct or absolute paths
• Warning when --include-formulation is used with --server-url (formulation may contain emails and secrets)
• In secure mode, using --include-formulation with --server-url calls process.exit(1) after the warning, preventing automatic upload of formulation data
• auditEnvironment detects and warns about credential-like environment variables
• Secret-bearing BOM metadata values are sanitized before emission in AI/MCP inventory and Chrome extension metadata flows:
  • URLs and URIs drop userinfo, query strings, and fragments
  • inline credential patterns are redacted
  • raw command strings are reduced to safer summaries such as the executable name
  • dangerous structured keys such as __proto__, constructor, and prototype are removed before JSON serialization
  • Hugging Face widget examples, gated-access forms, and GGUF tokenizer/chat-template payloads are reduced to bounded derivatives instead of being copied verbatim into BOM properties

Residual risk: Medium — SBOMs inherently contain metadata about the project. Users should review SBOMs before sharing, especially when formulation data is included.

T6.2 — SBOM tampering in transit

Threat: An SBOM is modified during upload to a BOM server (Dependency-Track, etc.).

Mitigations:

• Secure mode enforces HTTPS-only for all connections including SBOM upload
• cdxgen supports SBOM signing via SBOM_SIGN_PRIVATE_KEY

Residual risk: Low when secure mode and SBOM signing are enabled.

7. Dynamic Process Tracing (tracebom, lib/helpers/traceRunner.js)

T7.1 — Sandbox bypass or escape during command execution

Threat: The user executes a malicious binary under tracebom --cmd which escapes @cdxgen/safer-exec sandboxing to access the host filesystem or perform network operations.

Mitigations:

• @cdxgen/safer-exec implements kernel-level namespace isolation, Landlock network confinement, and cgroup v2 resource limits on Linux, and Seatbelt sandboxing on macOS.
• Tracing is locked down using LD_AUDIT / DYLD_INSERT_LIBRARIES mechanism enforced securely by the sandbox boundary.
• Configurable sandbox limits (--max-memory, --max-cpu, --max-processes, --timeout, --disable-network, --read-paths, --write-paths, --strict, --sanitize-env, --diff, --block-fork, --trace-exec, --allow-exec, --block-exec, --allow-host, --allow-port, --allow-url) allow operators to restrict the traced process.

T7.2 — Arbitrary command execution on host operating system

Threat: The command supplied to --cmd contains shell metacharacters or executes untrusted binaries directly.

Mitigations:

• traceRunner.js splits and parses the command string into an array of arguments, avoiding shell wrapper execution.
• Command execution is performed via SaferExec class which enforces the standard process constraints and does not run raw strings inside shell wrappers.
• No allowlist enforcement in traceRunner — the CLI operator is trusted to pass safe commands. The sandbox itself is the enforcement mechanism.
• Additional sandbox controls (--allow-exec, --block-exec, --block-fork, --trace-exec) allow restricting which child processes the command can spawn, mitigating post-install script attacks.

Data Flow Diagram

                                     ┌───────────────┐
                                     │ Package       │
                                     │ Registries    │
                                     │ (npm, maven,  │
                                     │  pypi, etc.)  │
                                     └───────┬───────┘
                                             │ HTTP(S)
                                             │ [TB2]
                                             │
┌───────────┐    ┌─────────────────┐  ┌───────▼───────┐     ┌──────────────┐
│ Project   │    │    cdxgen       │  │ Build Tools   │     │ BOM Server   │
│ Files     │───►│  ┌───────────┐  │  │ (npm, mvn,    │     │ (Dependency  │
│(manifests,│    │  │ Parsers   │  │  │  pip, go...)  │     │  Track, etc.)│
│ lockfiles,│    │  └─────┬─────┘  │  └───────────────┘     └──────▲───────┘
│ configs)  │    │        │        │         ▲                     │
└───────────┘    │  ┌─────▼─────┐  │         │ safeSpawnSync       │ SBOM
   [TB4]         │  │ BOM       │  │─────────┘ [TB1]               │ Upload
                 │  │ Builder   │  │                               │
┌──────────┐     │  └─────┬─────┘  │                               │
│ HTTP     │     │        │        │───────────────────────────────┘
│ Client   │────►│  ┌─────▼─────┐  │        HTTP(S) [TB2]
└──────────┘     │  │ Server    │  │
   [TB3]         │  └───────────┘  │
                 └─────────────────┘
                     cdxgen
                     process
                     [TB4, TB5]

TB = Trust Boundary (see Trust Boundaries section above)

Security Controls Summary

Control	Implementation	Threat(s) Addressed
Command allowlisting	CDXGEN_ALLOWED_COMMANDS + safeSpawnSync; HBOM secure-mode dry-run preflight validates declared host-collector commands before live execution	T1.1, T1.2, T1.10
Host allowlisting	CDXGEN_ALLOWED_HOSTS + CDXGEN_GIT_ALLOWED_HOSTS + cdxgenAgent hooks; server-side Dependency-Track submission uses strict wildcard subdomain matching	T2.3, T2.2, T2.6
Path allowlisting	CDXGEN_SERVER_ALLOWED_PATHS + isAllowedPath; HBOM secure-mode dry-run preflight validates declared local collector paths against CDXGEN_ALLOWED_PATHS	T1.10, T2.1
Node.js permission model	--permission flags in NODE_OPTIONS	T1.4, T5.1
Secure mode	CDXGEN_SECURE_MODE=true	T1.2, T2.2, T2.3, T6.2
Environment audit	auditEnvironment() at startup	T1.3
Unicode validation	hasDangerousUnicode(), isValidDriveRoot()	T1.4, T2.1
Git hardening	validateAndRejectGitSource(), hardened clone config	T1.5, T2.2, T2.6
Safe wrappers	safeExistsSync, safeMkdirSync, safeSpawnSync	T1.1, T1.4
BOM metadata sanitization	URL scrubbing, inline secret redaction, command summarization, structured-key filtering	T6.1, T2.3
Helper binary pinning and metadata	Optional helper package version pinning, companion binary SBOM/metadata generation, CI parity checks, and tool identity evidence	T1.8, T4.3
Trust-material modeling	Repository-source data components, trusted-key cryptographic-asset components, file hashes, and repo-to-key dependency edges	T1.9, T6.1
Structured logging	thoughtLog, traceLog, commandsExecuted, remoteHostsAccessed	Auditability for all threats
Dependency pinning	pnpm-lock.yaml, SHA-pinned Actions, SHA-pinned base images	T3.1, T3.2, T4.1
Provenance attestation	NPM_CONFIG_PROVENANCE=true	T4.3
Non-root container	USER cyclonedx in Dockerfile-secure	T5.1
Request limits	Body parser 1MB limit, server timeout, spawn timeout, max buffer	T2.4

Recommendations for Deployers

1. Use secure mode — Set CDXGEN_SECURE_MODE=true and configure NODE_OPTIONS with the Node.js permission model, or use the ghcr.io/cyclonedx/cdxgen-secure container image.
2. Configure allowlists — Set CDXGEN_ALLOWED_HOSTS and CDXGEN_ALLOWED_COMMANDS based on your project types. For HBOM in secure mode, run hbom --dry-run first and use the declared command set as the review baseline before enabling live collection.
3. Restrict paths deliberately — When running HBOM in secure mode, set CDXGEN_ALLOWED_PATHS to the approved local inventory roots for that host profile (for example /proc,/sys,/etc on Linux where appropriate). In server mode, also set CDXGEN_SERVER_ALLOWED_PATHS and CDXGEN_GIT_ALLOWED_HOSTS (or CDXGEN_SERVER_ALLOWED_HOSTS).
4. Deploy server behind a proxy — The cdxgen server has no built-in authentication. Use a reverse proxy (nginx, Envoy, etc.) with authentication and rate limiting.
5. Sandbox untrusted projects — Scan untrusted code in containers or ephemeral CI environments, not on developer machines.
6. Review environment — Check auditEnvironment output for warnings. Remediate HIGH severity findings before production use.
7. Enable trace logging in CI — Set CDXGEN_TRACE_MODE=true in CI pipelines for auditability of commands and network access.
8. Review generated metadata before sharing — Even with built-in redaction, inspect BOM properties when scanning AI/MCP configs, agent instructions, or browser extension manifests.
9. Keep cdxgen updated — Apply updates promptly, especially those that reference security fixes.