Skip to content

Sign SBOMs

A signature proves which repository, workflow and commit produced an SBOM, and that nobody changed it afterwards. Affectra checks the signature when you upload, keeps the evidence, and shows it on the release. Anyone can check it again without trusting Affectra.

You sign with Sigstore. There are no keys to manage. The GitHub Actions job gets a short-lived certificate that names the run, and the signature is recorded in Sigstore’s public transparency log.

  • Signatures made in a GitHub Actions run. The certificate must come from GitHub Actions and name the repository by its numeric IDs. Signatures made with your own key, or by another CI system, are refused.
  • Signatures made with Sigstore’s public instance. GitHub signs attestations of private repositories with its own Sigstore instance, which Affectra does not check yet. Use sign: true or cosign sign-blob for SBOMs of private repositories, and see Limits.
  • Three kinds of evidence: a signature over the SBOM file, an SBOM attestation, and build provenance. Each is described below.

Set sign: true. The action signs each SBOM with cosign sign-blob and uploads the signature with it.

The job needs id-token: write for the signing certificate, and cosign 2.4 or later on the runner:

permissions: {}
jobs:
sbom:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write # for the signing certificate, and for the upload without an API key
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
# ... build, and write your SBOMs to build/sbom/
- uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532 # v4.1.3
- uses: affectra/upload-sbom@9d96158dc5e1155428b006b8d1fa37458afb5e98 # v2.1.0
with:
url: https://affectra.example.com
organization: acme
product: Gateway
version: ${{ github.ref_name }}
sbom: build/sbom/*.cdx.json
sign: true

Signing works with an API key too. The signature, not the credential, says who built the document.

If you sign in an earlier step, leave sign off. The action then uploads a <file>.sigstore.json next to an SBOM as that SBOM’s signature. It never uploads *.sigstore.json files as SBOMs:

Terminal window
cosign sign-blob --yes --new-bundle-format \
--bundle sbom.cdx.json.sigstore.json sbom.cdx.json

GitHub’s actions/attest-sbom signs a statement that an SBOM describes your build outputs, such as a firmware image, by digest. It says more than a plain signature: this SBOM describes these files.

Save its bundle as the SBOM’s .sigstore.json. Affectra verifies it like a signature, and also records which files the SBOM describes:

permissions: {}
jobs:
sbom:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
attestations: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
# ... build dist/firmware.bin and dist/sbom.cdx.json
- uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e # v4.1.0
id: attest
with:
subject-path: dist/firmware.bin
sbom-path: dist/sbom.cdx.json
- run: cp "$BUNDLE" dist/sbom.cdx.json.sigstore.json
env:
BUNDLE: ${{ steps.attest.outputs.bundle-path }}
- uses: affectra/upload-sbom@9d96158dc5e1155428b006b8d1fa37458afb5e98 # v2.1.0
with:
url: https://affectra.example.com
organization: acme
product: Gateway
version: ${{ github.ref_name }}
sbom: dist/sbom.cdx.json

Leave sign off here. With sign: true, the action replaces the attestation with a plain signature.

Only JSON SBOMs can be attested, because the attestation holds the SBOM as JSON, and Affectra compares it with the file you upload. An XML or tag-value SBOM never matches.

actions/attest-build-provenance signs a statement that this workflow run built your firmware images. Pass its bundle as provenance. Affectra lists each file on the release’s Artifacts tab, with the run that built it and the SBOMs that describe it. The tab’s number counts these files:

# ... after the steps above
- uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
id: provenance
with:
subject-path: dist/firmware.bin
- run: cp "$BUNDLE" dist/firmware.provenance.sigstore.json
env:
BUNDLE: ${{ steps.provenance.outputs.bundle-path }}
- uses: affectra/upload-sbom@9d96158dc5e1155428b006b8d1fa37458afb5e98 # v2.1.0
with:
url: https://affectra.example.com
organization: acme
product: Gateway
version: ${{ github.ref_name }}
sbom: dist/sbom.cdx.json
provenance: dist/firmware.provenance.sigstore.json

The bundles go to the same release, after the SBOMs. Affectra accepts SLSA v1 provenance made by a GitHub Actions run. It refuses provenance whose contents do not match its signing certificate, and keeps the certificate’s values. An SBOM attestation sent as provenance is refused, because it belongs with its SBOM.

Provenance counts against your organization’s signature requirement too.

When a signature, attestation or provenance bundle arrives, Affectra checks it before it creates anything. An upload that fails creates no product, variant or release.

  • The bundle is a valid Sigstore bundle and the certificate chains to Sigstore’s public instance.
  • A signature covers the exact bytes of the SBOM you uploaded. An attestation holds the SBOM as JSON, and it must be the document you uploaded.
  • The signature carries a verified time, and Sigstore’s transparency log has an entry for it.
  • The certificate comes from GitHub Actions and names the repository and its owner by numeric ID.

A bundle that fails any check is refused with a 400. The message says why.

Then Affectra looks at who signed. It compares the run in the certificate with your organization’s trusted publishers: the repository, and the workflow and ref if you restricted them. A certificate does not name the GitHub environment, so a repository that is trusted only for one environment never counts as a signer.

On the release’s SBOMs tab, each SBOM has a badge:

Badge Meaning
signed Signed in CI by a repository your organization trusts.
signed, untrusted Signed, but by a repository or workflow that is not one of your trusted publishers. The upload shows a warning.
unsigned Uploaded without a Sigstore signature.

The SBOM’s badge is the best of its signatures. In the list of releases, a release shows signed when every SBOM of it is signed by a trusted publisher.

Open an SBOM to see each of its signatures: which repository and workflow signed it, from which tag and commit, when, and the run and the transparency log entry. An SBOM attestation also lists the files it says it describes, and whether build provenance names them. What a signature shows explains how to read it.

Affectra keeps what held at the time of the upload. If you later stop trusting the repository, the old badge stays.

A signature card has three kinds of statement, and they are not equally strong.

Verified. The certificate proves these, and Affectra checked them when the SBOM arrived:

  • Signed in CI. A GitHub Actions run of that repository and workflow signed it, from that tag or branch and commit, at that time. The transparency log has an entry for it.
  • Unchanged. The SBOM Affectra stores is the document the run signed. For a signature these are the exact bytes. For an attestation it is the document inside the signed statement.
  • Trusted publisher. Which of your trusted publishers allowed it. If you deleted that publisher since, the card says so. If none matches, the card says the signer is not one of your trusted publishers.

Stated by the workflow. An attestation lists the files the SBOM describes. That is the workflow’s claim. Affectra compares it with the build provenance of the release, and tells you for each file whether provenance from the same run, or the same commit, names it, or whether none does.

Not shown. The component list is what the SBOM tool recorded, and Affectra does not inspect the images. Nothing here shows that devices run these images. A signature ties the SBOM to a commit, not to a review of that code.

Affectra compares the tag of the signing run with the release’s version, for an SBOM and for build provenance. A release 1.0.2 signed from tag v1.0.2 shows matches release 1.0.2. If a run for tag v1.0.1 signed something you uploaded to release 1.0.2, the upload shows the warning “signed for tag v1.0.1, not version 1.0.2”, and the release page flags the signature, because it then vouches for another version’s build. Tags such as v1.0.2, gateway-1.0.2 or gateway/v1.0.2 match version 1.0.2. Runs on a branch or a pull request are not checked. The upload is never refused for this.

Under Check it yourself, each signature has a link to its bundle and the cosign command filled in with its signer. See Check a signature yourself for the same steps by hand.

Download the SBOM with Download the document as uploaded, and its bundle with the bundle link. Then check them with cosign:

Terminal window
cosign verify-blob \
--bundle sbom.cdx.json.sigstore.json \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp '^https://github.com/acme/gateway/' \
sbom.cdx.json

Replace acme/gateway with your repository. For a build provenance bundle, use gh attestation verify <image> --bundle <file> --repo <owner/name>.

  • The signature must come from a GitHub Actions run. Signing in another CI system, or with a key, is not accepted. Upload from there without a signature, or sign in a GitHub Actions job.
  • Attestations of private repositories are not accepted yet, because GitHub signs them with its own Sigstore instance. The SBOM can still be signed with sign: true, which uses Sigstore’s public instance.
  • Signing with Sigstore’s public instance writes the repository name, workflow and commit into a public log. If that is not acceptable for a private repository, upload without a signature.
  • A bundle that signs an SBOM is at most 64 KiB. An attestation also holds the SBOM, so it may be up to 64 KiB plus twice the SBOM, and at most 24 MiB. actions/attest-sbom takes SBOMs up to 16 MiB. A provenance bundle is at most 64 KiB.
  • If Affectra cannot load Sigstore’s trust data for a moment, signed uploads fail with 503. Unsigned uploads keep working. Try again later.

With another CI system, or from a script, send the SBOM and its bundle together as multipart/form-data. The part sbom is the document, and sigstore_bundle is the bundle. This works only for a signature made in a GitHub Actions run, which is what Affectra accepts:

Terminal window
cosign sign-blob --yes --new-bundle-format \
--bundle sbom.sigstore.json sbom.cdx.json
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $AFFECTRA_API_KEY" \
--form sbom=@sbom.cdx.json \
--form sigstore_bundle=@sbom.sigstore.json \
"https://affectra.example.com/v1/orgs/acme/sbom-uploads?product=Gateway&version=1.4.0"

Build provenance goes to attestation-uploads with the same names, as the bundle itself:

Terminal window
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $AFFECTRA_API_KEY" \
--header "Content-Type: application/json" \
--data-binary @firmware.provenance.sigstore.json \
"https://affectra.example.com/v1/orgs/acme/attestation-uploads?product=Gateway&version=1.4.0"

Uploading a document the release already has, with another bundle, adds that signature to the existing SBOM.