Gå til hovedindhold

SBOM'er (Software Bill of Materials)

En SBOM (Software Bill of Materials) er ingredienslisten for et build: hver direkte og transitiv afhængighed, der er bygget ind i et artefakt, med versioner og hashes. fremforge gemmer de SBOM’er, din CI producerer, så oversigten overlever på tværs af builds, udskiftning af images og afhængigheder, der glider.

Når SBOM’er genereres automatisk

Der er intet at installere. fremforge genererer centralt en CycloneDX 1.6-SBOM for hver pull request på sine egne runners og binder den SBOM til en release, når du udgiver en: ethvert tag, også de almindelige semver- og calver-former (v1.2.3, v2026.06).

Vi scanner bevidst ikke igen ved release. En SBOM er en funktion af kildetræet, og det træ, du udgiver, er allerede scannet som head af den pull request, der mergede det, så en ny generering ville give en byte-identisk fil. Når du udgiver en release, markeres i stedet den SBOM, der allerede findes for præcis det commit, som release-SBOM’en. To konsekvenser, der er værd at kende:

  • Det sker med det samme. Der kører intet build, så release-SBOM’en er tilgængelig, så snart releasen er udgivet.
  • Bindingen sker på serveren. fremforge slår dit tag op til dets commit gennem Forgejo og matcher på det commit, så intet i et build kan gøre krav på en release-SBOM, det ikke har gjort sig fortjent til.

Udgiver du en release for et commit, der aldrig har været gennem en pull request (et tag på et meget gammelt commit eller et repository, hvis historik er ældre end scanningen), er der ingen SBOM at binde. Den release rapporteres som udækket i stedet for at blive sprunget stille over; kør en scanning igen på committet for at dække den.

Udløs en SBOM ved at tagge en release

Fra kommandolinjen:

git tag v1.2.3
git push origin v1.2.3

Fra Forgejos brugerflade: åbn repositoriet → Udgivelser → Ny udgivelse, angiv et tagnavn, der begynder med v (f.eks. v1.2.3), og klik på Publish.

En enkeltstående SBOM for et vilkårligt commit kan også laves via fanen Actions → SBOM (Syft) → Run workflow.

Hvorfor bindes kun en release? Der laves en SBOM for hver pull request, men kun den for et commit, der udgives, bliver en release-SBOM: revisorer vil have SBOM’en “på det tidspunkt, vi leverede release X”. At binde ved en release holder antallet af release-SBOM’er i forhold til din faktiske release-takt.

Hvad fremforge accepterer

fremforge genererer både CycloneDX 1.6 og SPDX 2.3-SBOM’er og accepterer begge ved modtagelse:

  • CycloneDX JSON (1.6): den oversigt, som alle fremforges funktioner læser (binding til release, tjekket for tom oversigt, overblikket). Det bredere værktøjsøkosystem (Trivy, Syft, anchore) udsender CycloneDX direkte.
  • SPDX JSON (2.3): genereret ved siden af af samme Syft-kørsel ved hver PR-scanning og gemt under samme build, så siden med SBOM’er tilbyder begge downloads for én release. Dine egne uploads kan være CycloneDX 1.5–1.7 eller SPDX 2.x/3.x; modtagelsen validerer specVersion / spdxVersion, før den gemmer.

SPDX-dokumentet er et eksportformat, der genereres efter bedste evne: for et meget stort repository, hvis to dokumenter tilsammen ville overskride leveringsgrænsen på 14 MiB, gemmes kun CycloneDX-SBOM’en, så oversigten aldrig går tabt for at gøre plads til det andet format.

Hver SBOM gemmes med:

  • SHA-256-digesten af SBOM-filen. Den, der uploader, sender den, og serveren beregner den igen, så en afkortet eller ændret upload afvises.
  • Et valgfrit in-toto-attesteringsbundt (JSONL), signeret med Cosign, når dit workflow signerer SBOM’en. Modtagelsen validerer JSONL-formen og in-toto-felterne på hver linje, før den gemmer.
  • Artefaktets navn og version, præcis som dit workflow navngiver det. Bruges til nøglen for deduplikering (samme digest + navn + version = én række, ikke mange).

Fast grænse på 5 MiB pr. SBOM. Modtagelsens endpoint returnerer 413 payload-too-large over den grænse; del store SBOM’er fra monorepos op efter modul, hvis du rammer den.

Sådan sender du en SBOM fra CI

fremforges runner-image indeholder Syft og Trivy, så de fleste workflows klarer sig med et lille uddrag:

- name: Generate + push SBOM
  run: |
    syft packages dir:. --output cyclonedx-json=sbom.json
    # The digest is the SHA-256 of the SBOM file itself; the server recomputes it
    # and refuses a mismatch with 400 digest-mismatch.
    DIGEST=$(sha256sum sbom.json | cut -d' ' -f1)
    curl -sS --fail \
      -H "Authorization: Bearer ${{ secrets.FREMFORGE_API_TOKEN }}" \
      -F "sbom=@sbom.json" \
      -F "artifact_name=myapp" \
      -F "artifact_version=${GITHUB_SHA}" \
      -F "sha256_digest=${DIGEST}" \
      -F "format=cyclonedx-json" \
      "https://frem.sh/_app/api/v1/orgs/${ORG}/sboms"

Tokenet skal have scopet sboms:write; opret et under Administration → API-tokens med scopet til at sende SBOM’er markeret.

To valgfrie felter registrerer, hvor artefaktet kører, og hvilket repository det er bygget fra:

  • environment: den miljøklasse, artefaktet kører i, en af sandbox, development, test eller production. Alt andet afvises med invalid-environment.
  • source_repo: det repository, artefaktet er bygget fra, som owner/repo. Alt andet afvises med invalid-source-repo.
      -F "environment=production" \
      -F "source_repo=acme/payments-api" \

Ingen af felterne ændrer opbevaringen eller noget gate. En CycloneDX-SBOM med source_repo låner også sin afhængighedsgraf ud til det repositorys afhængighedsstier, og det er sådan, Maven- og Gradle-repositorier får dem.

Hvor SBOM’er vises i administrationen

Administration → Sikkerhed › Komponenter › SBOM’er lister hver modtaget SBOM grupperet efter artefakt. Hver række viser:

  • Artefaktets navn + version + SHA-256-digest
  • Format (CycloneDX / SPDX) + størrelse
  • Tidspunkt for modtagelse + den bruger eller det token, der sendte den
  • Linket “Verify signature”, når en attestering er vedhæftet

Sådan spiller SBOM’er sammen med andre sikkerhedssignaler

  • Scorecard: driver scorerne for Dependencies og Vulnerabilities i beregningen af OpenSSF Scorecard.
  • OSV-anbefalinger: når en OSV-advisory matcher en komponent, der står i en SBOM, vises anbefalingen med den påvirkning, der er forankret i SBOM’en (“this affects build myapp@v1.2.3 from 2026-05-12”).
  • Cosign: signeringen af SBOM’er bruger samme Cosign-tillidsrod som signeringen af images. Se Cosign for verificeringen.

Opbevaring

Release-SBOM’er gemmes, så længe din organisation findes. SBOM’er fra builds, der ikke blev udgivet, slettes efter din opbevaring af dokumentation for sbom: 14 dage som standard, 0 til 3650 dage. SBOM’en for standardbranchens head, SBOM’erne for aktuelle images og SBOM’erne for pakkefiler gemmes uanset alder. Intet slettes, mens der er et legal hold. (Indtil 2026-10-08 sagde dette afsnit, at SBOM’er fulgte forvalgene for opbevaring af revisionsloggen; det gjorde de aldrig.)

Se også

  • Cosign: signering af images og SBOM’er.
  • OSV-anbefalinger: sårbarheder matchet med SBOM-komponenter.
  • Scorecard: SBOM’er driver scorerne for afhængigheder og sårbarheder.
  • API-reference: endpointet POST /_app/api/v1/orgs/{slug}/sboms til modtagelse.
Eksempel-repositoryAI-rettelse