fremforge neben GitHub nutzen, während du migrierst

Eine Migration passiert selten an einem Wochenende. Solange dein Code und deine CI noch auf GitHub liegen, kannst du fremforges Scans, das SBOM-Inventar und die Befunde schon nutzen. Diese Seite beschreibt die zwei Teile, die heute funktionieren:

Spiegle deine GitHub-Repositorys nach fremforge, damit fremforge sie scannt.
Lade SBOMs aus deinen GitHub-Actions-Jobs hoch und lies die Befunde über die API.

Beides sind Zwischenschritte, nicht das Ziel. Pull Requests, Merge-Gates und CI laufen dort, wo der Code liegt; sie kommen also mit, wenn du das Repository selbst mit der GitHub-Migrationsanleitung umziehst.

Um aus GitHub Actions in fremforges Paket-Registrys zu veröffentlichen und daraus zu laden, nutze einen Registry-Robot: siehe fremforge-Registrys aus GitHub Actions und OpenShift nutzen.

1. Das Repository nach fremforge spiegeln

Ein Pull-Mirror hält eine schreibgeschützte Kopie eines GitHub-Repositorys in deiner fremforge-Organisation, nach Zeitplan synchronisiert.

Öffne frem.sh/repo/migrate (oder + → Neue Migration) und wähle GitHub.
Füge die HTTPS-URL des Repositorys ein. Für ein privates Repository gibst du ein GitHub-Token an, das den Inhalt des Repositorys lesen kann, und nicht mehr. Ein Fine-grained-Token, beschränkt auf dieses Repository, mit Contents: read genügt.
Setze den Haken bei Dieses Repository wird ein Spiegel sein, bevor du auf Repository migrieren klickst. Ohne ihn ist der Import eine einmalige Kopie.
Wähle die Zielorganisation. Das Intervall ist standardmäßig 8 Stunden; du kannst es in den Einstellungen → Spiegeleinstellungen des Repositorys auf 10 Minuten senken.

Details, Grenzen und die Liste der erlaubten Quell-Hosts stehen unter Repository-Spiegelung.

Was fremforge mit einem Mirror macht

Wenn eine Synchronisierung den Standard-Branch weiterbewegt, behandelt fremforge das wie einen Push auf den Standard-Branch: Es scannt den neuen Stand auf verwundbare Abhängigkeiten, Lizenzen und Code-Probleme (SAST) und erfasst ein SBOM des Repositorys. Jedes Repository wird höchstens einmal pro Stunde gescannt, und der neueste Stand gewinnt.

Auch die erste Kopie wird gescannt: Wird ein Mirror oder ein migriertes Repository angelegt, scannt fremforge seinen Standard-Branch sofort, ohne auf einen Push oder eine Synchronisierung zu warten. Ein leeres Repository wird beim ersten Push gescannt.

Die Befunde erscheinen in der Verwaltung unter /<org>/_admin/code-security und über die Findings-API.

Was ein Mirror dir nicht gibt:

Keine Scans von Pull Requests und keine Merge-Gates. Pull Requests bleiben auf GitHub und werden nicht gespiegelt, daher kann fremforge keine Status an ihnen setzen.
Keine Actions-Läufe. Der Mirror ist schreibgeschützt; Workflows laufen dort, wohin du pushst.
Eine Verzögerung. Die Kopie ist so aktuell wie die letzte Synchronisierung.

2. SBOMs aus GitHub Actions hochladen

Erzeugt dein Build Artefakte, die der Repository-Scan nicht sieht, etwa ein Container-Image oder eine gebündelte Binärdatei, lade ihr SBOM aus dem Job hoch, der sie baut.

Ein Token erstellen

Öffne in fremforge Verwaltung → API-Token und erstelle ein Token mit dem Scope sboms:write (füge findings:read hinzu, wenn derselbe Job Befunde liest, siehe unten). Das Token beginnt mit ffp_. Gib ihm ein Ablaufdatum und speichere es in GitHub als Actions-Secret, zum Beispiel FREMFORGE_API_TOKEN. Den Slug deiner Organisation speicherst du als Variable, zum Beispiel FREMFORGE_ORG.

Upload-Schritt

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

Die Anfrage ist multipart/form-data an POST /_app/api/v1/orgs/{org}/sboms:

Feld	Pflicht	Wert
`sbom`	ja	Die SBOM-Datei, höchstens 5 MiB.
`artifact_name`	ja	Buchstaben, Ziffern, `.`, `_`, `/` und `-`, bis zu 255 Zeichen.
`artifact_version`	ja	Derselbe Zeichensatz, bis zu 255 Zeichen.
`format`	ja	`cyclonedx-json` oder `spdx-json`. Die Datei muss tatsächlich dieses Format haben.
`sha256_digest`	ja	SHA-256 der SBOM-Datei in Hex-Kleinbuchstaben. Bei Abweichung wird mit `400 digest-mismatch` abgewiesen.
`git_ref`	nein	Eine vollständige Ref wie `refs/heads/main`.
`commit_sha`	nein	7 bis 64 Hex-Zeichen in Kleinbuchstaben.
`repo_full_name`	nein	`owner/repo`. Setze es auf den Namen des Mirrors in fremforge, um das SBOM diesem Repository zuzuordnen.
`attestation`	nein	Ein in-toto-Attestierungsbundle (JSONL).

Ein erfolgreicher Upload antwortet mit 201 und der id des SBOM. Das SBOM erscheint dann unter Verwaltung → Sicherheit › Komponenten › SBOMs. Was gespeichert und wie es angezeigt wird, steht unter SBOMs.

3. Befunde aus GitHub Actions lesen

Mit einem Token mit findings:read kann ein GitHub-Actions-Job die Befunde lesen, die fremforge zu deinen gespiegelten Repositorys hat, zum Beispiel um einen Release-Job scheitern zu lassen, solange ein ungelöster kritischer Abhängigkeitsbefund existiert:

- 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

Die Ergebnisse werden mit limit (bis 200) und offset paginiert; die Antwort enthält has_more, wenn es eine weitere Seite gibt. Die anderen Scanner nutzen dieselbe Hülle (mit eigenen Feldern und Schweregradskalen) unter code-security/sast, code-security/images, code-security/licenses und code-security/secrets. Die Seite Findings-API enthält die vollständige Referenz, einschließlich Verwerfungen.

Nächster Schritt: das Repository umziehen

Sobald das Team an fremforges Befunde gewöhnt ist, ziehst du das Repository und seine Workflows mit der GitHub-Migrationsanleitung wirklich um. Nach dem Umzug werden Pushes und Pull Requests gescannt, sobald sie passieren, Merge-Gates greifen, und die CI läuft auf fremforges Runnern.

Von Azure DevOps Secrets in der Historie