attest-sbom

GitHub Action to create, sign and upload a SBOM (Software Bill of Materials) attestation for artifacts built as part of a workflow.

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
   

   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.

   Note

   : The set of required permissions will be refined in a future release.

2. After your artifact build step, add the following:

   - uses: actions/attest-sbom@main
     with:
       path: 
       subject-path: '${{ github.workspace }}/PATH_TO_FILE'
       format: 'spdx'
   

   The subject-path parameter should identity the artifact for which you want to generate an attestation.

What is being attested?

The generated attestation is a Software Bill of Materials (SBOM), which is essentially a detailed list of all the components in a software artifact.

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "subject",
      "digest": {
        "sha256": "7d070f6b64d9bcc530fe99cc21eaaa4b3c364e0b2d367d7735671fa202a03b32"
      }
    }
  ],
  "predicateType": "https://spdx.dev/Document/v2.3",
  "predicate": {
    "spdxVersion": "SPDX-2.3",
    "dataLicense": "CC0-1.0",
    "SPDXID": "SPDXRef-DOCUMENT",
    "name": "./",
    "documentNamespace": "https://anchore.com/syft/dir/80b363b6-87f4-4162-853f-60d402537d20",
    "creationInfo": {
      "licenseListVersion": "3.22",
      "creators": [
        "Organization: Anchore, Inc",
        "Tool: syft-0.103.1"
      ],
      "created": "2024-01-31T18:22:50Z"
    },
    "packages": [
      {
        "name": "@ampproject/remapping",
        "SPDXID": "SPDXRef-Package-npm--ampproject-remapping-5266573ba4f24a42",
        "versionInfo": "2.2.1",
        "supplier": "NOASSERTION",
        "downloadLocation": "NOASSERTION",
        "filesAnalyzed": false,
        "sourceInfo": 
        "acquired package info from installed node module manifest file: /yarn.lock",
        "licenseConcluded": "NOASSERTION",
        "licenseDeclared": "Apache-2.0",
        "copyrightText": "NOASSERTION",
        "externalRefs": [
          {
            "referenceCategory": "SECURITY",
            "referenceType": "cpe23Type",
            "referenceLocator": 
            "cpe:2.3:a:\\@ampproject\\/remapping:\\@ampproject\\/remapping:2.2.1:*:*:*:*:*:*:*"
          },
          {
            "referenceCategory": "PACKAGE-MANAGER",
            "referenceType": "purl",
            "referenceLocator": "pkg:npm/%40ampproject/remapping@2.2.1"
          }
        ]
      }
    ]
  }
}

The SBOM statement is signed with a short-lived, Sigstore-issued certificate.

If the repository initiating the GitHub Actions workflow is public, the public instance of Sigstore will be used to generate the attestation signature. If the repository is private, it will use the GitHub private Sigstore instance.

Where does the attestation go?

On the actions summary page for a repository you'll see an "Attestations" link which will take you to a list of all the attestations generated by workflows in that repository.

How are attestations verified?

Attestations can be verified using the gh-attestation extension for the GitHub CLI.

Customization

See action.yml

Inputs

• path - A path to a directory on the filesystem to scan and generate SBOM.

  If sbom-path is specified, the path will not be used to generate SBOM.

• sbom-path - A path to a directory on the filesystem which contains SBOM for signing and uploading.

  If sbom-path is not specified, the default implementation will be used path to generate SBOM for signing.

• format - The format of the SBOM. Either spdx or cyclonedx

• subject-path - Path to the artifact for which the SBOM statement will be generated.

  Must specify exactly one of subject-path or subject-digest. Wildcards can be used to identify more than one artifact.

• subject-digest - Digest of the subject for which the SBOM statement will be generated.

  Only SHA-256 digests are accepted and the supplied value must be in the form "sha256:<hex-encoded-digest>". Must specify exactly one of subject-path or subject-digest.

• subject-name - Subject name as it should appear in the SBOM statement.

  Required when the subject is identified by the subject-digest parameter. When attesting container images, the name should be the fully qualified image name.

• push-to-registry - If true, the signed attestation is pushed to the container registry identified by the subject-name. Default: false.

• github-token - Token used to make authenticated requests to the GitHub API. Default: ${{ github.token }}.

  The supplied token must have the permissions necessary to write attestations to the repository.

Outputs

• bundle-path - The file path of JSON-serialized Sigstore bundle containing the attestation and related verification material.

Sample Workflows

Identify Artifact by Path

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

name: attest-sbom

on:
  workflow_dispatch:

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

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

Identify Artifacts by Wildcard

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

name: build-wildcard-with-sbom

on:
  workflow_dispatch:

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

    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Go
        uses: actions/setup-go@v4
      - name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v5
        with:
          distribution: goreleaser
          version: latest
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Attest artifact
        uses: actions/attest-sbom@main
        with:
          subject-path: 'dist/**/my-bin-*'
          path: '.'
          format: 'spdx'

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 may not have a subject-path value you can supply. In this case 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-image-with-sbom

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 from Docker Image
        id: sbom
        uses: anchore/sbom-action@v0
        with:
          image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
          registry-username: ${{ github.actor }}
          registry-password: ${{ secrets.GITHUB_TOKEN }}
          format: "spdx-json"
          output-file: "sbom.json"
      - name: Attest SBOM
        uses: actions/attest-sbom@main
        id: attest-sbom
        with:
          sbom-path: "sbom.json"
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          subject-digest: ${{ steps.push.outputs.digest }}
          format: "spdx"