使用构件证明确认构建来源-未完纪

构件证明通过确认软件在哪里、以何种方式构建，提高发布版本的供应链安全性。

谁可以使用此功能

当前 GitHub 各套餐中的仓库均可使用构件证明；旧版 Bronze、Silver、Gold 等套餐不提供该功能。GitHub Free、Pro、Team 套餐仅支持公共仓库。私有或内部仓库需要 GitHub Enterprise Cloud。

前提条件

开始生成构件证明前，先了解其用途及适用场景，参见构件证明。

为构建生成构件证明

可以使用 GitHub Actions 为二进制文件、容器镜像等构件生成证明，确立其构建来源。工作流必须配置适当权限，并包含调用 actions/attest 的步骤。

更新后的工作流运行时，会生成构件及用于确认构建来源的证明。可以在仓库的 Actions 选项卡查看证明；具体用法参见 attest 仓库。

二进制文件

在构建目标二进制文件的工作流中添加权限：

permissions:
  id-token: write
  contents: read
  attestations: write

在生成二进制文件的步骤之后添加：

- name: Generate artifact attestation
  uses: actions/attest@v4
  with:
    subject-path: 'PATH/TO/ARTIFACT'

subject-path 应设为需要证明的二进制文件路径。

容器镜像

在构建镜像的工作流中添加权限：

permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

在生成镜像的步骤之后添加：

- name: Generate artifact attestation
  uses: actions/attest@v4
  with:
    subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
    subject-digest: 'sha256:fedcba0...'
    push-to-registry: true

subject-name 应为镜像的完整限定名称，例如 ghcr.io/user/app 或 acme.azurecr.io/user/app，不要包含标签。

subject-digest 应为证明对象的 SHA256 摘要，格式为 sha256:HEX_DIGEST。如果工作流使用 docker/build-push-action，可以使用该步骤的 digest 输出。关于输出的用法，参见GitHub Actions 工作流语法。

生成软件物料清单（SBOM）证明

可以为工作流构件生成签名的 SBOM 证明。工作流需要适当权限、为构件创建的 SBOM，以及把 attest 操作与 sbom-path 输入搭配使用的步骤。SBOM 生成工具可参见 GitHub Marketplace 中的 anchore-sbom-action。

更新后的工作流会生成构件和 SBOM 证明，可以在 Actions 选项卡查看。具体用法参见 attest 仓库。

二进制文件的 SBOM 证明

在工作流中添加：

permissions:
  id-token: write
  contents: read
  attestations: write

在构建步骤之后添加：

- name: Generate SBOM attestation
  uses: actions/attest@v4
  with:
    subject-path: 'PATH/TO/ARTIFACT'
    sbom-path: 'PATH/TO/SBOM'

subject-path 指向 SBOM 所描述的二进制文件；sbom-path 指向已生成的 SBOM 文件。

容器镜像的 SBOM 证明

在工作流中添加：

permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

在构建镜像之后添加：

- name: Generate SBOM attestation
  uses: actions/attest@v4
  with:
    subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE
    subject-digest: 'sha256:fedcba0...'
    sbom-path: 'sbom.json'
    push-to-registry: true

subject-name 同样使用不含标签的完整镜像名称；subject-digest 使用 sha256:HEX_DIGEST 格式的摘要。通过 docker/build-push-action 构建时，可使用其 digest 输出。

sbom-path 应设为待证明的 JSON 格式 SBOM 文件路径。

上传到关联构件页面

建议把经过证明的资产上传到组织的关联构件页面（linked artifacts page）。此页面展示构件的构建历史、部署记录和存储详情，可帮助确定安全警报的处理优先级，并把易受攻击的构件与所属团队、源代码和构建运行关联起来。参见关于关联构件。

同时满足以下条件时，attest 会在关联构件页面自动创建存储记录：

push-to-registry 设为 true。
工作流具有 artifact-metadata: write 权限。

示例参见上传存储和部署数据。

使用 GitHub CLI 验证证明

GitHub CLI 可以验证二进制文件、容器镜像和 SBOM 的证明，参见 attestation 手册。以下命令假定处于在线环境；离线或隔离环境参见离线验证证明。

验证二进制文件

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME

验证容器镜像

使用带 oci:// 前缀的镜像完整限定名称，代替二进制文件路径：

docker login ghcr.io

gh attestation verify oci://ghcr.io/ORGANIZATION_NAME/IMAGE_NAME:test -R ORGANIZATION_NAME/REPOSITORY_NAME

验证 SBOM

使用 --predicate-type 指定非默认谓词。具体谓词参见 in-toto/attestation 仓库。attest 当前支持 SPDX 或 CycloneDX SBOM 谓词；验证 SPDX SBOM 的示例：

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3

使用 --format json 查看证明详情，这对查看 SBOM 尤其有用：

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3 \
  --format json \
  --jq '.[].verificationResult.statement.predicate'