Docker SBOM: så genererar du en och vad den missar

Så genererar du en SBOM för en Docker-avbild

Det finns tre vanliga sätt. BuildKit kan skriva SBOM:en medan avbilden byggs och koppla den till avbilden som en attestering. Docker Scout och Syft genererar en från en avbild som redan finns, lokalt eller i ett register.

Under bygget, med BuildKit

Lägg till --sbom=true, eller den långa formen --attest type=sbom, till docker buildx build. BuildKit kör sitt skannerplugin Syft på resultatet och kopplar SBOM:en till avbilden som ett SPDX JSON-dokument. Bygg med exportören local för att titta på SBOM:en innan du pushar något:

# 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

Läs SBOM:en som är kopplad till en avbild

docker buildx imagetools inspect läser tillbaka attesteringen från registret. Allt som rör SBOM:en finns under .SBOM i dess Go-mall:

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

Från en befintlig avbild, med Docker Scout

docker scout sbom använder avbildens SBOM-attestering när det finns en. När det inte finns någon indexerar verktyget själv avbildens innehåll. Det skriver ut JSON som standard och skriver till en fil med --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

Från en befintlig avbild, med Syft

Syft är den skanner med öppen källkod som BuildKits plugin bygger på. Peka den mot en avbild och välj format med -o. Lägg till =file för att skriva varje format till en egen fil:

# 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 eller CycloneDX?

BuildKit-attesteringar är alltid SPDX. Docker Scout skriver SPDX eller CycloneDX, och Syft skriver båda, bland andra format. Båda standarderna listar paket, versioner, licenser och package URL:er, så valet handlar oftast om vilket verktyg som läser SBOM:en härnäst. Se CycloneDX vs SPDX för skillnaderna.

Så bygger en avbildsskanner en SBOM

Alla de här verktygen fungerar på samma sätt. De packar upp avbildens lager och läser paketmetadatan de hittar: operativsystemets paketdatabas och den metadata som pakethanterare för olika språk lämnar efter sig. Varje paket de kan identifiera blir en post i SBOM:en, inklusive paketen som kom från basavbilden.

Ta med byggsteg och byggkontexten

Som standard skannar BuildKit bara det sista steget. I ett flerstegsbygge finns kompilatorerna, byggverktygen och paketen från tidigare steg inte i den slutliga avbilden, så de finns inte heller i dess SBOM. Dockers dokumentation om SBOM-attesteringar beskriver två byggargument som breddar skanningen. BUILDKIT_SBOM_SCAN_STAGE lägger till ett steg, och BUILDKIT_SBOM_SCAN_CONTEXT lägger till byggkontexten:

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

Båda måste deklareras med ARG i Dockerfile. Att bara sätta dem med --build-arg har ingen effekt, men --build-arg kan åsidosätta ett värde som Dockerfile deklarerar. Med exportören local får varje skannat steg en egen fil, till exempel sbom-build.spdx.json bredvid sbom.spdx.json.

Vad en skanning ändå missar

Skanning av byggsteg täpper till en lucka. Skannern läser ändå filer, och en del av det ett bygge använder lämnar ingen fil efter sig, eller ingen som den kan identifiera:

• Filer utan paketmetadata. En binär som laddas ner med curl, ett tar-arkiv som packas upp i ett RUN-steg eller vendorad kod som kopieras in. Vissa binärer bär på bygginformation som en skanner kan läsa, till exempel Go-binärer; många gör det inte.
• Det bygget laddade ner och tog bort. Ett paket eller installationsprogram som ett RUN-steg hämtar, använder och tar bort i samma lager lämnar inget i filsystemet som någon skanner kan läsa, oavsett om det är det sista steget eller inte.
• Hur saker kom in. En SBOM från en skanning listar vad som finns där. Den säger inte vilket register eller vilken värd ett paket kom från, eller vilket steg som hämtade det.
• Steg du inte markerade. Skanning av byggsteg är något du väljer att slå på, per steg eller globalt. Ett steg utan argumentet lämnas fortfarande utanför.
• Skanningsinställningar. Vad som visas beror på hur skannern körs. I ett projekt avgör en enda Syft-flagga om npm-paket över huvud taget visas i resultatet.

Varför det spelar roll

Ett komprometterat byggverktyg eller en komprometterad basavbild påverkar det du levererar även om det aldrig syns i den slutliga avbilden. Och en binär utan metadata kan bära på en sårbarhet som ingen post i SBOM:en pekar på. När ett säkerhetsmeddelande dyker upp behöver du veta vad som gick in i bygget av avbilden, inte bara vad som finns i den.

Registrera bygget också

Avbildens SBOM besvarar vad som finns i avbilden. En registrering av bygget besvarar vad bygget drog in: basavbilderna det hämtade och paketen som varje steg hämtade, inklusive de dolda beroenden som ingen lockfile listar. CRACI registrerar det medan ditt GitHub Actions-jobb körs, via en paketmedveten proxy på runnern, och API:t returnerar SBOM:er, nätverksspårningar och proveniens för jobbet. Använd avbildens SBOM för det du levererar och byggregistreringen för hur det togs fram.

Se SBOM-verktyg i jämförelse, SBOM:er från bygget och så genererar du en SBOM i GitHub Actions.

Docker-SBOM:er: vanliga frågor

Hur genererar jag en SBOM för en Docker-avbild?

Det finns tre vanliga sätt. Lägg till --sbom=true till docker buildx build så kopplar BuildKit en SPDX-SBOM till avbilden. Kör docker scout sbom på en befintlig avbild. Eller kör Syft, till exempel syft IMAGE -o cyclonedx-json. Alla tre läser paketen de hittar i avbilden.

Vad är en SBOM-skanner?

Ett verktyg som läser filer, till exempel en källkodskatalog, en lockfile eller en containeravbild, och skriver en SBOM över de paket det kan identifiera. Syft, Trivy, Docker Scout och BuildKits Syft-plugin är SBOM-skannrar. De beskriver filerna framför dem, inte bygget som producerade filerna.

Vilket SBOM-format producerar Docker?

BuildKit-attesteringar är SPDX JSON-dokument som kopplas till avbilden. Docker Scout kan skriva ut en paketlista eller skriva SPDX eller CycloneDX. Syft skriver båda, och fler. Välj det format som verktyget som läser SBOM:en förväntar sig.

Hur bygger en skanner en SBOM från en Docker-avbild?

Den packar upp avbildens lager och läser paketmetadatan den hittar: operativsystemets paketdatabas och språkspecifika paketfiler, till exempel metadata för installerade npm- eller Python-paket. Varje paket den kan identifiera blir en post i SBOM:en.

Varför skulle en SBOM för en avbild missa en komponent?

Därför att den bara kan lista det den kan identifiera i filerna den läser. En binär som laddats ner med curl saknar paketmetadata, ett paket som ett byggsteg laddade ner och tog bort lämnar inget att läsa, och tidigare byggsteg lämnas utanför om du inte slår på skanning av byggsteg.

Är en SBOM för en avbild fortfarande användbar?

Ja. Den är rätt registrering av vad som finns i avbilden du levererar, inklusive paket från basavbilden. Den beskriver bara inte hur avbilden byggdes, så kombinera den med en registrering av bygget när det spelar roll.