Komponentbeholdning

Komponentbeholdningen besvarer to spørgsmål uden at du skal åbne en eneste SBOM: hvor bruges denne komponent, og hvilke sårbare komponenter er i brug lige nu. Den bygges ud fra de SBOM’er, fremforge har for din organisation, og er slået til for alle organisationer.

Du finder den i organisationsadministrationen under Sikkerhed › Komponenter med fanerne Beholdning, Sårbare i brug, Hentede versioner, Udrulninger og Miljøregler. Hentede versioner viser de pakkeversioner, dine forbrugere faktisk har downloadet, se Hentede pakkeversioner. Udrulninger er beskrevet nedenfor.

Hvad indekseres

Hver aktuel CycloneDX-SBOM læses ind i beholdningen med én række pr. komponent og sted, den bruges:

En ny SBOM opdaterer kun det, der er ændret: en komponent, der stadig er der, beholder sin række og datoen, hvor den først blev set, og en komponent, der er forsvundet, markeres som fjernet. Fjernede anvendelser gemmes i 180 dage, så du stadig kan svare på “hvornår holdt vi op med at bruge X”. Nye SBOM’er indekseres, når de ankommer; et baggrundsjob indhenter alt, der er gået glip af, hvert 30. minut.

Søgning

Alle lister tager de samme filtre, som alle er valgfrie og kombineres:

REST API

API’et ligger under https://frem.sh/_app/api/v1. Brug et API-token for organisationen eller et PAT med scopet components:read; findings:read accepteres også.

For eksempel alle steder, hvor lodash under 4.17.21 er i brug:

curl -sS -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/<org>/components/usages?purl=pkg:npm/lodash&range=vers:npm/%3C4.17.21"

Sideinddeling

Lister sideinddeles med en cursor. Hvert svar er { "items": [...], "next_cursor": "..." }; send next_cursor tilbage som cursor for at få næste side, indtil den er null. limit er 1 til 500, og standarden er 100. En cursor hører til det endpoint, der udstedte den; et andet endpoint afviser den med invalid-cursor.

CSV-eksport

Tilføj format=csv, eller send Accept: text/csv, til en hvilken som helst liste (/components, /components/usages, /components/{id}/usages, /components/vulnerable), så kommer hele resultatet tilbage som én CSV-fil med de samme filtre og uden sideinddeling. En CSV indeholder højst 200.000 rækker; derover svarer API’et 413 too-many-rows, og så må du indsnævre filtrene, bladre gennem JSON’en eller bruge dataeksporten. Administrationssiderne har den samme eksport som en downloadknap.

Hele beholdningen, inklusive fjernede anvendelser, findes også i hver dataeksport som metadata/components.ndjson, se Eksportskema.

Afhængighedsstier

For en transitiv afhængighed viser beholdningen, hvilken direkte afhængighed der bringer den ind, på samme måde som GitHubs afhængighedsgraf. På Sårbare i brug står der i hver række Kommer ind via efterfulgt af stien, for eksempel async@2.6.3 → lodash; på en komponents side viser kolonnen Afhængighed den samme sti, eller Direkte, når repositoriet selv afhænger af komponenten.

Stien kommer fra afhængighedsgrafen i en SBOM. fremforge gemmer en kompakt kopi af grafen for hver SBOM, den indekserer, så en sti ikke kræver, at SBOM’en downloades. Stier findes kun, hvor en SBOM har afhængighedskanter. Med de SBOM’er, fremforge selv genererer (syft, ud fra filerne i repositoriet), gælder:

Hvor der ikke er nogen sti, viser rækken ingen sti i stedet for et gæt.

Hvordan en direkte afhængighed afgøres, afhænger af lockfilen. En npm-package-lock.json, en uv.lock, en Cargo.lock og en go.mod angiver selve projektet, og dets afhængigheder er de direkte (i go.mod de krav, der ikke er markeret // indirect). pnpm-lock.yaml, yarn.lock, poetry.lock og packages.lock.json angiver ikke projektet i SBOM’en, så en direkte afhængighed antages at være en pakke, som intet andet i lockfilen afhænger af. En direkte afhængighed, som en anden pakke også kræver, vises så gennem den pakke. En SBOM, hvis rodkomponent angiver sine egne afhængigheder, som CycloneDX-build-plugins skriver den, siger selv, hvilke der er direkte. API’et oplyser i graph.direct_basis (project, roots eller declared), hvilken regel der blev brugt.

På API’et svarer GET /orgs/{slug}/repos/{repo}/dependencies/paths for hovedet af repositoriets standardbranch og for de SBOM’er, din CI har pushet for det (nedenfor), med én korteste sti pr. direkte afhængighed, der fører til komponenten, korteste først. Angiv purl (uden version matcher den alle versioner) eller component_id samt limit (1 til 100, standard 20) og cursor for næste side. Hver sti angiver i source (scan eller upload) og sbom_id, hvor den kom fra, og graph.sources viser hver graf, der blev læst. Elementerne i /components/vulnerable og /components/usages har via, den direkte afhængigheds package URL, og dependency_path, den korteste sti fra den til komponenten.

curl -sS -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/<org>/repos/<repo>/dependencies/paths?purl=pkg:npm/lodash"

Stier for Maven, Gradle og Go fra CI

At opløse et afhængighedstræ for Maven eller Gradle betyder at køre byggeværktøjet, og byggeværktøjet kører plugins fra dine buildfiler. fremforge kører ikke dit build på sine servere, så for disse økosystemer kommer grafen fra din egen CI: generér en CycloneDX-SBOM med byggeværktøjets CycloneDX-plugin, som skriver hele den opløste dependencies-graf, og push den med source_repo sat til repositoriet. Sti-API’et, via på Sårbare i brug og komponentsiden bruger så den graf for repositoriet. Push den fra standardbranchen, fordi det er den nyeste upload for hvert artifact_name, der tæller.

Det samme push-trin virker for alle tre. Secreten FREMFORGE_API_TOKEN indeholder et token med scopet sboms:write; fremforge opretter den i hvert nyt repository.

      - name: Push the SBOM to fremforge
        env:
          FREMFORGE_API_TOKEN: ${{ secrets.FREMFORGE_API_TOKEN }}
        run: |
          set -euo pipefail
          DIGEST=$(sha256sum "$SBOM" | cut -d' ' -f1)
          curl -sS --fail-with-body \
            -H "Authorization: Bearer $FREMFORGE_API_TOKEN" \
            -F "sbom=@$SBOM" \
            -F "format=cyclonedx-json" \
            -F "sha256_digest=$DIGEST" \
            -F "artifact_name=${GITHUB_REPOSITORY#*/}-cyclonedx" \
            -F "artifact_version=$GITHUB_SHA" \
            -F "source_repo=$GITHUB_REPOSITORY" \
            -F "repo_full_name=$GITHUB_REPOSITORY" \
            -F "commit_sha=$GITHUB_SHA" \
            -F "git_ref=$GITHUB_REF" \
            "$GITHUB_SERVER_URL/_app/api/v1/orgs/$GITHUB_REPOSITORY_OWNER/sboms"

Maven, med cyclonedx-maven-plugin. Der skal ikke ændres noget i din pom.xml:

name: sbom
on:
  push:
    branches: [main]

jobs:
  sbom:
    runs-on: fremforge
    env:
      SBOM: target/bom.json
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
      - name: CycloneDX SBOM with the full dependency graph
        run: mvn -B -q org.cyclonedx:cyclonedx-maven-plugin:2.9.1:makeBom -DoutputFormat=json -DoutputName=bom -DschemaVersion=1.6
      # then the push step above

Ved et build med flere moduler bruger du i stedet goal’et makeAggregateBom; dets SBOM er target/bom.json i topniveauprojektet.

Gradle, med CycloneDX Gradle-pluginet. Tilføj pluginet til build.gradle:

plugins {
    id 'org.cyclonedx.bom' version '3.5.1'
}

og generér SBOM’en i jobbet med SBOM: build/reports/cyclonedx-direct/bom.json:

      - name: CycloneDX SBOM with the full dependency graph
        run: gradle cyclonedxDirectBom

Go, med cyclonedx-gomod. fremforge finder allerede selv stier for Go (se tabellen ovenfor). Push fra CI, når fremforge ikke kan hente dine moduler, for eksempel private moduler, som dens Go-modulcache ikke kan nå, med SBOM: bom.json:

      - uses: actions/setup-go@v5
        with:
          go-version: '1.27'
      - name: CycloneDX SBOM with the module graph
        run: |
          go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.9.0
          "$(go env GOPATH)/bin/cyclonedx-gomod" mod -json -output "$SBOM" .

Den pushede SBOM indekseres også som et selvstændigt uploadet artefakt, så dens komponenter vises i beholdningen under dens artifact_name såvel som under repositoriet. En afhængighedsscanning af en Gradle-buildfil ser kun de afhængigheder, filen erklærer, og en scanning af en pom.xml ser det, dens pom-filer opløses til, ikke det, et plugin ændrer. Derfor matches hver Maven-komponent i en pushet graf, inklusive de transitive, mod den samme advisory-database, som scanningerne bruger, og hvert match er et afhængighedsfund i det repository, der er angivet i source_repo. Disse fund har manifestet sbom:<artifact_name>. De vises på Sårbare i brug med deres sti, blandt afhængighedsfundene på sikkerhedssiderne og i findings-API’et, og de afvises som ethvert andet fund. De genberegnes, når SBOM’en pushes, efter hver scanning af repositoriets standardbranch og efter hver opdatering af advisory-databasen, så en ny advisory tilføjer et fund, og en tilbagetrukket fjerner det. En advisory, som repositoriets egen scanning allerede rapporterer, vises ikke to gange. Det er fund på standardbranchen: en pushet SBOM ændrer ikke en pull requests fremforge/dep-scan-status. En NuGet-graf, der pushes på denne måde, bruges, som den er skrevet, medmindre den er skrevet af en syft ældre end 1.54.1.

Miljøklasser

Hver anvendelse kan have en miljøklasse: sandbox, development, test, staging eller production. Den kommer fra et af tre steder, og det første, der gælder, vinder:

1. deployment: en udrulning, som din CI/CD har rapporteret med POST /orgs/{slug}/repos/{repo}/deployments, og hvis seneste status er success, nævner anvendelsens image-digest, commit, release-tag eller pakkeversion. Gør flere det, vinder den højeste klasse. Anvendelsesrækken har deployment_id og deployment_environment. Se API-referencen.
2. reported: en SBOM-upload angav sit eget environment.
3. rule: den første matchende regel under Miljøregler, der matcher på typen af anvendelse, et repository, et tag, et image eller et artefaktnavn.

Klassen bruges til søgning og rapportering; den ændrer ikke opbevaring eller nogen gate.

Udrulninger

Fanen Udrulninger viser de udrulninger, din CI/CD har rapporteret, nyeste først: repositoriet, miljøets navn og klasse, tilstanden (en udrulning, hvis seneste status er success, markeres som udrullet nu), commit eller ref, de image-digests og pakkeversioner, den nævner, og hvem der rapporterede den (et CI-job med dets kørsel, en registry-robot, en bruger eller et API-token). Filtrér på repository, miljønavn, miljøklasse og tilstand, eller sæt flueben ved Kun udrullet nu. Næste side og Første side bladrer gennem listen. Den samme liste findes på API’et på GET /orgs/{slug}/deployments/reported (scope components:read), og hver dataeksport indeholder den som metadata/deployments.ndjson med hver udrulnings statushistorik, se Eksportskema.

Relateret

• SBOM’er: hvor SBOM’erne kommer fra.
• Compliance-rapport: dens afsnit om “de mest risikable komponenter” læser beholdningen.
• Hentede pakkeversioner: hvilke sårbare versioner dine forbrugere faktisk downloader, på GET /orgs/{slug}/components/pulled.