📚 课程目录第4章 CycloneDX标准详解

4、CycloneDX标准详解：文档结构、组件与依赖表示、1.4/1.5新特性

聊到SBOM，就绕不开CycloneDX。我个人觉得，它是目前软件供应链安全领域最务实的标准之一。你想想看，一个BOM格式，既要描述清楚组件，又要理清依赖关系，还得能承载漏洞、许可证这些信息——CycloneDX就是干这个的。

这一章，我们把它掰开揉碎。从文档骨架讲起，再到组件怎么表示、依赖怎么建模，最后看看1.4和1.5版本带来了哪些实用的新东西。嗯，我还会分享一些实战中踩过的坑。

4.1 CycloneDX文档结构：从根到叶

一个标准的CycloneDX文档，本质上就是一个JSON或XML文件。它的顶层结构很清晰，我习惯把它想象成一棵树：根节点是bom，下面挂着元数据、组件列表、依赖列表、漏洞信息等分支。

先看一个最简的JSON示例：

{
  "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.5",
  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
  "version": 1,
  "metadata": {
    "timestamp": "2025-03-20T10:00:00Z",
    "tools": [
      {
        "vendor": "MyCompany",
        "name": "bom-generator",
        "version": "1.0.0"
      }
    ],
    "component": {
      "type": "application",
      "name": "my-app",
      "version": "2.1.0"
    }
  },
  "components": [],
  "dependencies": []
}

这里有几个关键字段，我重点说一下：

bomFormat：固定为"CycloneDX"，这是格式标识。
specVersion：版本号，比如1.4或1.5。这个决定了你能用哪些特性。
serialNumber：全局唯一ID。我建议每次生成都换一个新的，方便追踪。
version：BOM自身的版本。如果你更新了同一个组件的BOM，这个版本号要递增。
metadata：元数据。里面可以放工具信息、作者、生命周期阶段等。我个人习惯把生成工具和生成时间写清楚，方便事后溯源。

小技巧： 如果你用Git管理BOM文件，记得把serialNumber和version一起更新。我曾经遇到过两个BOM的serialNumber一模一样，排查了半天才发现是生成脚本忘了刷新UUID。

4.2 组件与依赖表示：怎么描述一个软件零件

组件（component）是BOM的核心。每个组件就是一个软件零件，可以是应用、库、容器镜像、文件等。CycloneDX用type字段来区分：

类型	说明	常见场景
application	应用程序	你的主项目、微服务
library	库	第三方依赖，比如log4j、requests
container	容器镜像	Docker镜像、OCI制品
file	文件	配置文件、脚本、二进制文件
firmware	固件	嵌入式设备、IoT组件

一个完整的组件描述，通常包含这些字段：

{
  "type": "library",
  "name": "log4j-core",
  "version": "2.17.1",
  "purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1",
  "bom-ref": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1",
  "licenses": [
    {
      "license": {
        "id": "Apache-2.0"
      }
    }
  ],
  "hashes": [
    {
      "alg": "SHA-256",
      "content": "a1b2c3d4e5f6..."
    }
  ]
}

这里我特别想强调purl和bom-ref：

purl（Package URL）：一种标准化的包标识符。比如pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1，一看就知道是Maven仓库里的log4j。我建议所有组件都带上purl，这样工具才能自动解析。
bom-ref：组件在BOM内部的唯一引用ID。依赖关系就是靠它来连接的。

依赖表示则更直接。每个依赖项就是一个dependsOn列表：

{
  "dependencies": [
    {
      "ref": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1",
      "dependsOn": [
        "pkg:maven/org.apache.logging.log4j/log4j-api@2.17.1"
      ]
    }
  ]
}

说白了，就是"谁依赖谁"。CycloneDX不要求你写出完整的传递依赖树，但至少直接依赖要写清楚。嗯，这里要注意：如果某个组件没有依赖，你可以不写它的依赖项，或者写一个空的dependsOn列表。

避坑指南： 我曾经在生成BOM时，漏掉了间接依赖。结果安全扫描工具只检查了直接依赖，漏掉了深层的漏洞。后来我强制要求：所有直接依赖的传递依赖，只要出现在组件列表里，就必须在依赖关系里体现。哪怕只是空列表，也要显式声明。

4.3 CycloneDX 1.4/1.5新特性：实用升级

这两个版本带来了不少好东西。我挑几个最常用的说说。

4.3.1 CycloneDX 1.4：服务与漏洞描述

1.4版本最大的亮点是服务组件和漏洞描述的标准化。

服务组件（services）：以前只能描述软件库，现在可以描述API、数据库、消息队列等服务了。比如你的应用依赖一个Redis服务，可以在services字段里声明。
漏洞描述（vulnerabilities）：可以直接在BOM里嵌入漏洞信息。包括CVE编号、严重等级、评分、修复建议等。这样BOM就不仅是清单，还是安全报告。

举个例子，服务组件的写法：

{
  "services": [
    {
      "name": "redis-cache",
      "version": "6.2.6",
      "provider": {
        "name": "MyCompany"
      },
      "endpoints": ["tcp://redis.internal:6379"]
    }
  ]
}

4.3.2 CycloneDX 1.5：配方与证据

1.5版本更进了一步，引入了配方（formulation）和证据（evidence）。

配方：描述构建过程。比如用了什么编译器、什么构建工具、什么环境变量。这对于复现构建非常有用。
证据：证明组件来源的信息。比如代码仓库的commit ID、签名信息、时间戳。说白了，就是"你怎么证明这个组件是可信的"。

我个人觉得，证据是1.5最实用的特性。以前我们只能靠purl来标识组件，但purl本身不保证来源可信。有了evidence，你可以把Git提交哈希、CI构建ID都写进去，审计时一目了然。

  核心观点： 如果你还在用1.3或更早版本，我建议尽快迁移到1.5。证据和配方这两个特性，在供应链安全审计中几乎是刚需。

4.4 使用cyclonedx-bom生成BOM：实战操作

理论讲完了，我们来点实际的。官方提供的cyclonedx-bom工具，可以帮你从现有项目生成BOM。它支持多种语言和包管理器。

安装很简单：

npm install -g @cyclonedx/bom

生成BOM：

cyclonedx-bom -o bom.json

这个命令会扫描当前目录下的package.json、pom.xml、requirements.txt等文件，自动提取依赖并生成BOM。嗯，这里要注意：它只扫描直接依赖，传递依赖需要你自己配置。

如果你需要更精细的控制，可以用配置文件。比如指定输出格式、排除某些组件：

cyclonedx-bom -o bom.xml --format xml --exclude "test-*"

我个人习惯在CI/CD流水线里集成这个工具。每次构建时自动生成BOM，然后上传到制品仓库。这样每个版本都有对应的SBOM，审计时直接拉取就行。

实战建议： 生成BOM后，记得用cyclonedx-cli validate验证一下格式。我曾经因为版本号写错，导致BOM解析失败。验证工具能帮你提前发现问题。

4.5 知识体系总览

下面这张图，把本章的核心知识点串起来了。你可以看到，从文档结构到组件表示，再到版本特性和工具使用，是一条完整的链路。

从这张图可以看出，CycloneDX的核心就是三件事：描述清楚（文档结构）、标识准确（组件与依赖）、信息丰富（版本特性）。而cyclonedx-bom工具，则是把这些理论落地的桥梁。