Verifica la procedencia de la imagen

Puedes verificar las certificaciones de procedencia de compilación de SLSA (niveles de la cadena de suministro para artefactos de software) para tus imágenes de SO personalizadas y garantizar la integridad de la cadena de suministro de software.

Cuando configuras tu canalización de Image Builder para que genere resultados en Artifact Registry y habilitas las opciones de verificación, Cloud Build genera automáticamente una certificación criptográfica que describe el código fuente, las configuraciones, los parámetros de ejecución y la imagen base exactos de la canalización que se usaron durante la compilación. La verificación de la procedencia de esta compilación confirma que las canalizaciones de confianza compilaron tus imágenes de forma segura y sin manipulaciones no autorizadas.

Antes de comenzar

  • Completa los pasos de configuración del entorno en Prepara tu entorno.
  • Si aún no lo hiciste, configura la autenticación. La autenticación verifica tu identidad para acceder a los servicios y las APIs de Cloud de Confiance by S3NS . Para ejecutar código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

    Selecciona la pestaña que corresponda a la forma en que planeas usar las muestras de esta página:

    Console

    Cuando usas la consola de Cloud de Confiance para acceder a los servicios y las APIs de Cloud de Confiance by S3NS , no necesitas configurar la autenticación.

    gcloud

    1. Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada. Después de acceder, inicializa Google Cloud CLI con el siguiente comando: 

      gcloud init
  • Configura una región y una zona predeterminadas.

    • REST

    Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.

      Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada.

    Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de Cloud de Confiance .

Roles obligatorios

Para obtener los permisos que necesitas para ver y verificar las certificaciones de procedencia de la compilación, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Configura la generación de procedencia

Para generar la procedencia de la compilación, asegúrate de configurar los bloques substitutions, options, results y artifacts en tu archivo cloudbuild.yaml como se muestra en el siguiente fragmento:

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

Verifica los datos de procedencia

Puedes ver y verificar los datos de procedencia de compilación y los artefactos de ejecución con la Cloud de Confiance consola o Google Cloud CLI:

Consola (Cloud Build)

Para ver la procedencia de la compilación y los artefactos de salida a través del historial de compilaciones de Cloud Build, haz lo siguiente:

  1. En la consola Cloud de Confiance , ve a la página Cloud Build.

    Ir a Cloud Build

  2. Haz clic en Historial y selecciona el ID de compilación de la ejecución de tu canalización de imágenes. En la página de detalles de la compilación, se muestran los registros de los tres pasos del proceso (imagebuilder-customize, imagebuilder-validate y imagebuilder-publish).

  3. Haz clic en la pestaña Artefactos de compilación para ver la imagen de SO exacta que se creó durante la ejecución.

  4. Haz clic en la pestaña Adjuntos para ver los archivos de certificación y los archivos de resultados de la procedencia de SLSA firmada. El archivo de resultados registra la imagen base de origen que se usó durante la ejecución.

Consola (Artifact Registry)

Para ver la procedencia de la compilación directamente en Artifact Registry, haz lo siguiente:

  1. En la consola de Cloud de Confiance , ve a la página Artifact Registry.

    Ir a Artifact Registry

  2. En la lista de repositorios, haz clic en el nombre de tu repositorio genérico.

  3. En la lista de paquetes, haz clic en el nombre del paquete de la imagen de SO.

  4. En la lista de historial de versiones, haz clic en el ID de versión (v${BUILD_ID}) de la ejecución de tu canalización.

  5. Haz clic en la pestaña Adjuntos para ver los archivos de certificación de procedencia de SLSA firmados y los archivos de resultados de esa versión de la imagen. El archivo de resultados registra la imagen de origen base que se usó durante la ejecución.

gcloud

Artifact Registry almacena los registros de procedencia como archivos adjuntos junto con los archivos .tar.gz de imágenes genéricas.

Dado que la certificación se formatea como un sobre de firma simple (DSSE), la carga útil real de la declaración de procedencia dentro del JSON está codificada en base64. Para leer los detalles, sigue estos pasos con gcloud CLI y la utilidad jq:

  1. Ejecuta el comando gcloud artifacts versions list para enumerar las versiones de tu paquete y encontrar la versión específica del ID de compilación que deseas verificar:

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

    Reemplaza lo siguiente:

    • PACKAGE_NAME: Es el nombre del paquete en tu repositorio de Artifact Registry, por ejemplo, my-custom-image.
    • REPOSITORY_NAME: Es el nombre de tu repositorio genérico de Artifact Registry, por ejemplo, custom-os-images.
    • REPOSITORY_LOCATION: Es la región de tu repositorio, por ejemplo, us-central1.
    • PROJECT_ID: el ID de tu proyecto

  2. Ejecuta el comando gcloud artifacts attachments list para consultar los metadatos de los archivos adjuntos que coinciden con la versión del paquete de destino:

    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

    Reemplaza BUILD_ID por el identificador de versión que se devolvió en el paso 1, por ejemplo, 12345.

    En el resultado del comando, busca la entrada del adjunto cuyo campo name contenga build-result (con type: application/vnd.in-toto+json) y copia la ruta que aparece en files:, por ejemplo:

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

  3. Descarga la carga útil del adjunto de metadatos JSON de tu repositorio ejecutando el comando gcloud artifacts files download:

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

    Reemplaza ATTACHMENT_FILE_ID por la ruta de acceso del adjunto files: que recuperaste en el paso anterior.

  4. Ejecuta el siguiente comando para aislar, decodificar en Base64 y dar formato al contenido de la carga útil de JSON:

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

    El resultado contiene parámetros de formato SLSA estándar que destacan el activador de compilación, los detalles del repositorio de recetas, las imágenes de contenedor utilizadas, los hashes de compilación y los atributos de la imagen base.