Artifact attestations

Overview

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

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

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

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

SLSA levels for artifact attestations

The SLSA framework is an industry standard used to evaluate supply chain security. It is organized into levels. Each level represents an increasing degree of security and trustworthiness for a software supply chain. Artifact attestations by itself provides SLSA v1.0 Build Level 2.

This provides a link between your artifact and its build instructions, but you can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3. For more information, see 使用项目证明和可重用工作流来实现 SLSA v1 生成级别 3.

For more information on SLSA levels, see SLSA Security Levels.

How GitHub generates artifact attestations

To generate artifact attestations, GitHub uses Sigstore, which is an open source project that offers a comprehensive solution for signing and verifying software artifacts via attestations.

Public repositories that generate artifact attestations use the Sigstore Public Good Instance. A copy of the generated Sigstore bundle is stored with GitHub and is also written to an immutable transparency log that is publicly readable on the internet.

Private repositories that generate artifact attestations use GitHub's Sigstore instance. GitHub's Sigstore instance uses the same codebase as the Sigstore Public Good Instance, but it does not have a transparency log and only federates with GitHub Actions.

When to generate attestations

Generating attestations alone doesn't provide any security benefit, the attestations must be verified for the benefit to be realized. Here are some guidelines for how to think about what to sign and how often:

You should sign:

• Software you are releasing that you expect people to run gh attestation verify ... on.
• Binaries people will run, packages people will download, or manifests that include hashes of detailed contents.

You should not sign:

• Frequent builds that are just for automated testing.
• Individual files like source code, documentation files, or embedded images.

Verifying artifact attestations

If you consume software that publishes artifact attestations, you can use the GitHub CLI to verify those attestations. Because the attestations give you information about where and how software was built, you can use that information to create and enforce security policies that elevate your supply chain security.

Next steps

To start generating and verifying artifact attestations for your builds, see 使用项目证明确立生成的来源.