fremforge naast GitHub gebruiken terwijl je migreert

Een migratie gebeurt zelden in één weekend. Terwijl je code en CI nog op GitHub staan, kun je de scans, de SBOM-inventaris en de bevindingen van fremforge al aan het werk zetten. Deze pagina behandelt de twee onderdelen die vandaag werken:

1. Spiegel je GitHub-repository’s naar fremforge, zodat fremforge ze scant.
2. Upload SBOM’s vanuit je GitHub Actions-jobs, en lees de bevindingen via de API.

Beide zijn tussenstappen, niet de bestemming. Pull requests, mergepoorten en CI draaien waar de code staat, dus die komen mee wanneer je de repository zelf verhuist met de migratiehandleiding voor GitHub.

Wil je vanuit GitHub Actions publiceren naar en ophalen uit de pakketregisters van fremforge, gebruik dan een registry-robot: zie Registers van fremforge gebruiken vanuit GitHub Actions en OpenShift.

1. De repository naar fremforge spiegelen

Een pull-mirror houdt een alleen-lezen kopie van een GitHub-repository in je fremforge-organisatie, volgens een schema gesynchroniseerd.

1. Ga naar frem.sh/repo/migrate (of + → Nieuwe migratie) en kies GitHub.
2. Plak de HTTPS-URL van de repository. Geef bij een privérepository een GitHub-token dat de inhoud van de repository kan lezen, en verder niets. Een fine-grained token dat tot die repository is beperkt met Contents: read is genoeg.
3. Vink Deze repositorie zal een mirror zijn aan voordat je op Migrate klikt. Zonder dat vinkje is de import een eenmalige kopie.
4. Kies de doelorganisatie. Het interval is standaard 8 uur; je kunt het onder Instellingen → Mirror instellingen van de repository verlagen tot 10 minuten.

Details, limieten en de lijst met toegestane bronhosts staan op Repository’s spiegelen.

Wat fremforge met een spiegel doet

Verplaatst een synchronisatie de standaardbranch, dan behandelt fremforge dat als een push naar de standaardbranch: het scant de nieuwe head op kwetsbare afhankelijkheden, licenties en codeproblemen (SAST), en legt een SBOM van de repository vast. Elke repository wordt hoogstens eens per uur gescand, en de nieuwste head wint.

De eerste kopie wordt ook gescand: wanneer een spiegel of een gemigreerde repository wordt aangemaakt, scant fremforge de standaardbranch direct, zonder op een push of synchronisatie te wachten. Een lege repository wordt bij de eerste push gescand.

Bevindingen verschijnen in de beheer-UI onder /<org>/_admin/code-security, en via de Findings-API.

Wat een spiegel je niet geeft:

• Geen scans van pull requests en geen mergepoorten. Pull requests blijven op GitHub en worden niet gespiegeld, dus fremforge kan er geen statussen op plaatsen.
• Geen Actions-runs. De spiegel is alleen-lezen; workflows draaien waar je pusht.
• Een vertraging. De kopie is zo actueel als de laatste synchronisatie.

2. SBOM’s uploaden vanuit GitHub Actions

Maakt je build artefacten die de scan van de repository niet ziet, zoals een containerimage of een gebundelde binary, upload dan hun SBOM vanuit de job die ze bouwt.

Een token aanmaken

Ga in fremforge naar Organisatiebeheer → API-tokens en maak een token aan met de scope sboms:write (voeg findings:read toe als dezelfde job bevindingen leest, zie hieronder). Het token begint met ffp_. Geef het een vervaldatum en bewaar het in GitHub als Actions-secret, bijvoorbeeld FREMFORGE_API_TOKEN. Bewaar de slug van je organisatie als variabele, bijvoorbeeld FREMFORGE_ORG.

Uploadstap

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

Het verzoek is multipart/form-data naar POST /_app/api/v1/orgs/{org}/sboms:

Een geslaagde upload antwoordt met 201 en de id van de SBOM. De SBOM verschijnt daarna onder Organisatiebeheer → Beveiliging › Componenten › SBOM’s. Zie SBOM’s voor wat er wordt opgeslagen en hoe het wordt getoond.

3. Bevindingen lezen vanuit GitHub Actions

Met een token met findings:read kan een GitHub Actions-job de bevindingen lezen die fremforge voor je gespiegelde repository’s heeft, bijvoorbeeld om een releasejob te laten falen zolang er een onopgeloste kritieke bevinding in een afhankelijkheid is:

- 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 worden gepagineerd met limit (tot 200) en offset; het antwoord zegt has_more als er nog een pagina is. De andere scanners gebruiken dezelfde envelop (met hun eigen velden en ernstschalen) onder code-security/sast, code-security/images, code-security/licenses en code-security/secrets. De pagina Findings-API bevat de volledige naslag, inclusief het afwijzen van bevindingen.

Volgende stap: de repository verhuizen

Is het team eenmaal gewend aan de bevindingen van fremforge, verhuis de repository en zijn workflows dan echt met de migratiehandleiding voor GitHub. Na de verhuizing worden pushes en pull requests direct gescand, gelden de mergepoorten, en draait CI op de runners van fremforge.