Använda fremforge vid sidan av GitHub medan du migrerar

En migrering sker sällan på en helg. Medan din kod och din CI fortfarande finns på GitHub kan du redan sätta fremforges skanning, SBOM-inventering och fynd i arbete. Den här sidan beskriver de två delar som fungerar i dag:

1. Spegla dina GitHub-repon till fremforge så att fremforge skannar dem.
2. Ladda upp SBOM:er från dina GitHub Actions-jobb och läs fynden via API:t.

Båda är steg på vägen, inte målet. Pull requests, merge-grindar och CI körs där koden finns, så de kommer på plats när du flyttar själva repot med migreringsguiden för GitHub.

För att publicera till och hämta från fremforges paketregister från GitHub Actions använder du en registry-robot: se Använda registry-robotar från GitHub Actions och OpenShift.

1. Spegla repot till fremforge

En pull-spegel håller en skrivskyddad kopia av ett GitHub-repo i din fremforge-organisation, synkad enligt ett schema.

1. Gå till frem.sh/repo/migrate (eller + → Ny migrering) och välj GitHub.
2. Klistra in repots HTTPS-URL. För ett privat repo anger du en GitHub-token som kan läsa repots innehåll, och inget mer. En finkornig token som är begränsad till det repot med Contents: read räcker.
3. Kryssa i This repository will be a mirror innan du klickar på Migrate. Utan den blir importen en engångskopia.
4. Välj målorganisationen. Intervallet är 8 timmar som standard; du kan sänka det till 10 minuter under repots Inställningar → Inställningar för spegling.

Detaljer, gränser och listan över tillåtna källvärdar finns under Spegling av repon.

Vad fremforge gör med en spegel

När en synkning flyttar standardbranchen behandlar fremforge det som en push till standardbranchen: den nya toppen skannas efter sårbara beroenden, licenser och kodproblem (SAST), och en SBOM för repot registreras. Varje repo skannas högst en gång i timmen, och den senaste toppen gäller.

Även den första kopian skannas: när en spegel eller ett migrerat repo skapas skannar fremforge dess standardbranch direkt, utan att vänta på en push eller en synkning. Ett tomt repo skannas vid sin första push.

Fynden visas i administrationsgränssnittet under /<org>/_admin/code-security och via Findings-API:t.

Det här ger en spegel dig inte:

• Inga skanningar av pull requests och inga merge-grindar. Pull requests stannar på GitHub och speglas inte, så fremforge kan inte sätta statusar på dem.
• Inga Actions-körningar. Spegeln är skrivskyddad; arbetsflöden körs där du pushar.
• En fördröjning. Kopian är aldrig färskare än den senaste synkningen.

2. Ladda upp SBOM:er från GitHub Actions

Om ditt bygge producerar artefakter som skanningen av repot inte ser, till exempel en containeravbildning eller en paketerad binärfil, laddar du upp deras SBOM från jobbet som bygger dem.

Skapa en token

Gå i fremforge till Organisationens administration → API-token och skapa en token med scopet sboms:write (lägg till findings:read om samma jobb läser fynd, se nedan). Token börjar med ffp_. Ge den ett utgångsdatum och lagra den i GitHub som en Actions-hemlighet, till exempel FREMFORGE_API_TOKEN. Lagra organisationens slug som en variabel, till exempel FREMFORGE_ORG.

Uppladdningssteg

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

Begäran är multipart/form-data till POST /_app/api/v1/orgs/{org}/sboms:

En lyckad uppladdning svarar 201 med SBOM:ens id. SBOM:en visas sedan under Organisationens administration → Säkerhet › Komponenter › SBOM:er. Se SBOM:er för vad som lagras och hur det visas.

3. Läsa fynd från GitHub Actions

Med en token som har findings:read kan ett GitHub Actions-jobb läsa de fynd som fremforge har för dina speglade repon, till exempel för att låta ett release-jobb misslyckas så länge det finns ett olöst kritiskt fynd i ett beroende:

- name: Check fremforge findings
  env:
    FREMFORGE_API_TOKEN: ${{ secrets.FREMFORGE_API_TOKEN }}
    ORG: ${{ vars.FREMFORGE_ORG }}
    REPO: ${{ vars.FREMFORGE_ORG }}/backend   # the mirror's name in fremforge
  run: |
    curl -sS --fail-with-body \
      -H "Authorization: Bearer ${FREMFORGE_API_TOKEN}" \
      "https://frem.sh/_app/api/v1/orgs/${ORG}/code-security/deps/findings?limit=200" \
      > deps.json
    CRITICAL=$(jq --arg r "$REPO" '[.findings[] | select(.repo_full_name == $r and .severity == "critical" and .state == "open")] | length' deps.json)
    echo "open critical dependency findings: ${CRITICAL}"
    test "${CRITICAL}" -eq 0

Resultaten delas upp i sidor med limit (upp till 200) och offset; svaret anger has_more när det finns en sida till. De andra skannrarna använder samma kuvert (med egna fält och allvarlighetsskalor) under code-security/sast, code-security/images, code-security/licenses och code-security/secrets. Sidan Findings-API har den fullständiga referensen, inklusive avfärdanden.

Nästa steg: flytta repot

När teamet har vant sig vid fremforges fynd flyttar du repot och dess arbetsflöden på riktigt med migreringsguiden för GitHub. Efter flytten skannas pushar och pull requests när de sker, merge-grindar tillämpas och CI körs på fremforges runners.