lfreleng-actions/sbom-action
GitHub: lfreleng-actions/sbom-action
该 Action 基于 syft 为任意语言的项目生成 CycloneDX 格式的 SBOM，解决供应链组件清单自动化产出的需求。
Stars: 0 | Forks: 1
[](https://linuxfoundation.org/) [](https://github.com/lfreleng-actions/sbom-action) [](https://opensource.org/licenses/Apache-2.0) [![pre-commit.ci status badge]][pre-commit.ci results page] [](https://scorecard.dev/viewer/?uri=github.com/lfreleng-actions/sbom-action)
为任何语言/生态系统的项目生成 CycloneDX 软件物料清单 (SBOM) 报告。
## sbom-action
此 Action 在可插拔的 SBOM 生成后端之上提供了一个通用接口。默认后端包装了 [syft](https://github.com/anchore/syft)，它对 lockfile 和文件系统内容执行静态分析，通过单一工具涵盖 Go modules、Node.js/npm、Java、Rust、容器、二进制文件及其他生态系统。Syft 与本组织可重用工作流用于在独立下游作业中审计生成的 SBOM 的 [Grype](https://github.com/anchore/grype) 共享同一供应商。
该接口借鉴了 [python-sbom-action](https://github.com/lfreleng-actions/python-sbom-action)，为整个 Action 资产中的调用者提供统一的契约。未来的后端（如 `cyclonedx-npm`、`cyclonedx-gomod` 或基于环境的 Python 后端）可以通过 `backend` 输入接入同一接口，而无需更改调用工作流。
## 用法示例
```
steps:
- name: "Generate SBOM"
id: sbom
uses: lfreleng-actions/sbom-action@main
with:
path_prefix: '.'
```
## 要求
该 Action 需要在 runner 上安装 `jq`、`realpath`（GNU coreutils，包括对 `-m` 的支持）和 `mktemp`。GitHub 托管的 Ubuntu runner 包含这些工具；最小化的自托管或非 Linux runner 必须自行提供。该 Action 会在开始时检查它们，如果缺少任何工具，将失败并明确指出缺少的工具名称。syft 二进制文件通过锁定的 `anchore/sbom-action/download-syft` 辅助程序下载，因此 runner 需要能够访问 GitHub release 资产。
## 输入
| 名称 | 必需 | 默认值 | 描述 |
| ----------------- | -------- | ---------------- | --------------------------------------------------------------------- |
| backend | False | `syft` | SBOM 生成后端；支持 `syft` |
| path_prefix | False | `.` | 项目目录；必须解析到工作区内 |
| sbom_format | False | `both` | SBOM 输出格式：`json`、`xml` 或 `both` |
| sbom_spec_version | False | `1.5` | 要使用的 CycloneDX 规范版本 |
| filename_prefix | False | `sbom-cyclonedx` | SBOM 输出的基础文件名（不带扩展名） |
| output_directory | False | `.` | SBOM 报告目录，位于工作区或 runner 临时目录内 |
| include_dev | False | `false` | 在 SBOM 中包含开发依赖 |
| fail_on_error | False | `true` | 如果 SBOM 生成遇到错误则使 Action 失败 |
| syft_version | False | `''` | 要下载的 Syft 版本（默认为安装程序锁定的版本） |
## 输出
| 名称 | 描述 |
| --------------- | ------------------------------------------ |
| sbom_json_path | 生成的 JSON SBOM 文件的路径 |
| sbom_xml_path | 生成的 XML SBOM 文件的路径 |
| component_count | 生成的 SBOM 中的组件数量 |
| backend | 使用的 SBOM 生成后端 |
此 Action 会针对 `json` 和 `both` 格式输出 `sbom_json_path`，针对 `xml` 和 `both` 格式输出 `sbom_xml_path`；如果调用者未请求某种格式，则该格式的输出保持为空。
## 路径约束
`path_prefix` 和 `output_directory` 的相对值会根据 `GITHUB_WORKSPACE` 而不是当前工作目录进行解析，因此当调用工作流设置自定义工作目录时，行为将保持确定性。此 Action 在使用前会针对 runner 文件系统检查这两个目录输入：`path_prefix` 必须解析到 `GITHUB_WORKSPACE` 内，而 `output_directory` 必须解析到 `GITHUB_WORKSPACE` 或 `RUNNER_TEMP` 内。逃逸出这些位置的路径将导致 Action 失败，从而防止扫描或写入 runner 文件系统上的任意位置。
## 开发依赖范围界定
`include_dev` 输入控制是否将开发依赖包含在 SBOM 中。syft 后端会将其映射到其 JavaScript cataloger (`SYFT_JAVASCRIPT_INCLUDE_DEV_DEPENDENCIES`)，因此对于 Node.js 项目，SBOM 默认仅涵盖生产环境依赖。Go modules 没有开发范围的概念，因此此输入在那里不起作用。随着 syft 暴露出更多选项，将进一步添加每个生态系统的范围界定选项。
## Monorepo 和嵌套模块支持
将 `path_prefix` 指向包含项目 lockfile/manifest 的目录。这支持模块不在仓库根目录的仓库，例如托管在 Gerrit 上的 monorepo（如 `onap/multicloud-k8s`），其中 Go modules 位于 `src/` 下：
```
steps:
- name: "Generate SBOM for nested module"
uses: lfreleng-actions/sbom-action@main
with:
path_prefix: 'src/k8splugin'
```
## 工作流集成
本组织中的可重用工作流将 SBOM 生成和 SBOM 审计保留在单独的作业中，并通过 artifact 进行连接。生成作业运行此 Action 并上传结果；下游作业下载它们并使用 Grype 进行审计。这种分离保持了失败模式的独立性，即使在审计失败时也能保留 SBOM 以供检查：
```
- name: "Generate SBOM"
id: sbom
uses: lfreleng-actions/sbom-action@main
- name: "Upload SBOM artifact"
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: sbom-files
path: sbom-cyclonedx.*
if-no-files-found: error
```
## 实现细节
1. **输入验证**：在使用前验证后端、格式、布尔标志、规范版本和文件名前缀（受限字符集）；验证项目目录是否存在
2. **Syft 下载**：通过锁定的 `anchore/sbom-action/download-syft` 辅助 Action 获取 syft 二进制文件
3. **SBOM 生成**：运行单个 syft 扫描，生成请求的 CycloneDX 格式（`format@version=path` 语法）；JSON 文档始终在内部生成，以计算组件数量
4. **输出和摘要**：输出所请求格式的路径、组件数量和步骤摘要
## 注意事项
- 生成的文件名遵循本组织可重用工作流所使用的 `sbom-cyclonedx.*` 命名约定（即 `sbom-files` artifact 契约）
- 静态分析在不安装项目依赖的情况下读取 lockfile/manifest，因此生成速度快且不需要任何语言工具链
- 对于 Python 项目，建议使用 [python-sbom-action](https://github.com/lfreleng-actions/python-sbom-action)：其基于环境的生成方式能为解析出的 Python 依赖图提供更高保真度的结果
标签：DevSecOps, GitHub Actions, LLM防护, SBOM生成, 上游代理, 组件分析, 自动笔记