Come generare una SBOM in GitHub Actions

Quattro approcci

1. Esporti il dependency graph

GitHub costruisce un dependency graph dai manifest e dai lockfile di un repository e può esportarlo come SBOM SPDX. Non richiede modifiche al workflow: apra la scheda Insights del repository, scelga Dependency graph e faccia clic su Export SBOM. Descrive il repository sul branch predefinito, non una build specifica, quindi non contiene gli strumenti e i pacchetti che un workflow installa.

Per automatizzarlo con uno script, usi la REST API. GET /repos/{owner}/{repo}/dependency-graph/sbom restituisce lo SPDX JSON con una sola chiamata, ma GitHub lo dismette dopo il 13 novembre 2026. Il sostituto è asincrono: si richiede un report, poi si recupera il sbom_url che restituisce. Quell'URL risponde 202 mentre la SBOM viene generata, poi reindirizza al file SPDX JSON, che GitHub conserva per un massimo di una settimana.

# Export the dependency graph as SPDX JSON (closing down after November 13, 2026)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/dependency-graph/sbom

# The replacement: request a report; the response carries an sbom_url
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/dependency-graph/sbom/generate-report

2. Aggiunga uno step di generazione

Uno step del workflow esegue un generatore sul workspace o su un'immagine. anchore/sbom-action esegue Syft: per impostazione predefinita scansiona la directory del workspace e produce SPDX JSON, può invece scansionare un'immagine container, carica la SBOM come artefatto del workflow e la allega alle release. Il suo README richiede contents: write, più actions: read quando allega la SBOM a una release:

name: sbom
on:
  push:
    branches: [main]
  release:
    types: [published]

jobs:
  sbom:
    runs-on: ubuntu-latest
    permissions:
      contents: write # upload the SBOM
      actions: read # attach it to a release
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      # Scan the workspace after the install step
      - uses: anchore/sbom-action@v0
        with:
          path: .
          format: cyclonedx-json

format accetta spdx, spdx-json, cyclonedx o cyclonedx-json. Per scansionare un'immagine, sostituisca path con image, ad esempio image: ghcr.io/OWNER/app:1.0. Veda Docker SBOM per le SBOM di immagine generate da BuildKit.

Trivy e cdxgen si possono eseguire allo stesso modo, come semplici step run. cdxgen scrive CycloneDX; dalla versione 13 il suo pacchetto npm è @cdxgen/cdxgen:

    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npm install -g @cdxgen/cdxgen --ignore-scripts
      - run: cdxgen -o bom.json .
      - uses: actions/upload-artifact@v7
        with:
          name: sbom
          path: bom.json

Il momento conta. Esegua lo step dopo l'installazione delle dipendenze, altrimenti non le vedrà. Anche così, un generatore vede i file che ha davanti: un pacchetto che uno script ha scaricato, usato ed eliminato, o uno strumento installato al di fuori di un package manager, possono mancare.

3. La firmi come attestazione

Le artifact attestation di GitHub vincolano una SBOM all'artefatto che descrive e la firmano con Sigstore. actions/attest@v4 accetta SPDX o CycloneDX JSON tramite sbom-path, fino a 16 MB. Senza sbom-path produce invece una build provenance SLSA. actions/attest-sbom è in fase di deprecazione a favore di actions/attest, di cui ora è un wrapper. Il job ha bisogno di id-token: write per ottenere un certificato di firma e di attestations: write per archiviare il risultato:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # sign with a Sigstore certificate
      contents: read
      attestations: write # store the attestation
    steps:
      - uses: actions/checkout@v7
      - run: make build # writes dist/my-app
      - uses: anchore/sbom-action@v0
        with:
          path: .
          format: spdx-json
          output-file: sbom.spdx.json
          upload-artifact: false
      - uses: actions/attest@v4
        with:
          subject-path: dist/my-app
          sbom-path: sbom.spdx.json

Per un'immagine container, passi subject-name e subject-digest invece di subject-path, imposti push-to-registry: true e aggiunga packages: write. Le artifact attestation funzionano nei repository pubblici con tutti i piani GitHub attuali; i repository privati e interni richiedono GitHub Enterprise Cloud.

La GitHub CLI verifica poi chi ha prodotto la SBOM e per quale artefatto. Le attestazioni SBOM richiedono --predicate-type; aggiunga --format json per vedere la SBOM stessa. Per un'immagine, usi oci:// seguito dal nome dell'immagine al posto del percorso del file.

gh attestation verify dist/my-app \
  -R OWNER/REPO \
  --predicate-type https://spdx.dev/Document/v2.3

Un'attestazione dimostra chi ha prodotto la SBOM e per quale artefatto. Non rende la SBOM più completa.

4. La registri durante la build

CRACI registra la SBOM durante l'esecuzione del job. Lei cambia runs-on in craci:

jobs:
  build:
    runs-on: craci # was: ubuntu-latest

Un proxy sul runner che riconosce i pacchetti registra quindi ogni pacchetto scaricato dal job, compresi i pacchetti ripristinati dalle cache CI e le dipendenze nascoste che nessun lockfile elenca, come il codice scaricato dagli script di installazione. Non c'è alcuno step di generazione da posizionare, quindi la questione del momento non si pone. Ogni SBOM, in CycloneDX o SPDX, indica la propria completezza per job e per cache, e l'API restituisce SBOM, tracce di rete e provenance. La configurazione, compresi la GitHub App di CRACI e le impostazioni di rete, è descritta nella documentazione di CRACI, e il significato di ogni stato di completezza è spiegato in completezza della SBOM per job e cache.

Quale usare

• Un inventario rapido di un repository: l'export del dependency graph.
• Una SBOM di un'immagine container: uno step di generazione sull'immagine.
• La prova di chi ha prodotto una SBOM per quale artefatto: un'attestazione, in aggiunta a uno dei due.
• Un registro di ciò che la build ha effettivamente usato, per la risposta alle vulnerabilità o per il Cyber Resilience Act: la registrazione in fase di build. Veda gli strumenti SBOM a confronto.

SBOM in GitHub Actions: domande frequenti

Come si genera una SBOM in GitHub Actions?

Aggiunga uno step di generazione dopo lo step di installazione. Il più breve è anchore/sbom-action@v0, che esegue Syft sul workspace e carica una SBOM SPDX JSON come artefatto del workflow. Per una SBOM firmata, passi il file ad actions/attest@v4 con sbom-path.

GitHub genera automaticamente una SBOM?

GitHub può esportare il dependency graph di un repository come SBOM SPDX, dalla scheda Insights o tramite la REST API. Descrive i manifest e i lockfile del repository, non una build specifica, quindi non mostra gli strumenti o i pacchetti che un workflow scarica.

Quale action genera una SBOM in GitHub Actions?

anchore/sbom-action esegue Syft. Per impostazione predefinita scansiona la directory del workspace e produce SPDX JSON; può invece scansionare un'immagine container, carica la SBOM come artefatto del workflow e la allega alle release.

Di quali permessi ha bisogno un workflow SBOM?

anchore/sbom-action richiede contents: write, più actions: read per allegare la SBOM a una release. La firma con actions/attest richiede id-token: write e attestations: write, e packages: write quando l'attestazione viene inviata a un container registry.

Come si firma una SBOM in GitHub Actions?

Usi le artifact attestation di GitHub. actions/attest firma una SBOM SPDX o CycloneDX JSON con Sigstore e la vincola a un artefatto; la verifichi con gh attestation verify. actions/attest-sbom è in fase di deprecazione a favore di actions/attest, di cui ora è un wrapper.

Come si genera una SBOM per un'immagine container in GitHub Actions?

Passi l'immagine ad anchore/sbom-action con l'input image invece di path. Per firmarla, fornisca ad actions/attest il nome e il digest dell'immagine tramite subject-name e subject-digest, imposti push-to-registry: true e verifichi con gh attestation verify oci://IMAGE.

Il workflow dovrebbe produrre SPDX o CycloneDX?

Quello previsto dallo strumento che legge la SBOM. L'export del dependency graph è solo SPDX e cdxgen scrive CycloneDX. anchore/sbom-action scrive entrambi e actions/attest li accetta entrambi. Veda CycloneDX vs SPDX.

Lo step SBOM va eseguito prima o dopo la build?

Dopo l'installazione delle dipendenze, altrimenti non le vedrà. Anche così vede ciò che è su disco, non ciò che il job ha scaricato e rimosso né ciò che uno script ha scaricato. Registrare durante la build evita la questione del momento.