/os-hardware-inventory

name: os-hardware-inventory
description: Collects live operating-system inventory (OBOM) and host hardware inventory (HBOM) as CycloneDX documents using the cdxgen obom and hbom commands, including osquery-backed runtime artifacts, Linux hardening snapshots, GTFOBins enrichment, firmware and bus topology, and macOS permission troubleshooting. Use when asked to inventory a live machine, audit a running host's packages or services, produce a hardware BOM, or check host trust posture.

Live OS and hardware inventory

Two distinct documents, two distinct commands. Do not mix them.

| Want | Command | | --------------------------------- | -------------------------------- | | Software on a running machine | `obom` (`cdxgen -t os`) | | Physical hardware of the host | `hbom` | | Offline host from a mounted disk | `-t rootfs` (see `container-sbom`) |

Read [reference/safety.md](../../reference/safety.md) first. Live host collection reads far more of the machine than a project scan, so the dry-run-and-confirm step matters more here, not less.

The hard rule

Never combine `hbom` / `hardware` with software project types such as `js`, `java`, `python`, `os`, or `oci` in one invocation. Generate them separately. If the user wants one merged host document, use `hbom --include-runtime` rather than stacking `-t` flags.

OBOM: live operating-system inventory

obom -o /absolute/path/to/obom.json --deep

`obom` is an alias for `cdxgen -t os`. Aliases `osquery`, `windows`, `linux`, `mac`, `macos`, `darwin` reach the same pipeline.

With a runtime audit:

obom -o /absolute/path/to/obom.json --deep \
  --bom-audit --bom-audit-categories obom-runtime

What Linux OBOM adds

• osquery-derived runtime artifacts: processes, listening ports, users, services, scheduled jobs
• `sysctl_hardening` and `mount_hardening` snapshots
• GTFOBins enrichment on privileged and network-active runtime rows — a shell-escape-capable binary running privileged or listening on the network is the signal worth escalating

macOS OBOM

Collection uses the bundled osquery binary in **shell mode**, which avoids the older `/var/osquery` startup failure. Some tables still require Full Disk Access or elevated privileges.

If tables come back empty or permission-gated, that is a host configuration issue, not a cdxgen bug. Point the user at <https://cdxgen.github.io/cdxgen/#/OBOM_MACOS_TROUBLESHOOTING> rather than retrying the same command.

For live-host triage patterns generally, see <https://cdxgen.github.io/cdxgen/#/OBOM_LESSONS>.

OS trust inventory modelling

Understand the split before interpreting the output:

• **Repository sources** are ordinary `data` components.
• **Trusted keys and certificates** are `cryptographic-asset` components, and they **have no purls**. A missing purl here is correct, not a gap.

HBOM: host hardware inventory

hbom -o /absolute/path/to/hbom.json

Hardware collection comes from the optional `@cdxgen/cdx-hbom` library, loaded only when requested. Supported hosts:

• `darwin/arm64` (Apple Silicon macOS)
• `linux/amd64`
• `linux/arm64`

On an unsupported host, say so directly rather than producing an empty document and calling it a success.

The equivalent library path is `cdxgen -t hbom .`, but prefer the dedicated command.

Merged hardware plus runtime host view

hbom --include-runtime -o /absolute/path/to/host-view.json

This is the supported way to get one document covering both. It also extends the default audit categories to include `host-topology`.

Diagnosing missing collectors

hbom diagnostics

Reports missing native utilities and permission-sensitive enrichments. Run this first when an HBOM comes back sparse — the usual cause is an absent host command, not a collection bug.

Useful hbom flags

| Flag | Effect | | ------------------------- | ---------------------------------------------------------- | | `--include-runtime` | Merge runtime host inventory into the hardware document | | `--privileged` | Enable collectors that need elevated privileges | | `--sensitive` | Include sensitive identifiers (ask the user first) | | `--plist-enrichment` | macOS property-list enrichment | | `--no-command-enrichment` | Skip host command invocation | | `--timeout` | Bound collector runtime | | `--export-proto` | Protobuf output via `--proto-bin-file` | | `--dry-run` | Preview collection without writing |

Treat `--sensitive` as a confirm-first flag. It widens what lands in a document the user may share.

HBOM audit behaviour

For `hbom` / `hardware` targets, cdxgen **skips the predictive dependency audit entirely** and defaults the audit categories to `hbom-security,hbom-performance,hbom-compliance`. With `--include-runtime` it adds `host-topology`.

hbom -o /absolute/path/to/hbom.json --bom-audit
cdx-audit --bom /absolute/path/to/hbom.json --direct-bom-audit --categories hbom

The `hbom` alias expands to the full HBOM review pack in one switch.

Exploring the results

`cdxi` has dedicated commands for both document types (see `bom-explore`):

• OBOM: `.osinfocategories`, `.obomtips`, `.trusted`, `.instrumented`
• HBOM: `.hbomsummary`, `.hbomclasses`, `.hbomevidence`, `.hbomdiagnostics`, `.hbomfirmware`, `.hbombuses`, `.hbompower`, `.hbomtips`

Start with `.hbomsummary` or `.osinfocategories` before drilling into specifics.

Reference

• HBOM guide: <https://cdxgen.github.io/cdxgen/#/HBOM>
• macOS OBOM troubleshooting: <https://cdxgen.github.io/cdxgen/#/OBOM_MACOS_TROUBLESHOOTING>
• OBOM triage patterns: