アーティファクトの構成証明を使用してビルドの出所を確立する

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

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

成果物構成証明は、現在のすべての 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 にアップロードすることをお勧めします。 このページには、成果物のビルド履歴、デプロイ レコード、およびストレージの詳細が表示されます。 このデータを使用して、セキュリティ アラートに優先順位を付けたり、脆弱な成果物を所有するチーム、ソース コード、ビルド実行にすばやく接続したりすることができます。 詳しくは、「リンクされた成果物について」をご覧ください。

構成証明アクションと構成証明ビルド-実証アクションでは、次の両方の場合、linked artifacts page にストレージ レコードが自動的に作成されます。

  •         `push-to-registry` オプションは次の値に設定されます。`true`
  • アクションを含むワークフローには、 artifact-metadata: write アクセス許可があります

ワークフロー例については、「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'

次のステップ

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

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