cdx-hbom

cdx-hbom is a small, dependency-free Hardware Bill of Materials (HBOM) collector for CycloneDX BOM tools.

It currently supports following OS hosts:

• darwin/arm64 (Apple Silicon Macs)
• linux/amd64
• linux/arm64
• win32/amd64
• win32/arm64

Install

npm

npm install @cdxgen/cdx-hbom

JSR

npx jsr add @cdxgen/cdx-hbom

CLI

Generate a hardware inventory for the current host:

npx @cdxgen/cdx-hbom --pretty > host-hbom.json

Common options:

• --pretty pretty-print the JSON output
• --dry-run block command execution and trace planned collection activity
• --platform <value> override platform detection
• --arch <value> override architecture detection
• --sensitive include raw identifiers instead of redacted defaults
• --no-command-enrichment disable optional command-based enrichment (Linux commands; on macOS the per-interface ifconfig and pmset calls are skipped; on Windows only the windows-cim-platform batch runs)
• --privileged collect sources that need elevated rights. On Linux this enables privileged enrichment and explicit non-interactive sudo -n retries for documented permission-sensitive commands that opt in (currently drm_info). On Windows it adds the windows-cim-privileged batch (TPM, BitLocker, storage reliability counters, Confirm-SecureBootUEFI), which only administrators can read; cdx-hbom never elevates itself, so run it from an elevated session to get that data and expect permission-denied diagnostics otherwise
• --plist-enrichment enable additional Darwin plist-based enrichment
• --strict fail instead of returning partial results when enrichment fails
• --spec-version <value> CycloneDX version to emit: 1.7 (default) or 2.0. The 2.0 output is described in CycloneDX 2.0 output
• --timeout <ms> set per-command timeout

Examples:

npx @cdxgen/cdx-hbom --pretty
npx @cdxgen/cdx-hbom --privileged --pretty > host-hbom.json
npx @cdxgen/cdx-hbom --plist-enrichment --pretty > mac-hbom.json
npx @cdxgen/cdx-hbom --spec-version 2.0 --pretty > host-hbom-2.0.json

Library usage

import {
  collectHardware,
  createCollectorTrace,
  buildHardwareFromSources,
  getCollectorTrace,
  getCommandPlan,
} from "@cdxgen/cdx-hbom";

const trace = createCollectorTrace();

const bom = await collectHardware({
  dryRun: true,
  includePlistEnrichment: true,
  trace,
});

const collectedTrace = getCollectorTrace(bom) ?? trace;
console.log(collectedTrace.activities);

const plan = getCommandPlan({ platform: "linux", architecture: "amd64" });

// Some plan entries are templates; their final arguments are resolved per
// device or interface at runtime when live collection expands the plan.

const rebuilt = buildHardwareFromSources({
  platform: "linux",
  architecture: "amd64",
  sources: {
    osRelease: { NAME: "Ubuntu", VERSION_ID: "24.04" },
    cpuInfo: [{ processor: "0", "model name": "AMD Ryzen 7" }],
  },
});

Reading command diagnostics from the library

cdx-hbom keeps JSON output on the BOM itself and records optional command issues in the attached collector trace and BOM evidence properties.

import {
  collectHardware,
  createCollectorTrace,
  getCollectorTrace,
} from "@cdxgen/cdx-hbom";

const trace = createCollectorTrace();

const bom = await collectHardware({
  platform: "linux",
  architecture: "amd64",
  includeCommandEnrichment: true,
  includePrivilegedEnrichment: true,
  allowPartial: true,
  trace,
});

const collectedTrace = getCollectorTrace(bom) ?? trace;
const commandDiagnostics = collectedTrace.activities.filter(
  (entry) =>
    entry.kind === "command-diagnostic" || entry.kind === "command-warning",
);

for (const entry of commandDiagnostics) {
  if (entry.issue === "missing-command") {
    console.error(
      `Install hint for ${entry.command}: ${entry.hint ?? "see package docs"}`,
    );
  }

  if (entry.issue === "permission-denied") {
    console.error(
      `Privilege hint for ${entry.command}: ${entry.hint ?? "retry with --privileged"}`,
    );
  }
}

You can also read serialized command diagnostics from the BOM root by inspecting cdx:hbom:evidence:commandDiagnostic* properties.

CycloneDX 2.0 output

collectHardware({ specVersion: "2.0" }) and --spec-version 2.0 emit the CycloneDX 2.0 draft (CycloneDX/specification 2.0-dev at ea8c3605829d1da13339a0790b6da73548e42a6b). The collectors still build the 1.7 document; the 2.0 envelope is derived from it, so the 1.7 output does not change. In the 2.0 document:

• the host component is inventories[0].subject and the other components are inventories[0].components; every bom-ref becomes refId
• the tool entry carries version (left out when the package version cannot be read, for example in a bundle without package.json) and refId: "pkg:npm/@cdxgen/cdx-hbom" (the 1.7 tool entry stays { type, name })
• manufacturer becomes a parties[] entry with the manufacturer role
• cdx:hbom:hardwareClass becomes classification.category, and cdx:hbom:pciClassCode / cdx:hbom:usbClass become classification.codes entries ({ standard: "PCI-SIG class code" | "USB-IF class code", value })
• the per-unit identifiers (serial-number, asset-tag, mac-address, imei) are emitted only when collection ran with includeSensitiveIdentifiers / --sensitive and the value is not a redaction marker. model-number names a product rather than a unit, so it is emitted whenever its value is not a redaction marker. A redaction marker is an empty value or one that starts with redacted or withheld, compared without case and surrounding whitespace (redacted, redacted:<last4>, redacted-serial, Withheld)
• identifiers are asserted by the party-cdx-hbom party (role asserter, system kind automation, with system.ref set to the refId of the cdx-hbom tool entry, or no ref when the metadata has no such entry), which is declared in definitions.parties only when an identifier references it
• boardLocation is not emitted: boardLocation.designators is reserved for PCB reference designators such as U5 or R12, so firmware slot labels such as DIMM3 stay in cdx:hbom:* properties
• every cdx:hbom:* property is kept

Tools that render their own 2.0 documents, such as cdxgen, can reuse the mapping through the @cdxgen/cdx-hbom/cdx20 export:

import { mapCdx20HardwareComponent } from "@cdxgen/cdx-hbom/cdx20";

const { component, partyRefIds } = mapCdx20HardwareComponent(hbomComponent, {
  partyRefId: "party-cdxgen", // a declared party, never a tool refId
  includeSensitiveIdentifiers: false, // default; true only for --sensitive runs
});
// Existing identifiers (for example purl identities) are kept and the hardware
// identities are appended. Declare every refId in partyRefIds in
// definitions.parties.

The field-by-field table is in docs/hardware-properties.md.

Native enrichment currently covered

cdx-hbom uses a fixed command registry and array-based process spawning, but upstream wrappers and integrators are responsible for any stricter command allowlisting, PATH hardening, or execution policy controls around the collector process.

Dry-run and trace support

• dryRun: true blocks command execution inside cdx-hbom itself instead of relying on a caller-side fallback.
• getCommandPlan() exposes the static command registry, including template entries whose concrete arguments are resolved per device or interface at runtime.
• Successful file reads and directory discovery, plus completed/blocked/failed command attempts, are recorded in the collector trace.
• Pass trace: createCollectorTrace() to collect activity into a caller-owned ledger, or read it later via getCollectorTrace(bom).
• The attached trace is non-enumerable, so JSON.stringify(bom) still emits a normal CycloneDX document.

Linux

• /proc and /sys baseline discovery
• CPU, memory, storage, PCI, USB, DRM display, audio, MMC/SDIO, and network inventory
• USB device topology showing the hub hierarchy, with per-device driver, lanes, and interface drivers
• USB-C connectors, electronically marked cables, and the peer on the far end from /sys/class/typec, with decoded data rate, current, delivery wattage, advertised power profiles, alternate modes, and charging verdicts
• USB-C peers correlated to their enumerated USB device and power delivery node, and live charging readouts from the UCSI power supply when available
• hwmon, thermal zones, TPM, and NVMe controller enrichment
• optional command enrichment via lscpu, lsblk, ip, lsmem, hostnamectl, lspci, lsusb, ethtool, cpupower, drm_info, upower, fwupdmgr, boltctl, mmcli, and edid-decode
• command diagnostics for missing utilities, partial support, and permission-sensitive enrichments

If you want to improve Linux enrichment coverage by installing the optional host tools, see linux-troubleshooting.md.

Darwin arm64

• system_profiler hardware, storage, display, Wi-Fi, USB, audio, camera, Bluetooth, Thunderbolt, and power data
• networksetup hardware-port mapping
• live ifconfig network-interface enrichment
• optional plist enrichment via diskutil, diskutil apfs list -plist, and ioreg

Windows (win32/amd64, win32/arm64)

Windows inventory comes from CIM/WMI classes and a few registry keys, read by the built-in Windows PowerShell 5.1 (%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe) running one fixed, single-line script per batch. The platform value emitted in the BOM is windows; --platform windows and --platform win32 both route to it. A Node os-module baseline (processor, memory, OS release) is always produced, so a host where PowerShell is blocked still yields a valid BOM.

The command ids and their sources (the list is checked against the registry by a test, and getCommandPlan({ platform: "win32" }) returns the full command lines):

• windows-cim-platform: root/cimv2: Win32_ComputerSystem, Win32_ComputerSystemProduct, Win32_BIOS, Win32_BaseBoard, Win32_SystemEnclosure, Win32_Processor, Win32_PhysicalMemory, Win32_PhysicalMemoryArray, Win32_OperatingSystem; root/wmi: MS_SystemInformation
• windows-cim-storage-network: root/Microsoft/Windows/Storage: MSFT_PhysicalDisk; root/cimv2: Win32_DiskDrive, Win32_Volume, Win32_NetworkAdapter; root/StandardCimv2: MSFT_NetAdapter, MSFT_NetAdapterHardwareInfoSettingData
• windows-cim-display-media: root/cimv2: Win32_VideoController, Win32_SoundDevice, Win32_PnPEntity; root/wmi: WmiMonitorID, WmiMonitorBasicDisplayParams, WmiMonitorConnectionParams
• windows-pnp-devices: root/cimv2: Win32_PnPEntity, Win32_PnPSignedDriver; Get-PnpDevice -PresentOnly and Get-PnpDeviceProperty (DEVPKEY_Device_Parent, DEVPKEY_Device_LocationPaths, DEVPKEY_Device_DriverVersion, DEVPKEY_Device_DriverProvider, DEVPKEY_Device_DriverDate, DEVPKEY_Device_BusReportedDeviceDesc, DEVPKEY_Device_BusNumber, DEVPKEY_Device_Address)
• windows-cim-trust: root/Microsoft/Windows/DeviceGuard: Win32_DeviceGuard; root/cimv2: Win32_Battery; registry HKLM:\SYSTEM\CurrentControlSet\Control\SecureBoot\State (UEFISecureBootEnabled); registry subkeys of HKLM:\SYSTEM\CurrentControlSet\Control\FirmwareResources (LastAttemptStatus, LastAttemptVersion, Version)
• windows-cim-privileged: root/cimv2/Security/MicrosoftTpm: Win32_Tpm; root/cimv2/Security/MicrosoftVolumeEncryption: Win32_EncryptableVolume; root/Microsoft/Windows/Storage: MSFT_StorageReliabilityCounter; cmdlet Confirm-SecureBootUEFI

Component coverage: host metadata, processor, memory and memory modules, board, firmware (BIOS) and chassis; storage (Win32_DiskDrive enriched from MSFT_PhysicalDisk) and volumes; network and wireless adapters; display adapters and monitors; audio controllers and endpoints; cameras; USB controllers and devices, PCI devices and Bluetooth radios and devices with driver versions and signing and a parent/child dependencies graph; TPM, firmware (ESRT) devices and batteries; and a host security posture (virtualization-based security, code integrity, Secure Boot, BitLocker per volume with --privileged). Property names are documented in docs/hardware-properties.md.

Option semantics on Windows:

• --privileged adds the windows-cim-privileged batch (TPM, BitLocker, storage reliability counters, Confirm-SecureBootUEFI). Those classes deny non-administrators; cdx-hbom never elevates, never calls sudo.exe and never prompts, so run it from an elevated session to get the data. Without elevation the batch records permission-denied diagnostics and the run still succeeds.
• --no-command-enrichment keeps only windows-cim-platform (and the Node baseline).
• --dry-run produces the Node baseline only and traces every planned PowerShell command as blocked.
• --plist-enrichment does not apply to Windows.
• --timeout <ms> overrides the per-batch timeouts (60 s per CIM batch, 90 s for windows-pnp-devices).
• When powershell.exe cannot start (missing, blocked by AppLocker, WDAC or the command allowlist) or runs in Constrained Language Mode, the device inventory comes from pnputil /enum-devices /connected /relations /drivers and a windows-fallback partial-support diagnostic is recorded. pnputil labels are localized, so a non-English host gets the Node baseline only. The fallback command is not in the command plan; an allowlist must name pnputil.exe to permit it.
• Command allowlist entries match Windows commands case-insensitively (POWERSHELL.EXE allows powershell.exe); POSIX commands match exactly.

Permissions, PowerShell restrictions, EDR allowlisting, slow providers and the x64-on-ARM64 case are covered in windows-troubleshooting.md.

Permissions

Short answer: run cdx-hbom as a normal local user. That gives nearly the whole hardware inventory on every supported OS. Elevation (administrator or root) adds a few security- and health-related details. cdx-hbom never prompts for a password and never elevates on Windows; on Linux, --privileged retries a few documented commands with non-interactive sudo -n.

On Windows one more detail depends on state rather than rights: disk bus type, media type and health (MSFT_PhysicalDisk) reach a standard user only while the Storage Spaces SMP service (smphost) is already running. This is explained in the troubleshooting page.

Privacy defaults on every platform: serial numbers, UUIDs, MAC addresses and PnP instance segments are redacted to redacted:<last 4>; host names, user names and domain names are never collected. Pass --sensitive only when raw identifiers are needed.

Development

npm test

License

MIT