[](https://securityscorecards.dev/viewer/?uri=github.com/bomctl/bomctl)
[](https://goreportcard.com/report/github.com/bomctl/bomctl)
[](https://pkg.go.dev/github.com/bomctl/bomctl)
[](https://slack.openssf.org/#bomctl)
__bomctl__ 是一种与格式无关的软件物料清单（SBOM）工具，旨在弥合 SBOM 生成工具与 SBOM 分析工具之间的差距。它通过坚持仅支持 [NTIA 最小字段](https://www.ntia.doc.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) 或 [protobom](https://github.com/protobom/protobom) 支持的其他字段，专注于对表示系统的多个 SBOM 文件执行更复杂的 SBOM 操作。
- [在我们的 gitpod playground 中试用 `bomctl`](https://gitpod.io/?autostart=true#https://github.com/bomctl/bomctl-playground)
## 功能
- 通过树状结构（借助外部引用）处理多个 SBOM
- 使用多种受支持的协议获取和推送 SBOM
- 利用 `.netrc` 文件处理身份验证
- 使用持久化数据库缓存管理 SBOM
- __未来计划__ - 通过 `diff`、`split` 和 `redact` 等命令操作 SBOM
- __未来计划__ - 与其他 OpenSSF 项目和服务（如 [GUAC](https://guac.sh/) 和 [Sigstore](https://www.sigstore.dev/)）进行交互
## 安装
### Homebrew
```
brew tap bomctl/bomctl && brew install bomctl
```
### 容器镜像
bomctl 的容器镜像可以在 [Docker Hub](https://hub.docker.com/r/bomctl/bomctl) 上找到。
```
docker run bomctl/bomctl:latest --help
```
### 从源码安装
要安装 bomctl，你需要以下条件：
- [Go](https://go.dev/dl)
- [Git](https://git-scm.com/downloads)
- 以下其中之一：
- [Make](https://www.gnu.org/software/make/manual/make.html)
- [Task](https://taskfile.dev)
#### 克隆 bomctl 仓库
```
git clone https://github.com/bomctl/bomctl.git
cd bomctl
```
#### 使用 `make` 或 `task` 构建
| 平台 | `make` 命令 | `task` 命令 |
| :------------ | :----------------------- | :----------------------- |
| linux/amd64 | `make build-linux-amd` | `task build:linux:amd` |
| linux/arm | `make build-linux-arm` | `task build:linux:arm` |
| windows/amd64 | `make build-windows-amd` | `task build:windows:amd` |
| windows/arm | `make build-windows-arm` | `task build:windows:arm` |
| darwin/amd64 | `make build-macos-intel` | `task build:macos:intel` |
| darwin/arm | `make build-macos-apple` | `task build:macos:apple` |
## 命令
`bomctl` 将 SBOM 存储在缓存数据库中，这使得更复杂的跨 SBOM 文档操作成为可能。这是一个基本概念；直接修改的不是文件，而是缓存。
`bomctl` 使用 [protobom library](https://github.com/protobom/protobom) 以与 SBOM 无关的格式存储 SBOM 组件图。当你与 `bomctl` 缓存交互时，实际上是在与 [protobom library](https://github.com/protobom/protobom) 交互。
- 读取 SBOM 并将其加载到缓存中
- [fetch](#fetch)
- [import](#import)
- 对缓存的 SBOM 执行操作
- [alias](#alias)
- [list](#list)
- [merge](#merge)
- [tag](#tag)
- 从缓存中输出 SBOM
- [export](#export)
- [push](#push)
### Alias
编辑 SBOM 文档的别名。
```
bomctl alias [command]
Subcommands:
list List all alias definitions
remove Remove the alias for a specific document
set Set the alias for a specific document
Flags:
-h, --help help for alias
```
### Export
将存储的 SBOM 导出到文件系统
```
bomctl export [flags] SBOM_ID...
Flags:
-e, --encoding CHOICE Output encoding ('xml' supported for CycloneDX formats only) [json, xml] (default json)
-f, --format CHOICE Output format [original, spdx, spdx-2.3, cyclonedx, cyclonedx-1.0, cyclonedx-1.1, cyclonedx-1.2, cyclonedx-1.3, cyclonedx-1.4, cyclonedx-1.5, cyclonedx-1.6] (default original)
-h, --help help for export
-o, --output-file FILE Path to output file
```
### Fetch
支持通过多种协议和 Web API（包括 HTTPS、OCI、Git、GitHub 和 GitLab）检索 SBOM 文件。
```
bomctl fetch [flags] SBOM_URL...
Flags:
--alias string Readable identifier to apply to document
-h, --help help for fetch
--netrc Use .netrc file for authentication to remote hosts
-o, --output-file FILE Path to output file
--tag stringArray Tag(s) to apply to document (can be specified multiple times)
```
这包括递归加载 SBOM 中指向其他 SBOM 的外部引用，并将它们放入持久化缓存中。如果 SBOM 受访问控制，可以使用用户的 [.netrc](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html) 文件进行身份验证。
以下示例将获取这个代表容器镜像的 [CycloneDX SBOM](https://raw.githubusercontent.com/bomctl/bomctl-playground/main/examples/bomctl-container-image/bomctl_bomctl_v0.3.0.cdx.json)，
然后递归获取一个代表该容器镜像中某个应用程序的外部引用 SBOM。
```
bomctl fetch https://raw.githubusercontent.com/bomctl/bomctl-playground/main/examples/bomctl-container-image/bomctl_bomctl_v0.3.0.cdx.json
```
或者，使用以下语法直接获取 GitHub 仓库（本例中为 bomctl 仓库）的最新 dependency graph SBOM。此语法适用于公开和私有仓库，但需要通过 `--netrc` 提供凭据才能访问私有仓库。
```
bomctl fetch https://github.com/bomctl/bomctl
```
也可以通过 [DependencyListExport web API](https://docs.gitlab.com/ee/api/dependency_list_export.html) 使用以下 URL 格式从 GitLab 仓库获取 SBOM。此命令的授权通过将你的 GitLab token 值分配给 `BOMCTL_GITLAB_TOKEN` 环境变量来配置。
```
bomctl fetch https://www.gitlab.com/PROJECT/REPOSITORY@BRANCH
```
### Import
从标准输入或本地文件系统导入 SBOM 文件。
```
bomctl import [flags] { - | FILE...}
Flags:
--alias stringArray Readable identifier(s) to apply to imported document(s) (specify multiple times for multiple documents)
-h, --help help for import
--tag stringArray Tag(s) to apply to all imported documents (can be specified multiple times)
```
### Link
编辑文档和/或节点之间的链接
```
bomctl link [command]
Subcommands:
add Add a link from a document or node to a document
clear Remove all links from specified documents and nodes
list List the links of a document or node
remove Remove specified links from a document or node
Flags:
-h, --help help for link
-t, --type CHOICE Type referenced by SRC_ID [node, document] (default node)
```
### List
列出缓存的 SBOM 文档。
```
bomctl list [flags] SBOM_ID...
Aliases:
list, ls
Flags:
-h, --help help for list
--tag stringArray Tag(s) used to filter documents (can be specified multiple times)
```
### Merge
合并指定的已缓存 SBOM 文档。
```
bomctl merge [flags] DOCUMENT_ID...
Flags:
--alias string Readable identifier to apply to merged document
-h, --help help for merge
-n, --name string Name of merged document
--tag stringArray Tag(s) to apply to merged document (can be specified multiple times)
```
### Push
将存储的 SBOM 文件推送到远程 URL 或文件系统
```
bomctl push [flags] SBOM_ID DEST_PATH
Flags:
-e, --encoding CHOICE Output encoding ('xml' supported for CycloneDX formats only) [json, xml] (default json)
-f, --format CHOICE Output format [original, spdx, spdx-2.3, cyclonedx, cyclonedx-1.0, cyclonedx-1.1, cyclonedx-1.2, cyclonedx-1.3, cyclonedx-1.4, cyclonedx-1.5, cyclonedx-1.6] (default original)
-h, --help help for push
--netrc Use .netrc file for authentication to remote hosts
--tree Recursively push all SBOMs in external reference tree
```
也可以通过 [Generic Package Registry web API](https://docs.gitlab.com/ee/user/packages/generic_packages) 使用以下 URL 格式将 SBOM 作为包推送到 GitLab 仓库。此命令的授权通过将你的 GitLab token 值分配给 `BOMCTL_GITLAB_TOKEN` 环境变量来配置。
```
bomctl push SBOM_ID_OR_ALIAS https://www.gitlab.com/PROJECT/REPOSITORY#PACKAGE_NAME@PACKAGE_VERSION
```
### Tag
编辑 SBOM 文档的标签。
```
bomctl tag [command]
Subcommands:
add Add tags to a document
clear Clear all tags from a document
list List the tags of a document
remove Remove specified tags from a document
Flags:
-h, --help help for tag
```
## 路线图
本项目专注于构建一种架构，以实现对与格式无关的 SBOM 文件集合进行读取、操作和输出。该项目需要一种优先考虑 SBOM 文档内部组件之间以及 SBOM 文档之间关系的架构。
- [完整路线图](ROADMAP.md)
建立此架构后，即可实现更复杂的操作。这些操作包括：
- `diff`
- 生成组件与组件依赖之间的差异
- 生成组件属性的差异
- 以机器可读和人类可读的格式创建差异
- `enrich`
- 使用 [Transparency Exchange API](https://github.com/CycloneDX/transparency-exchange-api) 查找并使用附加数据丰富 sbom 组件。
- 与 [GUAC](https://guac.sh/) 交互
- `merge`
- 合并两个或多个 SBOM 文档中相似组件的字段
- 合并两个或多个 SBOM 文档中的组件及组件依赖
- 将多个 SBOM 文档的组件依赖扁平化为单个 SBOM 文档
- `redact`
- 通过正则表达式或字段名对字段进行脱敏，同时保持对原始文档的可追溯性
- `split`
- 根据 purl 类型或组件标识符将 SBOM 依赖树拆分为多个文件
- `trim`
- 根据 purl 类型或组件标识符修剪 SBOM 依赖树
- __也欢迎你的建议！__
我们使用 [架构决策记录](docs/architecture/README.md) 来跟踪有关 `bomctl` 架构和实现细节的关键决策。已提议但尚未最终确定的决策带有 [adr 标签](https://github.com/bomctl/bomctl/labels/adr)。
## 类似项目
- [Kubernetes bom](https://github.com/kubernetes-sigs/bom) 是一个实用工具，允许你创建、查看和转换软件物料清单（SBOM）。bom 最初是作为为 Kubernetes 项目创建 SBOM 的项目的一部分而创建的。它使软件作者能够以简单而强大的方式为他们的项目生成 SBOM。
- [CycloneDX sbom-utility](https://github.com/CycloneDX/sbom-utility) 旨在成为用于验证、分析和编辑物料清单（BOM）的 API 平台。最初，创建它是为了根据各自标准社区发布的官方版本化 JSON schema 来验证 CycloneDX 或 SPDX 格式的 BOM。
- [Hoppr](https://hoppr.dev/) 是一个基于 Python 插件的框架，用于收集、处理和打包你的软件供应链。
- [sbommerge](https://github.com/anthonyharrison/sbommerge) 将两个软件物料清单（SBOM）文档合并在一起。它支持以 SPDX 和 CycloneDX 格式创建的 SBOM。
## 验证完整性
### 验证容器镜像
`bomctl` 的容器镜像可以在[这里](https://hub.docker.com/r/bomctl/bomctl)找到，并使用 cosign 进行无密钥签名。
然后你可以使用 cosign 验证此容器镜像。
```
cosign verify --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp 'https://github\.com/bomctl/bomctl/\.github/.+' bomctl/bomctl:latest
```
### 验证发布版本
`bomctl` 的发布版本可以在[这里](https://github.com/bomctl/bomctl/releases)找到，并使用 cosign 进行无密钥签名。
然后你可以使用 cosign 验证此制品。
```
cosign verify-blob --certificate ${artifact}-keyless.pem --signature ${artifact}-keyless.sig --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp 'https://github\.com/bomctl/bomctl/\.github/.+' ${artifact}
```
如果结果为 `Verified OK`，则验证成功。
你还可以使用 sha256 哈希值在公开的 Rekor 实例中查找该条目。
```
shasum -a 256 bomctl_SNAPSHOT-3f16bdb_checksums.txt |awk '{print $1}'
```
打印出的 `hash` 可用于在
查找该条目。