Komponentinventering

Komponentinventeringen besvarar två frågor utan att du behöver öppna en enda SBOM: var används den här komponenten, och vilka sårbara komponenter är i bruk just nu. Den byggs från de SBOM:er som fremforge har för din organisation och är påslagen för alla organisationer.

Du hittar den i organisationens administration under Säkerhet › Komponenter, med flikarna Inventering, Sårbara i bruk, Hämtade versioner, Driftsättningar och Miljöregler. Hämtade versioner listar de paketversioner som dina konsumenter faktiskt laddade ned, se Hämtade paketversioner. Driftsättningar beskrivs nedan.

Vad som indexeras

Varje aktuell CycloneDX-SBOM läses in i inventeringen, med en rad per komponent och plats där den används:

En ny SBOM uppdaterar bara det som ändrats: en komponent som fortfarande finns kvar behåller sin rad och datumet då den först sågs, och en komponent som har försvunnit markeras som borttagen. Borttagna användningar behålls i 180 dagar, så att du fortfarande kan besvara “när slutade vi använda X”. Nya SBOM:er indexeras när de kommer in; ett bakgrundsjobb tar igen allt som missats var 30:e minut.

Sök

Varje lista tar samma filter, alla valfria och kombinerade:

REST-API

API:t levereras under https://frem.sh/_app/api/v1. Använd en API-token för organisationen eller en PAT med scopet components:read; findings:read accepteras också.

Till exempel varje plats där lodash under 4.17.21 är 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"

Sidindelning

Listor delas upp i sidor med en cursor. Varje svar är { "items": [...], "next_cursor": "..." }; skicka tillbaka next_cursor som cursor för nästa sida, tills den är null. limit är 1 till 500 och är 100 som standard. En cursor hör till den endpoint som utfärdade den; en annan endpoint nekar den med invalid-cursor.

CSV-export

Lägg till format=csv, eller skicka Accept: text/csv, till valfri lista (/components, /components/usages, /components/{id}/usages, /components/vulnerable), så kommer hela resultatet tillbaka som en enda CSV-fil med samma filter, utan sidindelning. En CSV innehåller högst 200 000 rader; över det svarar API:t 413 too-many-rows, och du får snäva in filtren, bläddra igenom JSON-svaret eller använda dataexporten. Administrationssidorna har samma export som en nedladdningsknapp.

Hela inventeringen, inklusive borttagna användningar, finns också i varje dataexport som metadata/components.ndjson, se Exportschema.

Beroendesökvägar

För ett transitivt beroende visar inventeringen vilket direkt beroende som drar in det, på samma sätt som GitHubs beroendegraf. Under Sårbara i bruk anger varje rad Kommer in via följt av sökvägen, till exempel async@2.6.3 → lodash; på en komponents sida visar kolumnen Beroende samma sökväg, eller Direkt när repot själv är beroende av komponenten.

Sökvägen kommer från beroendegrafen i en SBOM. fremforge behåller en kompakt kopia av den grafen för varje SBOM som indexeras, så en sökväg kostar ingen nedladdning av SBOM:en. Sökvägar finns bara där en SBOM har beroendekanter. Med de SBOM:er som fremforge själv genererar (syft, från filerna i repot) är det:

Där det inte finns någon sökväg visar raden ingen sökväg i stället för en gissning.

Hur ett direkt beroende avgörs beror på låsfilen. En npm-package-lock.json, en uv.lock, en Cargo.lock och en go.mod listar själva projektet, och dess beroenden är de direkta (i go.mod de krav som inte är markerade // indirect). pnpm-lock.yaml, yarn.lock, poetry.lock och packages.lock.json listar inte projektet i SBOM:en, så ett direkt beroende antas vara ett paket som inget annat i låsfilen är beroende av. Ett direkt beroende som ett annat paket också kräver visas då via det paketet. En SBOM vars rotkomponent listar sina egna beroenden, som CycloneDX-byggpluginerna skriver den, anger vilka som är direkta. API:t anger vilken regel som tillämpades i graph.direct_basis (project, roots eller declared).

I API:t svarar GET /orgs/{slug}/repos/{repo}/dependencies/paths för huvudet på repots standardbranch, och för de SBOM:er som din CI pushat för det (nedan), med en kortaste sökväg per direkt beroende som leder till komponenten, kortast först. Skicka purl (utan version matchar den alla versioner) eller component_id, plus limit (1 till 100, standard 20) och cursor för nästa sida. Varje sökväg anger var den kom ifrån i source (scan eller upload) och sbom_id, och graph.sources listar varje graf som lästes. Posterna i /components/vulnerable och /components/usages har via, det direkta beroendets paket-URL, och dependency_path, den kortaste sökvägen från det till komponenten.

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

Sökvägar för Maven, Gradle och Go från CI

Att lösa upp ett beroendeträd för Maven eller Gradle innebär att köra byggverktyget, och byggverktyget kör plugins från dina byggfiler. fremforge kör inte ditt bygge på sina servrar, så för de här ekosystemen kommer grafen från din egen CI: generera en CycloneDX-SBOM med byggverktygets CycloneDX-plugin, som skriver hela den upplösta dependencies-grafen, och pusha den med source_repo satt till repot. Sökvägs-API:t, via under Sårbara i bruk och komponentsidan använder då den grafen för repot. Pusha den från standardbranchen, eftersom det är den senaste uppladdningen för varje artifact_name som räknas.

Samma push-steg fungerar för alla tre. Hemligheten FREMFORGE_API_TOKEN innehåller en token med scopet sboms:write; fremforge skapar den i varje nytt repo.

      - 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 behöver ändras 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

För ett bygge med flera moduler använder du i stället målet makeAggregateBom; dess SBOM är target/bom.json i toppnivåprojektet.

Gradle, med CycloneDX Gradle-pluginen. Lägg till pluginen i build.gradle:

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

och generera 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 hittar redan sökvägar för Go på egen hand (se tabellen ovan). Pusha från CI när fremforge inte kan hämta dina moduler, till exempel privata moduler som dess Go-modulcache inte 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 pushade SBOM:en indexeras också som en egen uppladdad artefakt, så dess komponenter visas i inventeringen under sitt artifact_name såväl som under repot. En beroendeskanning av en Gradle-byggfil ser bara de beroenden som filen deklarerar, och en av en pom.xml ser det som dess pom-filer löses upp till, inte det som en plugin ändrar. Därför matchas varje Maven-komponent i en pushad graf, även de transitiva, mot samma databas med säkerhetsmeddelanden som skanningarna använder, och varje träff blir ett beroendefynd för det repo som anges i source_repo. De här fynden har manifestet sbom:<artifact_name>. De visas under Sårbara i bruk med sin sökväg, bland beroendefynden på säkerhetssidorna och i Findings API, och de avfärdas som alla andra fynd. De beräknas om när SBOM:en pushas, efter varje skanning av repots standardbranch och efter varje uppdatering av databasen med säkerhetsmeddelanden, så ett nytt säkerhetsmeddelande lägger till ett fynd och ett återkallat tar bort det. Ett säkerhetsmeddelande som repots egen skanning redan rapporterar listas inte två gånger. Det är fynd på standardbranchen: en pushad SBOM ändrar inte statusen fremforge/dep-scan på en pull request. En NuGet-graf som pushas på det här sättet används som den är skriven, såvida inte syft äldre än 1.54.1 skrev den.

Miljöklasser

Varje användning kan ha en miljöklass: sandbox, development, test, staging eller production. Den kommer från ett av tre ställen, och det första som gäller vinner:

1. deployment: en driftsättning som din CI/CD rapporterade med POST /orgs/{slug}/repos/{repo}/deployments, vars senaste status är success, anger användningens image-digest, commit, release-tagg eller paketversion. När flera gör det vinner den högsta klassen. Användningsraden har deployment_id och deployment_environment. Se API-referensen.
2. reported: en SBOM-uppladdning angav sin egen environment.
3. rule: den första matchande regeln under Miljöregler, som matchar på typ av användning, ett repo, en tagg, en image eller ett artefaktnamn.

Klassen är till för sökning och rapportering; den ändrar inte lagringstid eller någon spärr.

Driftsättningar

Fliken Driftsättningar listar de driftsättningar som din CI/CD har rapporterat, nyaste först: repot, miljöns namn och dess klass, tillståndet (en driftsättning vars senaste status är success markeras som driftsatt nu), commiten eller ref, de image-digests och paketversioner den anger, och vem som rapporterade den (ett CI-jobb med sin körning, en registry-robot, en användare eller en API-token). Filtrera på repo, miljönamn, miljöklass och tillstånd, eller markera Endast driftsatt nu. Nästa sida och Första sidan flyttar dig genom listan. Samma lista finns i API:t på GET /orgs/{slug}/deployments/reported (scope components:read), och varje dataexport innehåller den som metadata/deployments.ndjson med varje driftsättnings statushistorik, se Exportschema.

Relaterat

• SBOM:er: var SBOM:erna kommer ifrån.
• Compliancerapport: dess avsnitt om “de mest riskfyllda komponenterna” läser inventeringen.
• Hämtade paketversioner: vilka sårbara versioner dina konsumenter faktiskt laddar ned, på GET /orgs/{slug}/components/pulled.