使用 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 Enforcer 会禁止部署该映像。

注意：在本教程中，您将构建 Voucher Server 并将其部署到 Cloud Run。此外，如果您希望在 Google Kubernetes Engine (GKE) 上托管预建的 Voucher Server，则还可以将 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. 将 cloudkms.signer 角色授予给 Compute Engine 运行时引擎服务账号。

   在此步骤中，将 cloudkms.signer 角色授予给运行 Voucher Server 的服务账号。这样，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

在这个一次性设置中，您将获取、配置和构建 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
   

   其他操作系统

   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 Server 对映像执行漏洞检查。如果映像包含严重程度为 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
   

部署 Voucher Server on Cloud Run

1. 选择一个区域。

   如需查看可用区域的列表，请参阅查看可用区域的列表。创建一个变量来存储您选择的区域：

   export REGION=REGION
   

   将 REGION 替换为您打算在其中部署 Voucher Server 的区域的名称。

2. 部署 Voucher Server on Cloud Run。

   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 服务网址：

   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. 将 iam.serviceAccountTokenCreator 角色授予给 Cloud Build 的调用方服务账号。

   在本部分中，您将为 Cloud Build 服务账号授予模拟调用方服务账号的权限，以便 Voucher Client 有权在构建期间向 Voucher Server 发送请求。为此，请输入以下命令：

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

使用 Voucher 检查映像是否存在漏洞

在本部分中，您将运行两个 Cloud Build 流水线示例。在这两个流水线中，您都会构建映像，然后使用 Voucher 来检查其是否存在漏洞。

失败案例

在本部分中，构建流水线示例未能成功创建证明。您基于 Debian 9 构建的映像至少包含一个严重程度为 HIGH 的漏洞。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. 在上一个 Build 中搜索日志，查找 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. 在上一个 Build 中搜索日志，查找 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。