Bruke fremforge ved siden av GitHub mens du migrerer

En migrering skjer sjelden på én helg. Mens koden og CI-en din fortsatt ligger på GitHub, kan du allerede ta i bruk fremforges skanning, SBOM-oversikt og funn. Denne siden dekker de to delene som virker i dag:

1. Speil GitHub-repositoryene dine til fremforge, slik at fremforge skanner dem.
2. Last opp SBOM-er fra jobbene dine i GitHub Actions, og les funnene via API-et.

Begge er steg på veien, ikke målet. Pull requests, merge-sperrer og CI kjører der koden ligger, så de kommer når du flytter selve repositoryet med guiden for migrering fra GitHub.

For å publisere til og hente fra fremforges pakkeregistre fra GitHub Actions bruker du en registerrobot: se Bruke fremforges registre fra GitHub Actions og OpenShift.

1. Speil repositoryet til fremforge

Et pull-speil holder en skrivebeskyttet kopi av et GitHub-repository i fremforge-organisasjonen din, synkronisert etter en tidsplan.

1. Gå til frem.sh/repo/migrate (eller + → Ny migrasjon) og velg GitHub.
2. Lim inn HTTPS-URL-en til repositoryet. For et privat repository oppgir du et GitHub-token som kan lese innholdet i repositoryet, og ikke noe mer. Et finmasket token begrenset til det repositoryet med Contents: read er nok.
3. Kryss av for Dette repositoryet blir et speil før du klikker Migrate. Uten det blir importen en engangskopi.
4. Velg målorganisasjonen. Intervallet er 8 timer som standard; du kan senke det til 10 minutter under repositoryets Innstillinger → Speilinnstillinger.

Detaljer, begrensninger og listen over tillatte kildeverter står på Speiling av repositoryer.

Hva fremforge gjør med et speil

Når en synkronisering flytter standardbranchen, behandler fremforge det som en push til standardbranchen: den skanner den nye headen etter sårbare avhengigheter, lisenser og kodeproblemer (SAST), og registrerer en SBOM for repositoryet. Hvert repository skannes høyst én gang i timen, og den nyeste headen vinner.

Den første kopien skannes også: når et speil eller et migrert repository opprettes, skanner fremforge standardbranchen med en gang, uten å vente på en push eller en synkronisering. Et tomt repository skannes ved første push.

Funnene vises i admingrensesnittet under /<org>/_admin/code-security og via Findings-API-et.

Hva et speil ikke gir deg:

• Ingen skanning av pull requests og ingen merge-sperrer. Pull requests blir værende på GitHub og speiles ikke, så fremforge kan ikke legge inn statuser på dem.
• Ingen Actions-kjøringer. Speilet er skrivebeskyttet; workflower kjører der du pusher.
• En forsinkelse. Kopien er bare så fersk som den siste synkroniseringen.

2. Last opp SBOM-er fra GitHub Actions

Hvis bygget ditt lager artefakter som skanningen av repositoryet ikke ser, for eksempel et containerimage eller en samlet binærfil, laster du opp SBOM-en for dem fra jobben som bygger dem.

Opprett et token

I fremforge går du til Organisasjonsadministrasjon → API-tokener og oppretter et token med scopet sboms:write (legg til findings:read hvis den samme jobben leser funn, se nedenfor). Tokenet starter med ffp_. Gi det en utløpstid, og lagre det i GitHub som en Actions-secret, for eksempel FREMFORGE_API_TOKEN. Lagre organisasjonens slug som en variabel, for eksempel FREMFORGE_ORG.

Opplastingssteg

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

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

En vellykket opplasting svarer 201 med SBOM-ens id. SBOM-en vises deretter under Organisasjonsadministrasjon → Sikkerhet › Komponenter › SBOM-er. Se SBOM-er for hva som lagres og hvordan det vises.

3. Les funn fra GitHub Actions

Med et token med findings:read kan en jobb i GitHub Actions lese funnene fremforge har for de speilede repositoryene dine, for eksempel for å la en utgivelsesjobb feile så lenge et uløst kritisk avhengighetsfunn finnes:

- 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

Resultatene pagineres med limit (opptil 200) og offset; svaret oppgir has_more når det finnes en side til. De andre skannerne bruker den samme konvolutten (med egne felt og skalaer for alvorlighetsgrad) under code-security/sast, code-security/images, code-security/licenses og code-security/secrets. Siden om Findings-API-et har den fullstendige referansen, inkludert avvisninger.

Neste steg: flytt repositoryet

Når teamet er vant til funnene i fremforge, flytter du repositoryet og workflowene for alvor med guiden for migrering fra GitHub. Etter flyttingen skannes pusher og pull requests mens de skjer, merge-sperrer gjelder, og CI kjører på fremforges runnere.