jrjsmrtn/ansible-bom

# ansible-bom [](https://github.com/jrjsmrtn/ansible-bom/actions/workflows/ci.yml) [](LICENSE) [](https://pkg.go.dev/github.com/jrjsmrtn/ansible-bom) **锁定实际运行的内容。** `ansible-bom` 会对控制节点上安装的 Ansible 内容（包括 collections *和* 传统 roles）进行盘点，并生成 Ansible Galaxy 从未提供过的 lockfile、针对您的 `requirements.yml` 的漂移报告，以及 CycloneDX bill of materials。 ## 为什么需要 Ansible 的核心承诺是**幂等收敛**（idempotent convergence）：再次运行 playbook，会得到相同的状态。这个承诺暗中假设了模块本身没有发生变化。 在使用未锁定的 collections 和 roles 的情况下（这是默认设置，在实践中也几乎成为了普遍现象），一月份的运行与六月份的运行会通过*不同的代码*来执行一个字节完全相同的 playbook。模块的默认值发生偏移，行为被弃用，bug 被修复同时也被引入。Playbook 是相同的，但收敛结果却不同。生态系统中的任何环节都没有报告这一点。 由此造成的后果是具体的： - **Check 模式不可信** —— 空运行（dry run）只能预测*今天*的模块会做什么。 - **主机漂移难以界定** —— 你无法将配置漂移与工具漂移区分开来。 - **无法进行取证** —— “三月份那台主机上运行了什么代码？”这个问题没有答案。 Ansible Galaxy 没有 lockfile。这个功能曾在现已归档的跟踪器中被提出过请求，在 `mazer` 中实现过一次，并在 2020 年随着它一起被废弃了。与此同时，主流的 SBOM 生成器根本没有对 Ansible 内容进行分类编目 —— `syft` 覆盖了 61 个生态系统；但其中不包括 Ansible。 ## 它的功能 | 命令 | 用途 | |---|---| | `ansible-bom lock` | 从已安装的目录树生成解析后的 lockfile —— 包含每一个处于其确切版本的 collection 和 role | | `ansible-bom drift` | 将已安装的内容与 `requirements.yml` 进行比较：查找未声明的传递性内容、未锁定的声明、版本不匹配、可变的 git 源 | | `ansible-bom scan` | 生成包含 purl 身份标识、文件哈希、许可证和依赖关系图的 CycloneDX BOM | | `ansible-bom verify` | 根据安装时记录的 checksum 检查已安装的文件。它回答的是“自安装以来有什么变化吗？”—— 而不是“这是上游发布的版本吗？”，后者的回答需要 Galaxy 服务器或签名 | 只读、离线、无需 Galaxy 凭证，也不会改变你今天安装内容的方式。 ## 安装 从[最新发布版本](https://github.com/jrjsmrtn/ansible-bom/releases)下载适合你平台的二进制文件， 验证它，并将其放入你的 `PATH` 中： ``` # 调整 version 和 platform curl -fsSLO https://github.com/jrjsmrtn/ansible-bom/releases/download/v0.2.0/ansible-bom_v0.2.0_linux_amd64 curl -fsSLO https://github.com/jrjsmrtn/ansible-bom/releases/download/v0.2.0/SHA256SUMS sha256sum --ignore-missing -c SHA256SUMS chmod +x ansible-bom_v0.2.0_linux_amd64 ``` 每个二进制文件都随附了一份包含其自身 Go 依赖的 CycloneDX SBOM。 或者从源码构建： ``` go install github.com/jrjsmrtn/ansible-bom/cmd/ansible-bom@latest ``` ## 快速开始 ``` # 实际安装的内容，已锁定 ansible-bom lock /path/to/content > ansible-bom.lock.yaml # ...以及一个可安装的 requirements.yml ansible-bom lock --requirements /path/to/content > requirements.lock.yml # 与您声明的配置发生 drift 的内容 ansible-bom drift -r requirements.yml /path/to/content # 一个 CycloneDX bill of materials ansible-bom scan /path/to/content > bom.json # 自安装以来有什么变化吗？ ansible-bom verify /path/to/content ``` *内容根目录*（content root）是一个包含 `ansible_collections/` 和/或 `roles/` 的目录。当它们分开放置时可以传入多个目录，这很常见 —— `ansible.cfg` 决定了它们的位置。 ## 适用人群 - **平台 / IaC 工程师** —— 可重现的控制平面，以及随时间推移依然可靠的幂等性 - **OEM 交付团队** —— 用于已交付基础设施的 xBOM，目前在溯源链中，Ansible 内容是一个缺失环节 - **打包者** —— 用于重新分发内容的权威组件列表 - **SecOps** —— 机器可读的 IaC 清单，可通过你已在运行的 SBOM 工具进行调用 ## 设计说明 有两个事实决定了这个工具的形态，在提交 issue 之前值得了解： **Roles 和 collections 并不等价。** Collections 附带了 `MANIFEST.json` 和 `FILES.json`，其中包含每个文件的 sha256。而 Roles 两者都没有 —— 通过 Galaxy 安装的 role 唯一的溯源信息是 `meta/.galaxy_install_info` 中的一个版本字符串。`ansible-bom` 会报告这两者，并明确指出一个组件处于哪个层级，而不是输出看似等价实则不然的条目。 **标识符在 v1.0 版本前均是暂定的。** 目前还没有注册的 `ansible` purl 类型；[purl-spec#854](https://github.com/package-url/purl-spec/pull/854) 提出了一个但仍然处于开放状态。 0.x 版本会输出提议的格式，并明确标注。**v1.0 会等待该类型被批准*并且*实现之后才推出** —— 1.0 是一项兼容性承诺，如果基于可能还会更改的标识符来发布它，将是不诚实的。 ## 路线图 | 里程碑 | 内容 | 状态 | |---|---|---| | M1 清单 | Collection 和 role 解析；`lock` | 完成 | | M2 漂移 | 针对 `requirements.yml` 的 `drift` | 完成 | | M3 BOM | `scan` —— CycloneDX 输出 | 完成 | | M4 完整性 | 根据记录的 checksum 进行 `verify` | 完成 | | M5 上游 | syft catalogers | 已构建；等待 [anchore/syft#5129](https://github.com/anchore/syft/issues/5129) | | **v1.0** | **取决于 `ansible` purl 类型的批准与实现** | 被上游阻塞 | 里程碑特意设定为*非*版本号。M1–M4 都在 v0.1.x 中发布了，发布版本追踪的是已发布的契约，而不是此列表。 已推迟：collection 签名验证，将 Execution Environment 镜像作为输入，TEA 发布。明确不在范围内：依赖项解析、安装，以及对 playbook 在受管主机上部署内容的建模。 ## 文档 - [SPARK 分析](docs/inception/spark-analysis.md) —— 设计文档：问题、证据、替代方案、风险 - [受众登记表](docs/reference/audience-registry.md) - [架构决策记录](docs/adr/) ## 许可证 [Apache-2.0](LICENSE)。 ## 商标 不隶属于 Red Hat, Inc.，也未获得其认可或赞助。“Ansible”和“Ansible Galaxy”是 Red Hat, Inc. 的商标。本项目仅出于描述性目的使用该名称，以标识其所运行的生态系统。

标签：Ansible, CycloneDX, EVTX分析, Go, Google Gemini, Ruby工具, SBOM, 依赖管理, 日志审计, 硬件无关, 系统提示词