@cyclonedx/cdxgen 12.2.0 → 12.3.0

package/README.md

@@ -12,7 +12,7 @@
 
 <img src="./docs/_media/cdxgen.png" width="200" height="auto" />
 
-cdxgen is a CLI tool, library, [REPL](./ADVANCED.md), and server to create, validate, sign, and verify [CycloneDX][cyclonedx-homepage] Bill of Materials (BOM) containing an aggregate of all project dependencies in JSON format. CycloneDX is a full-stack BOM specification that is easily created, human and machine-readable, and simple to parse. The tool supports CycloneDX specification versions from 1.5 - 1.7.
+cdxgen is a CLI tool, library, [REPL](./ADVANCED.md), and server to create, validate, sign, and verify software BOMs. It generates CycloneDX JSON BOMs and supports SPDX 3.0.1 JSON-LD export. CycloneDX is a full-stack BOM specification that is easily created, human and machine-readable, and simple to parse. The tool supports CycloneDX specification versions from 1.5 - 1.7.
 
 Supported BOM formats:
 
@@ -23,6 +23,42 @@ Supported BOM formats:
 - Attestations (CDXA) - Generate SBOM with templates for multiple standards. Sign the BOM document at a granular level to improve authenticity.
 - Vulnerability Disclosure Report (VDR) - Use cdxgen with [OWASP depscan](https://github.com/owasp-dep-scan/dep-scan) to automate the generation of VDR at scale.
 
+Supported output document formats:
+
+- CycloneDX JSON (primary native format)
+- SPDX 3.0.1 JSON-LD (`cdxgen --format spdx` or `cdx-convert`)
+
+## Choose your path
+
+| Persona              | What cdxgen helps you do                                                               | First command                                                              | Read next                                                                                                 |
+| -------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Developers**       | Generate a CycloneDX BOM from a local repo, git URL, purl, or container image          | `cdxgen -o bom.json .`                                                     | [CLI Usage][docs-cli], [Supported Project Types][docs-project-types]                                      |
+| **AppSec**           | Enrich BOMs with evidence, run BOM audit rules, and feed downstream security workflows | `cdxgen -o bom.json --profile appsec --evidence --bom-audit .`             | [BOM Audit](docs/BOM_AUDIT.md), [Threat Model](docs/THREAT_MODEL.md)                                      |
+| **SOC analysts**     | Build OBOM inventories for live hosts and triage runtime posture issues                | `obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime` | [OBOM lessons](docs/OBOM_LESSONS.md), [Server Usage][docs-server]                                         |
+| **Compliance teams** | Validate BOM quality, check SCVS/CRA posture, and export SPDX deliverables             | `cdx-validate -i bom.json --benchmark scvs-l2,cra`                         | [cdx-validate](docs/CDX_VALIDATE.md), [cdx-convert](docs/CDX_CONVERT.md), [Permissions][docs-permissions] |
+
+### Role-based quick starts
+
+#### For developers
+
+- Start with a local path, git URL, or purl and generate a BOM in one command.
+- Use [Supported Project Types][docs-project-types] to confirm ecosystem coverage before wiring cdxgen into CI.
+
+#### For AppSec
+
+- Use `--profile appsec`, `--evidence`, and `--bom-audit` when you want richer security context.
+- Combine generation with [BOM Audit](docs/BOM_AUDIT.md), [cdx-validate](docs/CDX_VALIDATE.md), signing, and verification for a fuller secure-SBOM workflow.
+
+#### For SOC analysts
+
+- Use `obom` for live-system and runtime inventory on Linux and Windows hosts.
+- Focus on [OBOM lessons](docs/OBOM_LESSONS.md) when you need host triage, persistence review, LOLBAS-backed Windows startup analysis, or incident-response evidence.
+
+#### For compliance and platform governance
+
+- Use `cdx-validate` to assess structural and compliance posture, then `cdx-convert` when SPDX output is required.
+- Review [Permissions][docs-permissions] and hardened-environment guidance before adopting cdxgen in controlled pipelines.
+
 ## Why cdxgen?
 
 Most SBOM tools are like simple barcode scanners. For easy applications, they can parse a few package manifests and create a list of components only based on these files without any deep inspection. Further, a typical application might have several repos, components, and libraries with complex build requirements. Traditional techniques to generate an SBOM per language or package manifest either do not work in enterprise environments or don't provide the confidence required for both compliance and automated analysis. So we built cdxgen - the universal polyglot SBOM generator that is user-friendly, precise, and comprehensive!
@@ -44,6 +80,8 @@ Sections include:
 - [Getting Started][docs-homepage]
 - [CLI Usage][docs-cli]
 - [Server Usage][docs-server]
+- [Hands-on Lessons](docs/LESSON8.md)
+- [Container Escape & Privilege Lesson](docs/LESSON9.md)
 - [Supported Project Types][docs-project-types]
 - [Environment Variables][docs-env-vars]
 - [Advanced Usage][docs-advanced-usage]
@@ -56,16 +94,52 @@ Sections include:
 
 ## Installing
 
+Install the npm package when you want the full multi-command CLI surface.
+
 ```shell
 npm install -g @cyclonedx/cdxgen
 ```
 
+Installing `@cyclonedx/cdxgen` exposes these commands:
+
+| Command         | Purpose                                                                                              | Standalone GitHub release binary |
+| --------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `cdxgen`        | Generate CycloneDX / SPDX BOMs from source, images, binaries, git URLs, or purls                     | yes                              |
+| `cdx-audit`     | Prioritize existing BOM dependencies for upstream supply-chain review using explainable risk signals | yes                              |
+| `cdx-convert`   | Convert CycloneDX JSON to SPDX 3.0.1 JSON-LD                                                         | yes                              |
+| `cdx-sign`      | Sign BOMs with JSF signatures                                                                        | yes                              |
+| `cdx-validate`  | Validate BOMs and benchmark posture                                                                  | yes                              |
+| `cdx-verify`    | Verify BOM signatures                                                                                | yes                              |
+| `cdxi`          | Open the interactive REPL                                                                            | no                               |
+| `evinse`        | Add evidence, reachability, and service context                                                      | no                               |
+| `cbom`          | Alias for CBOM-oriented `cdxgen` defaults                                                            | use `cdxgen`                     |
+| `obom`          | Alias for `cdxgen -t os`                                                                             | use `cdxgen`                     |
+| `saasbom`       | Alias for SaaSBOM-oriented `cdxgen` defaults                                                         | use `cdxgen`                     |
+| `spdxgen`       | Alias for `cdxgen --format spdx`                                                                     | use `cdxgen`                     |
+| `cdxgen-secure` | Alias for hardened `cdxgen` defaults                                                                 | use `cdxgen`                     |
+
+Standalone GitHub release binaries are published for `cdxgen`, `cdxgen-slim`, `cdx-audit`, `cdx-convert`, `cdx-sign`, `cdx-validate`, and `cdx-verify`.
+
+`cdx-audit` is designed to accelerate upstream dependency review with explainable, evidence-backed risk prioritization. It complements provenance, reproducibility, and manual investigation rather than replacing them.
+
 To run cdxgen without installing (hotloading), use the [pnpm dlx](https://pnpm.io/cli/dlx) command.
 
 ```shell
 corepack pnpm dlx @cyclonedx/cdxgen --help
 ```
 
+You can call any packaged command the same way:
+
+```shell
+corepack pnpm dlx --package=@cyclonedx/cdxgen cdx-audit --help
+corepack pnpm dlx --package=@cyclonedx/cdxgen cdx-convert --help
+corepack pnpm dlx --package=@cyclonedx/cdxgen cdx-validate --help
+corepack pnpm dlx --package=@cyclonedx/cdxgen cdx-sign --help
+corepack pnpm dlx --package=@cyclonedx/cdxgen cdx-verify --help
+corepack pnpm dlx --package=@cyclonedx/cdxgen evinse --help
+corepack pnpm dlx --package=@cyclonedx/cdxgen cdxi --help
+```
+
 If you are a [Homebrew][homebrew-homepage] user, you can also install [cdxgen][homebrew-cdxgen] via:
 
 ```shell
@@ -78,6 +152,86 @@ If you are a [Winget][winget-homepage] user on windows, you can also install cdx
 winget install cdxgen
 ```
 
+### Standalone GitHub release binaries
+
+If you want a single-file executable instead of an npm installation, download a published release asset and verify its hash before executing it.
+
+Common asset names:
+
+- `cdxgen-linux-amd64`
+- `cdxgen-linux-amd64-musl`
+- `cdxgen-darwin-arm64`
+- `cdxgen-windows-amd64.exe`
+- `cdx-audit-linux-amd64`
+- `cdx-audit-darwin-arm64`
+- `cdx-audit-windows-amd64.exe`
+- `cdx-convert-*`, `cdx-sign-*`, `cdx-validate-*`, `cdx-verify-*`
+
+#### Linux
+
+```bash
+VERSION="v12.3.0"
+ASSET="cdx-audit-linux-amd64"
+BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
+
+curl -fsSLO "${BASE_URL}/${ASSET}"
+curl -fsSLO "${BASE_URL}/${ASSET}.sha256"
+sha256sum -c "${ASSET}.sha256"
+chmod +x "${ASSET}"
+./"${ASSET}" --help
+```
+
+#### macOS
+
+```bash
+VERSION="v12.3.0"
+ASSET="cdx-audit-darwin-arm64"
+BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
+
+curl -fsSLO "${BASE_URL}/${ASSET}"
+curl -fsSLO "${BASE_URL}/${ASSET}.sha256"
+shasum -a 256 -c "${ASSET}.sha256"
+chmod +x "${ASSET}"
+./"${ASSET}" --help
+```
+
+#### Windows (PowerShell)
+
+```powershell
+$Version = "v12.3.0"
+$Asset = "cdx-audit-windows-amd64.exe"
+$BaseUrl = "https://github.com/cdxgen/cdxgen/releases/download/$Version"
+
+Invoke-WebRequest -Uri "$BaseUrl/$Asset" -OutFile $Asset
+Invoke-WebRequest -Uri "$BaseUrl/$Asset.sha256" -OutFile "$Asset.sha256"
+$Expected = (Get-Content "$Asset.sha256" | Select-Object -First 1).Trim().Split()[0]
+$Actual = (Get-FileHash $Asset -Algorithm SHA256).Hash.ToLowerInvariant()
+if ($Actual -ne $Expected.ToLowerInvariant()) {
+  throw "SHA256 mismatch for $Asset"
+}
+.\$Asset --help
+```
+
+#### GitHub Actions with the GitHub CLI
+
+```yaml
+permissions:
+  contents: read
+
+steps:
+  - name: Download cdx-audit release binary
+    env:
+      GH_TOKEN: ${{ github.token }}
+    run: |
+      gh release download v12.3.0 \
+        --repo cdxgen/cdxgen \
+        --pattern 'cdx-audit-linux-amd64' \
+        --pattern 'cdx-audit-linux-amd64.sha256'
+      sha256sum -c cdx-audit-linux-amd64.sha256
+      chmod +x cdx-audit-linux-amd64
+      ./cdx-audit-linux-amd64 --help
+```
+
 Deno and bun runtime can be used with limited support.
 
 ```shell
@@ -104,95 +258,42 @@ For the bun version, use `ghcr.io/cyclonedx/cdxgen-bun` as the image name.
 docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen-bun:master -r /app -o /app/bom.json
 ```
 
-In deno applications, cdxgen could be directly imported without any conversion. Please see the section on [integration as a library](#integration-as-library)
+In deno applications, cdxgen could be directly imported without any conversion.
 
 ```ts
-import { createBom, submitBom } from "npm:@cyclonedx/cdxgen@^12.2.0";
-```
-
-## Getting Help
-
-```text
-cdxgen [command]
-
-Commands:
-  cdxgen completion  Generate bash/zsh completion
-
-Options:
-  -o, --output                    Output file. Default bom.json                                    [default: "bom.json"]
-  -t, --type                      Project type. Please refer to https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES for supp
-                                  orted languages/platforms.                                                     [array]
-      --exclude-type              Project types to exclude. Please refer to https://cdxgen.github.io/cdxgen/#/PROJECT_TY
-                                  PES for supported languages/platforms.
-  -r, --recurse                   Recurse mode suitable for mono-repos. Defaults to true. Pass --no-recurse to disable.
-                                                                                               [boolean] [default: true]
-  -p, --print                     Print the SBOM as a table with tree.                                         [boolean]
-  -c, --resolve-class             Resolve class names for packages. jars only for now.                         [boolean]
-      --deep                      Perform deep searches for components. Useful while scanning C/C++ apps, live OS and oc
-                                  i images.                                                                    [boolean]
-      --server-url                Dependency track url. Eg: https://deptrack.cyclonedx.io
-      --skip-dt-tls-check         Skip TLS certificate check when calling Dependency-Track.   [boolean] [default: false]
-      --api-key                   Dependency track api key
-      --project-group             Dependency track project group
-      --project-name              Dependency track project name. Default use the directory name
-      --project-version           Dependency track project version                                [string] [default: ""]
-      --project-tag               Dependency track project tag. Multiple values allowed.                         [array]
-      --project-id                Dependency track project id. Either provide the id or the project name and version tog
-                                  ether                                                                         [string]
-      --parent-project-id         Dependency track parent project id                                            [string]
-      --required-only             Include only the packages with required scope on the SBOM. Would set compositions.aggr
-                                  egate to incomplete unless --no-auto-compositions is passed.                 [boolean]
-      --fail-on-error             Fail if any dependency extractor fails.                                      [boolean]
-      --no-babel                  Do not use babel to perform usage analysis for JavaScript/TypeScript projects.
-                                                                                                               [boolean]
-      --generate-key-and-sign     Generate an RSA public/private key pair and then sign the generated SBOM using JSON We
-                                  b Signatures.                                                                [boolean]
-      --server                    Run cdxgen as a server                                                       [boolean]
-      --server-host               Listen address                                                  [default: "127.0.0.1"]
-      --server-port               Listen port                                                          [default: "9090"]
-      --install-deps              Install dependencies automatically for some projects. Defaults to true but disabled fo
-                                  r containers and oci scans. Use --no-install-deps to disable this feature.
-                                                                                               [boolean] [default: true]
-      --validate                  Validate the generated SBOM using json schema. Defaults to true. Pass --no-validate to
-                                   disable.                                                    [boolean] [default: true]
-      --evidence                  Generate SBOM with evidence for supported languages.        [boolean] [default: false]
-      --spec-version              CycloneDX Specification version to use. Defaults to 1.7
-                                                                   [number] [choices: 1.4, 1.5, 1.6, 1.7] [default: 1.7]
-      --filter                    Filter components containing this word in purl or component.properties.value. Multiple
-                                   values allowed.                                                               [array]
-      --only                      Include components only containing this word in purl. Useful to generate BOM with firs
-                                  t party components alone. Multiple values allowed.                             [array]
-      --author                    The person(s) who created the BOM. Set this value if you're intending the modify the B
-                                  OM and claim authorship.                         [array] [default: "OWASP Foundation"]
-      --profile                   BOM profile to use for generation. Default generic.
-  [choices: "appsec", "research", "operational", "threat-modeling", "license-compliance", "generic", "machine-learning",
-                                                       "ml", "deep-learning", "ml-deep", "ml-tiny"] [default: "generic"]
-      --include-regex             glob pattern to include. This overrides the default pattern used during auto-detection
-                                  .                                                                             [string]
-      --exclude, --exclude-regex  Additional glob pattern(s) to ignore                                           [array]
-      --export-proto              Serialize and export BOM as protobuf binary.                [boolean] [default: false]
-      --proto-bin-file            Path for the serialized protobuf binary.                          [default: "bom.cdx"]
-      --include-formulation       Generate formulation section with git metadata and build tools. Defaults to false.
-                                                                                              [boolean] [default: false]
-      --include-crypto            Include crypto libraries as components.                     [boolean] [default: false]
-      --standard                  The list of standards which may consist of regulations, industry or organizational-spe
-                                  cific standards, maturity models, best practices, or any other requirements which can
-                                  be evaluated against or attested to.
-  [array] [choices: "asvs-5.0", "asvs-4.0.3", "bsimm-v13", "masvs-2.0.0", "nist_ssdf-1.1", "pcissc-secure-slc-1.1", "scv
-                                                                                         s-1.0.0", "ssaf-DRAFT-2023-11"]
-      --json-pretty               Pretty-print the generated BOM json.                        [boolean] [default: false]
-      --min-confidence            Minimum confidence needed for the identity of a component from 0 - 1, where 1 is 100%
-                                  confidence.                                                      [number] [default: 0]
-      --technique                 Analysis technique to use
-  [array] [choices: "auto", "source-code-analysis", "binary-analysis", "manifest-analysis", "hash-comparison", "instrume
-                                                                                                   ntation", "filename"]
-      --auto-compositions         Automatically set compositions when the BOM was filtered. Defaults to true
-                                                                                               [boolean] [default: true]
-  -h, --help                      Show help                                                                    [boolean]
-  -v, --version                   Show version number                                                          [boolean]
-```
-
-All boolean arguments accept `--no` prefix to toggle the behavior.
+import { createBom, submitBom } from "npm:@cyclonedx/cdxgen@^12.2.1";
+```
+
+## Common workflows
+
+| Goal                                                       | First command                                                              | Read next                            |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------ |
+| Generate a BOM from the current repository                 | `cdxgen -o bom.json .`                                                     | [CLI Usage][docs-cli]                |
+| Generate a BOM from a git URL                              | `cdxgen -o bom.json https://github.com/example/project.git`                | [CLI Usage][docs-cli]                |
+| Generate a BOM from a package URL                          | `cdxgen -o bom.json "pkg:npm/lodash@4.17.21"`                              | [CLI Usage][docs-cli]                |
+| Scan a container image                                     | `cdxgen ghcr.io/owasp-dep-scan/depscan:nightly -o bom.json -t docker`      | [Server Usage][docs-server]          |
+| Audit a generated BOM for built-in supply-chain findings   | `cdxgen -o bom.json --bom-audit .`                                         | [BOM Audit](docs/BOM_AUDIT.md)       |
+| Prioritize an existing BOM for upstream risk-driven review | `cdx-audit --bom bom.json`                                                 | [cdx-audit](docs/CDX_AUDIT.md)       |
+| Validate a BOM against structural and compliance checks    | `cdx-validate -i bom.json`                                                 | [cdx-validate](docs/CDX_VALIDATE.md) |
+| Convert CycloneDX JSON to SPDX JSON-LD                     | `cdx-convert -i bom.json -o bom.spdx.json`                                 | [cdx-convert](docs/CDX_CONVERT.md)   |
+| Generate an OBOM for live-system triage                    | `obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime` | [OBOM lessons](docs/OBOM_LESSONS.md) |
+
+For the full option reference, use `cdxgen --help` or visit [CLI Usage][docs-cli].
+
+Companion commands also expose built-in help:
+
+- `cbom --help`
+- `cdx-audit --help`
+- `cdx-validate --help`
+- `cdx-convert --help`
+- `cdx-sign --help`
+- `cdx-verify --help`
+- `cdxgen-secure --help`
+- `cdxi --help`
+- `evinse --help`
+- `obom --help`
+- `saasbom --help`
+- `spdxgen --help`
 
 ## Example
 
@@ -202,6 +303,25 @@ Minimal example.
 cdxgen -o bom.json
 ```
 
+The primary positional input can be:
+
+- a local filesystem path (default: current directory)
+- a git URL that cdxgen clones before scanning
+- a package URL (purl) that cdxgen resolves to source and then scans
+
+Common source input examples:
+
+```shell
+# Local path
+cdxgen -o bom.json .
+
+# Git URL
+cdxgen -t java -o bom.json --git-branch main https://github.com/HooliCorp/java-sec-code.git
+
+# Package URL (purl)
+cdxgen -t js -o bom.json "pkg:npm/lodash@4.17.21"
+```
+
 For a java project. cdxgen would automatically detect maven, gradle, or sbt and build bom accordingly
 
 ```shell
@@ -220,6 +340,24 @@ To recursively generate a single BOM for all languages pass `-r` argument.
 cdxgen -r -o bom.json
 ```
 
+To generate an SBOM directly from a git URL:
+
+```shell
+cdxgen -t java -o bom.json --git-branch main https://github.com/HooliCorp/java-sec-code.git
+```
+
+This works anywhere cdxgen expects its primary source input, so a git URL can be used in place of `.` or any other local path.
+
+To generate an SBOM from a package URL (purl), cdxgen resolves registry metadata to a repository URL, clones it, and scans it:
+
+```shell
+cdxgen -t js -o bom.json "pkg:npm/lodash@4.17.21"
+```
+
+Supported purl source types: `npm`, `pypi`, `gem`, `cargo`, `pub`, `github`, `bitbucket`, `maven` (version required), `composer`, and `generic` (with `vcs_url` or `download_url` qualifier).
+
+> **Warning:** Repository URLs resolved from registries may be inaccurate or malicious. Review resolved sources before trusting generated output.
+
 The default specification used by cdxgen is 1.7. To generate BOM for a different specification version, such as 1.5 or 1.6, pass the version number using the `--spec-version` argument.
 
 ```shell
@@ -408,6 +546,8 @@ obom
 
 This feature is powered by osquery, which is [installed](https://github.com/cdxgen/cdxgen-plugins-bin/blob/main/build.sh#L8) along with the binary plugins. cdxgen would opportunistically try to detect as many components, apps, and extensions as possible using the [default queries](data/queries.json). The process would take several minutes and result in an SBOM file with thousands of components of various types, such as operating-system, device-drivers, files, and data.
 
+For practical SOC/IR and compliance workflows, see the dedicated [OBOM lessons](./docs/OBOM_LESSONS.md).
+
 ## Generate Cryptography Bill of Materials (CBOM)
 
 Use the `cbom` alias to generate a CBOM. This is currently supported only for Java projects.
@@ -496,7 +636,19 @@ cdxgen can automatically detect names of services from YAML manifests such as do
 
 ## Conversion to SPDX format
 
-Use the [CycloneDX CLI][cyclonedx-cli-github] tool for advanced use cases such as conversion, diff and merging.
+For direct conversion of an existing CycloneDX JSON BOM to SPDX JSON-LD, use
+the bundled `cdx-convert` command:
+
+```shell
+cdx-convert -i bom.json -o bom.spdx.json
+```
+
+`cdx-convert` currently supports CycloneDX 1.6 and 1.7 inputs and exports
+SPDX 3.0.1 JSON-LD.
+
+Use `cdxgen --format spdx` (or `--format cyclonedx,spdx`) when generating BOMs.
+Use the [CycloneDX CLI][cyclonedx-cli-github] tool for advanced use cases such
+as diff and merging.
 
 ## Including .NET Global Assembly Cache dependencies in the results
 
@@ -642,7 +794,7 @@ Copy the below block to your markdown files to show your ❤️ for cdxgen.
 [docs-permissions]: https://cdxgen.github.io/cdxgen/#/PERMISSIONS
 [docs-project-types]: https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES
 [docs-server]: https://cdxgen.github.io/cdxgen/#/SERVER
-[docs-support]: https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES
+[docs-support]: https://cdxgen.github.io/cdxgen/#/SUPPORT
 
 <!-- web links-->
 

package/bin/audit.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+import { writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import {
+  DEFAULT_AUDIT_CATEGORIES,
+  finalizeAuditReport,
+  runAudit,
+} from "../lib/audit/index.js";
+import { createProgressTracker } from "../lib/audit/progress.js";
+import {
+  retrieveCdxgenVersion,
+  safeExistsSync,
+  safeMkdirSync,
+} from "../lib/helpers/utils.js";
+
+const args = yargs(hideBin(process.argv))
+  .option("bom", {
+    description: "Path to a CycloneDX JSON BOM file.",
+    type: "string",
+  })
+  .option("bom-dir", {
+    description: "Directory containing one or more CycloneDX JSON BOM files.",
+    type: "string",
+  })
+  .option("workspace-dir", {
+    description:
+      "Optional directory to reuse git clones for purl-to-source enrichment.",
+    type: "string",
+  })
+  .option("reports-dir", {
+    description:
+      "Optional directory to store generated per-purl SBOMs and findings.",
+    type: "string",
+  })
+  .option("report", {
+    choices: ["console", "json", "sarif"],
+    default: "console",
+    description: "Output format.",
+  })
+  .option("report-file", {
+    alias: "o",
+    description: "Write the report to this file. Defaults to stdout.",
+    type: "string",
+  })
+  .option("categories", {
+    default: DEFAULT_AUDIT_CATEGORIES.join(","),
+    description:
+      "Comma-separated rule categories to evaluate for each generated child SBOM.",
+    type: "string",
+  })
+  .option("min-severity", {
+    choices: ["low", "medium", "high", "critical"],
+    default: "low",
+    description:
+      "Minimum final target severity to include in console or SARIF output.",
+    type: "string",
+  })
+  .option("fail-severity", {
+    choices: ["low", "medium", "high", "critical"],
+    default: "high",
+    description:
+      "Exit with code 3 when any target reaches this final severity or above.",
+    type: "string",
+  })
+  .option("max-targets", {
+    description:
+      "Optional safety limit for the number of unique npm/PyPI purls to analyze.",
+    type: "number",
+  })
+  .option("scope", {
+    choices: ["all", "required"],
+    default: "all",
+    description:
+      "Target selection scope. Use 'required' to scan only components with CycloneDX scope=required (missing scope is treated as required).",
+    type: "string",
+  })
+  .option("include-trusted", {
+    default: false,
+    description:
+      "Include packages already marked with trusted publishing metadata in predictive audit target selection.",
+    type: "boolean",
+  })
+  .option("only-trusted", {
+    default: false,
+    description:
+      "Restrict predictive audit target selection to packages marked with trusted publishing metadata.",
+    type: "boolean",
+  })
+  .check((argv) => {
+    if (!argv.bom && !argv.bomDir) {
+      throw new Error("Specify --bom or --bom-dir.");
+    }
+    if (argv.bom && argv.bomDir) {
+      throw new Error("Use either --bom or --bom-dir, not both.");
+    }
+    if (argv.output && argv.reportFile) {
+      throw new Error("Use either --report-file or --output, not both.");
+    }
+    if (argv.includeTrusted && argv.onlyTrusted) {
+      throw new Error(
+        "Use either --include-trusted or --only-trusted, not both.",
+      );
+    }
+    return true;
+  })
+  .completion("completion", "Generate bash/zsh completion")
+  .epilogue("for documentation, visit https://cdxgen.github.io/cdxgen")
+  .scriptName("cdx-audit")
+  .version(retrieveCdxgenVersion())
+  .help()
+  .wrap(Math.min(120, yargs().terminalWidth())).argv;
+
+/**
+ * Split a CSV option into a normalized string array.
+ *
+ * @param {string | undefined} value CSV string
+ * @returns {string[] | undefined} parsed values
+ */
+function splitCsv(value) {
+  if (!value) {
+    return undefined;
+  }
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Print or write rendered report output.
+ *
+ * @param {string} output rendered output
+ * @param {string | undefined} outputPath optional file path
+ * @returns {void}
+ */
+function writeOrPrint(output, outputPath) {
+  if (!outputPath) {
+    process.stdout.write(output);
+    return;
+  }
+  const parentDir = dirname(outputPath);
+  if (!safeExistsSync(parentDir)) {
+    safeMkdirSync(parentDir, { recursive: true });
+  }
+  writeFileSync(outputPath, output);
+}
+
+(async () => {
+  const progressTracker = createProgressTracker();
+  try {
+    const reportFile = args.reportFile || args.output;
+    const report = await runAudit({
+      bom: args.bom,
+      bomDir: args.bomDir,
+      categories: splitCsv(args.categories),
+      failSeverity: args.failSeverity,
+      maxTargets: args.maxTargets,
+      minSeverity: args.minSeverity,
+      onProgress: progressTracker.onProgress,
+      report: args.report,
+      reportsDir: args.reportsDir,
+      scope: args.scope === "required" ? "required" : undefined,
+      trusted: args.onlyTrusted
+        ? "only"
+        : args.includeTrusted
+          ? "include"
+          : undefined,
+      trustedSelectionHelp:
+        "Use --include-trusted to include them or --only-trusted to audit just those packages.",
+      workspaceDir: args.workspaceDir,
+    });
+    const finalized = finalizeAuditReport(report, {
+      failSeverity: args.failSeverity,
+      minSeverity: args.minSeverity,
+      report: args.report,
+    });
+    writeOrPrint(finalized.output, reportFile);
+    process.exit(finalized.exitCode);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  } finally {
+    progressTracker.stop();
+  }
+})();