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

先决条件

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

生成工件声明以证明您的构建

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

若要生成工件证明，必须：

• 确保在工作流中配置了适当的权限。
• 在工作流中包含使用 attest 操作的步骤。

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

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

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

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

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

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

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

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

为二进制文件生成 SBOM 声明

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

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

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

   - 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 声明

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

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

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

   - 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 参数的值应指定完全限定的映像名称。 例如，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 文件的路径。

将构件上传到 linked artifacts page

建议将经过证明的资产上传到组织的 linked artifacts page资产。 此页面显示项目的生成历史记录、部署记录和存储详细信息。 你可以使用这些数据来优先处理安全警报，或快速将易受攻击的工件与其所属团队、源代码和构建运行关联。 有关详细信息，请参阅“关于关联的项目”。

证明操作会在 linked artifacts page 上自动创建存储记录（如果满足以下两个条件）：

• push-to-registry 选项已设置为 true
• 包含该操作的工作流具有artifact-metadata: write权限

有关示例工作流，请参阅“将存储和部署数据上传到 linked artifacts page”。

使用 GitHub CLI 验证制品证明

可以验证二进制文件和容器映像的构件证明，并使用 GitHub CLI 验证 SBOM 证明。 有关详细信息，请参阅 attestation 手册的 GitHub CLI 一节。

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

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

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 。

docker login ghcr.io

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

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 操作当前支持 SPDX 或 CycloneDX SBOM 谓词。 若要验证 SPDX 格式的 SBOM 证明，可以使用以下命令 GitHub CLI 。

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

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'

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'

后续步骤

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

你还可以生成发布证明，帮助使用者验证你的发布版本的完整性与来源。 有关详细信息，请参阅“不可变版本”。