Docker SBOM: jak ji vygenerovat a co v ní chybí

Jak vygenerovat SBOM pro Docker image

Existují tři běžné způsoby. BuildKit může SBOM zapsat už během sestavování image a připojit ji k image jako atestaci. Docker Scout a Syft ji vygenerují z již existující image, lokálně nebo v registru.

V době buildu, pomocí BuildKitu

Přidejte --sbom=true nebo jeho dlouhý tvar --attest type=sbom k příkazu docker buildx build.BuildKit na výsledek spustí svůj skenovací plugin Syft a připojí SBOM k image jako dokument SPDX JSON. Pokud si chcete SBOM prohlédnout, než cokoli pushnete, použijte při buildu exportér local:

# 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

Přečtěte SBOM připojenou k image

docker buildx imagetools inspect načte atestaci zpět z registru. Vše, co se týká SBOM, najdete v jeho šabloně Go pod .SBOM:

# 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 }}"

Z existující image, pomocí Docker Scout

docker scout sbom použije atestaci SBOM image, pokud existuje. Pokud ne, zaindexuje obsah image sám. Ve výchozím stavu vypisuje JSON a s parametrem --output zapisuje do souboru:

# 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

Z existující image, pomocí Syftu

Syft je open source skener, na kterém je postaven plugin BuildKitu. Nasměrujte ho na image a formát zvolte pomocí -o. Přidáním =file zapíšete každý formát do vlastního souboru:

# 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, nebo CycloneDX?

Atestace BuildKitu jsou vždy SPDX. Docker Scout zapisuje SPDX nebo CycloneDX a Syft mimo jiné formáty oba. Oba standardy uvádějí balíčky, verze, licence a package URL, takže volba obvykle závisí na nástroji, který bude SBOM číst dál. Rozdíly popisuje článek CycloneDX vs SPDX.

Jak skener image sestavuje SBOM

Všechny tyto nástroje fungují stejně. Rozbalí vrstvy image a přečtou metadata balíčků, která najdou: databázi balíčků operačního systému a metadata, která po sobě zanechávají správci balíčků jednotlivých jazyků. Každý balíček, který dokážou identifikovat, se stane záznamem v SBOM, včetně balíčků ze základní image.

Zahrňte fáze buildu a kontext buildu

Ve výchozím stavu BuildKit skenuje jen poslední fázi. Ve vícefázovém buildu nejsou kompilátory, nástroje buildu a balíčky použité v dřívějších fázích ve výsledné image, takže nejsou ani v její SBOM. Dokumentace Dockeru k atestacím SBOM popisuje dva argumenty buildu, které sken rozšiřují. BUILDKIT_SBOM_SCAN_STAGE přidá fázi a BUILDKIT_SBOM_SCAN_CONTEXT přidá kontext buildu:

# 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"]

Oba musí být v Dockerfile deklarovány pomocí ARG. Pouhé nastavení přes --build-arg nemá žádný účinek, i když --build-arg může přepsat hodnotu, kterou Dockerfile deklaruje. S exportérem local dostane každá skenovaná fáze vlastní soubor, například sbom-build.spdx.json vedle sbom.spdx.json.

Co sken stále nezachytí

Skenování fází uzavírá jednu mezeru. Skener ale pořád čte soubory a část toho, co build používá, po sobě žádný soubor nezanechá, nebo žádný, který by dokázal identifikovat:

• Soubory bez metadat balíčků. Binárka stažená pomocí curl, tarball rozbalený v kroku RUN nebo zkopírovaný vendorovaný kód. Některé binárky nesou informace o buildu, které skener přečte, například binárky Go; mnohé ne.
• Co build stáhl a smazal. Balíček nebo instalátor, který krok RUN stáhne, použije a odstraní ve stejné vrstvě, nezanechá v souborovém systému nic, co by kterýkoli skener mohl přečíst, ať jde o poslední fázi, nebo ne.
• Jak se věci dostaly dovnitř. SBOM ze skenu uvádí, co tam je. Neříká, z jakého registru nebo hostitele balíček pochází, ani který krok ho stáhl.
• Fáze, které jste neoznačili. Skenování fází se zapíná výslovně, pro jednotlivé fáze nebo globálně. Fáze bez argumentu zůstává vynechána.
• Nastavení skenu. Co se objeví, závisí na tom, jak se skener spustí. U jednoho projektu rozhoduje jediný parametr Syftu o tom, zda se balíčky npm ve výsledku vůbec objeví.

Stejný problém u buildů Yocto popisuje článek proč skenery SBOM přehlížejí, co je v buildech Yocto.

Proč na tom záleží

Kompromitovaný nástroj buildu nebo základní image ovlivní to, co vydáváte, i když se ve výsledné image nikdy neobjeví. A binárka bez metadat může nést zranitelnost, na kterou neukazuje žádný záznam v SBOM. Když vyjde bezpečnostní upozornění, potřebujete vědět, co šlo do sestavení image, a také co je v ní.

Zaznamenejte i build

SBOM image odpovídá na to, co je uvnitř image. Záznam buildu odpovídá na to, co build natáhl: základní image, které stáhl, a balíčky, které stáhl každý krok, včetně skrytých závislostí, které neuvádí žádný lockfile. CRACI to zaznamenává během běhu vašeho jobu GitHub Actions pomocí proxy na runneru, která rozumí balíčkům, a API pro job vrací SBOM, síťové záznamy a původ (provenance). SBOM image používejte pro to, co vydáváte, a záznam buildu pro to, jak vzniklo.

Viz srovnání nástrojů SBOM, SBOM z doby buildu a jak vygenerovat SBOM v GitHub Actions.

Docker SBOM: časté dotazy

Jak vygeneruji SBOM pro Docker image?

Třemi běžnými způsoby. Přidejte --sbom=true k docker buildx build a BuildKit připojí k image SBOM ve formátu SPDX. Spusťte docker scout sbom na existující image. Nebo spusťte Syft, například syft IMAGE -o cyclonedx-json. Všechny tři čtou balíčky, které v image najdou.

Co je skener SBOM?

Nástroj, který čte soubory, například adresář se zdrojovým kódem, lockfile nebo image kontejneru, a zapíše SBOM balíčků, které dokáže identifikovat. Syft, Trivy, Docker Scout a plugin Syft v BuildKitu jsou skenery SBOM. Popisují soubory, které mají před sebou, ne build, který je vytvořil.

Jaký formát SBOM Docker vytváří?

Atestace BuildKitu jsou dokumenty SPDX JSON připojené k image. Docker Scout umí vypsat seznam balíčků nebo zapsat SPDX či CycloneDX. Syft zapisuje oba a další. Zvolte formát, který očekává nástroj, jenž bude SBOM zpracovávat.

Jak skener sestaví SBOM z Docker image?

Rozbalí vrstvy image a přečte metadata balíčků, která najde: databázi balíčků operačního systému a soubory balíčků jednotlivých jazyků, například metadata nainstalovaných balíčků npm nebo Pythonu. Každý balíček, který dokáže identifikovat, se stane záznamem v SBOM.

Proč by SBOM image mohla vynechat komponentu?

Protože dokáže uvést jen to, co identifikuje v souborech, které čte. Binárka stažená pomocí curl nenese žádná metadata balíčku, balíček, který krok buildu stáhl a smazal, nezanechá nic ke čtení, a dřívější fáze buildu jsou vynechány, pokud nezapnete skenování fází.

Má SBOM image stále smysl?

Ano. Je to správný záznam toho, co je uvnitř image, kterou vydáváte, včetně balíčků ze základní image. Jen nepopisuje, jak image vznikla, takže ji tam, kde na tom záleží, doplňte záznamem buildu.