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.
What Affectra supports today
Section titled “What Affectra supports today”- 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: trueorcosign sign-blobfor 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.
Sign with the action
Section titled “Sign with the action”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: trueSigning 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:
cosign sign-blob --yes --new-bundle-format \ --bundle sbom.cdx.json.sigstore.json sbom.cdx.jsonAttest the SBOM
Section titled “Attest the SBOM”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.jsonLeave 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.
Add build provenance
Section titled “Add build provenance”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.jsonThe 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.
What Affectra checks
Section titled “What Affectra checks”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.
What you see
Section titled “What you see”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.
What a signature shows
Section titled “What a signature shows”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.
The version check
Section titled “The version check”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.
Check it yourself
Section titled “Check it yourself”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.
Check a signature yourself
Section titled “Check a signature yourself”Download the SBOM with Download the document as uploaded, and its bundle with the bundle link. Then check them with cosign:
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.jsonReplace acme/gateway with your repository. For a build provenance bundle, use gh attestation verify <image> --bundle <file> --repo <owner/name>.
Limits
Section titled “Limits”- 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-sbomtakes 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.
Sign and upload without the action
Section titled “Sign and upload without the action”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:
cosign sign-blob --yes --new-bundle-format \ --bundle sbom.sigstore.json sbom.cdx.jsoncurl --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:
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.