使用制品证明建立构建来源 - GitHub Docs

关于工件证明

工件证明使您能够为构建的软件创建不可伪造的来源和完整性保证。反过来，使用您软件的人员可以验证软件构建的位置和方式。

当您使用软件生成工件证明时，您会创建加密签名的声明，这些声明会建立构建的来源并包含以下信息

与工件关联的工作流的链接。
工件的存储库、组织、环境、提交 SHA 和触发事件。
用于建立来源信息的 OIDC 令牌中的其他信息。有关更多信息，请参阅“关于使用 OpenID Connect 加强安全”。

您还可以生成包含关联软件物料清单 (SBOM) 的工件证明。将您的构建与其中使用的开源依赖项列表关联，可以提高透明度，并使使用者能够遵守数据保护标准。

关于工件证明的 SLSA 等级

SLSA 框架是用于评估供应链安全的行业标准。它被组织成不同的级别。每个级别代表软件供应链日益增强的安全性和可信度。工件证明本身提供 SLSA v1.0 构建级别 2。

这提供了工件与其构建指令之间的链接，但您可以更进一步，要求构建使用已知且经过验证的构建指令。一个很好的方法是让您的构建在一个可重用的工作流中进行，该工作流由您组织中的许多存储库共享。可重用的工作流可以在构建过程和调用工作流之间提供隔离，以满足 SLSA v1.0 构建级别 3。有关更多信息，请参阅使用工件证明和可重用工作流实现 SLSA v1 构建级别 3。

有关 SLSA 等级的更多信息，请参阅 SLSA 安全级别。

关于使用 Sigstore 进行工件证明

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

生成工件证明的公共存储库使用 Sigstore 公共实例。生成的 Sigstore 包的副本存储在 GitHub 上，并且还写入一个不可变的透明度日志，该日志可在互联网上公开读取。

生成工件证明的私有存储库使用 GitHub 的 Sigstore 实例。GitHub 的 Sigstore 实例使用与 Sigstore 公共实例相同的代码库，但它没有透明度日志，并且仅与 GitHub Actions 联合。

需要证明什么内容

仅生成证明本身并不能提供任何安全优势，必须验证证明才能实现其益处。以下是一些关于如何考虑要签名什么内容以及签名的频率的指南

您应该签名

您发布的并且希望人们对其运行 gh attestation verify ... 的软件。
人们将运行的二进制文件、人们将下载的包或包含详细内容哈希的清单。

您不应签名

仅用于自动测试的频繁构建。
单个文件，如源代码、文档文件或嵌入式图像。

关于验证工件证明

如果您使用发布工件证明的软件，则可以使用 GitHub CLI 来验证这些证明。由于证明为您提供了有关软件构建位置和方式的信息，因此您可以使用这些信息来创建和执行安全策略，从而提高您的供应链安全性。有关更多信息，请参阅“使用 GitHub CLI 验证工件证明”。

警告

务必记住，工件证明不是对工件安全的保证。相反，工件证明将您链接到生成它们的源代码和构建指令。您需要定义自己的策略标准，通过评估内容来评估该策略，并在使用软件时做出明智的风险决策。

为您的构建生成工件证明

您可以使用 GitHub Actions 生成工件证明，以建立二进制文件和容器镜像等工件的构建来源。

要生成工件证明，您必须

确保您在工作流中配置了适当的权限。
在您的工作流中包含一个步骤，该步骤使用 attest-build-provenance 操作。

运行更新后的工作流时，它们将构建您的工件并生成一个工件证明，以建立构建来源。您可以在存储库的“操作”选项卡中查看证明。有关更多信息，请参阅 attest-build-provenance 存储库。

为二进制文件生成构建来源

在构建要证明的二进制文件的工作流中，添加以下权限。

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

在构建二进制文件的步骤之后，添加以下步骤。

- name: Generate artifact attestation
  uses: actions/attest-build-provenance@v1
  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-build-provenance@v1
  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 证明

在构建要证明的二进制文件的工作流中，添加以下权限。

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

在构建二进制文件的步骤之后，添加以下步骤。
```
- 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 证明

在构建要证明的容器镜像的工作流中，添加以下权限。

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

在构建镜像的步骤之后，添加以下步骤。
```
- 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 命令。

Bash

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

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

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