Utiliser fremforge en parallèle de GitHub pendant la migration

Une migration se fait rarement en un week-end. Tant que votre code et votre CI sont encore sur GitHub, vous pouvez déjà mettre à profit l’analyse, l’inventaire des SBOM et les résultats de fremforge. Cette page couvre les deux volets qui fonctionnent aujourd’hui :

1. Créer un miroir de vos dépôts GitHub dans fremforge, afin que fremforge les analyse.
2. Téléverser des SBOM depuis vos jobs GitHub Actions, et lire les résultats via l’API.

Ce sont des étapes intermédiaires, pas la destination. Les pull requests, les contrôles de fusion et la CI s’exécutent là où se trouve le code : ils arrivent quand vous déplacez le dépôt lui-même avec le guide de migration depuis GitHub.

Pour publier dans les registres de paquets de fremforge et en récupérer depuis GitHub Actions, utilisez un robot de registre : voir Utiliser les registres fremforge depuis GitHub Actions et OpenShift.

1. Créer un miroir du dépôt dans fremforge

Un miroir pull conserve, dans votre organisation fremforge, une copie en lecture seule d’un dépôt GitHub, synchronisée selon un planning.

1. Allez sur frem.sh/repo/migrate (ou + → Nouvelle migration) et choisissez GitHub.
2. Collez l’URL HTTPS du dépôt. Pour un dépôt privé, fournissez un jeton GitHub capable de lire le contenu du dépôt, et rien de plus. Un jeton à granularité fine limité à ce dépôt avec Contents: read suffit.
3. Cochez Rendre ce dépôt mirroir avant de cliquer sur Migrer le dépôt. Sans cela, l’import est une copie unique.
4. Choisissez l’organisation cible. L’intervalle est de 8 heures par défaut ; vous pouvez le réduire à 10 minutes dans Paramètres → Réglages miroir du dépôt.

Les détails, les limites et la liste des hôtes sources autorisés se trouvent sur Miroirs de dépôts.

Ce que fremforge fait d’un miroir

Lorsqu’une synchronisation fait avancer la branche par défaut, fremforge la traite comme un push sur la branche par défaut : il analyse la nouvelle tête à la recherche de dépendances vulnérables, de problèmes de licence et de problèmes de code (SAST), et enregistre un SBOM du dépôt. Chaque dépôt est analysé au plus une fois par heure, et c’est la tête la plus récente qui l’emporte.

La première copie est analysée elle aussi : lorsqu’un miroir ou un dépôt migré est créé, fremforge analyse aussitôt sa branche par défaut, sans attendre un push ou une synchronisation. Un dépôt vide est analysé lors de son premier push.

Les résultats apparaissent dans l’interface d’administration sous /<org>/_admin/code-security, et via l’API des résultats.

Ce qu’un miroir ne vous apporte pas :

• Ni analyse des pull requests, ni contrôles de fusion. Les pull requests restent sur GitHub et ne sont pas reproduites dans le miroir : fremforge ne peut donc pas y publier de statuts.
• Aucune exécution Actions. Le miroir est en lecture seule ; les workflows s’exécutent là où vous poussez.
• Un décalage. La copie n’est jamais plus récente que la dernière synchronisation.

2. Téléverser des SBOM depuis GitHub Actions

Si votre build produit des artefacts que l’analyse du dépôt ne voit pas, comme une image de conteneur ou un binaire packagé, téléversez leur SBOM depuis le job qui les construit.

Créer un jeton

Dans fremforge, allez dans Admin → Jetons d’API et créez un jeton avec le scope sboms:write (ajoutez findings:read si le même job lit les résultats, voir plus bas). Le jeton commence par ffp_. Donnez-lui une date d’expiration et stockez-le dans GitHub comme secret Actions, par exemple FREMFORGE_API_TOKEN. Stockez le slug de votre organisation comme variable, par exemple FREMFORGE_ORG.

Étape de téléversement

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

La requête est un multipart/form-data vers POST /_app/api/v1/orgs/{org}/sboms :

Un téléversement réussi répond 201 avec l’id du SBOM. Le SBOM apparaît ensuite sous Admin → Sécurité › Composants › SBOM. Voir SBOM pour ce qui est stocké et la façon dont c’est affiché.

3. Lire les résultats depuis GitHub Actions

Avec un jeton disposant de findings:read, un job GitHub Actions peut lire les résultats que fremforge détient pour vos dépôts en miroir, par exemple pour faire échouer un job de release tant qu’un résultat critique non résolu sur une dépendance existe :

- 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

Les résultats sont paginés avec limit (jusqu’à 200) et offset ; la réponse indique has_more lorsqu’il existe une autre page. Les autres scanners utilisent la même enveloppe (avec leurs propres champs et échelles de sévérité) sous code-security/sast, code-security/images, code-security/licenses et code-security/secrets. La page API des résultats contient la référence complète, y compris les rejets.

Étape suivante : déplacer le dépôt

Une fois l’équipe habituée aux résultats de fremforge, déplacez réellement le dépôt et ses workflows avec le guide de migration depuis GitHub. Après le déplacement, les push et les pull requests sont analysés au fil de l’eau, les contrôles de fusion s’appliquent et la CI s’exécute sur les runners de fremforge.