actions/attest-sbom

Generate signed SBOM attestations for workflow artifacts. Internally powered by the @actions/attest-sbom package.

Attestations bind some subject (a named artifact along with its digest) to a a Software Bill of Materials (SBOM) using the in-toto format. The action accepts SBOMs which have been generated by external tools or can generate one automatically by invoking the anchore/sbom-action. Externally generated SBOMs must be in either the SPDX or CycloneDX JSON-serialized format.

A verifiable signature is generated for the attestation using a short-lived Sigstore-issued signing certificate. If the repository initiating the GitHub Actions workflow is public, the public-good instance of Sigstore will be used to generate the attestation signature. If the repository is private/internal, it will use the GitHub private Sigstore instance.

Once the attestation has been created and signed, it will be uploaded to the GH attestations API and associated with the repository from which the workflow was initiated.

Attestations can be verified using the attestation command in the GitHub CLI.

Usage

Within the GitHub Actions workflow which builds some artifact you would like to attest:

1. Ensure that the following permissions are set:

   permissions:
     id-token: write
     contents: write # TODO: Update this
   

   The id-token permission gives the action the ability to mint the OIDC token necessary to request a Sigstore signing certificate. The contents permission is necessary to persist the attestation.

2. Add the following to your workflow after your artifact has been built:

   - uses: actions/attest-sbom@v1
     with:
       subject-path: '<PATH TO ARTIFACT>'
   

   The subject-path parameter should identity the artifact for which you want to generate an SBOM attestation. When no other inputs are specified, the action will automatically generate an SPDX SBOM by scanning the github.workspace directory.

Inputs

See action.yml

- uses: actions/attest@v1
  with:
    # Path to the artifact serving as the subject of the attestation. Must
    # specify exactly one of "subject-path" or "subject-digest".
    subject-path:

    # SHA256 digest of the subject for for the attestation. Must be in the form
    # "sha256:hex_digest" (e.g. "sha256:abc123..."). Must specify exactly one
    # of "subject-path" or "subject-digest".
    subject-digest:

    # Subject name as it should appear in the attestation. Required unless
    # "subject-path" is specified, in which case it will be inferred from the
    # path.
    subject-name:

    # Path to the JSON-formatted SBOM file to attest. When specified, the
    # "scan-path" and "sbom-format" inputs are ignored.
    sbom-path:

    # Path on the filesystem to scan for SBOM generation. Ignored if "sbom-path"
    # is specified. Defaults to ${{ github.workspace }}
    scan-path:

    # Format to use for the generated SBOM output. Supported formats are
    # "spdx" and "cyclonedx". Ignored if "sbom-path" is specified. Defaults to
    # "spdx".
    sbom-format:

    # Whether to push the attestation to the image registry. Requires that the
    # "subject-name" parameter specify the fully-qualified image name and that
    # the "subject-digest" parameter be specified. Defaults to false.
    push-to-registry:

    # The GitHub token used to make authenticated API requests. Default is
    # ${{ github.token }}
    github-token:

Outputs

Name	Description	Example
bundle-path	Absolute path to the file containing the generated attestation	/tmp/attestaion.jsonl

Attestations are saved in the JSON-serialized Sigstore bundle format.

If multiple subjects are being attested at the same time, each attestation will be written to the output file on a separate line (using the JSON Lines format).

Examples

Identify Subject and SBOM by Path

For the basic use case, simply add the attest-sbom action to your workflow and supply the path to the artifact and SBOM for which you want to generate attestation.

name: build-attest

on:
  workflow_dispatch:

jobs:
  build:
    permissions:
      id-token: write
      contents: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Build artifact
        run: make my-app
      - name: Generate SBOM
        run: make sbom
      - name: Attest
        uses: actions/attest-sbom@v1
        with:
          subject-path: '${{ github.workspace }}/my-app'
          sbom-path: '${{ github.workspace }}/my-app.sbom.spdx.json'

Identify Subjects by Wildcard

If you are generating multiple artifacts, you can generate an attestation for each by using a wildcard in the subject-path input.

- uses: actions/attest-sbom@v1
  with:
    subject-path: 'dist/**/my-bin-*'
    sbom-path: '${{ github.workspace }}/my-bin.sbom.spdx.json'

For supported wildcards along with behavior and documentation, see @actions/glob which is used internally to search for files.

Container Image

When working with container images you can invoke the action with the subject-name and subject-digest inputs.

If you want to publish the attestation to the container registry with the push-to-registry option, it is important that the subject-name specify the fully-qualified image name (e.g. "ghcr.io/user/app" or "acme.azurecr.io/user/app"). Do NOT include a tag as part of the image name -- the specific image being attested is identified by the supplied digest.

Note

: When pushing to Docker Hub, please use "index.docker.io" as the registry portion of the image name.

name: build-attested-image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      packages: write
      contents: write
    env:
      REGISTRY: ghcr.io
      IMAGE_NAME: ${{ github.repository }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push image
        id: push
        uses: docker/build-push-action@v5.0.0
        with:
          context: .
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
      - name: Generate SBOM
        run: make sbom
      - name: Attest
        uses: actions/attest-sbom@v1
        id: attest
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          subject-digest: ${{ steps.push.outputs.digest }}
          sbom-path: 'sbom.cyclonedx.json'
          push-to-registry: true