Docker-SBOM: sådan genererer du en, og hvad den overser

Sådan genererer du en SBOM for et Docker-image

Der er tre almindelige måder. BuildKit kan skrive SBOM'en, mens det bygger imaget, og vedhæfte den til imaget som en attestation. Docker Scout og Syft genererer en ud fra et image, der allerede findes, lokalt eller i et registry.

Under buildet, med BuildKit

Tilføj --sbom=true, eller den lange form --attest type=sbom, til docker buildx build. BuildKit kører sit Syft-scanner-plugin på resultatet og vedhæfter SBOM'en til imaget som et SPDX JSON-dokument. Byg med local-exporteren for at se SBOM'en, før du pusher noget:

# 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 den SBOM, der er vedhæftet et image

docker buildx imagetools inspect læser attestationen tilbage fra registryet. Alt, der handler om SBOM'en, ligger under .SBOM i Go-skabelonen:

# 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 bruger imagets SBOM-attestation, når der er en. Er der ingen, indekserer det selv imagets indhold. Det udskriver 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 den open source-scanner, som BuildKits plugin er bygget på. Peg den på et image, og vælg formatet med -o. Tilføj =file for at 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-attestationer er altid SPDX. Docker Scout skriver SPDX eller CycloneDX, og Syft skriver begge, blandt andre formater. Begge standarder angiver pakker, versioner, licenser og package URL'er, så valget afhænger som regel af det værktøj, der læser SBOM'en bagefter. Se CycloneDX vs SPDX for forskellene.

Sådan bygger en image-scanner en SBOM

Alle disse værktøjer virker på samme måde. De pakker imagets lag ud og læser de pakkemetadata, de finder: styresystemets pakkedatabase og de metadata, sprogenes pakkehåndteringer efterlader. Hver pakke, de kan identificere, bliver en post i SBOM'en, inklusive pakkerne fra base-imaget.

Medtag build-stages og build-konteksten

Som standard scanner BuildKit kun den sidste stage. I et multi-stage-build er de compilere, build-værktøjer og pakker, der blev brugt i tidligere stages, ikke i det endelige image, så de er heller ikke i dets SBOM. Dockers dokumentation om SBOM-attestationer beskriver to build-argumenter, der udvider scanningen. BUILDKIT_SBOM_SCAN_STAGE tilføjer en stage, og BUILDKIT_SBOM_SCAN_CONTEXT tilføjer build-konteksten:

# 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 skal deklareres med ARG i Dockerfilen. Sætter du dem kun med --build-arg, har det ingen effekt, men --build-arg kan tilsidesætte en værdi, som Dockerfilen deklarerer. Med local-exporteren får hver scannet stage sin egen fil, for eksempel sbom-build.spdx.json ved siden af sbom.spdx.json.

Hvad en scanning stadig overser

Scanning af stages lukker ét hul. Men scanneren læser stadig filer, og noget af det, et build bruger, efterlader ingen fil eller ingen, den kan identificere:

• Filer uden pakkemetadata. En binærfil downloadet med curl, en tarball pakket ud i et RUN-trin eller vendored kode, der er kopieret ind. Nogle binærfiler har build-oplysninger, en scanner kan læse, for eksempel Go-binærfiler; mange har ikke.
• Det, buildet downloadede og slettede. En pakke eller et installationsprogram, som et RUN-trin henter, bruger og fjerner i det samme lag, efterlader intet i filsystemet, som nogen scanner kan læse, uanset om det er den sidste stage eller ej.
• Hvordan tingene kom ind. En SBOM fra en scanning angiver, hvad der er der. Den siger ikke, hvilket registry eller hvilken host en pakke kom fra, eller hvilket trin der hentede den.
• Stages, du ikke har markeret. Scanning af stages er noget, du selv slår til, pr. stage eller globalt. En stage uden argumentet bliver stadig udeladt.
• Scanningsindstillinger. Hvad der dukker op, afhænger af, hvordan scanneren køres. I ét projekt afgør et enkelt Syft-flag, om npm-pakker overhovedet kommer med i resultatet.

Derfor er det vigtigt

Et kompromitteret build-værktøj eller base-image påvirker det, du leverer, selv hvis det aldrig optræder i det endelige image. Og en binærfil uden metadata kan indeholde en sårbarhed, som ingen post i SBOM'en peger på. Når en advisory lander, skal du vide, hvad der blev brugt til at bygge imaget, og ikke kun hvad der er i det.

Registrér også buildet

Image-SBOM'en svarer på, hvad der er inde i imaget. En registrering af buildet svarer på, hvad buildet trak ind: de base-images, det hentede, og de pakker, hvert trin hentede, inklusive de skjulte afhængigheder, som ingen lockfile angiver. CRACI registrerer det, mens dit GitHub Actions-job kører, gennem en pakkebevidst proxy på runneren, og API'et returnerer SBOM'er, netværkstraces og provenance for jobbet. Brug image-SBOM'en til det, du leverer, og build-registreringen til, hvordan det blev lavet.

Se SBOM-værktøjer sammenlignet, SBOM'er fra buildet og sådan genererer du en SBOM i GitHub Actions.

Docker-SBOM'er: ofte stillede spørgsmål

Hvordan genererer jeg en SBOM for et Docker-image?

Der er tre almindelige måder. Tilføj --sbom=true til docker buildx build, så vedhæfter BuildKit en SPDX-SBOM til imaget. Kør docker scout sbom på et eksisterende image. Eller kør Syft, for eksempel syft IMAGE -o cyclonedx-json. Alle tre læser de pakker, de finder i imaget.

Hvad er en SBOM-scanner?

Et værktøj, der læser filer, for eksempel en kildemappe, en lockfile eller et container-image, og skriver en SBOM over de pakker, det kan identificere. Syft, Trivy, Docker Scout og BuildKits Syft-plugin er SBOM-scannere. De beskriver de filer, de har foran sig, ikke det build, der producerede dem.

Hvilket SBOM-format producerer Docker?

BuildKit-attestationer er SPDX JSON-dokumenter, der er vedhæftet imaget. Docker Scout kan udskrive en pakkeliste eller skrive SPDX eller CycloneDX. Syft skriver begge og flere til. Vælg det format, som det værktøj, der bruger SBOM'en, forventer.

Hvordan bygger en scanner en SBOM ud fra et Docker-image?

Den pakker imagets lag ud og læser de pakkemetadata, den finder: styresystemets pakkedatabase og sprogenes pakkefiler, for eksempel metadata for installerede npm- eller Python-pakker. Hver pakke, den kan identificere, bliver en post i SBOM'en.

Hvorfor kan en image-SBOM overse en komponent?

Fordi den kun kan angive det, den kan identificere i de filer, den læser. En binærfil downloadet med curl har ingen pakkemetadata, en pakke, som et build-trin downloadede og slettede, efterlader intet at læse, og tidligere build-stages udelades, medmindre du slår scanning af stages til.

Er en image-SBOM stadig nyttig?

Ja. Den er den rigtige registrering af, hvad der er inde i det image, du leverer, inklusive pakker fra base-imaget. Den beskriver bare ikke, hvordan imaget blev bygget, så kombinér den med en registrering af buildet, når det betyder noget.