NWarila/ubi9-application-template

# Ubi9 应用模板 构建最小 Red Hat UBI 9 运行时镜像的OCI镜像仓库的参考模板。构建阶段是 `ubi-minimal`，运行阶段是 `ubi-micro`，两者都使用 `@sha256` 锁定；运行时根文件系统使用 `dnf --installroot` 组装，以便安装的软件包保持可枚举。它作为一个完全工作的示例提供：一个小型 Go 二进制文件，真实的锁定上游摘要，一个由清单驱动的构建管道，以及所有在CI中端到端运行的运行时加固断言。 模板故意不是针对特定应用的。示例应用故意无用，以便关注供应链形状。 ## 前置条件 合约检查只需要 Python；镜像生命周期需要 Docker： - Python 3.12+ - Bash，用于构建和运行时加固脚本 - Docker Buildx，当构建镜像或重新构建示例二进制文件时 ## 快速入门 运行合约检查（无需 Docker）： ``` python tools/verify.py ci ``` 从头到尾构建示例镜像（需要 Docker）： ``` make image ``` `make image` 在一个摘要锁定的 `golang` 容器中构建示例 Go 二进制文件，验证生成的 SHA256 与提交的清单相匹配，从清单生成 docker buildx 标志，构建 `linux/amd64` 的 UBI 9 镜像，并对其运行运行时加固断言。 要派生真实的镜像仓库，从 `docs/how-to/derive-image-repo.md` 中的完整派生流程开始。第一次编辑是： 1. `examples/image-manifest.json`，或下游仓库的真实清单路径，包括 `base.builder`、`base.runtime` 和 `dnf.packages`。 2. `containers/Dockerfile`，特别是应用工件阶段。 3. 将 `app/` 替换为真实的应用源或使清单指向一个供应商发布二进制文件。 4. `README.md` 和仓库特定的文档。 5. `docs/decision-records/repo/` 用于本地决策。 6. 将发布、证明和签名真实镜像的发布工作流程。 ## 模板形状 | 路径 | 角色 | | --- | --- | | [`contracts/image-manifest.schema.json`](contracts/image-manifest.schema.json) | 可供人类审查的镜像清单模式。 | | [`examples/image-manifest.json`](examples/image-manifest.json) | 具有真实锁定上游值的实际清单。 | | [`app/`](app/) | 模板构建和提供的示例无用 Go 应用程序。 | | [`containers/Dockerfile`](containers/Dockerfile) | 多阶段 UBI 9 模式：摘要锁定的 `ubi-minimal` 构建器运行 `dnf --installroot` 以组装运行时根文件系统（保留 rpm 数据库），然后 `FROM ubi-micro` 将根文件系统和经过验证的应用程序二进制文件复制进来。 | | [`.dockerignore`](.dockerignore) | 默认情况下仅允许审查的应用程序工件的基础构建上下文基线。 | | [`tests/runtime-hardening.sh`](tests/runtime-hardening.sh) | 无 shell、无 dnf/microdnf/rpm/yum、无 curl 或 wget 的运行时断言脚本。 | | [`tools/verify.py`](tools/verify.py) | 本地和 CI 合约检查。 | | [`tools/generate_build_args.py`](tools/generate_build_args.py) | 从审查的清单生成 docker buildx 标志。 | | [`tools/build_app.sh`](tools/build_app.sh) | 确定性重新构建示例应用程序二进制文件。 | | [`tools/build_image.sh`](tools/build_image.sh) | 从清单和渲染的构建参数构建镜像。 | | [`tools/verify_app_shas.py`](tools/verify_app_shas.py) | 验证构建的二进制文件的 SHA256 是否与清单的 SHA256 值匹配。 | | [`docs/`](docs/) | Diataxis 文档以及派生、发布、治理和 org/template/repo ADR 范围。 | | [`.github/workflows/`](.github/workflows/) | `ci.yaml` 运行合约检查并调用图像构建可重用组件；`codeql.yaml`、`scorecard.yaml`、`security.yaml` 和 `repo-hygiene.yaml` 调用 `NWarila/.github` 中的规范可重用工作流程，用于 CodeQL、OpenSSF Scorecard、Trivy + Gitleaks + zizmor 和 org 仓库卫生。 | | [`.github/workflows/reusable-ubi-image-build.yaml`](.github/workflows/reusable-ubi-image-build.yaml) | 模板特定的可重用组件：构建应用程序二进制文件 -> 验证 SHA256 -> 构建 UBI 9 镜像 -> 运行运行时加固。下游仓库调用它（`uses: NWarila/ubi9-application-template/.github/workflows/reusable-ubi-image-build.yaml@`）而不是复制管道。 ## 这是什么，以及它不是什么 | | This repo | A downstream image repo | | --- | --- | --- | | 定义 UBI 9 镜像合约 | 是 | 是 | | 从头到尾构建工作镜像 | 是，一个故意无用的示例 | 是，真实的应用 | | 锁定基础镜像和 dnf 输入 | 示例的真实锁定 | 应用的真实锁定 | | 发布 SBOM、来源、签名和证明 | 记录所需的路径和发布工作流程形状 | 实现完整的发布路径 | | 包含 Vault 特定逻辑 | 否 | 只有当下游镜像为 Vault 时 | 模板不提供共享可变的基础镜像。派生仓库直接从摘要锁定的 `ubi-minimal` 构建器通过 `dnf --installroot` 构建自己的根文件系统，以便审查可以追踪基础镜像、安装的 `dnf.packages`、应用程序工件和运行时策略。 ## 标准化仓库接口 | 命令 | 目的 | | --- | --- | | `make verify` | 运行本地 CI 相似的合约检查。 | | `make build-args` | 从清单生成 docker buildx 标志。 | | `make app-build` | 确定性重新构建示例 Go 二进制文件。 | | `make app-verify` | 检查构建的二进制文件的 SHA256 是否与清单匹配。 | | `make image-build` | 构建 `linux/amd64` 的 OCI 镜像。 | | `make image-test` | 对构建的镜像运行运行时加固断言。 | | `make image` | 运行完整的 app -> image -> hardening 管道。 | ## 构建证据期望 下游镜像仓库应通过摘要发布镜像并附加： - 使用 `--provenance=mode=max` 的 BuildKit 来源。 - 使用 `--sbom=true` 的 BuildKit SBOM 证明。由于运行时镜像在 `/var/lib/rpm` 保留了 rpm 数据库，因此 SBOM 和下游扫描器枚举每个安装的软件包而不是报告空镜像。 - GitHub 艺术品证明对于推送的镜像摘要。BuildKit 携带 SBOM 证明。 - 使用 `--recursive` 签名以覆盖附加的 SBOM 和证明清单的 Cosign/Sigstore 无密钥签名。 - 构建镜像的合规性和扫描网关：OpenSCAP 对 RHEL 9 STIG 配置文件，以及 Trivy 和 Grype 漏洞扫描。 - 从 `tests/runtime-hardening.sh` 的运行时加固证据。 模板的 CI 在本地加载示例镜像进行运行时测试，并明确禁用本地来源，以便测试路径不会与发布证据混淆。BuildKit SBOM、BuildKit 来源、签名和 GitHub 艺术品证明是下游发布关注点，一旦选择了真实的注册表目标。详细的期望在 `docs/reference/supply-chain-evidence.md` 中，而 `docs/how-to/publish-image.md` 携带一个发布工作流程框架，该框架围绕现有的清单驱动管道，将构建 + 推送、Cosign 无密钥签名、GitHub 艺术品证明上传和针对推送摘要的运行时加固连接起来。 ## 许可证 MIT - 查看 [LICENSE](LICENSE).

标签：Buildx, Docker, GitHub Advanced Security, Go语言, NVR-pinning, OpenSCAP, Python, Red Hat, RHEL9, SBOM, Sigstore, STIG, UBI, 安全加固, 安全防御评估, 容器镜像, 应用安全, 应用模板, 文档, 无后门, 日志审计, 最小化镜像, 构建脚本, 硬件无关, 程序破解, 自动化构建, 请求拦截, 软件包管理, 软件开发生命周期, 逆向工具, 镜像仓库, 镜像构建