画像の来歴を確認する

カスタム OS イメージの SLSA（ソフトウェア アーティファクトのサプライ チェーン レベル）ビルドの来歴証明書を検証して、ソフトウェア サプライ チェーンの完全性を確保できます。

Artifact Registry に出力するように Image Builder パイプラインを構成し、検証オプションを有効にすると、Cloud Build は、コンパイル中に使用された正確なパイプライン ソースコード、構成、実行パラメータ、ベースイメージを記述する暗号証明書を自動的に生成します。このビルドの来歴を検証することで、信頼できるパイプラインが不正な改ざんなしにイメージを安全にビルドしたことを確認できます。

始める前に

  • 環境を準備するで環境の設定手順を完了します。
  • まだ設定していない場合は、認証を設定します。認証では、 Google Cloud サービスと API にアクセスするための ID が確認されます。ローカル開発環境からコードまたはサンプルを実行するには、次のいずれかのオプションを選択して Compute Engine に対する認証を行います。

    このページのサンプルをどのように使うかに応じて、タブを選択してください。

    コンソール

    Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

    gcloud

    1. Google Cloud CLI をインストールします。インストール後、次のコマンドを実行して Google Cloud CLI を初期化します。

      gcloud init

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

  • デフォルトのリージョンとゾーンを設定します。

    • REST

    このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

      Google Cloud CLI をインストールします。

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

    詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

必要なロール

ビルドの来歴証明書を表示して検証するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

来歴の生成を構成する

ビルドの来歴を生成するには、次のスニペットに示すように、cloudbuild.yaml ファイルで substitutions、options、results、artifacts の各ブロックを構成します。

substitutions:
  # 1. Specify your output path and target Artifact Registry resource URI
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'

steps:
  # 2. Configure step results and base image attestations
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'
    results:
      - name: image_builder_telemetry_metrics
      - name: base_image
        attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"
        attestationContent: base_image

options:
  # 3. Enable Cloud Logging and cryptographic provenance generation
  logging: CLOUD_LOGGING_ONLY
  requestedVerifyOption: VERIFIED

artifacts:
  # 4. Upload generic image artifacts and provenance to Artifact Registry
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'

来歴データを検証する

ビルドの来歴データと実行アーティファクトを表示して確認するには、 Google Cloud コンソールまたは Google Cloud CLI を使用します。

コンソール（Cloud Build）

Cloud Build のビルド履歴でビルドの来歴と出力アーティファクトを表示するには:

  1. Google Cloud コンソールで、[Cloud Build] ページに移動します。

    Cloud Build に移動

  2. [履歴] をクリックし、イメージ パイプライン実行の [ビルド ID] を選択します。ビルドの詳細ページには、3 つのプロセス ステップ（imagebuilder-customize、imagebuilder-validate、imagebuilder-publish）のログが表示されます。

  3. [ビルド アーティファクト] タブをクリックして、実行中に作成された正確な OS イメージを表示します。

  4. [アタッチメント] タブをクリックして、署名付き SLSA 出所証明書ファイルと結果ファイルを表示します。結果ファイルには、実行中に使用されたソースベースイメージが記録されます。

コンソール（Artifact Registry）

Artifact Registry でビルドの来歴を直接表示するには:

  1. Google Cloud コンソールで、[Artifact Registry] ページに移動します。

    Artifact Registry に移動

  2. リポジトリ リストで、汎用リポジトリの名前をクリックします。

  3. パッケージ リストで、OS イメージ パッケージ名をクリックします。

  4. 変更履歴リストで、パイプライン実行のバージョン ID（v${BUILD_ID}）をクリックします。

  5. [アタッチメント] タブをクリックして、そのイメージ バージョンの署名付き SLSA Provenance 構成証明ファイルと結果ファイルを表示します。結果ファイルには、実行中に使用されたベースソース画像が記録されます。

gcloud

Artifact Registry は、汎用イメージの tarball とともに、添付ファイルとして来歴レコードを保存します。

構成証明は Dead Simple Signing Envelope（DSSE）としてフォーマットされているため、JSON 内の実際のプロベナンス ステートメント ペイロードは Base64 エンコードされています。詳細を読み取るには、gcloud CLI と jq ユーティリティを使用して次の操作を行います。

  1. gcloud artifacts versions list コマンドを実行して、パッケージのバージョンを一覧表示し、検証する特定のビルド ID バージョンを見つけます。

    gcloud artifacts versions list \
    --package=PACKAGE_NAME \
    --repository=REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --project=PROJECT_ID

    次のように置き換えます。

    • PACKAGE_NAME: Artifact Registry リポジトリ内のパッケージの名前（例: my-custom-image）。
    • REPOSITORY_NAME: 汎用 Artifact Registry リポジトリの名前（例: custom-os-images）。
    • REPOSITORY_LOCATION: リポジトリのリージョン（例: us-central1）。
    • PROJECT_ID: プロジェクト ID。

  2. gcloud artifacts attachments list コマンドを実行して、ターゲット パッケージ バージョンに一致するアタッチメントのメタデータをクエリします。

    gcloud artifacts attachments list \
    --target=projects/PROJECT_ID/locations/REPOSITORY_LOCATION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/vBUILD_ID \
    --repository=REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --project=PROJECT_ID

    BUILD_ID は、ステップ 1 で返されたバージョン識別子（12345 など）に置き換えます。

    コマンド出力から、name フィールドに build-result（type: application/vnd.in-toto+json を含む）が含まれている添付ファイル エントリを見つけ、files: にリストされているパスをコピーします。例:

    projects/PROJECT_ID/locations/REPOSITORY_LOCATION/repositories/REPOSITORY_NAME/files/sha256:SHA256_HASH

  3. gcloud artifacts files download コマンドを実行して、リポジトリから JSON メタデータ添付ファイル ペイロードをダウンロードします。

    gcloud artifacts files download ATTACHMENT_FILE_ID \
    --repository=REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --project=PROJECT_ID \
    --destination=./provenance.json

    ATTACHMENT_FILE_ID は、前の手順で取得した files: アタッチメント パスに置き換えます。

  4. 次のコマンドを実行して、JSON ペイロードの内容を分離し、base64 デコードして、フォーマットします。

    cat ./provenance.json | jq -r '.payload' | base64 --decode | jq

    出力には、ビルドトリガー、レシピ リポジトリの詳細、使用されたコンテナ イメージ、ビルドハッシュ、ベースイメージ属性をハイライト表示する標準の SLSA 形式のパラメータが含まれています。