Brug fremforge sammen med GitHub, mens du migrerer

En migrering sker sjældent på én weekend. Mens din kode og din CI stadig ligger på GitHub, kan du allerede sætte fremforges scanning, SBOM-oversigt og fund i arbejde. Denne side dækker de to dele, der virker i dag:

1. Spejl dine GitHub-repositories ind i fremforge, så fremforge scanner dem.
2. Upload SBOM’er fra dine GitHub Actions-jobs, og læs fundene via API’et.

Begge er skridt på vejen, ikke målet. Pull requests, merge-gates og CI kører der, hvor koden ligger, så de kommer med, når du flytter selve repositoriet med migreringsguiden til GitHub.

For at publicere til og hente fra fremforges pakkeregistre fra GitHub Actions skal du bruge en registry-robot: se Brug fremforges registre fra GitHub Actions og OpenShift.

1. Spejl repositoriet ind i fremforge

Et pull-mirror holder en skrivebeskyttet kopi af et GitHub-repository i din fremforge-organisation, synkroniseret efter en tidsplan.

1. Gå til frem.sh/repo/migrate (eller + → Ny migration), og vælg GitHub.
2. Indsæt repositoriets HTTPS-URL. For et privat repository skal du angive et GitHub-token, der kan læse repositoriets indhold, og intet andet. Et finkornet token begrænset til det repository med Contents: read er nok.
3. Sæt flueben ved This repository will be a mirror, før du klikker på Migrate. Uden det er importen en engangskopi.
4. Vælg målorganisationen. Intervallet er som standard 8 timer; du kan sænke det til 10 minutter under repositoriets Indstillinger → Spejl indstillinger.

Detaljer, grænser og listen over tilladte kildeværter står på Spejling af repositories.

Hvad fremforge gør med et mirror

Når en synkronisering flytter default branch, behandler fremforge det som et push til default branch: den scanner det nye head for sårbare afhængigheder, licenser og kodeproblemer (SAST) og registrerer en SBOM for repositoriet. Hvert repository scannes højst én gang i timen, og det seneste head vinder.

Den første kopi bliver også scannet: når et mirror eller et migreret repository oprettes, scanner fremforge dets default branch med det samme, uden at vente på et push eller en synkronisering. Et tomt repository scannes ved sit første push.

Fundene vises i administrationsbrugerfladen under /<org>/_admin/code-security og via Findings API’et.

Hvad et mirror ikke giver dig:

• Ingen scanning af pull requests og ingen merge-gates. Pull requests bliver på GitHub og spejles ikke, så fremforge kan ikke sætte statusser på dem.
• Ingen Actions-kørsler. Mirroret er skrivebeskyttet; workflows kører der, hvor du pusher.
• En forsinkelse. Kopien er lige så frisk som den seneste synkronisering.

2. Upload SBOM’er fra GitHub Actions

Hvis dit build producerer artefakter, som scanningen af repositoriet ikke ser, f.eks. et container-image eller en samlet binær fil, så upload deres SBOM fra det job, der bygger dem.

Opret et token

Gå i fremforge til Administration → API-tokens, og opret et token med omfanget sboms:write (tilføj findings:read, hvis samme job læser fund, se nedenfor). Tokenet begynder med ffp_. Giv det et udløb, og gem det i GitHub som en Actions-secret, for eksempel FREMFORGE_API_TOKEN. Gem din organisations slug som en variabel, for eksempel FREMFORGE_ORG.

Upload-trin

- 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"

Anmodningen er multipart/form-data til POST /_app/api/v1/orgs/{org}/sboms:

En vellykket upload svarer 201 med SBOM’ens id. SBOM’en vises derefter under Administration → Sikkerhed › Komponenter › SBOM’er. Se SBOM’er for, hvad der gemmes, og hvordan det vises.

3. Læs fund fra GitHub Actions

Med et token, der har findings:read, kan et GitHub Actions-job læse de fund, fremforge har for dine spejlede repositories, for eksempel for at lade et release-job fejle, så længe der findes et uløst kritisk fund i en afhængighed:

- 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

Resultaterne pagineres med limit (op til 200) og offset; svaret siger has_more, når der er en side mere. De andre scannere bruger samme kuvert (med deres egne felter og alvorlighedsskalaer) under code-security/sast, code-security/images, code-security/licenses og code-security/secrets. Siden om Findings API’et har den fulde reference, også om afvisninger.

Næste skridt: flyt repositoriet

Når teamet har vænnet sig til fremforges fund, så flyt repositoriet og dets workflows for alvor med migreringsguiden til GitHub. Efter flytningen scannes push og pull requests, efterhånden som de sker, merge-gates gælder, og CI kører på fremforges runners.