Voucher で証明書を作成する

このチュートリアルでは、Voucher を設定して使用し、Binary Authorization 証明書を作成する方法について説明します。

Voucher の概要

Voucher はオープンソース ツールで、イメージの Binary Authorization 証明書を作成する前に、コンテナ イメージに一連のチェックを行います。Voucher にはクライアント コンポーネントとサーバー コンポーネントがあります。イメージをビルドするステップの後に、ビルド パイプライン内の追加ステップとして Voucher Client を実行します。Voucher Client のビルドステップが実行されると、Voucher Server にイメージが送信され、そこでチェックが実行されます。Voucher Server 構成ファイルで、Voucher が実行するチェックを他の条件とともに定義します。

このチュートリアルでは、Voucher の snakeoil チェックを使用して、イメージの脆弱性をテストする方法について説明します。構成ファイルのチェックを有効にするには、このチュートリアルの後半で説明するように脆弱性しきい値に fail-on オプションを設定します。

snakeoil のチェックが完了した後、検出された脆弱性すべてがしきい値を下回ると、Voucher Server はイメージの Binary Authorization 証明書を作成します。検出された脆弱性のいずれかがしきい値を上回る場合、Voucher Server は証明書を作成しません。

コンテナ イメージのデプロイ時に、検証済みの証明書がなければ、Binary Authorization 適用者はイメージのデプロイを拒否します。

注: このチュートリアルでは、Voucher Server をビルドして Cloud Run にデプロイします。ビルド済みの Voucher Server を Google Kubernetes Engine（GKE）にホストする場合は、Voucher Server をクリック デプロイ コンテナとして Google Cloud Marketplace で使用できます。詳しくは、GKE で Voucher Server を実行するをご覧ください。

目標

このガイドでは、次のことを行います。

1. Cloud Run で Voucher Server を設定します。
2. Voucher Client を設定します。
3. サンプル ビルド パイプラインで Voucher を使用します。

費用

このガイドでは、次の Google Cloud プロダクトを使用します。

• Container Registry
• Artifact Analysis
• Cloud Build
• Cloud Key Management Service
• Cloud Run

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを出すことができます。

始める前に

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Build, Container Registry, Artifact Analysis, Cloud KMS, Cloud Run, and Identity and Access Management APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the Cloud Build, Container Registry, Artifact Analysis, Cloud KMS, Cloud Run, and Identity and Access Management APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

12. Google Kubernetes Engine で Binary Authorization を設定することをおすすめします。このチュートリアルでは、証明書の作成方法について説明します。デプロイ時に証明書を検証し、関連するイメージをデプロイするには、Binary Authorization を設定する必要があります。証明書を要求するようにポリシーを構成します。ポリシーは、Google Cloud Console またはコマンドラインで構成できます。

13. 環境変数に Google Cloud プロジェクトを指定します。

    注: このプロジェクト ID は、このドキュメント全体で使用されます。

      export PROJECT_ID=PROJECT_ID
    

    PROJECT_ID を実際のプロジェクト ID に置き換えます。

14. gcloud コマンドにプロジェクト ID を設定します。

    gcloud config set project ${PROJECT_ID}

15. 以降の手順で使用するため、プロジェクト番号を環境変数に指定します。

    export PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" \
      --format='value(project_number)')

Voucher Server を設定する

以下の手順で Voucher Server を設定します。

Cloud Key Management Service の署名鍵を作成する

このセクションでは、Voucher Server が Binary Authorization 証明書の作成に使用する鍵を作成します。

1. キーリングを作成します。

   gcloud kms keyrings create KEY_RING\
      --location global
   

   KEY_RING は、voucher-key-ring などのキーリング名に置き換えます。

2. 署名鍵を作成します。

   gcloud kms keys create KEY_NAME \
     --keyring KEY_RING \
     --location global \
     --purpose "asymmetric-signing" \
     --default-algorithm "rsa-sign-pkcs1-4096-sha512"
   

   KEY_NAME は、voucher-key などのキー名に置き換えます。

   注: Voucher は SHA512 ダイジェスト アルゴリズムのみをサポートしています。

3. Cloud Key Management Service 鍵バージョンのリソース ID を保存します。

   export KMS_RESOURCE_ID=projects/$PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/1
   

4. Compute Engine ランタイム エンジン サービス アカウントに cloudkms.signer ロールを付与します。

   この手順では、Voucher Server を実行するサービス アカウントに cloudkms.signer ロールを付与します。これにより、Voucher Server で Cloud Key Management Service の鍵を使用して証明書に署名できるようになります。これを行うには、次のコマンドを実行します。

   gcloud kms keys add-iam-policy-binding\
     KEY_NAME --keyring=KEY_RING\
     --location=global\
     --member=serviceAccount:${PROJECT_NUMBER}[e-mail]\
     --role=roles/cloudkms.signer
   

Artifact Analysis メモを作成する

このセクションでは、メモを作成します。

1. メモの ID を保存します。

   export NOTE_ID=snakeoil
   

2. メモの URI を保存します。

   export NOTE_URI=projects/$PROJECT_ID/notes/$NOTE_ID
   

3. リクエストのペイロードを作成します。

   cat > /tmp/note_payload.json << EOM
   {
     "name": "${NOTE_URI}",
     "attestation": {
       "hint": {
         "human_readable_name": "voucher note for snakeoil check"
       }
     }
   }
   EOM
   

4. メモを作成します。

   curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $(gcloud --project ${PROJECT_ID} auth print-access-token)"  \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     --data-binary @/tmp/note_payload.json  \
   "https://containeranalysis.googleapis.com/v1/projects/${PROJECT_ID}/notes/?noteId=${NOTE_ID}"
   

Voucher Server の構築と構成を行う

この 1 回限りの設定で Voucher Server イメージを取得、構成、ビルドします。その後、イメージを Container Registry に格納します。

1. Voucher リポジトリのクローンを作成します。

   git clone https://github.com/grafeas/voucher.git
   cd voucher/
   

   このリポジトリには、以下のものが含まれます。

   • Voucher Server をビルドするソースコード。
   • Voucher Client をビルドするソースコード。
   • Voucher の使用方法を説明するサンプル。

2. Voucher Server 構成ファイルを更新します。

   Linux

   テンプレートから Voucher Server 構成ファイルを作成します。 と は、先ほど定義した値に置き換えます。これを行うには、次のコマンドを実行します。

    cat tutorials/cloudrun/config.toml.template \
       | sed -e "s?<PROJECT_ID>?${PROJECT_ID}?g" \
       | sed -e "s?<KMS_KEY_NAME>?${KMS_RESOURCE_ID}?g" \
         > tutorials/cloudrun/config.toml
   

   その他の OS

   1. tutorials/cloudrun/config.toml.template ファイルを編集します。

      • <PROJECT_ID> は、${PROJECT_ID} の値に置き換えます。
      • <KMS_KEY_NAME> は、${KMS_RESOURCE_ID} の値に置き換えます。

   2. ファイルを tutorials/cloudrun/config.toml として保存します。

3. Voucher Server 構成ファイルを確認します。

   cat tutorials/cloudrun/config.toml
   

   次の内容を含む出力が表示されます。

   failon = "high"
   

   構成ファイルでは、failon オプションが high に設定されています。この設定により、イメージの脆弱性チェックを実行するように Voucher サーバーが構成されます。重大度 HIGH の脆弱性がイメージに含まれている場合、チェックに失敗し、Voucher Server は Binary Authorization 証明書を作成しません。fail-on の設定の詳細については、フェイルオン: 脆弱性によるフェイルオンをご覧ください。

4. Voucher Server のコンテナ イメージをビルドしてアップロードします。

   このセクションでは、Cloud Build パイプラインを実行して Voucher Server コンテナ イメージをビルドします。このビルドにより、Voucher Server イメージが、gcr.io/$PROJECT_ID/voucher-server にアップロードされます。

   gcloud  builds submit --config ./tutorials/cloudrun/cloudbuild-server.yaml
   

Cloud Run に Voucher Server をデプロイする

1. リージョンを選択します。

   使用可能なリージョンのリストを表示するには、使用可能なリージョンのリストの表示をご覧ください。選択したリージョンを格納する変数を作成します。

   export REGION=REGION
   

   REGION は、Voucher Server をデプロイするリージョンの名前に置き換えます。

2. Cloud Run に Voucher Server をデプロイします。

   gcloud run deploy --image gcr.io/${PROJECT_ID}/voucher-server \
     --platform managed voucher-server \
     --region ${REGION} \
     --no-allow-unauthenticated
   

   次のような出力が表示されます。

   Service [voucher-server] revision [voucher-server-00001-caw] has been deployed and is serving 100 percent of traffic.
   Service URL: https://voucher-server-4wjtm2amga-uc.a.run.app
   

3. Voucher Server のサービス URL を保存します。

   export SERVER_SERVICE_URL=$(gcloud run services describe voucher-server --platform managed --region ${REGION} --format='value(status.url)')
   

Voucher Client を設定する

以下の手順で Voucher Client を設定します。

1. Voucher Client の呼び出し元サービス アカウントを作成します。

   gcloud iam service-accounts create INVOKER_ACCOUNT_NAME
   

   INVOKER_ACCOUNT_NAME は、呼び出し元サービス アカウントの名前（voucher-invoker など）に置き換えます。

2. サービス アカウントを指定します。

   export INVOKER_SERVICE_ACCOUNT=INVOKER_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

3. プロジェクトの呼び出し元サービス アカウントに run.invoker ロールを付与します。

   呼び出し元サービス アカウントに、Cloud Run で Voucher Server を呼び出す権限を付与します。これを行うには、次のコマンドを入力します。

   gcloud run services add-iam-policy-binding voucher-server \
     --member serviceAccount:$INVOKER_SERVICE_ACCOUNT \
     --role roles/run.invoker \
     --platform managed \
     --region ${REGION}
   

4. Cloud Build の呼び出し元サービス アカウントに iam.serviceAccountTokenCreator ロールを付与します。

   このセクションでは、Cloud Build サービス アカウントに呼び出し元サービス アカウントの権限借用を許可し、Voucher クライアントがビルド中に Voucher Server にリクエストを送信できるようにします。これを行うには、次のコマンドを入力します。

   gcloud iam service-accounts add-iam-policy-binding $INVOKER_SERVICE_ACCOUNT \
     --member=serviceAccount:$[e-mail] \
     --role=roles/iam.serviceAccountTokenCreator
   

Voucher を使用してイメージの脆弱性を確認する

このセクションでは、2 つのサンプル Cloud Build パイプラインを実行します。どちらのパイプラインでも、イメージをビルドしてから Voucher を使用して脆弱性を確認します。

失敗例

このセクションでは、サンプルのビルド パイプラインが証明書の作成に失敗します。Debian 9 に基づいてビルドされたイメージに、重大度 HIGH の脆弱性が 1 つ以上存在します。Voucher Server config.toml の fail-on オプションは、重大度が HIGH の脆弱性で失敗するように設定されています。この場合、Voucher Server は Binary Authorization 証明書を作成しません。

1. ビルド パイプラインを実行します。

   gcloud builds submit \
     --substitutions=_SERVICE_URL=$SERVER_SERVICE_URL,_SERVICE_ACCOUNT=$INVOKER_SERVICE_ACCOUNT \
     --config=tutorials/cloudrun/examples/cloudbuild-bad.yaml tutorials/cloudrun/examples
   

2. 前回のビルドからログを検索して、Voucher snakeoil の結果を見つけます。

   コンソール

   1. 最後のビルドのビルド ID をメモします。

   2. Google Cloud コンソールで [ビルド履歴] ページに移動します。

      [ビルド履歴] に移動

   3. [ビルド] で、ビルド ID の最初の数文字を含む項目をクリックします。

   4. [生データを表示] をクリックします。

   5. ブラウザを使用して「snakeoil」を検索します。

      次のような出力が表示されます。

      "name":"snakeoil","error":"vulnerable to 14 vulnerabilities"
      

   gcloud

   1. ビルドのビルド ID を保存します。

      export BUILD_ID=$(gcloud builds list --limit=1 --format="value('ID')")
      

   2. 次のコマンドを入力して、ビルドログを検索します。

       gcloud builds log ${BUILD_ID} | grep "snakeoil"
      

      出力は次のようになります。

      "name":"snakeoil","error":"vulnerable to 14 vulnerabilities"
      

成功例

このセクションでは、サンプル ビルド パイプラインが証明書の作成に成功します。検出されたすべての脆弱性は fail-on しきい値よりも低い値に分類されるため、チェックは合格し、パイプラインにより証明書が作成されます。

注: 異なる結果になる場合もあります。将来のどこかの時点で、脆弱性チェックで重大度 HIGH に分類される新しい脆弱性が特定されると、このビルドで証明書の作成が失敗する可能性があります。

1. パイプラインを実行します。

   gcloud builds submit\
     --substitutions=_SERVICE_URL=$SERVER_SERVICE_URL,_SERVICE_ACCOUNT=$INVOKER_SERVICE_ACCOUNT\
     --config=tutorials/cloudrun/examples/cloudbuild-good.yaml tutorials/cloudrun/examples
   

   注: このビルドでは、最初に証明書の作成が失敗する可能性があります。これは、このチュートリアルの前半で付与した権限が Voucher Server に反映されるまでに数分かかることがあるためです。この問題を解決するには、ビルドコマンドを再度実行します。

2. 前回のビルドからログを検索して、Voucher snakeoil の結果を見つけます。

   コンソール

   1. 最後のビルドのビルド ID をメモします。

   2. Google Cloud コンソールで [ビルド履歴] ページに移動します。

      [ビルド履歴] に移動

   3. [ビルド] で、ビルド ID の最初の数文字を含む項目をクリックします。

   4. [生データを表示] をクリックします。

   5. ブラウザを使用して「snakeoil」を検索します。

      次のような出力が表示されます。

      "name":"snakeoil","success":true,"attested":true
      

   gcloud

   1. 最後のビルドのビルド ID を保存します。

      export BUILD_ID=$(gcloud builds list --limit=1 --format="value('ID')")
      

   2. 次のコマンドを入力して、ビルドログを検索します。

       gcloud builds log ${BUILD_ID} | grep "snakeoil"
      

      出力は次のようになります。

      "name":"snakeoil","success":true,"attested":true
      

クリーンアップ

このドキュメントで使用されたリソースをクリーンアップするには、次のようにプロジェクトを削除します。

gcloud projects delete ${PROJECT_ID}

認証者を作成する

このガイドで説明する方法で作成した証明書を必要とするポリシーを作成するには、まず認証者を作成する必要があります。

認証者の作成手順は次のとおりです。

1. このガイドの前半で作成した Cloud KMS 鍵から公開鍵マテリアルを取得します。

   gcloud kms keys versions get-public-key 1 \
   --key KEY_NAME \
   --keyring KEY_RING \
   --location global \
   --output-file OUTPUT_PATH
   

   • KEY_NAME: 鍵名
   • KEY_RING: キーリング名
   • OUTPUT_PATH: ファイルパス（例: my-key.pem）

2. ファイル内の公開鍵マテリアルとこのガイドの前半で作成したメモを使用して、認証者を作成します。認証者を作成するには、Google Cloud コンソールまたは gcloud CLI を使用します。

3. 証明書を必要とするポリシーを作成し、このセクションで作成した認証者を指定します。ポリシーは、Google Cloud コンソールまたは gcloud CLI を使用して作成できます。

証明書を作成する

認証者を使用して証明書を作成するには、Cloud KMS を使用して証明書を作成するをご覧ください。

次のステップ

• コマンドライン ツールまたは Google Cloud Console を使用して、証明書を要求するように Binary Authorization ポリシーを構成する。
• コマンドライン ツールまたは Google Cloud Console を使用して、Binary Authorization がデプロイ時に証明書を検証するために使用する認証者を作成する。
• GitHub の Voucher ドキュメントを確認する。
• Binary Authorization について学習する。
• Artifact Analysis と脆弱性スキャンについて学習する。
• Cloud Key Management Service について学習する。