Genera y valida la procedencia de la compilación

En esta página, se proporcionan instrucciones para generar la procedencia de la compilación, ver el resultado y validarlo.

La procedencia de la compilación es una colección de datos verificables sobre una compilación. Los metadatos de procedencia incluyen detalles como los resúmenes de las imágenes compiladas, las ubicaciones de la fuente de entrada, los argumentos de compilación y la duración de la compilación. Puedes usar esta información para asegurarte de que los artefactos compilados que usas sean precisos y confiables, y que hayan sido creados por fuentes y compiladores de confianza.

Cloud Build admite la generación de procedencia de compilaciones que cumplen con la garantía de nivel 3 de Supply-chain Levels for Software Artifacts (SLSA) según las especificaciones de las versiones 0.1 y 1.0 de SLSA.

Como parte de la compatibilidad con la especificación de SLSA v1.0, Cloud Build proporciona detalles de buildType en la procedencia de la compilación. Puedes usar el esquema buildType para comprender la plantilla parametrizada que se usa en el proceso de compilación, incluidos los valores que registra Cloud Build y la fuente de esos valores. Para obtener más información, consulta Cloud Build buildType v1.

Limitaciones

• Cloud Build solo genera la procedencia de la compilación para los artefactos almacenados en Artifact Registry.
• Para obtener la procedencia de SLSA v1.0 y v0.1, debes compilar con activadores. Si inicias una compilación de forma manual con la CLI de gcloud, Cloud Build solo proporciona la procedencia de SLSA v0.1.
• Los adjuntos del repositorio de Docker, incluida la procedencia de la compilación, no están sujetos a las políticas de limpieza. En cambio, los archivos adjuntos se borran cuando se borra la imagen a la que están adjuntos. Para obtener más información, consulta Administra archivos adjuntos con políticas de limpieza.

Antes de comenzar

1. Enable the Cloud Build, Container Analysis, and Artifact Registry APIs.

   Enable the APIs

2. Para usar los ejemplos de la línea de comandos de esta guía, instala y configura el SDK de Google Cloud.

3. Ten a mano tu código fuente.

4. Tener un repositorio en Artifact Registry

Genera la procedencia de la compilación

En las siguientes instrucciones, se explica cómo generar la procedencia de la compilación para las imágenes de contenedor que almacenas en Artifact Registry:

1. En tu archivo de configuración de compilación, agrega el campo images para configurar Cloud Build de modo que almacene tus imágenes compiladas en Artifact Registry después de que se complete la compilación.

   Cloud Build no puede generar la procedencia si envías tu imagen a Artifact Registry con un paso docker push explícito.

   En el siguiente fragmento, se muestra una configuración de compilación para compilar una imagen de contenedor y almacenarla en un repositorio de Docker en Artifact Registry:

   YAML

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE', '.' ]
     images: ['LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE']
   

   Aquí:

   • LOCATION: Es la ubicación regional o multirregional de tu repositorio.
   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
   • REPOSITORY: Es el nombre de tu repositorio de Artifact Registry.
   • IMAGE: El nombre de tu imagen de contenedor

   JSON

     {
     "steps": [
         {
             "name": "gcr.io/cloud-builders/docker",
             "args": [
                 "build",
                 "-t",
                 "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE",
                 "."
             ]
         }
     ],
     "images": [
         "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE"
     ]
     }
   

   Aquí:

   • LOCATION: Es la ubicación regional o multirregional de tu repositorio.
   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
   • REPOSITORY: Es el nombre de tu repositorio de Artifact Registry.
   • IMAGE: El nombre de tu imagen de contenedor

2. En la sección options de tu configuración de compilación, agrega la opción requestedVerifyOption y configúrala con el valor VERIFIED.

   Este parámetro de configuración habilita la generación de la procedencia y configura Cloud Build para verificar que los metadatos de procedencia estén presentes. Las compilaciones solo se marcarán como exitosas si se genera la procedencia.

   YAML

   options:
     requestedVerifyOption: VERIFIED
   

   JSON

   {
       "options": {
           "requestedVerifyOption": "VERIFIED"
       }
   }
   

3. Comienza la compilación.

Cómo ver la procedencia de la compilación

En esta sección, se explica cómo ver los metadatos de procedencia de la compilación creados por Cloud Build. Puedes recuperar esta información para fines de auditoría.

Puedes acceder a los metadatos de procedencia de la compilación para contenedores con el panel lateral Estadísticas de seguridad en la consola de Google Cloud o con gcloud CLI.

  gcloud artifacts docker images describe \
  LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH \
  --show-provenance --format=FORMAT

Resultado de ejemplo

La procedencia de la compilación se ve de la siguiente manera:

      image_summary:
      digest: sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
      fully_qualified_digest: us-central1-docker.pkg.dev/my-project/my-repo/my-image@sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
      registry: us-central1-docker.pkg.dev
      repository: my-repo
      slsa_build_level: 0
    provenance_summary:
      provenance:
      - build:
          inTotoSlsaProvenanceV1:
            _type: https://in-toto.io/Statement/v1
            predicate:
              buildDefinition:
                buildType: https://cloud.google.com/build/gcb-buildtypes/google-worker/v1
                externalParameters:
                  buildConfigSource:
                    path: cloudbuild.yaml
                    ref: refs/heads/main
                    repository: git+https://github.com/my-username/my-git-repo
                  substitutions: {}
                internalParameters:
                  systemSubstitutions:
                    BRANCH_NAME: main
                    BUILD_ID: e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
                    COMMIT_SHA: 525c52c501739e6df0609ed1f944c1bfd83224e7
                    LOCATION: us-west1
                    PROJECT_NUMBER: '265426041527'
                    REF_NAME: main
                    REPO_FULL_NAME: my-username/my-git-repo
                    REPO_NAME: my-git-repo
                    REVISION_ID: 525c52c501739e6df0609ed1f944c1bfd83224e7
                    SHORT_SHA: 525c52c
                    TRIGGER_BUILD_CONFIG_PATH: cloudbuild.yaml
                    TRIGGER_NAME: github-trigger-staging
                  triggerUri: projects/265426041527/locations/us-west1/triggers/a0d239a4-635e-4bd3-982b-d8b72d0b4bab
                resolvedDependencies:
                - digest:
                    gitCommit: 525c52c501739e6df0609ed1f944c1bfd83224e7
                  uri: git+https://github.com/my-username/my-git-repo@refs/heads/main
                - digest:
                    sha256: 154fcd4d2d65c6a35b06b98053a0829c581e223d530be5719326f5d85d680e8d
                  uri: gcr.io/cloud-builders/docker@sha256:154fcd4d2d65c6a35b06b98053a0829c581e223d530be5719326f5d85d680e8d
              runDetails:
                builder:
                  id: https://cloudbuild.googleapis.com/GoogleHostedWorker
                byproducts:
                - {}
                metadata:
                  finishedOn: '2023-08-01T19:57:10.734471Z'
                  invocationId: https://cloudbuild.googleapis.com/v1/projects/my-project/locations/us-west1/builds/e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
                  startedOn: '2023-08-01T19:56:57.451553160Z'
            predicateType: https://slsa.dev/provenance/v1
            subject:
            - digest:
                sha256: 7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
              name: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image
            - digest:
                sha256: 7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
              name: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest
        createTime: '2023-08-01T19:57:14.810489Z'
        envelope:
          payload:
          eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdMWQ0LWVjNGEtNGVhNi1hY2RkLWFjOGJiMTZkY2M3OSIsICJzdGFydGVkT24iOiIyMDIzLTA4LTAxVDE5OjU2OjU3LjQ1MTU1MzE2MFoiLCAiZmluaXNoZWRPbiI6IjIwMjMtMDgtMDFUMTk6NTc6MTAuNzM0NDcxWiJ9LCAiYnlwcm9kdWN0cyI6W3t9XX19fQ==...
          payloadType: application/vnd.in-toto+json
          signatures:
          - keyid: projects/verified-builder/locations/global/keyRings/attestor/cryptoKeys/google-hosted-worker/cryptoKeyVersions/1
            sig: MEUCIQCss8UlQL2feFePRJuKTE8VA73f85iqj4OJ9SvVPqTNwAIgYyuyuIrl1PxQC5B109thO24Y6NA4bTa0PJY34EHRSVE=
        kind: BUILD
        name: projects/my-project/occurrences/71787589-c6a6-4d6a-a030-9fd041e40468
        noteName: projects/argo-qa/notes/intoto_slsa_v1_e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
        resourceUri: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image@sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
        updateTime: '2023-08-01T19:57:14.810489Z'
    

Estos son algunos aspectos importantes que debes tener en cuenta en este ejemplo:

• Fuente: La compilación se activó desde un repositorio de GitHub.

• Referencia de objeto: Los campos denominados digest y fileHash hacen referencia al mismo objeto. El campo digest incluido en el resultado de ejemplo está codificado en base 16 (codificado en hexadecimal). Si usas la versión 0.1 de la procedencia de SLSA, tu salida usa el campo fileHash codificado en base64.

• Firmas: Si usas la versión 0.1 de la procedencia de SLSA, tu resultado contiene dos firmas en el campo envelope. La primera firma, que tiene el nombre de clave provenanceSigner, usa una firma conforme con DSSE (con el formato de codificación previa a la autenticación [PAE]), que se puede verificar en las políticas de Autorización de binarios. Te recomendamos que uses esta firma en los nuevos usos de esta procedencia. La segunda firma, que tiene el nombre de clave builtByGCB, se proporciona para el uso heredado.

• Cuentas de servicio: Las firmas que se incluyen automáticamente en la procedencia de Cloud Build te ayudan a verificar el servicio de compilación que ejecutó una compilación. También puedes configurar Cloud Build para que registre metadatos verificables sobre la cuenta de servicio que se usó para iniciar una compilación. Para obtener más información, consulta Cómo firmar imágenes de contenedores con Cosign.

• Carga útil: El ejemplo de procedencia que se muestra en esta página se abrevió para facilitar la lectura. El resultado real será más largo, ya que la carga útil es una versión codificada en Base64 de todos los metadatos de procedencia.

• Dependencias: Las dependencias que especificas en tu archivo de compilación se incluyen en la procedencia, en el campo resolvedDependencies.

Cómo ver la procedencia de los artefactos que no son contenedores

Cloud Build genera metadatos de procedencia de SLSA para aplicaciones independientes de Go, Java (Maven), Python y Node.js (npm) cuando subes tus artefactos de compilación a Artifact Registry. Puedes recuperar los metadatos de procedencia con una llamada directa a la API.

1. Para generar los metadatos de procedencia de tus artefactos, ejecuta una compilación con Cloud Build. Usa una de las siguientes guías:

   • Cómo compilar aplicaciones independientes en Go
   • Compila aplicaciones independientes de Java
   • Compila aplicaciones de Python independientes
   • Compila aplicaciones independientes de Node.js

   Cuando se complete la compilación, anota el valor de BuildID.

2. Para recuperar los metadatos de procedencia, ejecuta la siguiente llamada a la API en tu terminal, en la que PROJECT_ID es el ID asociado a tu proyecto Google Cloud :

   alias gcurl='curl -H"Authorization: Bearer $(gcloud auth print-access-token)"'
       gcurl 'https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences'
   

   Debes usar una llamada a la API para acceder a los metadatos de procedencia de este tipo de artefacto. Los metadatos de procedencia de los artefactos que no son contenedores no se muestran en la consola de Google Cloud ni se puede acceder a ellos a través de gcloud CLI.

3. En las ocurrencias de tu proyecto, busca por BuildID para encontrar la información de procedencia asociada a un artefacto de compilación.

Valida la procedencia

En esta sección, se explica cómo validar la procedencia de la compilación para las imágenes de contenedor.

La validación de la procedencia de la compilación te ayuda a hacer lo siguiente:

• Confirma que los artefactos de compilación se generen a partir de fuentes y compiladores confiables.
• Asegúrate de que los metadatos de procedencia que describen tu proceso de compilación estén completos y sean auténticos.

Para obtener más información, consulta Protege las compilaciones.

Valida la procedencia con el verificador de SLSA

El verificador de SLSA es una herramienta de CLI de código abierto para validar la integridad de la compilación según las especificaciones de SLSA.

Si el verificador encuentra problemas, muestra mensajes de error detallados para ayudarte a actualizar tu proceso de compilación y mitigar los riesgos.

Para usar el verificador de SLSA, haz lo siguiente:

1. Instala la versión 2.1 o una posterior desde el repositorio de slsa-verifier.

   go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@VERSION
   

2. En tu CLI, configura una variable para el identificador de la imagen:

   export IMAGE=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH
   

   Aquí:

   • LOCATION: Ubicación regional o multirregional.
   • PROJECT_ID: Google Cloud ID del proyecto.
   • REPOSITORY: Es el nombre del repositorio.
   • IMAGE: Nombre de la imagen.
   • HASH: Es el valor de hash sha256 de la imagen. Puedes encontrarlo en el resultado de la compilación.

3. Autoriza la gcloud CLI para que el verificador de SLSA pueda acceder a tus datos de procedencia:

   gcloud auth configure-docker LOCATION-docker.pkg.dev
   

4. Recupera la procedencia de tu imagen y guárdala como JSON:

   gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.json
   

5. Verifica la procedencia:

   slsa-verifier verify-image "$IMAGE" \
   --provenance-path provenance.json \
   --source-uri SOURCE \
   --builder-id=BUILDER_ID
   

   Aquí:

   • SOURCE es el URI del repositorio de origen de tu imagen, por ejemplo, github.com/my-repo/my-application.
   • BUILDER_ID el ID único del compilador, por ejemplo, https://cloudbuild.googleapis.com/GoogleHostedWorker

   Si deseas imprimir la procedencia validada para usarla en un motor de políticas, usa el comando anterior con la marca --print-provenance.

   El resultado es similar a PASSED: Verified SLSA provenance o FAILED: SLSA verification failed: <error details>.

Para obtener más información sobre las marcas opcionales, consulta Opciones.

Valida los metadatos de procedencia con gcloud CLI

Si deseas verificar que no se haya manipulado los metadatos de procedencia de la compilación, puedes validar la procedencia siguiendo estos pasos:

1. Crea un directorio nuevo y ve a él.

   mkdir provenance && cd provenance
   

2. Con la información del campo keyid, obtén la clave pública.

   gcloud kms keys versions get-public-key 1 --location global --keyring attestor \
     --key builtByGCB --project verified-builder --output-file my-key.pub
   

3. El campo payload contiene la representación JSON de la procedencia, codificada en base64url. Decodifica los datos y almacénalos en un archivo.

   gcloud artifacts docker images describe \
   LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
     --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v0.1") | .envelope.payload' | tr '\-_' '+/' | base64 -d > provenance.json
   

   Cuando están disponibles, se almacenan los tipos de procedencia de las versiones 0.1 y 1.0 de SLSA. Si deseas filtrar la versión 1.0, cambia predicateType para usar https://slsa.dev/provenance/v1. Por ejemplo:

   gcloud artifacts docker images describe \
   LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
     --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v1") | .envelope.payload' | tr '\-_' '+/' | base64 -d > provenance.json
   

4. El sobre también contiene la firma sobre la procedencia. Decodifica los datos y almacénalos en un archivo.

     gcloud artifacts docker images describe LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
     --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v0.1") | .envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin
   

   Si deseas filtrar la versión 1.0, cambia predicateType para usar https://slsa.dev/provenance/v1. Por ejemplo:

   gcloud artifacts docker images describe LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
   --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v1") | .envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin
   

5. El comando anterior hace referencia a la primera firma de procedencia (.provenance_summary.provenance[0].envelope.signatures[0]) que está firmada por la clave provenanceSigner. La carga útil se firma sobre el sobre con formato de PAE. Para verificarlo, ejecuta este comando para transformar la procedencia en el formato PAE esperado de "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body.

   echo -n "DSSEv1 28 application/vnd.in-toto+json $(cat provenance.json | wc -c) $(cat provenance.json)" > provenance.json
   

6. Valida la firma.

   openssl dgst -sha256 -verify my-key.pub -signature signature.bin provenance.json
   

   Después de una validación exitosa, el resultado es Verified OK.

¿Qué sigue?

• Configura Cloud Build para hacer un seguimiento de quién inicia una compilación
• Usa el análisis de vulnerabilidades en tu canalización de Cloud Build
• Más información sobre la seguridad de la cadena de suministro de software