Docker SBOM: come generarne una e che cosa non vede

Come generare una SBOM per un'immagine Docker

Esistono tre modi comuni. BuildKit può scrivere la SBOM mentre compila l'immagine e allegarla all'immagine come attestazione. Docker Scout e Syft ne generano una da un'immagine già esistente, in locale o in un registry.

In fase di build, con BuildKit

Aggiunga --sbom=true, o la sua forma estesa --attest type=sbom, a docker buildx build. BuildKit esegue il suo plugin di scansione Syft sul risultato e allega la SBOM all'immagine come documento SPDX JSON. Compili con l'exporter local per esaminare la SBOM prima di eseguire qualsiasi push:

# Build the image, attach an SBOM attestation and push it
docker buildx build --sbom=true -t registry.example.com/app:1.0 --push .

# The long form of the same option
docker buildx build --attest type=sbom -t registry.example.com/app:1.0 --push .

# Check the SBOM before pushing: write the build result to ./out
docker buildx build --sbom=true --output type=local,dest=out .
# out/sbom.spdx.json is the SBOM

Leggere la SBOM allegata a un'immagine

docker buildx imagetools inspect rilegge l'attestazione dal registry. Tutto ciò che riguarda la SBOM si trova sotto .SBOM nel suo template Go:

# Print the SPDX document attached to the image
docker buildx imagetools inspect registry.example.com/app:1.0 \
  --format "{{ json .SBOM.SPDX }}"

# List each package and its version
docker buildx imagetools inspect registry.example.com/app:1.0 \
  --format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}"

Da un'immagine esistente, con Docker Scout

docker scout sbom usa l'attestazione SBOM dell'immagine quando esiste. Quando non esiste, indicizza da solo il contenuto dell'immagine. Per impostazione predefinita stampa JSON e scrive su file con --output:

# List the packages in an image
docker scout sbom --format list registry.example.com/app:1.0

# Write an SPDX or CycloneDX SBOM to a file
docker scout sbom --format spdx --output app.spdx.json registry.example.com/app:1.0
docker scout sbom --format cyclonedx --output app.cdx.json registry.example.com/app:1.0

Da un'immagine esistente, con Syft

Syft è lo scanner open source su cui si basa il plugin di BuildKit. Lo punti su un'immagine e scelga il formato con -o. Aggiunga =file per scrivere ogni formato nel proprio file:

# CycloneDX JSON to the terminal
syft registry.example.com/app:1.0 -o cyclonedx-json

# Both formats, each to its own file
syft registry.example.com/app:1.0 -o spdx-json=app.spdx.json -o cyclonedx-json=app.cdx.json

SPDX o CycloneDX?

Le attestazioni di BuildKit sono sempre SPDX. Docker Scout scrive SPDX o CycloneDX, e Syft scrive entrambi, tra gli altri formati. Entrambi gli standard elencano pacchetti, versioni, licenze e package URL, quindi di solito la scelta dipende dallo strumento che leggerà la SBOM. Veda CycloneDX vs SPDX per le differenze.

Come uno scanner di immagini costruisce una SBOM

Tutti questi strumenti funzionano allo stesso modo. Decomprimono i layer dell'immagine e leggono i metadati dei pacchetti che trovano: il database dei pacchetti del sistema operativo e i metadati lasciati dai package manager dei linguaggi. Ogni pacchetto che riescono a identificare diventa una voce della SBOM, compresi i pacchetti provenienti dall'immagine base.

Includere le fasi di build e il contesto di build

Per impostazione predefinita, BuildKit scansiona solo la fase finale. In una build multi-stage, i compilatori, gli strumenti di build e i pacchetti usati nelle fasi precedenti non sono nell'immagine finale, quindi non sono nemmeno nella sua SBOM. La documentazione di Docker sulle attestazioni SBOM descrive due argomenti di build che ampliano la scansione. BUILDKIT_SBOM_SCAN_STAGE aggiunge una fase e BUILDKIT_SBOM_SCAN_CONTEXT aggiunge il contesto di build:

# syntax=docker/dockerfile:1
# Scan the build context as well as the image
ARG BUILDKIT_SBOM_SCAN_CONTEXT=true

FROM golang:1.25 AS build
# Include this build stage in the SBOM
ARG BUILDKIT_SBOM_SCAN_STAGE=true
WORKDIR /src
COPY . .
RUN go build -o /out/app .

FROM scratch
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

Entrambi devono essere dichiarati con ARG nel Dockerfile. Impostarli solo con --build-arg non ha effetto, anche se --build-arg può sovrascrivere un valore dichiarato dal Dockerfile. Con l'exporter local, ogni fase scansionata ottiene il proprio file, ad esempio sbom-build.spdx.json accanto a sbom.spdx.json.

Che cosa sfugge ancora a una scansione

La scansione delle fasi chiude una lacuna. Lo scanner però continua a leggere file, e parte di ciò che una build usa non lascia alcun file, o nessuno che possa identificare:

• File senza metadati di pacchetto. Un binario scaricato con curl, un archivio tar decompresso in un passaggio RUN, oppure codice vendored copiato all'interno. Alcuni binari contengono informazioni di build leggibili da uno scanner, come i binari Go; molti no.
• Ciò che la build ha scaricato ed eliminato. Un pacchetto o un installer che un passaggio RUN scarica, usa e rimuove nello stesso layer non lascia nulla sul filesystem da leggere per alcuno scanner, fase finale o meno.
• Come sono entrate le cose. Una SBOM da scansione elenca ciò che c'è. Non dice da quale registry o host proviene un pacchetto, né quale passaggio lo ha scaricato.
• Le fasi che non ha contrassegnato. La scansione delle fasi va attivata esplicitamente, per fase o globalmente. Una fase senza l'argomento resta esclusa.
• Impostazioni di scansione. Ciò che compare dipende da come viene eseguito lo scanner. In un progetto, un singolo flag di Syft decide se i pacchetti npm compaiono o meno nel risultato.

Perché è importante

Uno strumento di build o un'immagine base compromessi influiscono su ciò che Lei distribuisce anche se non compaiono mai nell'immagine finale. E un binario senza metadati può contenere una vulnerabilità a cui nessuna voce della SBOM rimanda. Quando arriva un advisory, deve sapere che cosa è servito a compilare l'immagine oltre a che cosa contiene.

Registri anche la build

La SBOM dell'immagine risponde alla domanda su che cosa c'è dentro l'immagine. Un registro della build risponde alla domanda su che cosa ha introdotto la build: le immagini base che ha scaricato e i pacchetti scaricati da ogni passaggio, comprese le dipendenze nascoste che nessun lockfile elenca. CRACI li registra durante l'esecuzione del Suo job GitHub Actions, tramite un proxy sul runner che riconosce i pacchetti, e l'API restituisce SBOM, tracce di rete e provenance per il job. Usi la SBOM dell'immagine per ciò che distribuisce e il registro della build per come è stato prodotto.

Veda gli strumenti SBOM a confronto, le SBOM in fase di build e come generare una SBOM in GitHub Actions.

SBOM Docker: domande frequenti

Come si genera una SBOM per un'immagine Docker?

In tre modi comuni. Aggiunga --sbom=true a docker buildx build e BuildKit allegherà all'immagine una SBOM SPDX. Esegua docker scout sbom su un'immagine esistente. Oppure esegua Syft, ad esempio syft IMAGE -o cyclonedx-json. Tutti e tre leggono i pacchetti che trovano nell'immagine.

Che cos'è uno scanner SBOM?

Uno strumento che legge file, come una directory di sorgenti, un lockfile o un'immagine container, e scrive una SBOM dei pacchetti che riesce a identificare. Syft, Trivy, Docker Scout e il plugin Syft di BuildKit sono scanner SBOM. Descrivono i file che hanno davanti, non la build che li ha prodotti.

Quale formato SBOM produce Docker?

Le attestazioni di BuildKit sono documenti SPDX JSON allegati all'immagine. Docker Scout può stampare un elenco di pacchetti oppure scrivere SPDX o CycloneDX. Syft scrive entrambi, e altri ancora. Scelga il formato previsto dallo strumento che userà la SBOM.

Come fa uno scanner a costruire una SBOM da un'immagine Docker?

Decomprime i layer dell'immagine e legge i metadati dei pacchetti che trova: il database dei pacchetti del sistema operativo e i file dei pacchetti dei linguaggi, come i metadati dei pacchetti npm o Python installati. Ogni pacchetto che riesce a identificare diventa una voce della SBOM.

Perché una SBOM dell'immagine può non includere un componente?

Perché può elencare solo ciò che riesce a identificare nei file che legge. Un binario scaricato con curl non ha metadati di pacchetto, un pacchetto scaricato ed eliminato da un passaggio di build non lascia nulla da leggere, e le fasi di build precedenti restano escluse a meno che non attivi la scansione delle fasi.

Una SBOM dell'immagine è ancora utile?

Sì. È il registro giusto di ciò che si trova nell'immagine che Lei distribuisce, compresi i pacchetti provenienti dall'immagine base. Semplicemente non descrive come l'immagine è stata compilata, quindi la abbini a un registro della build quando questo conta.