使用项目证明确立生成的来源

利用项目证明，可以通过确定软件构建的位置和方式，来提高版本的供应链安全性。

谁可以使用此功能？

所有当前 GitHub 计划的项目证明都在公共存储库中可用。 旧版计划（如 Bronze、Silver 或 Gold）中不提供这些内容。 如果你使用的是 GitHub Free、GitHub Pro 或 GitHub Team 计划，项目证明仅适用于公共仓库。 若要在私人或内部仓库中使用项目证明，必须在 GitHub Enterprise Cloud 计划中。

本文内容

先决条件

在开始生成项目证明之前，需要了解它们是什么以及应何时使用它们。 请参阅“项目证明”。

为生成生成项目证明

可以使用 GitHub Actions 生成项目证明，这些证明为二进制文件和容器映像等项目确立生成来源。

若要生成项目证明，必须：

运行更新的工作流时，它们将生成项目，并生成用于确立生成来源的项目证明。 可以在存储库的“操作”选项卡中查看证明。有关详细信息，请参阅 attest-build-provenance 存储库。

生成二进制文件的生成来源

  1. 在生成要证明的二进制文件的工作流中，添加下列权限。

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

  2. 在生成二进制文件的步骤后，添加下列步骤。

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

    subject-path 参数的值应设置为要证明的二进制文件的路径。

生成容器映像的生成来源

  1. 在生成要证明的容器映像的工作流中，添加下列权限。

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

  2. 在生成映像的步骤后，添加下列步骤。

    - name: Generate artifact attestation
  uses: actions/attest-build-provenance@v2
  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 生成证明，必须：

  • 确保在工作流中配置了适当的权限。
  • 为项目创建 SBOM。 有关详细信息，请参阅 GitHub Marketplace 中的 anchore-sbom-action。
  • 在工作流中包含使用 attest-sbom 操作的步骤。

运行更新的工作流时，它们将生成项目，并生成 SBOM 证明。 可以在存储库的“操作”选项卡中查看证明。有关详细信息，请参阅 attest-sbom 操作存储库。

为二进制文件生成 SBOM 证明

  1. 在生成要证明的二进制文件的工作流中，添加下列权限。

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

  2. 在生成二进制文件的步骤后，添加下列步骤。

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

    subject-path 参数的值应设置为 SBOM 描述的二进制文件的路径。 sbom-path 参数的值应设置为你生成的 SBOM 文件的路径。

为容器映像生成 SBOM 证明

  1. 在生成要证明的容器映像的工作流中，添加下列权限。

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

  2. 在生成映像的步骤后，添加下列步骤。

    - name: Generate SBOM attestation
  uses: actions/attest-sbom@v2
  with:
    subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE
    subject-digest: 'sha256:fedcba0...'
    sbom-path: 'sbom.json'
    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-path 参数的值应设置为要证明的 JSON 格式 SBOM 文件的路径。

使用 GitHub CLI 验证项目证明

可以使用 GitHub CLI 验证二进制文件和容器映像的项目证明以及验证 SBOM 证明。 有关详细信息，请参阅 GitHub CLI 手册的 attestation 部分。

注意

这些命令假定你处于在线环境中。 如果处于离线或实体隔离环境中，请参阅“离线验证证明”。

验证二进制文件的项目证明

若要验证二进制文件的项目证明，请使用以下 GitHub CLI 命令。

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

验证容器映像的项目证明

若要验证容器映像的项目证明，必须提供前缀为 oci:// 的映像 FQDN，而不是二进制文件的路径。 可以使用以下 GitHub CLI 命令。

Bash
docker login ghcr.io

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

验证 SBOM 的证明

若要验证 SBOM 证明，必须提供 --predicate-type 标志来引用非默认谓词。 有关详细信息，请参阅 in-toto/attestation 存储库中的 经过审查的谓词。

例如，attest-sbom 操作当前支持 SPDX 或 CycloneDX SBOM 谓词。 要验证 SPDX 格式的 SBOM 证明，可使用以下 GitHub CLI 命令。

Bash
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 证明时，这尤其有用。

Bash
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'

后续步骤

为了使证明保持相关性和可管理性，应删除不再需要的证明。 请参阅“管理项目证明的生命周期”。