@cyclonedx/cdxgen 12.3.2 → 12.4.0

package/README.md

@@ -16,8 +16,9 @@ cdxgen is a CLI tool, library, [REPL](./ADVANCED.md), and server to create, vali
 
 Supported BOM formats:
 
+- Hardware (HBOM) - For supported live hosts such as Apple Silicon macOS and Linux amd64/arm64 systems.
 - Software (SBOM) - For many languages and container images.
-- Cryptography (CBOM) - For Java and Python projects.
+- Cryptography (CBOM) - For Java keystores and certificates, plus JavaScript and TypeScript source-level algorithm inventory.
 - Operations (OBOM) - For Linux container images and VMs running Linux or Windows operating systems.
 - Software-as-a-Service (SaaSBOM) - For Java, Python, JavaScript, TypeScript, and PHP projects.
 - Attestations (CDXA) - Generate SBOM with templates for multiple standards. Sign the BOM document at a granular level to improve authenticity.
@@ -33,6 +34,7 @@ Supported output document formats:
 | 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]                                      |
+| **Hardware teams**   | Generate an HBOM or merged HBOM+OBOM host view for the current host                    | `hbom -o hbom.json`                                                        | [HBOM guide](docs/HBOM.md), [HBOM lesson](docs/LESSON13.md)                                               |
 | **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] |
@@ -44,6 +46,14 @@ Supported output document formats:
 - 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 hardware and platform teams
+
+- Use `hbom` when you need a CycloneDX hardware inventory for the current host rather than a software dependency graph.
+- Start with the [HBOM guide](docs/HBOM.md) and the [HBOM lesson](docs/LESSON13.md) for supported platforms, enrichment options, and validation workflows.
+- Use `hbom --dry-run` first when you want a read-only partial HBOM plus an exact list of blocked hardware probe commands before a full collection run.
+- Use `hbom diagnostics` when you want a focused summary of missing native utilities and permission-denied enrichments before deciding whether to install host packages or rerun with `--privileged`.
+- Use `hbom --include-runtime` when you want one topology-aware CycloneDX host document that merges hardware inventory with runtime evidence using strict, non-guessing joins.
+
 #### For AppSec
 
 - Use `--profile appsec`, `--evidence`, and `--bom-audit` when you want richer security context.
@@ -51,8 +61,8 @@ Supported output document formats:
 
 #### 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.
+- Use `obom` for live-system and runtime inventory on Linux, Windows, and macOS hosts.
+- Focus on [OBOM lessons](docs/OBOM_LESSONS.md) when you need host triage, persistence review, Linux GTFOBins-backed runtime analysis, hardening drift review, or incident-response evidence.
 
 #### For compliance and platform governance
 
@@ -79,7 +89,7 @@ When you want to inspect what cdxgen would do before allowing side effects, use
 cdxgen --dry-run -p -t js .
 ```
 
-Dry-run mode keeps cdxgen read-only: it reads local files, blocks writes/exec/temp creation/cloning/submission, and prints an activity summary table for both beginners and power users.
+Dry-run mode keeps cdxgen read-only: it reads local files, blocks writes/exec/temp creation/cloning/submission, and prints an activity summary table for both beginners and power users. When available, the recorded activity data also captures archive extraction intent, command I/O volume, and followed symlink-resolution traces.
 
 ## Documentation
 
@@ -89,9 +99,12 @@ Sections include:
 
 - [Getting Started][docs-homepage]
 - [CLI Usage][docs-cli]
+- [HBOM Guide](docs/HBOM.md)
+- [Merged Host View Lesson](docs/LESSON13.md)
 - [Server Usage][docs-server]
 - [Hands-on Lessons](docs/LESSON8.md)
 - [Container Escape & Privilege Lesson](docs/LESSON9.md)
+- [HBOM Lesson](docs/LESSON13.md)
 - [Supported Project Types][docs-project-types]
 - [Environment Variables][docs-env-vars]
 - [Advanced Usage][docs-advanced-usage]
@@ -115,6 +128,7 @@ 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                              |
+| `hbom`          | Generate a CycloneDX hardware BOM for the current host                                               | yes (`hbom`, `hbom-slim`)        |
 | `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                              |
@@ -128,10 +142,14 @@ Installing `@cyclonedx/cdxgen` exposes these commands:
 | `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`.
+Standalone GitHub release binaries are published for `cdxgen`, `cdxgen-slim`, `hbom`, `hbom-slim`, `cdx-audit`, `cdx-convert`, `cdx-sign`, `cdx-validate`, and `cdx-verify`.
+
+`hbom` release binaries bundle both `@cdxgen/cdx-hbom` and the matching `@cdxgen/cdxgen-plugins-bin*` companion helpers for the target platform. `hbom-slim` keeps the dedicated hardware collector (`@cdxgen/cdx-hbom`) but omits the companion plugin bundle when you want the smallest single-file HBOM executable.
 
 `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.
 
+For host inventories, `hbom --include-runtime` produces a merged HBOM + OBOM view with strict topology links such as interface-name, driver-module, storage/runtime, and explicit secure-boot trust matches, plus a `host-topology` BOM audit pack for higher-confidence host findings. When the live hardware collector reports missing utilities or permission-sensitive enrichments, use `hbom diagnostics` (or inspect the derived `cdx:hbom:analysis:*` summary properties) before deciding whether a rerun with `--privileged` is justified.
+
 To run cdxgen without installing (hotloading), use the [pnpm dlx](https://pnpm.io/cli/dlx) command.
 
 ```shell
@@ -146,6 +164,8 @@ 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 hbom --help
+corepack pnpm dlx --package=@cyclonedx/cdxgen hbom diagnostics --help
 corepack pnpm dlx --package=@cyclonedx/cdxgen evinse --help
 corepack pnpm dlx --package=@cyclonedx/cdxgen cdxi --help
 ```
@@ -172,6 +192,10 @@ Common asset names:
 - `cdxgen-linux-amd64-musl`
 - `cdxgen-darwin-arm64`
 - `cdxgen-windows-amd64.exe`
+- `hbom-linux-amd64`
+- `hbom-linux-amd64-slim`
+- `hbom-darwin-arm64`
+- `hbom-windows-amd64.exe`
 - `cdx-audit-linux-amd64`
 - `cdx-audit-darwin-arm64`
 - `cdx-audit-windows-amd64.exe`
@@ -276,17 +300,19 @@ 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) |
+| 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)       |
+| Re-audit a saved OBOM or BOM directly later                | `cdx-audit --bom obom.json --direct-bom-audit --categories obom-runtime`                                    | [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) |
+| Review an offline rootfs for hardening drift               | `cdxgen /absolute/path/to/rootfs -t rootfs -o bom.json --bom-audit --bom-audit-categories rootfs-hardening` | [BOM Audit](docs/BOM_AUDIT.md)       |
 
 For the full option reference, use `cdxgen --help` or visit [CLI Usage][docs-cli].
 
@@ -494,7 +520,7 @@ cdxgen can retain the dependency tree under the `dependencies` attribute for a s
 
 ## Plugins
 
-cdxgen could be extended with external binary plugins to support more SBOM use cases. These are now installed as an optional dependency.
+cdxgen could be extended with external binary plugins to support more SBOM use cases. These are installed as an optional dependency.
 
 ```shell
 sudo npm install -g @cdxgen/cdxgen-plugins-bin
@@ -503,7 +529,7 @@ sudo npm install -g @cdxgen/cdxgen-plugins-bin
 ## Plugins (pnpm)
 
 `cdxgen` can be extended with external binary plugins to support more SBOM use cases.  
-These are now installed as optional dependencies and can be used without a global install.
+These are installed as optional dependencies and can be used without a global install.
 
 ```shell
 pnpm dlx @cdxgen/cdxgen-plugins-bin
@@ -523,6 +549,14 @@ You can also pass `-t docker` with repository names. Only the `latest` tag would
 cdxgen shiftleft/scan-slim -o /tmp/bom.json -t docker
 ```
 
+For offline or staged scans, point cdxgen at a locally reconstructed root filesystem directory. The container pipeline accepts `-t docker`, `-t rootfs`, or `-t oci-dir` for this mode.
+
+```shell
+cdxgen /tmp/remote_target -o /tmp/bom.json -t rootfs
+```
+
+With the packaged helpers installed, rootfs and container BOMs gain repository trust-source components, deep keyring / CA-store `cryptographic-asset` components, native CycloneDX origin fields such as `supplier`, `manufacturer`, and `authors` for OS package trust metadata, plus additional package trust-state properties such as `PackageArchitecture`, `PackageSource`, and `PackageStatus`.
+
 You can also pass the .tar file of a container image.
 
 ```shell
@@ -546,7 +580,7 @@ podman system service -t 0 &
 
 ## 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. Windows and Linux operating systems are supported in this mode.
+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.
 
 ```shell
 # obom is an alias for cdxgen -t os
@@ -554,19 +588,33 @@ obom
 # cdxgen -t os
 ```
 
-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.
+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 platform-specific default queries under `data/queries*.json`. The Linux profile includes dedicated `sysctl_hardening` and `mount_hardening` snapshots, GTFOBins enrichment for privileged and network-active runtime rows, Secure Boot certificate inventory, and improved npm package discovery. When the optional `trustinspector` helper is available, OBOM collection is further enriched with:
+
+- macOS code-signing authority, team ID, and notarization assessment metadata for discovered application paths
+- Windows Authenticode signer/timestamp metadata for discovered executable paths
+- Windows WDAC active-policy inventory
+- batched path inspection so large host inventories keep their trust metadata instead of stopping at the first few hundred paths
+
+Container and rootfs BOMs also summarize how many executable and shared-library file components were discovered outside OS package ownership. Look for `cdx:container:unpackagedExecutableCount` and `cdx:container:unpackagedSharedLibraryCount` in metadata, or use `.unpackagedbins` and `.unpackagedlibs` in `cdxi` for an interactive pivot.
 
-For practical SOC/IR and compliance workflows, see the dedicated [OBOM lessons](./docs/OBOM_LESSONS.md).
+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). For macOS-specific setup and permission caveats, see [OBOM macOS troubleshooting](./docs/OBOM_MACOS_TROUBLESHOOTING.md). For compact before/after examples of the new trust metadata, see [Trust enrichment BOM diff examples](./docs/TRUST_ENRICHMENT_DIFF.md).
 
 ## Generate Cryptography Bill of Materials (CBOM)
 
-Use the `cbom` alias to generate a CBOM. This is currently supported only for Java projects.
+Use the `cbom` alias to generate a CBOM. In addition to keystores and certificates, cdxgen can also derive cryptographic algorithm inventory from JavaScript and TypeScript source by following lightweight constant propagation through common `node:crypto`, WebCrypto, and JWT call sites.
 
 ```shell
 cbom -t java
 # cdxgen -t java --include-crypto -o bom.json .
+
+# Add source-derived crypto algorithms for a JS or TS project
+cdxgen --include-crypto -o bom.json /absolute/path/to/js-project
 ```
 
+When reviewing the result in `cdxi`, use `.cryptos` for the full cryptographic asset view or `.sourcecryptos` to narrow the list to source-derived algorithm components only.
+
 ## Generating SaaSBOM and component evidences
 
 See [evinse mode](./ADVANCED.md) in the advanced documentation.

package/bin/audit.js

@@ -7,11 +7,7 @@ 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 { finalizeAuditReport, runAudit } from "../lib/audit/index.js";
 import { createProgressTracker } from "../lib/audit/progress.js";
 import {
   retrieveCdxgenVersion,
@@ -38,6 +34,17 @@ const args = yargs(hideBin(process.argv))
       "Optional directory to store generated per-purl SBOMs and findings.",
     type: "string",
   })
+  .option("direct-bom-audit", {
+    default: false,
+    description:
+      "Evaluate audit rules directly against the supplied BOM(s) instead of running only the predictive dependency audit.",
+    type: "boolean",
+  })
+  .option("rules-dir", {
+    description:
+      "Directory containing additional YAML audit rules (merged with built-in). Applies to direct BOM audit and predictive child-SBOM rule evaluation.",
+    type: "string",
+  })
   .option("report", {
     choices: ["console", "json", "sarif"],
     default: "console",
@@ -49,9 +56,8 @@ const args = yargs(hideBin(process.argv))
     type: "string",
   })
   .option("categories", {
-    default: DEFAULT_AUDIT_CATEGORIES.join(","),
     description:
-      "Comma-separated rule categories to evaluate for each generated child SBOM.",
+      "Comma-separated rule categories. In predictive mode this applies to generated child SBOMs (default: ai-agent, ci-permission, dependency-source, package-integrity). In direct BOM audit mode it applies to the supplied BOM(s) themselves (default: obom-runtime for OBOMs, all categories otherwise).",
     type: "string",
   })
   .option("min-severity", {
@@ -98,6 +104,11 @@ const args = yargs(hideBin(process.argv))
       "Prioritize direct runtime dependencies ahead of optional, development-only, or platform-specific transitive packages during target selection.",
     type: "boolean",
   })
+  .option("allowlist-file", {
+    description:
+      "Optional JSON array or newline-delimited file of purl prefixes to exclude from predictive audit target selection in addition to the built-in well-known allowlist.",
+    type: "string",
+  })
   .check((argv) => {
     if (!argv.bom && !argv.bomDir) {
       throw new Error("Specify --bom or --bom-dir.");
@@ -162,9 +173,11 @@ function writeOrPrint(output, outputPath) {
   try {
     const reportFile = args.reportFile || args.output;
     const report = await runAudit({
+      allowlistFile: args.allowlistFile,
       bom: args.bom,
       bomDir: args.bomDir,
       categories: splitCsv(args.categories),
+      directBomAudit: args.directBomAudit,
       failSeverity: args.failSeverity,
       maxTargets: args.maxTargets,
       minSeverity: args.minSeverity,
@@ -172,6 +185,7 @@ function writeOrPrint(output, outputPath) {
       prioritizeDirectRuntime: args.prioritizeDirectRuntime,
       report: args.report,
       reportsDir: args.reportsDir,
+      rulesDir: args.rulesDir,
       scope: args.scope === "required" ? "required" : undefined,
       trusted: args.onlyTrusted
         ? "only"