erlef/mix_sbom
GitHub: erlef/mix_sbom
为 Elixir/Mix 项目自动生成 CycloneDX 格式软件物料清单的工具，由 Erlang Ecosystem Foundation 安全工作组维护。
Stars: 47 | Forks: 20
# SBoM
[](https://github.com/erlef/security-wg)
[](https://github.com/erlef/mix_sbom/actions/workflows/branch_main.yml)
[](https://coveralls.io/github/erlef/mix_sbom?branch=main)
[](https://scorecard.dev/viewer/?uri=github.com/erlef/mix_sbom)
[](https://www.bestpractices.dev/projects/11509)
[](https://api.reuse.software/info/github.com/erlef/mix_sbom)
以 [CycloneDX](https://cyclonedx.org) 格式为 Mix 项目生成软件物料清单。
完整文档可在 [https://hexdocs.pm/sbom](https://hexdocs.pm/sbom) 找到。
有关如何使用此工具的快速演示，请查看[此博客文章](https://blog.voltone.net/post/24)。
## 安装
此工具可以通过多种方式安装：
### 1. 项目依赖（推荐用于开发）
将依赖项添加到项目的 `mix.exs` 中（仅用于开发环境）：
```
def deps do
[
{:sbom, "~> 0.8", only: :dev, runtime: false},
# If using Elixir < 1.18 and want JSON output, also add:
# {:jason, "~> 1.4"}
]
end
```
### 2. Mix Escript（全局安装）
在您的系统上全局安装 Mix 任务：
```
mix escript.install hex sbom
```
### 4. Burrito 二进制文件（从 releases 获取）
从 [releases 页面](https://github.com/erlef/mix_sbom/releases) 下载独立的二进制文件（不需要 BEAM 运行时）。
## 用法
### 作为 Mix 任务（仅限项目依赖）
当作为项目依赖安装时，从包含 `mix.exs` 的项目目录运行：
```
mix sbom.cyclonedx
```
结果将被写入 `bom.cdx.json`，除非使用 `-o` 选项指定了不同的文件名。使用 `--only dev --only test --only prod` 可以包含来自特定环境的依赖。
### 作为独立二进制文件（escript 安装或 Burrito）
当使用全局安装的 escript、下载的 escript 或 Burrito 二进制文件时，您必须将项目路径作为参数提供：
```
# 全局 escript 或下载的 binary
mix_sbom cyclonedx /path/to/your/project
# 或使用 options
mix_sbom cyclonedx --output=my-sbom.json --format=json --only prod \
/path/to/your/project
```
### 常见注意事项
默认情况下，所有环境的依赖都会被包含。若仅包含生产环境依赖，请使用 `--only prod`。要包含特定环境，请使用多个 `--only` 标志，如 `--only dev --only test --only prod`。
*请注意，MIX_ENV 不会影响输出中包含的依赖项；该任务通常应在默认环境 中运行*
### 可用选项
- `-o, --output PATH`：输出文件路径（默认为 `bom.cdx.json`）
使用 `-` 输出到 STDOUT
- `-s, --schema VERSION`：CycloneDX 架构版本 - 1.3、1.4、1.5、1.6、1.7（默认为 1.6）
- `-t, --format FORMAT`：输出格式 - xml、json、protobuf（默认为 json）
- `-l, --only ENV`：仅包含指定环境的依赖（默认为所有环境，使用多个标志可指定多个环境）
- `-a, --targets TARGET`：包含来自指定 Mix 目标的组件（默认为所有目标，使用多个标志可指定多个目标）
- `-c, --classification TYPE`：组件分类类型（默认为 application）。常见类型包括 `application`、`framework` 和 `library`。有关所有可用类型，请参阅 [CycloneDX 文档](https://cyclonedx.org/docs/1.7/json/#components_items_type_enum)。
- `-f, --force`：覆盖现有输出文件
- `-r, --recurse`：递归进入 umbrella 应用程序
- `-x, --exclude-system-dependencies`：从 SBoM 中排除系统依赖（Erlang/OTP、Elixir、Hex）
获取更多信息：
- Mix 任务：`mix help sbom.cyclonedx`
- 独立二进制文件：`mix_sbom --help`
## GitHub Action
此工具也可作为 GitHub Action 用于 CI/CD 工作流。
该 action 会下载并验证二进制文件的来源，然后为您的项目生成 SBoM。
### 基本用法
```
- name: Generate SBoM
uses: erlef/mix_sbom@v0
id: sbom
with:
project-path: ${{ github.workspace }}
schema: "1.6"
format: "json"
- name: Display SBoM
run: cat "$SBOM_FILE"
env:
SBOM_FILE: ${{ steps.sbom.outputs.sbom-path }}
```
### 输入
- `project-path`：包含 mix.exs 的目录路径（默认为仓库根目录）
- `schema`：CycloneDX 架构版本（默认为 "1.6"）
- `format`：输出格式 - "json"、"xml" 或 "protobuf"（默认为 "json"）
- `reuse-beam`：使用本地 BEAM 安装而不是预编译的二进制文件（默认为 "false"）
- `include-system-dependencies`：在 SBoM 中包含系统依赖（Erlang/OTP、Elixir、Hex）（默认为 "true"）
### 输出
- `sbom-path`：生成的 SBoM 文件的路径
该 action 会自动处理为您的运行器架构下载正确的二进制文件，并使用 GitHub 的证明系统验证其来源。
### 使用本地 BEAM（推荐）
为了进行最准确的依赖分析，建议通过设置 `reuse-beam: true` 来使用本地 BEAM 安装。此方法：
- 能在生成的 SBoM 中正确检测 Elixir 和 Erlang 版本
- 可配合您项目的特定运行时环境工作
- 提供更准确的依赖信息
要使用此方法，请首先在工作流中设置 Elixir/Erlang：
```
- name: Set up Elixir
uses: erlef/setup-beam@v1
with:
elixir-version: '1.17.3'
otp-version: '27.1'
- name: Get dependencies
run: mix deps.get
- name: Generate SBoM
uses: erlef/mix_sbom@v0
with:
reuse-beam: true
```
**注意**：为了获得最详细的依赖分析，您应该在使用此操作之前运行 `mix deps.get`，以确保所有依赖都已解析。
## NPM 包和其他依赖
此工具仅考虑通过 Mix 管理的 Hex、GitHub 和 BitBucket 依赖。要构建部署的综合 SBoM（包括 NPM 和/或操作系统包），可能需要将多个 CycloneDX 文件合并为一个。
NPM 上的 [@cyclonedx/bom](https://www.npmjs.com/package/@cyclonedx/bom) 工具不仅能为您的 JavaScript 资产生成 SBoM，还可以通过 `-a` 选项将 `sbom.cyclonedx` Mix 任务及其他扫描器的输出合并为一个单独的 CycloneDX XML 文件。
标签：CycloneDX, DevSecOps, Elixir, Erlang Ecosystem Foundation, Escript, GPT, Hex包, Mix, SBoM, SBOM, 上游代理, 二进制发布, 依赖管理, 安全合规, 开源工具, 漏洞管理, 硬件无关, 网络代理, 跌倒检测, 软件物料清单