アーティファクトの構成証明を使用して構築の実績を確立する

アーティファクト構成証明を使用すると、ソフトウェアが構築された場所と方法を確立し、構築のサプライ チェーンのセキュリティを強化できます。

この機能を使用できるユーザーについて

アーティファクト構成証明は、現在のすべての GitHub プランのパブリック リポジトリで使用できます。 ブロンズ、シルバー、ゴールドなどの従来のプランでは使用できません。

この記事の内容

前提条件

成果物の構成証明の生成を始める前に、それがどのようなもので、どのようなときに使うべきかを理解しておく必要があります。 「アーティファクト構成証明」を参照してください。

構築のアーティファクト構成証明の生成

GitHub Actions を使用すると、バイナリやコンテナー イメージなどのアーティファクトの構築実証を確立するアーティファクト構成証明を生成できます。

アーティファクト構成証明を生成するには、次の操作をする必要があります。

  • ワークフローで適切なアクセス許可が構成されていることを確認します。
  • attest-build-provenanceアクションを使用するステップをワークフローに含めます。

更新されたワークフローを実行すると、アーティファクトが構築され、構築証明を確立するアーティファクトの構成証明が生成されます。 構成証明は、リポジトリ の** [アクション]** タブで表示できます。詳細については、リポジトリattest-build-provenanceを 参照してください。

バイナリの構築実績の生成

  1. 証明するバイナリを構築するワークフローで、次のアクセス許可を追加します。

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

  2. バイナリが構築された手順の後に、次の手順を追加します。

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

    パラメーターのsubject-path 値は、構成証明するバイナリへのパスに設定する必要があります。

コンテナー イメージの構築実績の生成

  1. 構成証明するコンテナー イメージを構築するワークフローで、次のアクセス許可を追加します。

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

  2. イメージが構築された手順の後に、次の手順を追加します。

    - 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

    パラメーターの subject-name 値には、完全修飾イメージ名を指定する必要があります。 たとえば、ghcr.io/user/app または acme.azurecr.io/user/app です。 イメージ名の一部としてタグを含めることはしないでください。

    パラメーターの subject-digest 値は、構成証明の件名の SHA256 ダイジェストに、形式 sha256:HEX_DIGESTで設定する必要があります。 ワークフローで使用 docker/build-push-action する場合は、そのステップの digest 出力を 使用して値を指定できます。 出力の使用の詳細については、「GitHub Actions　のワークフロー構文」を参照してください。

ソフトウェア部品表 (SBOM) の構成証明の生成

ワークフロー アーティファクトの署名付き SBOM 構成証明を生成できます。

SBOM の構成証明を生成するには、次の手順を実行する必要があります。

  • ワークフローで適切なアクセス許可が構成されていることを確認します。
  • アーティファクトの SBOM を作成します。 詳しくは、GitHub CLI で anchore-sbom-action をご覧ください。
  • attest-sbomアクションを使用するステップをワークフローに含めます。

更新されたワークフローを実行すると、アーティファクトが構築され、SBOM 構成証明が生成されます。 構成証明は、リポジトリの [アクション] タブで表示できます。詳細については、attest-sbomアクション リポジトリを参照してください。

バイナリの SBOM 構成証明の生成

  1. 証明するバイナリを構築するワークフローで、次のアクセス許可を追加します。

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

  2. バイナリが構築された手順の後に、次の手順を追加します。

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

    パラメーターのsubject-path値は、SBOM が記述するバイナリのパスに設定する必要があります。 パラメーターのsbom-path値は、生成した SBOM ファイルのパスに設定する必要があります。

コンテナー イメージの SBOM 構成証明の生成

  1. 構成証明するコンテナー イメージを構築するワークフローで、次のアクセス許可を追加します。

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

  2. イメージが構築された手順の後に、次の手順を追加します。

    - 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

    パラメーターの subject-name 値には、完全修飾イメージ名を指定する必要があります。 たとえば、ghcr.io/user/app または acme.azurecr.io/user/app です。 イメージ名の一部としてタグを含めることはしないでください。

    パラメーターの subject-digest 値は、構成証明の件名の SHA256 ダイジェストに、形式 sha256:HEX_DIGESTで設定する必要があります。 ワークフローで使用 docker/build-push-action する場合は、そのステップの digest 出力を 使用して値を指定できます。 出力の使用の詳細については、「GitHub Actions　のワークフロー構文」を参照してください。

    パラメーターの sbom-path 値は、構成証明する JSON 形式の SBOM ファイルへのパスに設定する必要があります。

GitHub CLI を使用したアーティファクト構成証明の検証

GitHub CLI を使用して、バイナリとコンテナー イメージの成果物構成証明を検証し、SBOM 構成証明を検証できます。 詳しくは、GitHub CLI のマニュアルで attestation セクションをご覧ください。

メモ

これらのコマンドは、オンライン環境であることを前提としています。 オフライン環境またはエアギャップ環境の場合は、「オフラインでの構成証明の確認」を参照してください。

バイナリの成果物構成証明を検証する

バイナリのアーティファクト構成証明を確認するには、次の GitHub CLI コマンドを使用します。

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

コンテナー イメージの成果物構成証明を検証する

コンテナー イメージのアーティファクト構成証明を確認するには、バイナリへのパスではなく、oci://プレフィックスが付いたイメージの FQDN を指定する必要があります。 次の GitHub CLI コマンドを使用できます。

Bash
docker login ghcr.io

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

SBOM 構成証明を検証する

SBOM 構成証明を検証するには、既定値ではない述語を参照する --predicate-type フラグを指定する必要があります。 詳細については、in-toto/attestation リポジトリの「検証済みの述語」を参照してください。

たとえば、現在、attest-sbom アクションは SPDX または CycloneDX SBOM 述語のいずれかをサポートしています。 SPDX 形式の SBOM 構成証明を検証するには、次の GitHub CLI コマンドを使用できます。

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 フラグを参照してください。 これは、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'

次のステップ

構成証明の関連性と管理性を維持するため、不要になった構成証明は削除する必要があります。 「成果物構成証明のライフサイクルの管理」をご覧ください。