Komponentoversikt

Komponentoversikten svarer på to spørsmål uten at du åpner en eneste SBOM: hvor brukes denne komponenten, og hvilke sårbare komponenter er i bruk akkurat nå. Den bygges fra SBOM-ene fremforge har for organisasjonen din, og er slått på for alle organisasjoner.

Du finner den i organisasjonsadministrasjonen under Sikkerhet › Komponenter, med fanene Oversikt, Sårbare i bruk, Hentede versjoner, Utrullinger og Miljøregler. Hentede versjoner lister pakkeversjonene konsumentene dine faktisk har lastet ned, se Nedlastede pakkeversjoner. Utrullinger er beskrevet nedenfor.

Hva som indekseres

Hver gjeldende CycloneDX-SBOM leses inn i oversikten, én rad per komponent og sted den brukes:

En ny SBOM oppdaterer bare det som er endret: en komponent som fortsatt er der, beholder raden sin og datoen den ble sett første gang, og en komponent som er borte, merkes som fjernet. Fjernede bruksforekomster beholdes i 180 dager, slik at du fortsatt kan svare på «når sluttet vi å bruke X». Nye SBOM-er indekseres når de kommer inn; en bakgrunnsjobb tar igjen alt som ble oversett, hvert 30. minutt.

Søk

Alle lister tar de samme filtrene, alle valgfrie og kombinerbare:

REST-API

API-et serveres under https://frem.sh/_app/api/v1. Bruk et API-token for organisasjonen eller et PAT med scopet components:read; findings:read godtas også.

For eksempel hvert sted lodash under 4.17.21 er i bruk:

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"

Paginering

Lister pagineres med markør. Hvert svar er { "items": [...], "next_cursor": "..." }; send next_cursor tilbake som cursor for neste side, til den er null. limit er 1 til 500, standard 100. En markør hører til endepunktet som utstedte den; et annet endepunkt avviser den med invalid-cursor.

CSV-eksport

Legg til 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 tilbake som én CSV-fil med de samme filtrene, uten paginering. En CSV har høyst 200 000 rader; over det svarer API-et 413 too-many-rows, og du snevrer inn filtrene, blar gjennom JSON-en eller bruker dataeksporten. Administrasjonssidene har den samme eksporten som en nedlastingsknapp.

Hele oversikten, inkludert fjernede bruksforekomster, ligger også i hver dataeksport som metadata/components.ndjson, se Eksportskjema.

Avhengighetsstier

For en transitiv avhengighet viser oversikten hvilken direkte avhengighet som bringer den inn, slik GitHubs avhengighetsgraf gjør. På Vulnerable in use sier hver rad Introduced via etterfulgt av stien, for eksempel async@2.6.3 → lodash; på siden for en komponent viser kolonnen Dependency den samme stien, eller Direct når repositoryet selv avhenger av komponenten.

Stien kommer fra avhengighetsgrafen inne i en SBOM. fremforge tar vare på en kompakt kopi av grafen for hver SBOM den indekserer, så en sti krever ingen nedlasting av SBOM-en. Stier finnes bare der en SBOM har avhengighetskanter. Med SBOM-ene fremforge genererer selv (syft, fra filene i repositoryet) gjelder dette:

Der det ikke finnes noen sti, viser raden ingen sti i stedet for en gjetning.

Hvordan en direkte avhengighet avgjøres, avhenger av låsefilen. En npm-package-lock.json, en uv.lock, en Cargo.lock og en go.mod lister selve prosjektet, og avhengighetene dets er de direkte (i go.mod kravene som ikke er merket // indirect). pnpm-lock.yaml, yarn.lock, poetry.lock og packages.lock.json lister ikke prosjektet i SBOM-en, så en direkte avhengighet antas å være en pakke som ingenting annet i låsefilen avhenger av. En direkte avhengighet som en annen pakke også krever, vises da gjennom den pakken. En SBOM der rotkomponenten lister sine egne avhengigheter, slik CycloneDX-byggepluginene skriver den, sier selv hvilke som er direkte. API-et sier hvilken regel som ble brukt i graph.direct_basis (project, roots eller declared).

I API-et svarer GET /orgs/{slug}/repos/{repo}/dependencies/paths for toppen av repositoryets standardbranch, og for SBOM-ene CI-en din har pushet for det (nedenfor), med én korteste sti per direkte avhengighet som fører til komponenten, korteste først. Send purl (uten versjon matcher den alle versjoner) eller component_id, pluss limit (1 til 100, standard 20) og cursor for neste side. Hver sti sier hvor den kom fra i source (scan eller upload) og sbom_id, og graph.sources lister hver graf som ble lest. Elementene i /components/vulnerable og /components/usages har via, pakke-URL-en til den direkte avhengigheten, og dependency_path, den korteste stien 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

Å løse opp et avhengighetstre for Maven eller Gradle betyr å kjøre byggeverktøyet, og byggeverktøyet kjører plugins fra byggefilene dine. fremforge kjører ikke bygget ditt på sine servere, så for disse økosystemene kommer grafen fra din egen CI: generer en CycloneDX-SBOM med byggeverktøyets CycloneDX-plugin, som skriver hele den oppløste dependencies-grafen, og push den med source_repo satt til repositoryet. Sti-API-et, via på Sårbare i bruk og komponentsiden bruker da den grafen for repositoryet. Push den fra standardbranchen, fordi det er den nyeste opplastingen av hvert artifact_name som teller.

Det samme push-steget fungerer for alle tre. Secreten FREMFORGE_API_TOKEN inneholder et token med scopet sboms:write; fremforge oppretter den i hvert nytt 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. Ingenting trenger å endres i 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

For et bygg med flere moduler bruker du målet makeAggregateBom i stedet; SBOM-en er da target/bom.json i toppnivåprosjektet.

Gradle, med CycloneDX Gradle-pluginen. Legg pluginen til i build.gradle:

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

og generer SBOM-en i jobben, med SBOM: build/reports/cyclonedx-direct/bom.json:

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

Go, med cyclonedx-gomod. fremforge finner allerede stier for Go på egen hånd (se tabellen over). Push fra CI når fremforge ikke kan hente modulene dine, for eksempel private moduler som Go-modulbufferen ikke når, 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-en indekseres også som et eget opplastet artefakt, så komponentene vises i oversikten under artifact_name i tillegg til under repositoryet. En avhengighetsskanning av en Gradle-byggefil ser bare avhengighetene filen deklarerer, og en skanning av en pom.xml ser det pom-filene løses opp til, ikke det en plugin endrer. Derfor matches hver Maven-komponent i en pushet graf, også de transitive, mot den samme sårbarhetsdatabasen som skanningene bruker, og hvert treff er et avhengighetsfunn i repositoryet som er angitt i source_repo. Disse funnene har manifestet sbom:<artifact_name>. De vises på Sårbare i bruk med stien sin, blant avhengighetsfunnene på sikkerhetssidene og i findings-API-et, og de avvises som alle andre funn. De beregnes på nytt når SBOM-en pushes, etter hver skanning av repositoryets standardbranch og etter hver oppdatering av sårbarhetsdatabasen, så et nytt sårbarhetsvarsel legger til et funn og et tilbaketrukket fjerner det. Et sårbarhetsvarsel som repositoryets egen skanning allerede rapporterer, listes ikke to ganger. Det er funn på standardbranchen: en pushet SBOM endrer ikke statusen fremforge/dep-scan på en pull request. En NuGet-graf som pushes på denne måten, brukes slik den er skrevet, med mindre syft eldre enn 1.54.1 skrev den.

Miljøklasser

Hver bruksforekomst kan ha en miljøklasse: sandbox, development, test, staging eller production. Den kommer fra ett av tre steder, og det første som gjelder, vinner:

1. deployment: en utrulling CI/CD-en din har rapportert med POST /orgs/{slug}/repos/{repo}/deployments, med siste status success, angir image-digesten, commiten, release-taggen eller pakkeversjonen for bruksforekomsten. Når flere gjør det, vinner den høyeste klassen. Raden for bruksforekomsten har deployment_id og deployment_environment. Se API-referansen.
2. reported: en SBOM-opplasting oppga sitt eget environment.
3. rule: den første regelen som matcher under Environment rules, ut fra type bruk, et repository, en tag, et image eller et artefaktnavn.

Klassen er for søk og rapportering; den endrer ikke oppbevaring eller noen sperre.

Utrullinger

Fanen Utrullinger lister utrullingene CI/CD-en din har rapportert, nyeste først: repositoryet, miljønavnet og klassen, tilstanden (en utrulling med siste status success merkes som utrullet nå), commiten eller ref-en, image-digestene og pakkeversjonene den angir, og hvem som rapporterte den (en CI-jobb med kjøringen sin, en registerrobot, en bruker eller et API-token). Filtrer på repository, miljønavn, miljøklasse og tilstand, eller kryss av for Bare det som er rullet ut nå. Neste side og Første side blar gjennom listen. Den samme listen finnes i API-et på GET /orgs/{slug}/deployments/reported (scope components:read), og hver dataeksport inneholder den som metadata/deployments.ndjson med statushistorikken for hver utrulling, se Eksportskjema.

Relatert

• SBOM-er: hvor SBOM-ene kommer fra.
• Compliance-rapport: delen om «de mest risikable komponentene» leser oversikten.
• Nedlastede pakkeversjoner: hvilke sårbare versjoner konsumentene dine faktisk laster ned, på GET /orgs/{slug}/components/pulled.