Crea certificaciones con Voucher

En este instructivo, se describe cómo configurar y usar Voucher para crear certificaciones de autorización binaria.

Descripción general de Voucher

Voucher es una herramienta de código abierto que ejecuta un conjunto de verificaciones en imágenes de contenedor antes de crear certificaciones de autorización binaria para las imágenes. Voucher tiene un cliente y un componente de servidor. Debes ejecutar el cliente de Voucher como un paso adicional dentro de tu canalización de compilación, después del paso que compila la imagen. Cuando se ejecuta el paso de compilación del cliente de Voucher, se envía la imagen al servidor de Voucher, que realiza las verificaciones. Puedes definir qué verificaciones se ejecutan en Voucher, junto con otros criterios, en el archivo de configuración del servidor de Voucher.

En este instructivo, se muestra cómo usar la verificación snakeoil de Voucher para detectar vulnerabilidades en las imágenes. Para habilitar la verificación en el archivo de configuración, configura la opción fail-on en un límite de vulnerabilidad, como se muestra más adelante en este instructivo.

Una vez que se complete la verificación snakeoil, si todas las vulnerabilidades identificadas caen por debajo del umbral, el servidor de Voucher crea la certificación de autorización binaria para la imagen. Si alguna de las vulnerabilidades identificadas alcanza o supera el umbral, el servidor de Voucher no crea una certificación.

En el momento de implementar la imagen de contenedor, sin una certificación verificada, el ejecutor de la autorización binaria no permite que se implemente la imagen.

Nota: En este instructivo, compilarás un servidor de Voucher y lo implementarás en Cloud Run. Si, en cambio, prefieres alojar un servidor compilado previamente de Voucher en Google Kubernetes Engine (GKE), este servidor también está disponible como un contenedor de implementación en un clic en Google Cloud Marketplace. Para obtener más información, consulta Ejecuta el servidor de Voucher en GKE.

Objetivos

En esta guía, harás lo siguiente:

1. Configurar el servidor de Voucher en Cloud Run.
2. Configurar el cliente de Voucher
3. Usar Voucher en canalizaciones de compilación de ejemplo

Costos

En esta guía, se usan los siguientes productos de Google Cloud.

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

Usa la calculadora de precios para estimar los costos según el uso previsto.

Antes de comenzar

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. Te recomendamos que configures la autorización binaria con Google Kubernetes Engine. En este instructivo, se describe cómo crear una certificación. Para usar la aplicación en el momento de la implementación a fin de verificar la certificación y, luego, implementar la imagen asociada, se debe configurar la autorización binaria. Asegúrate de configurar la política para solicitar certificaciones. Puedes configurar la política en la consola de Google Cloud o en la línea de comandos.

13. Especifica tu proyecto de Google Cloud en una variable de entorno.

    Nota: Este ID del proyecto se usa en todo este documento.

      export PROJECT_ID=PROJECT_ID
    

    Reemplaza PROJECT_ID con el ID del proyecto.

14. Configura el ID del proyecto para los comandos gcloud:

    gcloud config set project ${PROJECT_ID}

15. Especifica el número de proyecto en una variable de entorno para pasos futuros:

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

Configura el servidor de Voucher

En los siguientes pasos, configurarás el servidor de Voucher.

Crea una clave de firma de Cloud Key Management Service

En esta sección, crearás la clave que el servidor de Voucher usa para crear una certificación de autorización binaria.

1. Crea un llavero de claves

   gcloud kms keyrings create KEY_RING\
      --location global
   

   Reemplaza KEY_RING por un nombre de llavero de claves, como voucher-key-ring.

2. Crea una clave de firma:

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

   Reemplaza KEY_NAME por el nombre de una clave, como voucher-key.

   Nota: Voucher solo es compatible con los algoritmos del resumen SHA512.

3. Almacena el ID de recurso de la versión de la clave de Cloud Key Management Service:

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

4. Otorga el rol cloudkms.signer a la cuenta de servicio del entorno de ejecución de Compute Engine.

   En este paso, otorgas el rol cloudkms.signer a la cuenta de servicio que ejecuta el servidor de Voucher. Esto permite que el servidor de Voucher firme las certificaciones con las claves de Cloud Key Management Service. Para ello, ejecuta el siguiente comando:

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

Crea la nota de Artifact Analysis

En esta sección, crearás la nota.

1. Almacena el ID de la nota:

   export NOTE_ID=snakeoil
   

2. Almacena el URI de la nota:

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

3. Crea la carga útil de la solicitud:

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

4. Crea la nota:

   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}"
   

Compila y configura el servidor de Voucher

En esta configuración única, obtendrás, configurarás y compilarás la imagen del servidor Voucher. Luego, la almacenarás en Container Registry.

1. Clona el repositorio de Voucher:

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

   Este repositorio contiene lo siguiente:

   • Código fuente para compilar el servidor de Voucher.
   • Código fuente para compilar el cliente de Voucher.
   • Ejemplos en los que se demuestra el uso de Voucher.

2. Actualiza el archivo de configuración del servidor de Voucher.

   Linux

   Crea el archivo de configuración del servidor de Voucher a partir de una plantilla y reemplaza y por los valores que definiste antes. Para ello, ejecuta el siguiente comando:

    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
   

   Otro SO

   1. Edita el archivo tutorials/cloudrun/config.toml.template.

      • Reemplaza <PROJECT_ID> por el valor en ${PROJECT_ID}.
      • Reemplaza <KMS_KEY_NAME> por el valor en ${KMS_RESOURCE_ID}.

   2. Guarda el archivo como tutorials/cloudrun/config.toml.

3. Visualiza el archivo de configuración del servidor de Voucher:

   cat tutorials/cloudrun/config.toml
   

   Verás un resultado que contiene lo siguiente:

   failon = "high"
   

   Ten en cuenta que, en el archivo de configuración, la opción failon se configura como high. Este parámetro configura el servidor de Voucher para realizar una verificación de vulnerabilidades en una imagen. Si la imagen contiene vulnerabilidades con una gravedad de HIGH, la verificación fallará y el servidor de Voucher no creará la certificación de autorización binaria. Para obtener más información sobre la configuración de fail-on, consulta Error en las vulnerabilidades.

4. Compila y sube la imagen de contenedor del servidor de Voucher:

   En esta sección, debes ejecutar la canalización de Cloud Build que compila la imagen de contenedor del servidor de Voucher. La compilación también sube la imagen del servidor del cupón a gcr.io/$PROJECT_ID/voucher-server.

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

Implementa el servidor de Voucher en Cloud Run

1. Selecciona una región.

   Para ver una lista de regiones disponibles, Consulta una lista de regiones disponibles. Crea una variable para almacenar la región seleccionada:

   export REGION=REGION
   

   Reemplaza REGION por el nombre de la región en la que planeas implementar el servidor de Voucher.

2. Implementa el servidor de Voucher en Cloud Run

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

   Verás un resultado como el siguiente:

   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. Almacena la URL de servicio del servidor de Voucher:

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

Configura el cliente de Voucher

En los siguientes pasos, configurarás el cliente de Voucher.

1. Crea la cuenta de servicio de invocador para el cliente de Voucher:

   gcloud iam service-accounts create INVOKER_ACCOUNT_NAME
   

   Reemplaza INVOKER_ACCOUNT_NAME por un nombre para la cuenta de servicio de invocador, como voucher-invoker.

2. Especifica la cuenta de servicio:

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

3. Otorga el rol run.invoker a la cuenta de servicio de invocador de tu proyecto.

   Otorga permiso a tu cuenta de servicio de invocador para que invoque al servidor de Voucher en Cloud Run. Para ello, ingresa el siguiente comando:

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

4. Otorga el rol iam.serviceAccountTokenCreator a la cuenta de servicio del invocador para Cloud Build.

   En esta sección, otorgas a la cuenta de servicio de Cloud Build permiso para actuar en nombre de la cuenta de servicio del invocador a fin de que el cliente de Voucher tenga permiso para enviar solicitudes al servidor de Voucher durante la compilación. Para ello, ingresa el siguiente comando:

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

Usa el Voucher para verificar las imágenes en busca de vulnerabilidades

En esta sección, ejecutarás dos canalizaciones de Cloud Build de ejemplo. En ambas canalizaciones, compilarás una imagen y, luego, usarás Voucher para verificarla en busca de vulnerabilidades.

Caso de error

En esta sección, la canalización de compilación de ejemplo no crea una certificación. La imagen que compilas según Debian 9 contiene al menos una vulnerabilidad de gravedad HIGH. La opción fail-on en el servidor de Voucher config.toml está configurada para fallar en vulnerabilidades de gravedad HIGH. En este caso, el servidor de Voucher no crea una certificación de autorización binaria.

1. Ejecuta la canalización de compilación:

   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. Busca en el registro de la última compilación los resultados snakeoil de Voucher:

   Console

   1. Toma nota del ID de compilación de la última compilación.

   2. En la consola de Google Cloud, ve a la página Historial de compilaciones.

      Ir al historial de compilaciones

   3. En Compilar, haz clic en el elemento que contiene los primeros caracteres del ID de compilación.

   4. Haz clic en Ver sin procesar.

   5. Busca snakeoil con tu navegador.

      Verás un resultado como el siguiente:

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

   gcloud

   1. Guarda el ID de compilación de la compilación:

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

   2. Ingresa el siguiente comando para buscar tu registro de compilación:

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

      El resultado luce de la siguiente manera:

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

Caso de éxito

En esta sección, la canalización de compilación de ejemplo tiene éxito en la creación de una certificación. Todas las vulnerabilidades identificadas se clasifican por debajo del umbral fail-on, por lo que la verificación pasa la canalización y crea la certificación.

Nota: Es posible que observes resultados diferentes. Esta compilación podría no crear una certificación si, en algún momento, la verificación de vulnerabilidades identifica vulnerabilidades nuevas que se clasifican con una gravedad de HIGH.

1. Ejecuta la canalización:

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

   Nota: Es posible que, en un principio, esta compilación no genere la certificación. Esto se debe a que los permisos que otorgaste antes en este instructivo pueden tardar unos minutos en propagarse al servidor de Voucher. Para resolver esto, vuelve a ejecutar el comando de compilación.

2. Busca en el registro de la última compilación los resultados snakeoil de Voucher:

   Console

   1. Toma nota del ID de compilación de la última compilación.

   2. En la consola de Google Cloud, ve a la página Historial de compilaciones.

      Ir al historial de compilaciones

   3. En Compilar, haz clic en el elemento que contiene los primeros caracteres del ID de compilación.

   4. Haz clic en Ver sin procesar.

   5. Busca snakeoil con tu navegador.

      Verás un resultado como el siguiente:

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

   gcloud

   1. Guarda el ID de compilación de la última compilación:

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

   2. Ingresa el siguiente comando para buscar tu registro de compilación:

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

      El resultado luce de la siguiente manera:

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

Libera espacio

Para limpiar los recursos que se usan en este documento, puedes borrar el proyecto de la siguiente manera:

gcloud projects delete ${PROJECT_ID}

Crea un certificador

Para crear una política que requiera las certificaciones que creas con el método descrito en esta guía, primero debes crear un certificador.

Para crear un certificador, haz lo siguiente:

1. Recupera el material de clave pública de la clave de Cloud KMS que creaste antes en esta guía:

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

   • KEY_NAME: el nombre de la clave
   • KEY_RING: es el nombre del llavero de claves
   • OUTPUT_PATH: una ruta de acceso a archivos, por ejemplo, my-key.pem

2. Crea un certificador mediante el material de clave pública en el archivo y la nota que creaste antes en esta guía. Puedes crear un certificador mediante la consola de Google Cloud o gcloud CLI.

3. Crea una política que requiera certificaciones y proporciona el certificador que creaste en esta sección. Puedes crear una política a través de la consola de Google Cloud o la gcloud CLI.

Crea una certificación

Para crear una certificación mediante tu certificador, consulta Crea una certificación con Cloud KMS.

¿Qué sigue?

• Configura la política de la autorización binaria para requerir certificaciones mediante la herramienta de línea de comandos o la consola de Google Cloud.
• Crea el certificador que usa la autorización binaria para verificar la certificación en el momento de la implementación mediante la herramienta de línea de comandos o la consola de Google Cloud.
• Consulta la documentación sobre Voucher en GitHub.
• Obtén información sobre la autorización binaria.
• Obtén más información sobre Artifact Analysis y el análisis de vulnerabilidades.
• Obtén información sobre Cloud Key Management Service.