Utilisation d’attestations d’artefact pour établir la provenance des builds

Les attestations d’artefacts vous permettent d’accroître la sécurité de la chaîne d’approvisionnement de vos créations en établissant où et comment votre logiciel a été créé.

Qui peut utiliser cette fonctionnalité ?

Les attestations d’artefact sont disponibles dans les référentiels publics pour tous les plans GitHub actuels. Ils ne sont pas disponibles sur des plans hérités, tels que Bronze, Argent ou Or. Si vous avez un plan GitHub Free, GitHub Pro ou GitHub Team, les attestations d’artefact sont disponibles uniquement pour les référentiels publics. Pour utiliser des attestations d’artefact dans des référentiels privés ou internes, vous devez utiliser un plan GitHub Enterprise Cloud.

Dans cet article

Prérequis

Avant de commencer à générer des attestations d'artefacts, vous devez connaître leur nature et savoir quand les utiliser. Consultez Attestations d’artefacts.

Génération d’attestations d’artefact pour vos builds

Vous pouvez utiliser GitHub Actions pour générer des attestations d’artefacts qui établissent la provenance du build pour des artefacts tels que les binaires et les images de conteneurs.

Pour générer une attestation d’artefact, vous devez :

  • Vérifier que vous disposez des autorisations appropriées configurées dans votre flux de travail.
  • Inclure une étape dans votre flux de travail qui utilise l’action attest-build-provenance.

Lorsque vous exécutez vos flux de travail mis à jour, ils génèrent vos artefacts et génèrent une attestation d’artefact qui établit la provenance du build. Vous pouvez afficher les attestations sous l’onglet Actions de votre référentiel. Pour plus d’informations, consultez le référentiel attest-build-provenance.

Génération d’une provenance de build pour les fichiers binaires

  1. Dans le flux de travail qui génère le fichier binaire que vous souhaitez attester, ajoutez les autorisations suivantes.

    permissions:
  id-token: write
  contents: read
  attestations: write

  2. Après l’étape de génération du fichier binaire, ajoutez l’étape suivante.

    - name: Generate artifact attestation
  uses: actions/attest-build-provenance@v2
  with:
    subject-path: 'PATH/TO/ARTIFACT'

    La valeur du paramètre subject-path doit être définie sur le chemin d’accès au fichier binaire que vous souhaitez attester.

Génération d’une provenance de build pour les images conteneur

  1. Dans le flux de travail qui génère l’image conteneur que vous souhaitez attester, ajoutez les autorisations suivantes.

    permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

  2. Après l’étape de génération de l’image, ajoutez l’étape suivante.

    - name: Generate artifact attestation
  uses: actions/attest-build-provenance@v2
  with:
    subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
    subject-digest: 'sha256:fedcba0...'
    push-to-registry: true

    La valeur du paramètre subject-name doit spécifier le nom complet de l’image. Par exemple, ghcr.io/user/app ou acme.azurecr.io/user/app. N’incluez pas de balise dans le nom de l’image.

    La valeur du paramètre subject-digest doit correspondre au résumé SHA256 du sujet de l’attestation, sous la forme sha256:HEX_DIGEST. Si votre flux de travail utilise docker/build-push-action, vous pouvez utiliser la sortie digest de cette étape pour fournir la valeur. Pour plus d’informations sur l’utilisation des sorties, consultez « Workflow syntax for GitHub Actions. »

Génération d’une attestation pour une nomenclature logicielle (SBOM)

Vous pouvez générer des attestations SBOM signées pour les artefacts de flux de travail.

Pour générer une attestation pour un SBOM, vous devez :

  • Vérifier que vous disposez des autorisations appropriées configurées dans votre flux de travail.
  • Créez un SBOM pour votre artefact. Pour plus d’informations, consultez anchore-sbom-action dans la GitHub Marketplace.
  • Inclure une étape dans votre flux de travail qui utilise l’action attest-sbom.

Lorsque vous exécutez vos flux de travail mis à jour, ils génèrent vos artefacts et génèrent une attestation SBOM. Vous pouvez consulter les attestations dans l’onglet Actions de votre référentiel. Pour plus d’informations, consultez le référentiel d’actions attest-sbom.

Génération d’une attestation SBOM pour les fichiers binaires

  1. Dans le flux de travail qui génère le fichier binaire que vous souhaitez attester, ajoutez les autorisations suivantes.

    permissions:
  id-token: write
  contents: read
  attestations: write

  2. Après l’étape de génération du fichier binaire, ajoutez l’étape suivante.

    - name: Generate SBOM attestation
  uses: actions/attest-sbom@v2
  with:
    subject-path: 'PATH/TO/ARTIFACT'
    sbom-path: 'PATH/TO/SBOM'

    La valeur du paramètre subject-path doit être définie sur le chemin d’accès du fichier binaire décrit par SBOM. La valeur du paramètre sbom-path doit être définie sur le chemin d’accès du fichier SBOM que vous avez généré.

Génération d’une attestation SBOM pour les images conteneur

  1. Dans le flux de travail qui génère l’image conteneur que vous souhaitez attester, ajoutez les autorisations suivantes.

    permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

  2. Après l’étape de génération de l’image, ajoutez l’étape suivante.

    - name: Generate SBOM attestation
  uses: actions/attest-sbom@v2
  with:
    subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE
    subject-digest: 'sha256:fedcba0...'
    sbom-path: 'sbom.json'
    push-to-registry: true

    La valeur du paramètre subject-name doit spécifier le nom complet de l’image. Par exemple, ghcr.io/user/app ou acme.azurecr.io/user/app. N’incluez pas de balise dans le nom de l’image.

    La valeur du paramètre subject-digest doit correspondre au résumé SHA256 du sujet de l’attestation, sous la forme sha256:HEX_DIGEST. Si votre flux de travail utilise docker/build-push-action, vous pouvez utiliser la sortie digest de cette étape pour fournir la valeur. Pour plus d’informations sur l’utilisation des sorties, consultez « Workflow syntax for GitHub Actions. »

    La valeur du paramètre sbom-path doit être définie sur le chemin d’accès du fichier SBOM au format JSON que vous souhaitez attester.

Vérifier les attestations d’artefacts avec le GitHub CLI

Vous pouvez valider les attestations d’artefact pour les fichiers binaires et les images conteneur et valider les attestations SBOM à l’aide de GitHub CLI. Pour plus d’informations, consultez la section attestation du manuel GitHub CLI.

Remarque

Ces commandes supposent que vous utilisez un environnement en ligne. Si vous utilisez un environnement hors connexion ou en air gap, consultez « Vérification des attestations hors connexion ».

Vérification d’une attestation d’artefact pour les fichiers binaires

Pour vérifier les attestations d’artefact pour les fichiers binaires, utilisez la commande GitHub CLI suivante.

Bash
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME

Vérification d’une attestation d’artefact pour les images conteneur

Pour vérifier les attestations d’artefacts pour les images conteneurs, vous devez fournir le FQDN de l’image préfixé par oci:// au lieu du chemin d’accès à un fichier binaire. Vous pouvez utiliser la commande GitHub CLI suivante.

Bash
docker login ghcr.io

gh attestation verify oci://ghcr.io/ORGANIZATION_NAME/IMAGE_NAME:test -R ORGANIZATION_NAME/REPOSITORY_NAME

Vérification d’une attestation pour les SBOM

Pour vérifier les attestations SBOM, vous devez fournir l’indicateur --predicate-type pour référencer un prédicat non défini par défaut. Pour plus d’informations, consultez Prédicats approuvés dans le référentiel in-toto/attestation.

Par exemple, l’action attest-sbom prend actuellement en charge les prédicats SPDX ou CycloneDX SBOM. Pour vérifier une attestation SBOM au format SPDX, vous pouvez utiliser la commande GitHub CLI suivante.

Bash
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3

Pour afficher plus d’informations sur l’attestation, référencez l’indicateur --format json. Cela peut être particulièrement utile lors de la révision des attestations SBOM.

Bash
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3 \
  --format json \
  --jq '.[].verificationResult.statement.predicate'

Étapes suivantes

Pour conserver vos attestations pertinentes et gérables, vous devez supprimer les attestations qui ne sont plus nécessaires. Consultez Gestion du cycle de vie des attestations d'artefacts.