CycloneDX/cyclonedx-cli
GitHub: CycloneDX/cyclonedx-cli
CycloneDX 官方命令行工具，提供 SBOM 的分析、合并、差异比对、格式转换及签名验证等全流程处理能力，助力软件供应链安全与合规管理。
Stars: 462 | Forks: 76
[](https://hub.docker.com/r/cyclonedx/cyclonedx-cli)
[](LICENSE)
[](https://cyclonedx.org/)
[](https://cyclonedx.org/slack/invite)
[](https://groups.io/g/CycloneDX)
[](https://twitter.com/CycloneDX_Spec)
```
______ __ ____ _ __ ________ ____
/ ____/_ _______/ /___ ____ ___ / __ \ |/ / / ____/ / / _/
/ / / / / / ___/ / __ \/ __ \/ _ \/ / / / / / / / / / /
/ /___/ /_/ / /__/ / /_/ / / / / __/ /_/ / | / /___/ /____/ /
\____/\__, /\___/_/\____/_/ /_/\___/_____/_/|_| \____/_____/___/
/____/
Usage:
cyclonedx [command] [options]
Options:
--version Show version information
-?, -h, --help Show help and usage information
Commands:
add Add information to a BOM (currently supports files)
analyze Analyze a BOM file
convert Convert between different BOM formats
diff Generate a BOM diff
keygen Generates an RSA public/private key pair for BOM signing
merge Merge two or more BOMs
sign Sign a BOM or file
validate Validate a BOM
verify Verify signatures in a BOM
```
CycloneDX CLI 工具目前支持 BOM 分析、修改、差异比对、合并、格式转换、签名和验证。
支持在 CycloneDX XML、JSON、Protobuf、CSV 和 SPDX JSON v2.3 之间进行转换。
二进制文件可以从[发布页面](https://github.com/CycloneDX/cyclonedx-cli/releases)下载。
注意：CycloneDX CLI 工具是为自动化用例构建的。任何具有 `--input-file` 选项的命令也支持从 stdin 输入。同样，任何具有 `--output-file` 选项的命令都支持输出到 stdout。但是，您需要提供输入/输出格式。
例如：
`cat bom.json | cyclonedx-cli convert --input-format json --output-format xml > bom.xml`
# 命令
## Add 命令
### Add File 子命令
```
files
Add files to a BOM
Usage:
cyclonedx add files [options]
Options:
--input-file Input BOM filename.
--no-input Use this option to indicate that there is no input BOM.
--output-file Output BOM filename, will write to stdout if no value provided.
--input-format Specify input file format.
--output-format Specify output file format.
--base-path Base path for directory to process (defaults to current working directory if omitted).
--include Apache Ant style path and file patterns to specify what to include (defaults to all files, separate patterns with a space).
--exclude Apache Ant style path and file patterns to specify what to exclude (defaults to none, separate patterns with a space).
```
#### 示例
生成源代码 BOM，排除 Git 仓库目录：
`cyclonedx-cli add files --no-input --output-format json --exclude /.git/**`
将 `bin` 目录中的构建输出文件添加到现有 BOM 中：
`cyclonedx-cli add files --input-file bom.json --output-format json --base-path bin`
## Analyze 命令
```
analyze
Analyze a BOM file
Usage:
cyclonedx analyze [options]
Options:
--input-file Input BOM filename, will read from stdin if no value provided.
--input-format Specify input file format.
--output-format Specify output format (defaults to text).
--multiple-component-versions Report components that have multiple versions in use.
```
### 示例
报告包含不同版本的多次组件：
`cyclonedx-cli analyze --input-file sbom.xml --multiple-component-versions`
## Convert 命令
```
convert
Convert between different BOM formats
Usage:
cyclonedx convert [options]
Options:
--input-file Input BOM filename, will read from stdin if no value provided.
--output-file Output BOM filename, will write to stdout if no value provided.
--input-format Specify input file format.
--output-format Specify output file format.
--output-version Specify output BOM specification version. (ignored for CSV and SPDX formats)
```
### 示例
从 XML 转换为 JSON 格式：
`cyclonedx-cli convert --input-file sbom.xml --output-file sbom.json`
从 XML 转换为 JSON 格式并将输出通过管道传递给其他工具：
`cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"`
### CSV 格式
CSV 格式是对 BOM 中组件列表的有限表示。
其目的是为用户提供一种简单的方法，以便在简单的用例中生成和使用 BOM。包括简单的数据迁移用例。
唯一必需的字段是组件的 `name` 和 `version` 字段。其他字段可以留空或省略列。
[example.csv](example.csv)
### SPDX 格式
在 SPDX 和 CycloneDX 格式之间转换可能会导致某些信息丢失。转换功能由 `CycloneDX.Spdx.Interop` 库提供，该库是 CycloneDX .NET 库项目的一部分。
有关丢失哪些信息的更多详细信息，请参阅 [CycloneDX .NET 库项目页面](https://github.com/CycloneDX/cyclonedx-dotnet-library)。
## Diff 命令
```
diff
Generate a BOM diff
Usage:
cyclonedx diff [options]
Arguments:
From BOM filename.
To BOM filename.
Options:
--from-format Specify from file format.
--to-format Specify to file format.
--output-format Specify output format (defaults to text).
--component-versions Report component versions that have been added, removed or modified.
```
### 示例
报告版本发生变化的组件：
`cyclonedx-cli diff sbom-from.xml sbom-to.xml --component-versions`
## Keygen 命令
```
keygen
Generates an RSA public/private key pair for BOM signing
Usage:
cyclonedx keygen [options]
Options:
--private-key-file Filename for generated private key file (defaults to "private.key")
--public-key-file Filename for generated public key file (defaults to "public.key")
```
## Merge 命令
```
merge
Merge two or more BOMs
Usage:
cyclonedx merge [options]
Options:
--input-files Input BOM filenames (separate filenames with a space).
--output-file Output BOM filename, will write to stdout if no value provided.
--input-format Specify input file format.
--output-format Specify output file format.
--output-version Specify output BOM specification version.
--hierarchical Perform a hierarchical merge.
--group Provide the group of software the merged BOM describes.
--name Provide the name of software the merged BOM describes (required for hierarchical merging).
--version Provide the version of software the merged BOM describes (required for hierarchical merging).
```
注意：要执行分层合并，所有 BOM 都需要在 metadata component 元素中描述 BOM 的主题。
### 示例
合并两个 XML 格式的 BOM：
`cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-file sbom_all.xml`
合并两个 BOM 并将输出通过管道传递给其他工具：
`cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-format json | grep "something"`
## Sign 命令
对 BOM 或文件进行签名
### Sign Bom 子命令
```
bom
Sign the entire BOM document
Usage:
cyclonedx sign bom [options]
Arguments:
BOM filename
Options:
--key-file Signing key filename (RSA private key in PEM format, defaults to "private.key")
```
### Sign File 子命令
```
file
Sign arbitrary files and generate a PKCS1 RSA SHA256 signature file
Usage:
cyclonedx sign file [options]
Arguments:
Filename of the file the signature will be created for
Options:
--key-file Signing key filename (RSA private key in PEM format, defaults to "private.key")
--signature-file Filename of the generated signature file (defaults to the filename with ".sig" appended)
```
## Validate 命令
```
validate
Validate a BOM
Usage:
cyclonedx validate [options]
Options:
--input-file Input BOM filename, will read from stdin if no value provided.
--input-format Specify input file format.
--input-version Specify input file specification version (defaults to v1.7)
--fail-on-errors Fail on validation errors (return a non-zero exit code)
```
### 示例
验证 BOM 并返回非零退出代码（便于自动“中断”构建等）
`cyclonedx-cli validate --input-file sbom.xml --fail-on-errors`
## Verify 命令
验证 BOM 和文件的签名
### Verify All 子命令
```
all
Verify all signatures in a BOM
Usage:
cyclonedx verify all [options]
Arguments:
BOM filename
Options:
--key-file Public key filename (RSA public key in PEM format, defaults to "public.key")
```
### Verify File 子命令
```
file
Verifies a PKCS1 RSA SHA256 signature file for an arbitrary file
Usage:
cyclonedx verify file [options]
Arguments:
File the signature file is for
Options:
--key-file Public key filename (RSA public key in PEM format, defaults to "public.key")
--signature-file Signature file to be verified (defaults to the filename with ".sig" appended)
```
# Docker 镜像
CycloneDX CLI 工具也可以使用 docker `docker run cyclonedx/cyclonedx-cli` 运行。
# Homebrew
对于 Linux 和 MacOS，可以通过 [CycloneDX Homebrew tap](https://github.com/CycloneDX/homebrew-cyclonedx) 安装 CLI：
```
brew install cyclonedx/cyclonedx/cyclonedx-cli
```
# 支持的平台
以下平台提供官方支持的构建：
- Windows x64 (win-x64)
- Linux x64 (linux-x64)
- Linux musl x64 (linux-musl-x64, 包括 Alpine Linux)
- MacOS x64 (osx-x64)
以下平台提供社区支持的构建：
- Windows x86 (win-x86)
- Windows ARM x64 (win-arm64)
- Linux ARM (linux-arm)
- Linux ARM x64 (linux-arm64)
- MacOS ARM x64 (osx-arm64)
需要 .NET Core 运行时依赖项。
对于 Windows，这些应该是预装的。
对于 Ubuntu，这些是 libc6 libgcc1 libgssapi-krb5-2 libicu66 libssl1.1 libstdc++6 zlib1g。
# 使用 gron 进行临时搜索和分析
_gron 将 JSON 转换为离散赋值，以便更容易 grep 您想要的内容并查看其绝对“路径”。_
为方便起见，gron 包含在 CycloneDX CLI Docker 镜像中。
列出所有组件名称和版本的示例用法
```
$ gron bom-1.2.json | grep -E "(components\[[[:digit:]]*\].name)|(components\[[[:digit:]]*\].version)"
json.components[0].name = "tomcat-catalina";
json.components[0].version = "9.0.14";
json.components[1].name = "mylibrary";
json.components[1].version = "1.0.0";
```
或者使用 XML 格式的 BOM 进行相同操作
```
$ cyclonedx convert --input-file bom.xml --output-format json | gron | grep -E "(components\[[[:digit:]]*\].name)|(components\[[[:digit:]]*\].version)"
json.components[0].name = "tomcat-catalina";
json.components[0].version = "9.0.14";
json.components[1].name = "mylibrary";
json.components[1].version = "1.0.0";
```
有关 gron 用法的更多详细信息，请参阅 [gron 项目页面](https://github.com/TomNomNom/gron)。
有关 grep 用法的更多详细信息，请参阅 [grep 手册页](https://www.man7.org/linux/man-pages/man1/grep.1.html)。
## 许可证
在 Apache 2.0 许可证的条款下，授予修改和重新分发的权限。有关完整许可证，请参阅 [LICENSE] 文件。
## 贡献
欢迎提交 Pull requests。但请先阅读 [CycloneDX 贡献指南](https://github.com/CycloneDX/.github/blob/master/CONTRIBUTING.md)。
要在本地构建和测试解决方案，您应该安装 .NET 8。`dotnet build` 和 `dotnet test` 等标准命令有效。
通常期望 Pull requests 包含相关测试。
测试会在 Windows、MacOS 和 Linux 上针对每个 Pull request 自动运行。
构建警告将中断构建。
如果您在调试无法访问的平台上失败的测试时遇到问题，请告诉我们。
标签：BOM合并, BOM差异分析, CycloneDX, DevSecOps, Docker, GPT, JSON, protobuf, SBOM, SPDX, WebSocket, XML, 上游代理, 代码签名, 依赖分析, 占用监测, 多人体追踪, 安全防御评估, 开源合规, 文档安全, 文档结构分析, 格式转换, 漏洞管理, 硬件无关, 网络安全, 请求拦截, 资产管理, 跌倒检测, 软件物料清单, 隐私保护