Docker-SBOM: slik genererer du en, og dette går den glipp av

Slik genererer du en SBOM for et Docker-image

Det finnes tre vanlige måter. BuildKit kan skrive SBOM-en mens det bygger imaget, og knytte den til imaget som en attestasjon. Docker Scout og Syft genererer en fra et image som allerede finnes, lokalt eller i et register.

Under bygget, med BuildKit

Legg til --sbom=true, eller den lange formen --attest type=sbom, i docker buildx build. BuildKit kjører Syft-skannerpluginen sin på resultatet og knytter SBOM-en til imaget som et SPDX JSON-dokument. Bygg med local-eksportøren for å se på SBOM-en før du pusher noe:

# 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

Les SBOM-en som er knyttet til et image

docker buildx imagetools inspect leser attestasjonen tilbake fra registeret. Alt som gjelder SBOM, ligger under .SBOM i Go-malen:

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

Fra et eksisterende image, med Docker Scout

docker scout sbom bruker SBOM-attestasjonen til imaget når den finnes. Når den ikke finnes, indekserer det innholdet i imaget selv. Det skriver ut JSON som standard og skriver til 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

Fra et eksisterende image, med Syft

Syft er skanneren med åpen kildekode som BuildKit-pluginen er bygget på. Pek den mot et image og velg formatet med -o. Legg til =file for å skrive hvert format til sin 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-attestasjoner er alltid SPDX. Docker Scout skriver SPDX eller CycloneDX, og Syft skriver begge, blant andre formater. Begge standardene lister opp pakker, versjoner, lisenser og package URL-er, så valget kommer som regel an på verktøyet som skal lese SBOM-en etterpå. Se CycloneDX vs SPDX for forskjellene.

Slik bygger en image-skanner en SBOM

Alle disse verktøyene fungerer på samme måte. De pakker ut lagene i imaget og leser pakkemetadataene de finner: pakkedatabasen til operativsystemet og metadataene pakkebehandlere for programmeringsspråk legger igjen. Hver pakke de kan identifisere, blir en oppføring i SBOM-en, også pakkene som kom fra base-imaget.

Ta med byggestadier og byggekonteksten

Som standard skanner BuildKit bare det siste stadiet. I et flertrinnsbygg er kompilatorene, byggeverktøyene og pakkene fra tidligere stadier ikke med i det endelige imaget, og dermed heller ikke i SBOM-en. Dockers dokumentasjon om SBOM-attestasjoner beskriver to byggeargumenter som utvider skanningen. BUILDKIT_SBOM_SCAN_STAGE legger til et stadium, og BUILDKIT_SBOM_SCAN_CONTEXT legger til byggekonteksten:

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

Begge må deklareres med ARG i Dockerfile. Å sette dem bare med --build-arg har ingen effekt, men --build-arg kan overstyre en verdi Dockerfile deklarerer. Med local-eksportøren får hvert skannede stadium sin egen fil, for eksempel sbom-build.spdx.json ved siden av sbom.spdx.json.

Dette går en skanning fortsatt glipp av

Skanning av stadier tetter ett hull. Skanneren leser likevel filer, og noe av det et bygg bruker, etterlater ingen fil, eller ingen den kan identifisere:

• Filer uten pakkemetadata. En binærfil lastet ned med curl, en tarball pakket ut i et RUN-steg eller vendor-kode kopiert inn. Noen binærfiler, for eksempel Go-binærfiler, har byggeinformasjon en skanner kan lese; mange har det ikke.
• Det bygget lastet ned og slettet. En pakke eller et installasjonsprogram som et RUN-steg henter, bruker og fjerner i samme lag, etterlater ingenting i filsystemet som noen skanner kan lese, enten det er siste stadium eller ikke.
• Hvordan ting kom inn. En SBOM fra en skanning lister opp det som er der. Den sier ikke hvilket register eller hvilken vert en pakke kom fra, eller hvilket steg som hentet den.
• Stadier du ikke merket. Skanning av stadier må slås på, per stadium eller globalt. Et stadium uten argumentet blir fortsatt utelatt.
• Skanneinnstillinger. Hva som dukker opp, avhenger av hvordan skanneren kjøres. På ett prosjekt avgjør ett enkelt Syft-flagg om npm-pakker i det hele tatt kommer med i resultatet.

Hvorfor det er viktig

Et kompromittert byggeverktøy eller base-image påvirker det du leverer, selv om det aldri dukker opp i det endelige imaget. Og en binærfil uten metadata kan ha en sårbarhet som ingen SBOM-oppføring peker på. Når en advisory kommer, må du vite hva som gikk med til å bygge imaget, i tillegg til hva som er i det.

Registrer bygget også

Image-SBOM-en svarer på hva som er inne i imaget. En registrering av bygget svarer på hva bygget hentet inn: base-imagene det hentet, og pakkene hvert steg hentet, inkludert de skjulte avhengighetene som ingen lockfile lister opp. CRACI registrerer dette mens GitHub Actions-jobben din kjører, gjennom en pakkebevisst proxy på runneren, og API-et returnerer SBOM-er, nettverksspor og provenance for jobben. Bruk image-SBOM-en for det du leverer, og byggeregistreringen for hvordan det ble laget.

Se SBOM-verktøy sammenlignet, SBOM-er fra bygget og slik genererer du en SBOM i GitHub Actions.

Docker-SBOM-er: ofte stilte spørsmål

Hvordan genererer jeg en SBOM for et Docker-image?

Det finnes tre vanlige måter. Legg til --sbom=true i docker buildx build, så knytter BuildKit en SPDX-SBOM til imaget. Kjør docker scout sbom på et eksisterende image. Eller kjør Syft, for eksempel syft IMAGE -o cyclonedx-json. Alle tre leser pakkene de finner i imaget.

Hva er en SBOM-skanner?

Et verktøy som leser filer, for eksempel en kildekatalog, en lockfile eller et container-image, og skriver en SBOM over pakkene det kan identifisere. Syft, Trivy, Docker Scout og Syft-pluginen til BuildKit er SBOM-skannere. De beskriver filene de har foran seg, ikke bygget som produserte dem.

Hvilket SBOM-format produserer Docker?

BuildKit-attestasjoner er SPDX JSON-dokumenter knyttet til imaget. Docker Scout kan skrive ut en pakkeliste eller skrive SPDX eller CycloneDX. Syft skriver begge, og flere. Velg formatet verktøyet som bruker SBOM-en, forventer.

Hvordan bygger en skanner en SBOM fra et Docker-image?

Den pakker ut lagene i imaget og leser pakkemetadataene den finner: pakkedatabasen til operativsystemet og pakkefiler for programmeringsspråk, for eksempel metadata for installerte npm- eller Python-pakker. Hver pakke den kan identifisere, blir en oppføring i SBOM-en.

Hvorfor kan en image-SBOM gå glipp av en komponent?

Fordi den bare kan liste opp det den kan identifisere i filene den leser. En binærfil lastet ned med curl har ingen pakkemetadata, en pakke et byggesteg lastet ned og slettet, etterlater ingenting å lese, og tidligere byggestadier utelates med mindre du slår på skanning av stadier.

Er en image-SBOM fortsatt nyttig?

Ja. Den er den rette oversikten over hva som er inne i imaget du leverer, inkludert pakker fra base-imaget. Den beskriver bare ikke hvordan imaget ble bygget, så kombiner den med en registrering av bygget når det er viktig.