SBOM in GitHub Actions: scan na installatie

Wil je automatisch een SBOM maken in GitHub Actions, bepaal dan eerst wat je wilt inventariseren. De export van de dependency graph beschrijft repositoryafhankelijkheden in SPDX-formaat, met onder meer versies, pakketidentificaties, licenties en afhankelijkheidsrelaties. Wil je ook bestanden meenemen die tijdens de workflow worden geïnstalleerd, voer de scan dan na de installatiestap uit.

De Anchore SBOM Action gebruikt Syft om een werkmap of containerimage te scannen en ondersteunt zowel SPDX JSON als CycloneDX JSON. Bewaar de uitvoer als workflowartefact met een naam die het scanobject herkenbaar maakt. Zo kun je de inventaris van een repository, installatiewerkmap of image aan de juiste workflowrun koppelen.

Bepaal eerst welk moment telt

Een generator ziet het gekozen scanobject zoals het bestaat wanneer de scan begint. In een voorwaardelijk Node-voorbeeld komt daarom eerst de checkout, daarna de instelling van de Node-versie en npm ci, en pas vervolgens de scan van de werkmap. Gebruik bij een ander ecosysteem de installatieopdracht die bij de daadwerkelijke build hoort. Een scan vóór installatie kan wel pakketten uit aanwezige manifesten of lockfiles afleiden, maar kan nog geen bestanden inspecteren die pas door de installatie verschijnen.

Ook een scan na npm ci is geen geschiedenis van de hele job. Een script kan een pakket ophalen en vóór de scan verwijderen; dat pakket is dan mogelijk niet meer aantoonbaar in de werkmap. Plaats de scan na de laatste relevante installatie- of bouwstap en kies expliciet of je de werkmap op dat moment of het uiteindelijke uitleverbare image wilt beschrijven.

Route 1: exporteer de dependency graph

Deze route past bij een inventaris van de afhankelijkheden die in de dependency graph van de repository zijn geregistreerd. De graph omvat informatie uit ondersteunde manifesten en lockfiles en kan ook ingediende dependencygegevens bevatten. De export is daardoor geen momentopname van alle bestanden in één specifieke buildjob. Een pakket dat uitsluitend tijdens die job wordt opgehaald en niet in de graph belandt, verschijnt er niet vanzelf in.

De REST-specificatie voor SBOM-export beschrijft een aanvraag die een sbom_url teruggeeft; bij het ophalen betekent HTTP 202 dat het rapport nog wordt gemaakt en leidt HTTP 302 naar de download. Gebruik voor een nieuwe workflow deze asynchrone route. De oudere rechtstreekse export is volgens die specificatie na 13 november 2026 niet meer toegankelijk.

Maak een aparte job met permissions: contents: read. Geef de shellstap GH_TOKEN: ${{ github.token }} mee. Voor deze API-export zijn checkout en installatie niet nodig.
Vraag repos/$GITHUB_REPOSITORY/dependency-graph/sbom/generate-report op met gh api en lees sbom_url uit het JSON-antwoord.
Vraag de ontvangen URL opnieuw op zolang de reactie HTTP 202 is. Volg de redirect zodra het rapport gereed is, sla de SPDX JSON op als sbom-graph.spdx.json en laat de job falen als downloaden mislukt.
Bewaar dat bestand met actions/upload-artifact@v4, bijvoorbeeld onder de naam sbom-graph, en stel if-no-files-found: error in.

Route 2: scan de werkmap na installatie

Laat de SBOM-stap in dezelfde job draaien als de installatie. Voor het voorwaardelijke Node-voorbeeld staan actions/checkout, het instellen van de vereiste Node-versie en npm ci vóór uses: anchore/sbom-action@v0. Stel voor die action path: ., format: spdx-json en output-file: sbom-workspace.spdx.json in. Bij een monorepo kun je path beperken tot de map van de toepassing die je wilt inventariseren.

Wil je het bestand zelf controleren en daarna onder een vaste naam bewaren, stel dan bij de action upload-artifact: false en upload-release-assets: false in. Voeg een afzonderlijke stap met actions/upload-artifact@v4 toe, met name: sbom-workspace, path: sbom-workspace.spdx.json en if-no-files-found: error. Zet ook dependency-snapshot: false wanneer je geen gegevens naar de dependency submission API wilt sturen; dat is de standaardinstelling van de action.

Deze route kan zowel informatie uit lockfiles als herkenbare geïnstalleerde pakketbestanden in de gescande werkmap opleveren. De precieze inhoud hangt af van wat Syft in dat ecosysteem kan herkennen en welke bestanden op het scanmoment aanwezig zijn. Controleer daarom bij een Node-project of verwachte pakketten uit de installatie terugkomen, in plaats van uit een geslaagd workflowartefact af te leiden dat de inventaris volledig is.

Route 3: scan het gebouwde containerimage

Moet de SBOM het uitleverbare image beschrijven, bouw dan eerst dat image en geef de Anchore-stap image op in plaats van path. Als voorwaardelijk voorbeeld kun je een lokaal gebouwd image de tag app:sbom geven en vervolgens image: app:sbom, format: spdx-json en output-file: sbom-image.spdx.json instellen. Schakel ook hier de ingebouwde artefact- en releasepublicatie uit als je de uitvoer met een afzonderlijke uploadstap bewaart.

Geef die uploadstap de naam sbom-image en het pad sbom-image.spdx.json. Een eigen artefactnaam voorkomt verwarring met de werkmap-SBOM wanneer beide scans in dezelfde workflow draaien. Gebruik bij voorkeur dezelfde image-identiteit voor de scan als voor de latere publicatie; een nieuwe build met dezelfde tag kan immers andere inhoud hebben.

De imagescan richt zich op pakketten die Syft in het gescande image kan herkennen. Een pakket dat alleen in een tijdelijke bouwomgeving aanwezig was en niet in het uiteindelijke image terechtkwam, hoort niet bij deze inventaris. Voor de vraag wat de installatiewerkmap bevatte, blijft daarom de werkmapscan de passende route.

Controleer de uitvoer, het formaat en de rechten

Controleer het uitvoerbestand vóór het uploaden op bestaan en geldige JSON. Bij SPDX JSON kun je met jq controleren of spdxVersion is ingevuld en packages een array is. Bij CycloneDX JSON controleer je bomFormat en de verwachte componenten. Zoek daarna enkele bekende afhankelijkheden op die bij het gekozen scanobject horen. Deze controle zegt meer over de bruikbaarheid van het resultaat dan alleen een geslaagde upload.

Kies SPDX JSON voor de dependency-graph-export of wanneer een ontvangend systeem SPDX vraagt. Verwacht dat systeem CycloneDX JSON, gebruik dan bij een Syft-scan format: cyclonedx-json en een bijpassende bestandsnaam. Het gekozen formaat verandert de dekking niet: een werkmap vóór installatie, dezelfde werkmap erna en een gebouwd image blijven verschillende scanobjecten.

Houd de rechten bij de gekozen route. Met permissions: contents: read kan de exportjob de repository lezen; voor de beschreven Syft-jobs staan de ingebouwde artefactupload, releasepublicatie en dependency submission uit. Beoordeel schrijfrechten afzonderlijk als je later een SBOM aan een release wilt toevoegen of dependencygegevens wilt indienen.