attest-demo

This repository demonstrates the use of the actions/attest-build-provenance and actions/attest-sbom actions to generate attestations for software artifacts built with GitHub Actions.

We use a trivial Python project to show what a typical workflow might look like (see .github/workflows/build.yml).

Artifact Attestation

First, we need to ensure that we have the proper permissions set for our workflow:

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

Developers are probably already familiar with contents: read as this is necessary for the workflow to clone the repository.

The id-token: write permision is necessary for the creation of the attestation. The attest-* actions will request an OIDC token from the GitHub Actions runtime -- the identity information present in the OIDC token is embedded in the generated attestation and provides the verifiable papertrail that allows us to assert that the built artifact originated from this workflow.

The attestations: write permission is necessary to write the attestation to the GitHub API and associate it with the current repository.

With the proper permissions set, we can build our Python project:

- name: Install dependencies
  run: python -m pip install -r requirements.txt
- name: Build package
  run: python -m build .

The result of the build step will be a Python wheel package in the dist/ directory.

With our artifact built, we use the actions/attest-build-provenance action to generate a build provenance attestation which refers to the Python package.

- name: Attest build provenance
  uses: actions/attest-build-provenance@v1
  with:
    subject-path: "dist/*.whl"

See an example of a build provenance attestation here.

Developers may also wish to generate an Sofware Bill of Materials (SBOM) for their project and then attest that SBOM in order to link it to this workflow run. There are a number of tools which can be used to generate SBOMs for a project -- in our example we use the anchore/sbom-action:

- name: Generate SBOM
  uses: anchore/sbom-action@v0.15.11
  with:
    format: "spdx-json"
    output-file: "sbom.spdx.json"

This will scan the project directory and produce an inventory of all the referenced dependencies. In this case, we're asking for an SBOM in the SPDX format.

Once the SBOM has been generated, we can use the attest-sbom action to wrap the SBOM in a verifiable attestation:

- name: Attest SBOM
  uses: actions/attest-sbom@v1
  with:
    subject-path: "dist/*.whl"
    sbom-path: "sbom.spdx.json"

Note that The subject used for the SBOM attestation is the same that was used for the build provenance attestation. In both cases, we're binding the attestation to the build artifact generated in this workflow.

See an example of an SBOM attestation here.

Attestation Verification

The "verify" job in the workflow shows an example of using the gh CLI to verify the attestations which were generated for the build artifact:

- name: Verify build artifact
  env:
    GH_TOKEN: ${{ github.token }}
    run: ./bin/gh attestation verify *.whl --owner github

The output will look something like the following, showing both the build provenance and SBOM attestations:

github/attest-demo	https://spdx.dev/Document/v2.3	.github/workflows/build.yml@refs/heads/main
github/attest-demo	https://slsa.dev/provenance/v1	.github/workflows/build.yml@refs/heads/main