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

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

谁可以使用此功能？

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

本文内容

关于项目证明

项目证明使你能够为自己构建的软件创建不可伪造的来源和完整性保证。 反过来，使用软件的人员可以验证软件是在哪里以及如何构建的。

使用软件生成项目证明时，将创建加密签名的声明用于确立生成的来源，并包含以下信息：

  • 指向与项目关联的工作流的链接。
  • 项目的存储库、组织、环境、提交 SHA 以及触发事件。
  • OIDC 令牌中用于确立来源的其他信息。 有关详细信息，请参阅“关于使用 OpenID Connect 进行安全强化”。

还可以生成包含关联的软件物料清单 (SBOM) 的项目证明。 将你的版本与它们中使用的开放源代码依赖项列表相关联可提供透明度，并使使用者能够遵守数据保护标准。

关于项目证明的 SLSA 级别

SLSA 框架是用于评估供应链安全性的行业标准。 它按级别进行组织。 每个级别都表示软件供应链的安全性和可信度不断提高。 项目证明本身满足 SLSA v1.0 生成级别 2 的要求。

这在项目及其生成说明之间建立了链接，但你可以通过要求生成工作使用经过审查的已知生成说明以进一步完善此方法。 要执行此操作，最好是让生成工作在组织中许多存储库共享的可重用工作流中进行。 可重用工作流可以在生成过程和调用方工作流之间提供隔离，以满足 SLSA v1.0 生成级别 3 的要求。 有关详细信息，请参阅“使用项目证明和可重用工作流来实现 SLSA v1 生成级别 3”。

有关 SLSA 级别的详细信息，请参阅 SLSA 安全级别。

关于将 Sigstore 用于项目证明

为了生成项目证明，GitHub 使用 Sigstore，它是一个开放源代码项目，提供了一个全面的解决方案，用于通过证明对软件项目进行签名和验证。

生成项目证明的公共存储库使用 Sigstore Public Good 实例。 生成的 Sigstore 捆绑包的副本随 GitHub 一起存储，还写入 Internet 上公开可读的不可变透明度日志。

生成项目证明的专用存储库 使用 GitHub 的 Sigstore 实例。 GitHub 的 Sigstore 实例使用与 Sigstore Public Good 实例相同的代码库，但它没有透明度日志，并且仅与 GitHub Actions 联合。

需要证明的内容

仅生成证明并不能提供任何安全优势，必须验证证明才能实现该优势。 下面是有关如何考虑签署内容和签署频率的一些指南：

应签署：

  • 你发布的软件希望用户能够运行 gh attestation verify ...。
  • 人们会运行的二进制文件、会下载的包，或包含详细内容的哈希的清单。

不应签署：

  • 用于自动测试的频繁生成。
  • 单个文件，如源代码、文档文件，或嵌入图像。

关于验证项目证明

如果使用发布项目证明的软件，则可以使用 GitHub CLI 来验证这些证明。 由于证明提供了有关软件在哪里以及如何构建的信息，因此可以使用这些信息来创建和强制实施安全策略，从而提高供应链安全性。 有关详细信息，请参阅“使用 GitHub CLI 验证项目证明”。

Warning

请务必记住，项目证明_不能_保证项目是安全的。 相反，项目证明会将你链接到源代码和生成它们的生成说明。 可以定义策略标准，通过评估内容来评估该策略，并在使用软件时做出明智的风险决策。

为生成生成项目证明

可以使用 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@v1
  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@v1
  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 部分。

Note

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

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

若要验证二进制文件的项目证明，请使用以下 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'