# @cdxgen/cdx-hbom 中文文档

规范地址：https://npmcn.com/package/%40cdxgen/cdx-hbom/

版本：0\.8\.0
npm 元数据更新时间：2026-11-06T14:49:13.725Z
中文译文更新时间：2026-11-09T06:54:03.014Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cdxgen/cdx-hbom
原文对照：https://npmcn.com/package/%40cdxgen/cdx-hbom/?lang=original
项目主页：https://github.com/cdxgen/cdx-hbom
源码仓库：https://github.com/cdxgen/cdx-hbom

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：705 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-05-12T23:25:14.341Z
- 最新版本发布：2026-11-06T14:49:13.384Z
- 近 30 天下载量：766053（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

材质发现库无依赖硬件账单.

## 安装

```sh
npm install @cdxgen/cdx-hbom
```

也可以使用：`pnpm add @cdxgen/cdx-hbom`、`yarn add @cdxgen/cdx-hbom`、`bun add @cdxgen/cdx-hbom`

## README

# cdx-hbom (英语)

`cdx-hbom` 是一个小型的,无依赖的硬件单 材料(HBOM)收集器,用于CirponDX BOM工具.

它目前支持以下OS主机:

-   `darwin/arm64` (苹果硅麦克斯)
-   `linux/amd64`
-   `linux/arm64`
-   `win32/amd64`
-   `win32/arm64`

## 安装

### 无

```bash
npm install @cdxgen/cdx-hbom
```

### 日 尔

```bash
npx jsr add @cdxgen/cdx-hbom
```

## 国 际

为当前主机创建硬件目录 :

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

共同选项 :

-   `--pretty` 漂亮地打印 JSON 输出
-   `--dry-run` 块命令执行和跟踪计划收集活动
-   `--platform <value>` 覆盖平台检测
-   `--arch <value>` 覆盖架构检测
-   `--sensitive` 包含原始标识符而不是被编辑的默认
-   `--no-command-enrichment` 禁用基于命令的可选浓缩( Linux 命令; 在 macOS 上, 每个界面 `ifconfig` 财务报告和审定财务报表 `pmset` 调用被跳过;仅在 Windows 上 `windows-cim-platform` 批量运行)
-   `--privileged` 收集需要提高权利的源。 在Linux上,它使特权浓缩和明确的非互动 `sudo -n` 重试选择使用的文件权限敏感命令( 目前) `drm_info`) (中文(简体) ). 在视窗上,它添加 `windows-cim-privileged` (TPM、BitLocker、存储可靠性计数器、, `Confirm-SecureBootUEFI`)),只有管理员才能读取;cdx-hbom从不提升自身,因此从提升的会话运行到获取数据并期望 `permission-denied` 其他诊断
-   `--plist-enrichment` 允许额外的基于达尔文列表的浓缩
-   `--strict` 在浓缩失败时不返回部分结果
-   `--spec-version <value>` 发布 CircleDX 版本 : `1.7` (违约)或 `2.0`。在 [旋风DX 2.0 输出](https://npmcn.com/package/%40cdxgen/cdx-hbom/#readme-cyclonedx-20-output)
-   `--timeout <ms>` 设定每个命令的超时

实例:

```bash
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
```

## 图书馆使用情况

```js
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" }],
  },
});
```

### 从库读取命令诊断

`cdx-hbom` 保持JSON对BOM本身的输出,并在所附的采集器追踪和BOM证据属性中记录可选指令问题.

```js
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"}`,
    );
  }
}
```

也可以通过检查从 BOM 根读取序列化命令诊断 `cdx:hbom:evidence:commandDiagnostic*` 属性.

## 旋风DX 2.0 输出

`collectHardware({ specVersion: "2.0" })` 财务报告和审定财务报表 `--spec-version 2.0` 发射 旋风DX 2.0草案(CycloneDX/规格2.0-dev at `ea8c3605829d1da13339a0790b6da73548e42a6b`) (中文(简体) ). 收藏家们还在建造 1.7 文档; 2.0 信封来自它, 因此1.7 输出不 变化。 在2.0文档中:

-   主机组件是 `inventories[0].subject` 其他组成部分 为: `inventories[0].components`; 每一个 `bom-ref` 变成 `refId`
-   工具条目携带 `version` (当软件包版本不能时离开) 读取,例如,在不包含 `package.json`和 `refId: "pkg:npm/@cdxgen/cdx-hbom"` (保留1.7个工具条目) `{ type, name }`(中文(简体) )
-   `manufacturer` 变成一个 `parties[]` 条目 `manufacturer` 角色
-   `cdx:hbom:hardwareClass` 变成 `classification.category`,以及 `cdx:hbom:pciClassCode` 编号 : `cdx:hbom:usbClass` 变成 `classification.codes` 条目(`{ standard: "PCI-SIG class code" | "USB-IF class code", value }`(中文(简体) )
-   单位标识符`serial-number`, (中文(简体) ), `asset-tag`, (中文(简体) ), `mac-address`, (中文(简体) ), `imei`)仅在收藏随同运行时才被放出 `includeSensitiveIdentifiers` 编号 : `--sensitive` 而该值不是 编辑标记. `model-number` 命名一个产品而不是一个单位,所以 当其值不是编辑标记时,就会释放。 编辑标记 是一个空值或从 `redacted` 或者说 `withheld`比较 没有大小写和周围的空白空间( c)`redacted`, (中文(简体) ), `redacted:<last4>`, (中文(简体) ), `redacted-serial`, (中文(简体) ), `Withheld`(中文(简体) )
-   标识符由 `party-cdx-hbom` 政党(作用) `asserter`, (中文(简体) ), 系统类型 `automation`,与 `system.ref` 设置到 cdx- hbom 工具条目, 否 `ref` 当元数据没有这样的条目时, 以 `definitions.parties` 仅在标识符时 参考
-   `boardLocation` 未释放 : `boardLocation.designators` 预留用于 多氯联苯参考代号,例如: `U5` 或者说 `R12`,所以固件槽标签 例如 `DIMM3` 留下来 `cdx:hbom:*` 属性
-   每个 `cdx:hbom:*` 保存属性

制作自己的 2. 0 文档的工具,例如 cdxgen, 可以重新使用 绘制 `@cdxgen/cdx-hbom/cdx20` 导出 :

```js
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.
```

逐地表在 [文件/硬件-财产](https://npmcn.com/package/%40cdxgen/cdx-hbom/docs/hardware-properties.md#cyclonedx-20-overlap)。 。 。 .

## 目前覆盖的土著富集

`cdx-hbom` 使用固定的命令登记册和以阵列为基础的程序产卵,但上游包装和整装人员负责任何更严格的命令许可名单, `PATH` 硬化,或执行政策控制 围绕收集程序.

### 干流和微量支持

-   `dryRun: true` 块命令执行 `cdx-hbom` 而不是依赖呼叫方的后退.
-   `getCommandPlan()` 曝光静态命令注册,包括模板条目,每个设备或接口在运行时都会解决其具体参数.
-   成功的文件读取和目录发现,加上完成/封锁/失败的命令尝试,都记录在收集器的追踪中.
-   过 `trace: createCollectorTrace()` 将活动收集到呼叫者拥有的分类账中,或稍后通过 `getCollectorTrace(bom)`。 。 。 .
-   所附的痕迹是不可想象的,所以 `JSON.stringify(bom)` 仍然发出一个正常的 CircleDX 文件 .

### 链接

-   `/proc` 财务报告和审定财务报表 `/sys` 基线发现
-   CPU,内存,存储,PCI,USB,DRM显示,音频,MMC/SDIO,和网络库存
-   USB 设备的地貌显示中心等级, 包括每个设备驱动程序、 车道和接口驱动程序
-   USB-C连接器、电子标记电缆和远端对等器 `/sys/class/typec`,有解码数据率、电流、送电瓦、公示电源简介、替代模式和充电判决
-   USB-C同位素与所列举的USB设备和发电节点相关,可用时从UCSI供电中实时充电读取
-   `hwmon`、热区、TPM和NVMe控制器浓缩
-   可选命令浓缩通过 `lscpu`, (中文(简体) ), `lsblk`, (中文(简体) ), `ip`, (中文(简体) ), `lsmem`, (中文(简体) ), `hostnamectl`, (中文(简体) ), `lspci`, (中文(简体) ), `lsusb`, (中文(简体) ), `ethtool`, (中文(简体) ), `cpupower`, (中文(简体) ), `drm_info`, (中文(简体) ), `upower`, (中文(简体) ), `fwupdmgr`, (中文(简体) ), `boltctl`, (中文(简体) ), `mmcli`,以及 `edid-decode`
-   对缺失的公用事业、部分支持和对许可敏感的浓缩进行指令性诊断

如果您想要通过安装可选主机工具来提高 Linux 的浓缩范围, 请参见 [`linux-troubleshooting.md`](https://npmcn.com/package/%40cdxgen/cdx-hbom/linux-troubleshooting.md)。 。 。 .

### 达尔文臂64

-   `system_profiler` 硬件、存储、显示、Wi-Fi、USB、音频、相机、蓝牙、霹雳和电力数据
-   `networksetup` 硬件端口映射
-   现场直播 `ifconfig` 网络接口浓缩
-   可选 plist 浓缩通过 `diskutil`, (中文(简体) ), `diskutil apfs list -plist`,以及 `ioreg`

### 视窗( E)`win32/amd64`, (中文(简体) ), `win32/arm64`(中文(简体) )

Windows 库存来自 CIM/WMI 类和一些注册密钥,由 内置 Windows PowerShell 5.1 (`%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`(中文(简体) ) 每批运行一个固定的单行脚本。 平台值在 bOM是: 英国海洋局 `windows`· ; `--platform windows` 财务报告和审定财务报表 `--platform win32` 双向 这个 一个节点 `os`\- 模块基线(处理器、内存、OS发布)总是 所以PowerShell被屏蔽的宿主 仍然产生有效的BOM.

命令编号及其来源(清单与登记册对照核对: 测试,和 `getCommandPlan({ platform: "win32" })` 返回完整命令 线条 :

-   `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` 财务报告和审定财务报表 `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`; 登记册 `HKLM:\SYSTEM\CurrentControlSet\Control\SecureBoot\State` (单位:千美元)`UEFISecureBootEnabled`; 登记子密钥 `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`; 缩写 `Confirm-SecureBootUEFI`

内容覆盖范围:主机元数据、处理器、内存和内存模块, 板、固件(BIOS)和底盘;存储(`Win32_DiskDrive` 丰富 `MSFT_PhysicalDisk`)和卷;网络和无线适配器;显示 适配器和显示器; 音频控制器和端点;相机; USB 控制器和设备、PCI设备和蓝牙收音机和设备 驱动程序版本和签名及父/子 `dependencies` 图;TPM, 固件装置和电池;以及主机安全态势 (虚拟化安全、代码完整性、安全靴、BitLocker) 音量为 `--privileged`) (中文(简体) ). 财产名称记录于 [`docs/hardware-properties.md`](https://npmcn.com/package/%40cdxgen/cdx-hbom/docs/hardware-properties.md)。 。 。 .

窗口上的选项语义 :

-   `--privileged` 添加 `windows-cim-privileged` 批量(TPM、BitLocker、, 存储可靠性计数器, `Confirm-SecureBootUEFI`) (中文(简体) ). 那些班级否认 (cdx-hbom 从未升级,从未打电话) `sudo.exe` 财务报告和审定财务报表 永远不要提示,所以从一个提升的会话中运行来获取数据. 无 提升批次记录 `permission-denied` 诊断和运行 仍然成功.
-   `--no-command-enrichment` 仅保留 `windows-cim-platform` (和节点) 基线).
-   `--dry-run` 仅生成节点基线并跟踪每个计划 PowerShell 命令为 `blocked`。 。 。 .
-   `--plist-enrichment` 不适用于 Windows.
-   `--timeout <ms>` 超过每个批次的超时(每CIM批次60 s, 90 s为 `windows-pnp-devices`) (中文(简体) ).
-   何时 `powershell.exe` 无法启动( 丢失, 被 AppLocker 、 WDAC 或 命令允许列表)或运行于 Constract Language 模式,设备 库存来自 `pnputil /enum-devices /connected /relations /drivers` (单位:千美元) `windows-fallback` `partial-support` 诊断被记录下来。 pnputil 语录 标签是本地化的,因此一个非英语主机只获得节点基线. 后退命令不在命令计划中; 许可列表必须列出名称 `pnputil.exe` 允许它.
-   命令允许列表条目与 Windows 命令不敏感大小写匹配 (单位:千美元)`POWERSHELL.EXE` 允许 `powershell.exe`); POSIX 命令完全匹配.

权限、 PowerShell 限制、 EDR 允许列表、 慢速提供者和 x64-on-ARM64案件涵盖在以下几起: [`windows-troubleshooting.md`](https://npmcn.com/package/%40cdxgen/cdx-hbom/windows-troubleshooting.md)。 。 。 .

## 权限

简短回答: **运行 cdx- hbom 作为普通本地用户.** 这几乎给了 每一个支持的操作系统上的全部硬件库存. 电梯(管理员或 (b) 增加一些与安全和保健有关的细节。 cdx-hbom 从不提示 对于一个密码, 并且从未在 Windows; 在 Linux 上升级, `--privileged` 重试 几个有文件记录的、非交互命令 `sudo -n`。 。 。 .

| 平台 | 正常用户, 本地会话 | 管理员或根 | SSH 或 WinRM 上的非管理员 |
| --- | --- | --- | --- |
| **马科斯** (苹果硅) | 完整目录; 每个收藏器命令作为普通用户运行 | 没有额外的 | 未计量;预期与当地相同 |
| **链接** | `/proc` 财务报告和审定财务报表 `/sys` 基线加安装的可选工具 | `--privileged` 运行 `dmidecode` 重试 `drm_info` 与非交互式 `sudo -n` (见 [`linux-troubleshooting.md`](https://npmcn.com/package/%40cdxgen/cdx-hbom/linux-troubleshooting.md)(中文(简体) ) | 未计量;预期与当地相同 |
| **窗口** | 几乎所有; 参见测量矩阵 [`windows-troubleshooting.md`](https://npmcn.com/package/%40cdxgen/cdx-hbom/windows-troubleshooting.md#measured-matrix) | `--privileged` 添加 TPM 细节, BitLocker 状态, 固件确认的安全靴状态和磁盘可靠性计数器 | 每个 WMI 查询都被拒绝; 只生成基线( 处理器和内存) , 有一个 `permission-denied` 诊断说明原因 在5个命名空间上授予账户WMI"Remote Election",恢复了本地目录的大部分(参见故障排除页面) |

在Windows上,还有一个细节取决于状态而不是权利:磁盘总线 类型、媒体类型和健康`MSFT_PhysicalDisk`)仅达到标准用户 存储空格 SMP 服务时 (`smphost`) 已经运行中。 这是 在解决问题的一页里解释了.

每个平台的隐私默认:序列号、UUID、MAC地址和 PnP 实例段被修改为 `redacted:<last 4>`; 主机名称, 用户 名称和域名从未被收集。 过 `--sensitive` 仅在生时 需要识别资料.

## 发展

```bash
npm test
```

## 许可证

麻省理工学院

## 常见问题

### @cdxgen/cdx-hbom 是什么？

材质发现库无依赖硬件账单\.

### 如何安装 @cdxgen/cdx-hbom？

在项目目录运行 npm install @cdxgen/cdx-hbom，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cdx-hbom，可以用 npx cdx-hbom 直接运行。

### @cdxgen/cdx-hbom 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cdxgen\_\_cdx-hbom 是否存在。

### @cdxgen/cdx-hbom 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cdxgen/cdx-hbom 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cdxgen/cdx-hbom 可以商用吗？

@cdxgen/cdx-hbom 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cdxgen/cdx-hbom 的下载量有多少？

根据 npm 官方下载统计，@cdxgen/cdx-hbom 在 2026/10/10 – 2026/11/08 这 30 天内被下载 766,053 次，日均约 25,535 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cdxgen/cdx-hbom 还在维护吗？

最新版本 0\.8\.0 发布于 2026/11/06（2 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。