1
0
mirror of synced 2025-12-19 18:10:59 -05:00

Artifact Attestations [Public Beta] (#50246)

Co-authored-by: Zach Steindler <steiza@github.com>
Co-authored-by: Fredrik Skogman <kommendorkapten@github.com>
Co-authored-by: Phill MV <phillmv@github.com>
Co-authored-by: hubwriter <hubwriter@github.com>
This commit is contained in:
Siara
2024-04-30 11:08:43 -07:00
committed by GitHub
parent b41313ccf3
commit 5b14b2c247
14 changed files with 262 additions and 1 deletions

View File

@@ -83,6 +83,10 @@ jobs:
push_to_registry:
name: Push Docker image to Docker Hub
runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %}
permissions:
packages: write
contents: read
{% ifversion artifact-attestations %}attestations: write{% endif %}
steps:
- name: Check out the repo
uses: {% data reusables.actions.action-checkout %}
@@ -100,6 +104,7 @@ jobs:
images: my-docker-hub-namespace/my-docker-hub-repository
- name: Build and push Docker image
id: push
uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
with:
context: .
@@ -107,10 +112,16 @@ jobs:
push: true
tags: {% raw %}${{ steps.meta.outputs.tags }}{% endraw %}
labels: {% raw %}${{ steps.meta.outputs.labels }}{% endraw %}
{% ifversion artifact-attestations %}
{% data reusables.actions.artifact-attestations-step-for-container-images %}
{% endif %}
```
The above workflow checks out the {% data variables.product.prodname_dotcom %} repository, uses the `login-action` to log in to the registry, and then uses the `build-push-action` action to: build a Docker image based on your repository's `Dockerfile`; push the image to Docker Hub, and apply a tag to the image.
{% ifversion artifact-attestations %}{% data reusables.actions.artifact-attestations-step-explanation %}{% endif %}
## Publishing images to {% data variables.product.prodname_registry %}
{% ifversion ghes %}
@@ -174,6 +185,7 @@ jobs:
permissions:
packages: write
contents: read
{% ifversion artifact-attestations %}attestations: write{% endif %}
steps:
- name: Check out the repo
uses: {% data reusables.actions.action-checkout %}
@@ -200,13 +212,20 @@ jobs:
{% data reusables.package_registry.container-registry-hostname %}/{% raw %}${{ github.repository }}{% endraw %}
- name: Build and push Docker images
id: push
uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
with:
context: .
push: true
tags: {% raw %}${{ steps.meta.outputs.tags }}{% endraw %}
labels: {% raw %}${{ steps.meta.outputs.labels }}{% endraw %}
{% ifversion artifact-attestations %}
{% data reusables.actions.artifact-attestations-step-for-container-images %}
{% endif %}
```
The above workflow checks out the {% data variables.product.product_name %} repository, uses the `login-action` twice to log in to both registries and generates tags and labels with the `metadata-action` action.
Then the `build-push-action` action builds and pushes the Docker image to Docker Hub and the {% data variables.product.prodname_container_registry %}.
{% ifversion artifact-attestations %}{% data reusables.actions.artifact-attestations-step-explanation %}{% endif %}

View File

@@ -57,6 +57,8 @@ By default, npm uses the `name` field of the `package.json` file to determine th
If you're publishing a package that includes a scope prefix, include the scope in the name of your `package.json` file. For example, if your npm scope prefix is "octocat" and the package name is "hello-world", the `name` in your `package.json` file should be `@octocat/hello-world`. If your npm package uses a scope prefix and the package is public, you need to use the option `npm publish --access public`. This is an option that npm requires to prevent someone from publishing a private package unintentionally.
{% ifversion artifact-attestations %}If you would like to publish your package with provenance, include the `--provenance` flag with your `npm publish` command. This allows you to publicly and verifiably establish where and how your package was built, which increases supply chain security for people who consume your package. For more information, see [Generating provenance statements](https://docs.npmjs.com/generating-provenance-statements) in the npm documentation.{% endif %}
This example stores the `NPM_TOKEN` secret in the `NODE_AUTH_TOKEN` environment variable. When the `setup-node` action creates an `.npmrc` file, it references the token from the `NODE_AUTH_TOKEN` environment variable.
```yaml copy
@@ -75,7 +77,7 @@ jobs:
node-version: {% ifversion actions-node20-support %}'20.x'{% else %}'16.x'{% endif %}
registry-url: 'https://registry.npmjs.org'
- run: npm ci
- run: npm publish
- run: npm publish {% ifversion artifact-attestations %}--provenance --access public{% endif %}
env:
NODE_AUTH_TOKEN: {% raw %}${{ secrets.NPM_TOKEN }}{% endraw %}
```

View File

@@ -82,6 +82,9 @@ The following table shows the permissions granted to the `GITHUB_TOKEN` by defau
| Scope | Default access<br>(permissive) | Default access<br>(restricted) | Maximum access for<br>pull requests from<br>public forked repositories |
|---------------|-----------------------------|-----------------------------|--------------------------------|
| actions | read/write | none | read |
| {% ifversion artifact-attestations %} |
| attestations | read/write | none | read |
| {% endif %} |
| checks | read/write | none | read |
| contents | read/write | read | read |
| deployments | read/write | none | read |{% ifversion fpt or ghec %}

View File

@@ -11,5 +11,6 @@ children:
- /using-secrets-in-github-actions
- /using-githubs-security-features-to-secure-your-use-of-github-actions
- /automatic-token-authentication
- /using-artifact-attestations-to-establish-provenance-for-builds
---

View File

@@ -0,0 +1,179 @@
---
title: Using artifact attestations to establish provenance for builds
intro: 'Artifact attestations enable you to increase the supply chain security of your builds by publicly establishing where and how your software was built and associating it with a signed software build of materials (SBOM).'
versions:
fpt: '*'
ghec: '*'
shortTitle: Artifact attestations
---
{% data reusables.actions.artifact-attestations-public-beta-note %}
## About artifact attestations
{% data reusables.actions.about-artifact-attestations %}
### About 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 provides SLSA v1.0 Build Level 2.
You can use artifact attestations to achieve SLSA v1.0 Build Level 3; however, we strongly recommend first focusing on broad adoption of Build Level 2 across your organization. It is much better to consistently meet Level 2 across your builds than to have a small portion of builds that reach Level 3. To achieve Build Level 3, we recommend standardizing your build process with reusable workflows, auditing the reusable workflows to ensure they meet Level 3 requirements, and then updating your verification policy to require those audited reusable workflows.
For more information, see the [Provenance](https://slsa.dev/spec/v1.0/provenance) section of the SLSA documentation.
### About using Sigstore for artifact attestations
To generate artifact attestations, {% data variables.product.prodname_dotcom %} 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](https://openssf.org/blog/2023/10/03/running-sigstore-as-a-managed-service-a-tour-of-sigstores-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 {% data variables.product.prodname_actions %}.
### About verifying artifact attestations
If you consume software that publishes artifact attestations, you can use the {% data variables.product.prodname_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 {% data variables.product.prodname_cli %}](#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.
## Generating artifact attestations for your builds
You can use {% data variables.product.prodname_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](https://github.com/actions/attest-build-provenance).
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`](https://github.com/actions/attest-build-provenance) repository.
### Generating build provenance for binaries
1. In the workflow that builds the binary you would like to attest, add the following permissions.
```yaml
permissions:
id-token: write
contents: read
attestations: write
```
1. After the step where the binary has been built, add the following step.
```yaml
- 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.
### Generating build provenance for container images
1. In the workflow that builds the container image you would like to attest, add the following permissions.
```yaml
permissions:
id-token: write
contents: read
attestations: write
packages: write
```
1. After the step where the image has been built, add the following step.
```yaml
- name: Generate artifact attestation
uses: actions/attest-build-provenance@v1
with:
subject-name: {% raw %}${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}{% endraw %}
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`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) output from that step to supply the value. For more information on using outputs, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs)."
## Generating an attestation for a software bill of materials (SBOM)
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`](https://github.com/marketplace/actions/anchore-sbom-action) in the {% data variables.product.prodname_marketplace %}.
- Include a step in your workflow that uses the [`attest-sbom` action](https://github.com/actions/attest-sbom).
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](https://github.com/actions/attest-sbom) repository.
### Generating an SBOM attestation for binaries
1. In the workflow that builds the binary you would like to attest, add the following permissions.
```yaml
permissions:
id-token: write
contents: read
attestations: write
```
1. After the step where the binary has been built, add the following step.
```yaml
- 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.
### Generating an SBOM attestation for container images
1. In the workflow that builds the container image you would like to attest, add the following permissions.
```yaml
permissions:
id-token: write
contents: read
attestations: write
packages: write
```
1. After the step where the image has been built, add the following step.
```yaml
- name: Generate SBOM attestation
uses: actions/attest-sbom@v1
with:
subject-name: {% raw %}${{ env.REGISTRY }}/PATH/TO/IMAGE{% endraw %}
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`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) output from that step to supply the value. For more information on using outputs, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs)."
The value of the `sbom-path` parameter should be set to the path to the JSON-formatted SBOM file you want to attest.
## Verifying artifact attestations with the {% data variables.product.prodname_cli %}
To verify artifact attestations for **binaries**, use the following {% data variables.product.prodname_cli %} command.
```bash copy
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 {% data variables.product.prodname_cli %} command.
```bash copy
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`](https://cli.github.com/manual/gh_attestation) section of the {% data variables.product.prodname_cli %} manual.

View File

@@ -120,6 +120,20 @@ jobs:
path: output/test/code-coverage.html
```
{% ifversion artifact-attestations %}
## Generating artifact attestations for builds
{% data reusables.actions.artifact-attestations-public-beta-note %}
{% data reusables.actions.about-artifact-attestations %}
You can access attestations after a build run, underneath the list of the artifacts the build produced.
For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)."
{% endif %}
## Configuring a custom artifact retention period
You can define a custom retention period for individual artifacts created by a workflow. When using a workflow to create a new artifact, you can use `retention-days` with the `upload-artifact` action. This example demonstrates how to set a custom retention period of 5 days for the artifact named `my-artifact`:

View File

@@ -39,6 +39,20 @@ In addition to the security benefits, {% data variables.product.prodname_actions
{% data variables.product.prodname_actions %} is a big topic, but a good place to get started is "[AUTOTITLE](/actions/learn-github-actions/understanding-github-actions)," as well as "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#choosing-github-hosted-runners)," and "[AUTOTITLE](/actions/using-workflows/triggering-a-workflow)."
{% ifversion artifact-attestations %}
## Generate artifact attestations for your builds
{% data reusables.actions.artifact-attestations-public-beta-note %}
{% data reusables.actions.about-artifact-attestations %}
Artifact attestations include a signature over a built artifact, along with links to the source code and build instructions. If you sign your build with artifact attestations, you do not have to manage your own signing key material. {% data variables.product.prodname_dotcom %} handles this for you with the signing authority we operate.
For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)."
{% endif %}
## Sign your builds
After your build process is secure, you want to prevent someone from tampering with the end result of your build process. A great way to do this is to sign your builds. When distributing software publicly, this is often done with a public/private cryptographic key pair. You use the private key to sign the build, and you publish your public key so users of your software can verify the signature on the build before they use it. If the bytes of the build are modified, the signature will not verify.

View File

@@ -0,0 +1,5 @@
# Issue 13119
# Artifact Attestations Public Beta
versions:
fpt: '*'
ghec: '*'

View File

@@ -0,0 +1,9 @@
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 "[AUTOTITLE](/actions/deployment/security-hardening-your-deployments/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.

View File

@@ -0,0 +1 @@
>[!NOTE]Artifact attestations are in public beta and subject to change.

View File

@@ -0,0 +1 @@
In the last step, it generates an artifact attestation for the image, which increases supply chain security. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)."

View File

@@ -0,0 +1,6 @@
- name: Generate artifact attestation
uses: actions/attest-build-provenance@v1
with:
subject-name: {% raw %}${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}{% endraw %}
subject-digest: {% raw %}${{ steps.push.outputs.digest }}{% endraw %}
push-to-registry: true

View File

@@ -5,6 +5,7 @@ Available scopes and details of what each allows an action to do:
| Scope | Allows an action using `GITHUB_TOKEN` to |
| --- | --- |
| `actions` | Work with GitHub Actions. For example, `actions: write` permits an action to cancel a workflow run. For more information, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-actions)." |
{% ifversion artifact-attestations %}| `attestations` | Work with artifact attestations. For example, `attestations: write` permits an action to generate an artifact attestation for a build. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)" |{% endif %}
| `checks` | Work with check runs and check suites. For example, `checks: write` permits an action to create a check run. For more information, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-checks)." |
| `contents` | Work with the contents of the repository. For example, `contents: read` permits an action to list the commits, and `contents: write` allows the action to create a release. For more information, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-contents)." |
| `deployments` | Work with deployments. For example, `deployments: write` permits an action to create a new deployment. For more information, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-deployments)." |

View File

@@ -29,6 +29,7 @@ jobs:
permissions:
contents: read
packages: write
{% ifversion artifact-attestations %}attestations: write{% endif %}
#
steps:
- name: Checkout repository
@@ -50,10 +51,15 @@ jobs:
# It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
# It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
- name: Build and push Docker image
id: push
uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
with:
context: .
push: true
tags: {% raw %}${{ steps.meta.outputs.tags }}{% endraw %}
labels: {% raw %}${{ steps.meta.outputs.labels }}{% endraw %}
{% ifversion artifact-attestations %}
# This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)."
{% data reusables.actions.artifact-attestations-step-for-container-images %}
{% endif %}
```