@cdxgen/cdxgen 13.1.0 → 13.3.0

package/README.md

@@ -41,7 +41,7 @@ Supported output document formats:
 | **Build engineers**   | Grade how completely the SBOM captured the project, and get ranked fixes when the build environment degraded it      | `cdxgen --profile introspect --introspect-fail-below 70 -o bom.json .`     | [Build Introspection](docs/INTROSPECTION.md), [Fidelity loop skill](.agents/skills/sbom-fidelity-loop/SKILL.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]       |
-| **Security Teams**    | Dynamically trace executions to capture cryptographic activities, CBOM properties, software components, and services | `tracebom --cbom-output cbom.json -- npm test`                             | [Threat Model](docs/THREAT_MODEL.md)                                                                            |
+| **Security Teams**    | Dynamically trace executions to capture cryptographic activities, CBOM properties, software components, and services | `tracebom --cmd "npm test" --trace-crypto -o cbom.json`                    | [Threat Model](docs/THREAT_MODEL.md)                                                                            |
 
 ### Role-based quick starts
 
@@ -216,7 +216,7 @@ Common asset names:
 #### Linux
 
 ```bash
-VERSION="v13.1.0"
+VERSION="v13.3.0"
 ASSET="cdx-audit-linux-amd64"
 BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
 
@@ -230,7 +230,7 @@ chmod +x "${ASSET}"
 #### macOS
 
 ```bash
-VERSION="v13.1.0"
+VERSION="v13.3.0"
 ASSET="cdx-audit-darwin-arm64"
 BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
 
@@ -244,7 +244,7 @@ chmod +x "${ASSET}"
 #### Windows (PowerShell)
 
 ```powershell
-$Version = "v13.1.0"
+$Version = "v13.3.0"
 $Asset = "cdx-audit-windows-amd64.exe"
 $BaseUrl = "https://github.com/cdxgen/cdxgen/releases/download/$Version"
 
@@ -269,7 +269,7 @@ steps:
     env:
       GH_TOKEN: ${{ github.token }}
     run: |
-      gh release download v13.1.0 \
+      gh release download v13.3.0 \
         --repo cdxgen/cdxgen \
         --pattern 'cdx-audit-linux-amd64' \
         --pattern 'cdx-audit-linux-amd64.sha256'
@@ -391,7 +391,7 @@ import { createBom, submitBom } from "npm:@cdxgen/cdxgen@^13";
 | 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]                           |
-| Generate a dynamically traced CBOM for an application      | `tracebom --cbom-output cbom.json -- npm test`                                                              | [Threat Model](docs/THREAT_MODEL.md)            |
+| Generate a dynamically traced CBOM for an application      | `tracebom --cmd "npm test" --trace-crypto -o cbom.json`                                                     | [Threat Model](docs/THREAT_MODEL.md)            |
 | Generate and audit an AI-BOM from the current repository   | `cdxgen -r --include-formulation -o aibom.json --bom-audit --bom-audit-categories ai-bom .`                 | [AI-BOM Guide](docs/AI_BOM.md)                  |
 | 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)                  |
@@ -497,14 +497,13 @@ Use repeated `--component-type` values to include only selected CycloneDX compon
 cdxgen -t docker alpine:3.20 --spec-version 1.6 --component-type library --component-type data
 ```
 
-To generate SBOM for C or Python, ensure Java >= 21 is installed.
+To generate SBOM for C or Python, cdxgen uses the bundled atom companion. On linux-amd64, linux-arm64 (glibc), linux-amd64-musl, darwin-arm64, and windows-amd64, atom ships as a native binary and needs no JDK. Only the jar-based triples (darwin-amd64, windows-arm64, and linux-arm64-musl) run atom on the JVM.
 
 ```shell
-# Install java >= 21
 cdxgen -t c -o bom.json
 ```
 
-NOTE: cdxgen is known to freeze with Java 8 or 11, so ensure >= 21 is installed and JAVA_HOME environment variable is configured correctly. If in doubt, use the cdxgen container image.
+NOTE: On the jar-based triples, atom requires Java >= 23 and is known to freeze with Java 8 or 11, so ensure a suitable version is installed and the JAVA_HOME environment variable is configured correctly. If in doubt, use the cdxgen container image.
 
 ## Universal SBOM
 
@@ -684,6 +683,17 @@ systemctl --user start podman.socket
 podman system service -t 0 &
 ```
 
+### WSL Containers (wslc) on Windows
+
+On Windows, Docker Desktop is optional when [WSL Containers][wsl-containers-docs] is available. cdxgen automatically uses the `wslc` CLI (included with WSL 2.9.3 or higher) to pull, inspect, and export images whenever the docker CLI is not installed, so image scans such as the below work with just WSL:
+
+```shell
+wsl --update
+cdxgen alpine:latest -t oci -o bom.json
+```
+
+Set `DOCKER_CMD=wslc` to prefer wslc even when a docker CLI is installed. See [Generating container SBOM on Windows](./ADVANCED.md#generating-container-sbom-on-windows) for requirements, including the nested virtualization needed when Windows itself runs inside a VM.
+
 ## Generate OBOM for a live system
 
 You can use the `obom` command to generate an OBOM for a live system or a VM for compliance and vulnerability management purposes. Linux, Windows, and macOS are supported in this mode, though some macOS tables require elevated privileges and Full Disk Access.
@@ -733,12 +743,16 @@ cdxgen features a best-in-class, native **JSON Signature Format (JSF)** implemen
 
 To enable automatic signing during BOM generation, set the following environment variables:
 
-- `SBOM_SIGN_ALGORITHM`: JSF Algorithm. Examples: `RS512`, `ES256`, `Ed25519`, `HS256`
-- `SBOM_SIGN_PRIVATE_KEY`: Location of the private key (PEM format)
-- `SBOM_SIGN_PUBLIC_KEY`: Optional. Location of the public key
+- `SBOM_SIGN_ALGORITHM`: JSF Algorithm. Examples: `RS512`, `ES256`, `Ed25519`, `HS256`. It must match the key type.
+- `SBOM_SIGN_PRIVATE_KEY`: Location of the private key (PEM format), or of the shared secret for `HS256`, `HS384`, and `HS512`
+- `SBOM_SIGN_PUBLIC_KEY`: Optional. Location of the public key to embed. It must belong to the private key.
 - `SBOM_SIGN_MODE`: Optional. Signature mode (`replace`, `signers`, `chain`). Default is `replace`.
 
-To quickly generate test public/private key pairs and sign your first BOM, you can run cdxgen with the `--generate-key-and-sign` argument.
+To quickly generate a test key pair for `SBOM_SIGN_ALGORITHM` and sign your first BOM, you can run cdxgen with the `--generate-key-and-sign` argument.
+
+When signing is configured (`SBOM_SIGN_ALGORITHM` plus a private key), cdxgen signs the BOM it writes, prints, or submits to Dependency-Track, and exits with status 1 if it cannot sign it, including when the key file is missing. A private key without `SBOM_SIGN_ALGORITHM` leaves the BOM unsigned and prints a warning; set `SBOM_SIGN_ALGORITHM=none` to opt out explicitly.
+
+BOMs signed with cdxgen 13.2.0 or earlier must be re-signed with the current `cdx-sign` before they verify. See [cdx-sign](docs/CDX_SIGN.md#re-signing-boms-from-earlier-releases).
 
 ### Advanced Signing with `cdx-sign`
 
@@ -786,13 +800,15 @@ pnpm dlx @cdxgen/cdxgen cdx-sign -i bom.json -k private.key
 
 ## Automatic usage detection
 
-For node.js projects, lock files are parsed initially, so the SBOM would include all dependencies, including dev ones. An AST parser powered by babel-parser is then used to detect packages that are imported and used by non-test code. Such imported packages would automatically set their scope property to `required` in the resulting SBOM. You can turn off this analysis by passing the argument `--no-babel`. Scope property would then be set based on the `dev` attribute in the lock file.
+For node.js projects, lock files are parsed initially, so the SBOM would include all dependencies, including dev ones. An AST parser powered by babel-parser is then used to detect packages that are imported and used by non-test code. Such imported packages would automatically set their scope property to `required` in the resulting SBOM. A package with no observed usage keeps the scope from the lock file, since packages loaded from configuration, bundler entrypoints, stylesheets, or plugins are invisible to import analysis. A package imported only for its TypeScript types is scoped `excluded`, and a package that only such packages depend on is scoped `optional`. You can turn off this analysis by passing the argument `--no-babel`. Scope property would then be set based on the `dev` attribute in the lock file.
+
+Single-file component frameworks are handled natively by this analysis: `.vue` and `.svelte` templates are segmented position-preservingly so script imports recover with correct file and line evidence. For Svelte and SvelteKit, framework usage signals are additionally collected — SvelteKit virtual modules such as `$app/stores` are attributed to `@sveltejs/kit`, `$lib/*` imports resolve through `kit.alias`, `svelte.config.js` adapters and preprocessors, CSS preprocessor packages implied by `<style lang="...">` blocks together with their `@use`/`@import` package references, npm script executables such as `svelte-kit sync` and `svelte-check`, and rune usage (`$state`, `$derived`, ...) which marks `svelte` required even in components that never import it. This works in every installation; when the optional `@appthreat/atom-parsetools` package is present, template expressions also contribute usage occurrences.
 
 This attribute can be later used for various purposes. For example, [dep-scan][depscan-github] uses this attribute to prioritize vulnerabilities. Unfortunately, tools such as dependency track, do not include this feature and might over-report the CVEs.
 
 With the argument `--required-only`, you can limit the SBOM only to include packages with the scope "required", commonly called production or non-dev dependencies. Combine with `--no-babel` to limit this list to only non-dev dependencies based on the `dev` attribute being false in the lock files.
 
-For go, `go mod why` command is used to identify required packages. For php, composer lock file is parsed to distinguish required (packages) from optional (packages-dev).
+For go, `go list -deps` lists the modules the project's packages import, and a module is scoped `required` when go.mod requires it directly and `optional` when the requirement is `// indirect`. With `USE_GOSUM=true`, `go mod why` scopes each go.sum module instead: `required` when the main module needs it, and `optional` when go reports that it does not. If `go mod why` fails, no module is scoped `optional`. For php, composer lock file is parsed to distinguish required (packages) from optional (packages-dev).
 
 ## Automatic services detection
 
@@ -980,4 +996,5 @@ Copy the below block to your markdown files to show your ❤️ for cdxgen.
 [npmjs-cdxgen-v12]: https://www.npmjs.com/package/@cyclonedx/cdxgen
 [podman-github-rootless]: https://github.com/containers/podman/blob/master/docs/tutorials/rootless_tutorial.md
 [podman-github-remote]: https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md
+[wsl-containers-docs]: https://learn.microsoft.com/en-us/windows/wsl/wsl-container
 [swh-cdxgen]: https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/cdxgen/cdxgen