Note
Artifact attestations are in public beta and subject to change.
Artifact attestations enable you to create unfalsifiable provenance and integrity guarantees for the software you build. In turn, people who consume your software can verify where and how your software was built.
When you generate artifact attestations with your software, you create cryptographically signed claims that establish your build's provenance and include the following information:
- A link to the workflow associated with the artifact.
- The repository, organization, environment, commit SHA, and triggering event for the artifact.
- Other information from the OIDC token used to establish provenance. For more information, see "
About security hardening with OpenID Connect
."
You can also generate artifact attestations that include an associated software bill of materials (SBOM). Associating your builds with a list of the open source dependencies used in them provides transparency and enables consumers to comply with data protection standards.
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
Using artifact attestations and reusable workflows to achieve SLSA v1 Build Level 3
.
For more information on SLSA levels, see
SLSA Security Levels
.
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.
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.
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. For more information, see "
Verifying artifact attestations with the GitHub CLI
."
Warning
It is important to remember that artifact attestations are
not
a guarantee that an artifact is secure. Instead, artifact attestations link you to the source code and the build instructions that produced them. It is up to you to define your policy criteria, evaluate that policy by evaluating the content, and make an informed risk decision when you are consuming software.
You can use GitHub Actions to generate artifact attestations that establish build provenance for artifacts such as binaries and container images.
To generate an artifact attestation, you must:
- Ensure you have the appropriate permissions configured in your workflow.
- Include a step in your workflow that uses the
attest-build-provenance
action
.
When you run your updated workflows, they will build your artifacts and generate an artifact attestation that establishes build provenance. You can view attestations in your repository's
Actions
tab. For more information, see the
attest-build-provenance
repository.
-
In the workflow that builds the binary you would like to attest, add the following permissions.
permissions:
id-token:
write
contents:
read
attestations:
write
-
After the step where the binary has been built, add the following step.
-
name:
Generate
artifact
attestation
uses:
actions/attest-build-provenance@v1
with:
subject-path:
'PATH/TO/ARTIFACT'
The value of the
subject-path
parameter should be set to the path to the binary you want to attest.
-
In the workflow that builds the container image you would like to attest, add the following permissions.
permissions:
id-token:
write
contents:
read
attestations:
write
packages:
write
-
After the step where the image has been built, add the following step.
-
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
The value of the
subject-name
parameter should specify the fully-qualified image name. For example,
ghcr.io/user/app
or
acme.azurecr.io/user/app
. Do not include a tag as part of the image name.
The value of the
subject-digest
parameter should be set to the SHA256 digest of the subject for the attestation, in the form
sha256:HEX_DIGEST
. If your workflow uses
docker/build-push-action
, you can use the
digest
output from that step to supply the value. For more information on using outputs, see "
Workflow syntax for GitHub Actions
."
You can generate signed SBOM attestations for workflow artifacts.
To generate an attestation for an SBOM, you must:
- Ensure you have the appropriate permissions configured in your workflow.
- Create an SBOM for your artifact. For more information, see
anchore-sbom-action
in the GitHub Marketplace.
- Include a step in your workflow that uses the
attest-sbom
action
.
When you run your updated workflows, they will build your artifacts and generate an SBOM attestation. You can view attestations in your repository's
Actions
tab. For more information, see the
attest-sbom
action
repository.
-
In the workflow that builds the binary you would like to attest, add the following permissions.
permissions:
id-token:
write
contents:
read
attestations:
write
-
After the step where the binary has been built, add the following step.
-
name:
Generate
SBOM
attestation
uses:
actions/attest-sbom@v1
with:
subject-path:
'PATH/TO/ARTIFACT'
sbom-path:
'PATH/TO/SBOM'
The value of the
subject-path
parameter should be set to the path of the binary the SBOM describes. The value of the
sbom-path
parameter should be set to the path of the SBOM file you generated.
-
In the workflow that builds the container image you would like to attest, add the following permissions.
permissions:
id-token:
write
contents:
read
attestations:
write
packages:
write
-
After the step where the image has been built, add the following step.
-
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
The value of the
subject-name
parameter should specify the fully-qualified image name. For example,
ghcr.io/user/app
or
acme.azurecr.io/user/app
. Do not include a tag as part of the image name.
The value of the
subject-digest
parameter should be set to the SHA256 digest of the subject for the attestation, in the form
sha256:HEX_DIGEST
. If your workflow uses
docker/build-push-action
, you can use the
digest
output from that step to supply the value. For more information on using outputs, see "
Workflow syntax for GitHub Actions
."
The value of the
sbom-path
parameter should be set to the path to the JSON-formatted SBOM file you want to attest.
To verify artifact attestations for
binaries
, use the following GitHub CLI command.
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
To verify artifact attestations for
container images
, you must provide the image's FQDN prefixed with
oci://
instead of the path to a binary. You can use the following GitHub CLI command.
Bash
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
For more information, see the
attestation
section of the GitHub CLI manual.