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

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

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

成果物構成証明は、現在のすべての GitHub プランのリポジトリで使用できます。 ブロンズ、シルバー、ゴールドなどの従来のプランでは使用できません。 GitHub Free、GitHub Pro、または GitHub Team プランを利用している場合、成果物の構成証明はパブリック リポジトリでのみ使用できます。 プライベートまたは内部リポジトリでアーティファクト構成証明を使用するには、GitHub Enterprise Cloud プランを利用している必要があります。

この記事で

前提条件

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

ビルドのアーティファクトの証明書を生成する

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

アーティファクトの証明書を生成するためには、次の手順を行う必要があります。

  • ワークフローで適切なアクセス許可が構成されていることを確認します。
  •         [
        `attest-build-provenance`アクション](https://github.com/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@v3
  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@v3
  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 Marketplace で anchore-sbom-action をご覧ください。
  •         [
        `attest-sbom`アクション](https://github.com/actions/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 ファイルへのパスに設定する必要があります。

linked artifacts page

へのアーティファクトのアップロード

確認済みの資産を組織の linked artifacts page にアップロードすることをお勧めします。 このページには、成果物のビルド履歴、デプロイ レコード、およびストレージの詳細が表示されます。 このデータを使用して、セキュリティ アラートに優先順位を付けたり、脆弱な成果物を所有するチーム、ソース コード、ビルド実行にすばやく接続したりすることができます。 詳しくは、「リンクされた成果物について」をご覧ください。

(Note: Depending on specific requirements or known terms within the application's Japanese context, further information or context might adjust how this content should be presented.)

ワークフロー例については、「linked artifacts page へのストレージおよびデプロイメント データのアップロード」を参照してください。

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 のフラグを指定する必要があります。 詳細については、 リポジトリの「検証済み述語」を参照してください。

たとえば、現在、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'

次のステップ

構成証明の関連性と管理性を維持するため、不要になった構成証明は削除する必要があります。 「成果物（テクノロジー）証明のライフサイクルの管理」を参照してください。

また、コンシューマーがリリースの整合性と配信元を検証できるように、リリース構成証明を生成することもできます。 詳しくは、「変更不可リリース」をご覧ください。