Usar procedencia firmada y autorización binaria

En esta página, se proporcionan instrucciones para ver los metadatos de procedencia de la compilación y controlar las implementaciones con Cloud Build.

La procedencia de compilación es una colección de datos verificables sobre una compilación que ejecuta Cloud Build. 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 la compilación y la duración de la compilación.

Para ayudarte a proteger tu cadena de suministro de software, Cloud Build registra los metadatos de procedencia y crea certificaciones de las imágenes de contenedor en el tiempo de compilación. Puedes usar los metadatos de origen con fines de auditoría y usar las certificaciones para controlar las implementaciones con la autorización binaria.

Limitaciones

Cloud Build genera todos los recursos de autorización binaria y de Container Analysis en el mismo proyecto. Si ejecutas la plataforma de implementación en otro proyecto cuando configuras la autorización binaria, debes hacer referencia al proyecto de Cloud Build cuando agregues el certificador built-by-cloud-build.

Antes de comenzar

  • Para ver los metadatos generados sobre la procedencia de la compilación, haz lo siguiente:

    Habilita las API de Cloud Build, Container Analysis, and Artifact Registry.

    Habilita las API

  • Para controlar las implementaciones con la autorización binaria y ver los metadatos del certificador, sigue estos pasos:

    1. Habilita las API de Cloud Build, Binary Authorization, and Artifact Registry.

      Habilita las API

    2. Configura la autorización binaria para tu plataforma.

Ver procedencia de la compilación

En esta sección, se explica cómo ver los metadatos de procedencia de la compilación que creó Cloud Build.

Cuando compilas una imagen con Cloud Build, la procedencia de compilación de la imagen se registra de forma automática. Luego, puedes recuperar esta información para fines de auditoría. Para generar los metadatos de origen, ejecuta una compilación con Cloud Build.

Para ver los metadatos de procedencia, ejecuta el siguiente comando:

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

Reemplaza los valores de marcador de posición en el comando por los siguientes:

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

El resultado es la procedencia del contenedor, como se describe en la especificación de procedencia de SLSA. como los siguientes:

image_summary:
  digest: sha256:991ff3a4548c72e671070be2e86ff684fd0924f6b75ee60d25d85c8cdfde1293
  fully_qualified_digest: us-east1-docker.pkg.dev/PROJECT_ID/my-repo/my-image@sha256:991ff3a4548c72e671070be2e86ff684fd0924f6b75ee60d25d85c8cdfde1293
  registry: us-east1-docker.pkg.dev
  repository: my-repo
provenance_summary:
  provenance:
  - createTime: '2021-09-24T16:20:36.854156Z'
    dsseAttestation:
      envelope:
        payload: eyJfdHlwZS...
        payloadType: application/vnd.in-toto+json
        signatures:
        - keyid: projects/verified-builder/locations/global/keyRings/attestor/cryptoKeys/builtByGCB/cryptoKeyVersions/1
          sig: MEQCIHusA75t6LoyCngZ1_ACc-wWOlTThW6VKCyz75bnmSU0AiBYV50eFWQlDlp2cF-OV1u6j1_CtmrFdCNJCdyB6pYFsw==
      statement:
        predicateType: https://slsa.dev/provenance/v0.1
        provenance:
          builderConfig:
            id: https://cloudbuild.googleapis.com/Worker@v336731714
          metadata:
            buildFinishedOn: '2021-09-24T16:20:35.828284Z'
            buildInvocationId: c2f645df-f705-4aab-8d8f-ba2b1260f8ab
            buildStartedOn: '2021-09-24T16:20:23.224165401Z'
          recipe:
            arguments:
            - '@type': type.googleapis.com/google.devtools.cloudbuild.v1.BuildStep
              args:
              - build
              - --network
              - cloudbuild
              - --no-cache
              - -t
              - us-east1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag1
              ....

Si deseas verificar que los metadatos no se hayan alterado, puedes validar la procedencia mediante los siguientes pasos:

  1. Crea un directorio nuevo y ve a ese directorio.

    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. 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[0].dsseAttestation.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[0].dsseAttestation.envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin
    
  5. 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.

Controla implementaciones con la autorización binaria

En la autorización binaria, una política es un conjunto de reglas que rigen la implementación de imágenes. Puedes configurar una regla para que requiera certificaciones con firma digital.

Cloud Build genera y firma certificaciones en el momento de la compilación. Con la autorización binaria, puedes usar el certificador built-by-cloud-build para verificar las certificaciones y, luego, implementar solo imágenes compiladas por Cloud Build. El certificador built-by-cloud-build se crea la primera vez que ejecutas una compilación en un proyecto.

Para permitir que solo se implementen imágenes compiladas por Cloud Build, sigue estos pasos:

Console

  1. Ve a la página Autorización binaria (Binary Authorization) en Google Cloud Console.

    Ir a Autorización binaria.

  2. En la pestaña Política, haz clic en Editar política.

  3. En el cuadro de diálogo Editar política, selecciona Permitir solo imágenes aprobadas por todos los certificadores que se indican a continuación.

  4. Haz clic en Agregar certificadores.

  5. En el cuadro de diálogo Agregar certificadores, haz lo siguiente:

    1. Selecciona Agregar por proyecto y nombre del certificador y realiza los siguientes pasos:
      1. En el campo Project name (Nombre del proyecto), ingresa el proyecto en el que ejecutas Cloud Build.
      2. Haz clic en el campo Nombre del certificador y observa que el certificador built-by-cloud-build está disponible.
      3. Haga clic en built-by-cloud-build.
    2. Como alternativa, selecciona Agregar por ID de recurso del certificador. En ID de recurso del certificador, ingresa projects/PROJECT_ID/attestors/built-by-cloud-build y reemplaza PROJECT_ID por el proyecto en el que ejecutas Cloud Build.
  6. Haz clic en Agregar 1 certificador.

  7. Haga clic en Save Policy.

gcloud

  1. Exporta tu política existente a un archivo mediante el siguiente comando:

    gcloud container binauthz policy export > /tmp/policy.yaml
    
  2. Edita el archivo de política.

  3. Edita una de las siguientes reglas:

    • defaultAdmissionRule
    • clusterAdmissionRules
    • istioServiceIdentityAdmissionRules
    • kubernetesServiceAccountAdmissionRules
  4. Agrega un bloque requireAttestationsBy a la regla si no hay uno ya.

  5. En el bloque requireAttestationsBy, agrega projects/<var>PROJECT_ID</var>/attestors/built-by-cloud-build y reemplaza PROJECT_ID por el proyecto en el que ejecutas Cloud Build.

  6. Guarda el archivo de política.

  7. Importa el archivo de políticas.

    gcloud container binauthz policy import /tmp/policy.yaml
    

    El siguiente es un ejemplo de archivo de política que contiene la referencia a built-by-cloud-build-attestor:

    defaultAdmissionRule:
      evaluationMode: REQUIRE_ATTESTATION
      enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
      requireAttestationsBy:
        - projects/PROJECT_ID/attestors/built-by-cloud-build
    name: projects/PROJECT_ID/policy
    

    Reemplaza PROJECT_ID por el ID del proyecto en el que ejecutas Cloud Build.

Puedes ver los errores de la política en los mensajes de registro de la autorización binaria para GKE o Cloud Run.

Usa el modo de ejecución de prueba

En el modo de ejecución de prueba, la autorización binaria verifica el cumplimiento de la política sin bloquear la implementación. En cambio, los mensajes de estado del cumplimiento de políticas se registran en Cloud Logging. Puedes usar estos registros para determinar si tu política de bloqueo funciona correctamente y, también, a fin de identificar falsos positivos.

Para habilitar la ejecución de prueba, haz lo siguiente:

Console

  1. Ve a la página Autorización binaria en Google Cloud Console.

    Ir a Autorización binaria.

  2. Haz clic en Editar política.

  3. En Regla predeterminada o una regla específica, selecciona Modo de ejecución de prueba.

  4. Haga clic en Save Policy.

gcloud

  1. Exporta la política de autorización binaria a un archivo YAML:

    gcloud container binauthz policy export  > /tmp/policy.yaml
    
  2. En un editor de texto, configura enforcementMode como DRYRUN_AUDIT_LOG_ONLY y guarda el archivo.

  3. Para actualizar la política, importa el archivo mediante la ejecución del siguiente comando:

    gcloud container binauthz policy import /tmp/policy.yaml
    

Puedes ver los errores de la política en los mensajes de registro de la autorización binaria para GKE o Cloud Run.

Ver los metadatos del certificador

Los certificadores se crean la primera vez que ejecutas una compilación en un proyecto. El ID del certificador es projects/PROJECT_ID/attestors/built-by-cloud-build. Puedes verificar los metadatos del certificador de compilación mediante el siguiente comando:

curl -X GET -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://binaryauthorization.googleapis.com/v1beta1/projects/PROJECT_ID/attestors/built-by-cloud-build

Reemplaza PROJECT_ID por el proyecto en el que ejecutas Cloud Build.

El resultado contiene información sobre el certificador y las claves públicas correspondientes. Por ejemplo:

name": "projects/PROJECT_ID/attestors/built-by-cloud-build",
  "userOwnedDrydockNote": {
    "noteReference": "projects/PROJECT_ID/notes/built-by-cloud-build",
    "publicKeys": [
      {
        "id": "//cloudkms.googleapis.com/v1/projects/verified-builder/locations/asia/keyRings/attestor/cryptoKeys/builtByGCB/cryptoKeyVersions/1",
        "pkixPublicKey": {
          "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMMvFxZLgIiWOLIXsaTkjTmOKcaK7\neIZrgpWHpHziTFGg8qyEI4S8O2/2wh1Eru7+sj0Sh1QxytN/KE5j3mTvYA==\n-----END PUBLIC KEY-----\n",
          "signatureAlgorithm": "ECDSA_P256_SHA256"
        }
      },
...
      }
    ],
    "delegationServiceAccountEmail": "service-942118413832@gcp-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2021-09-24T15:26:44.808914Z",
  "description": "Attestor autogenerated by build ID fab07092-30f4-4f70-caf7-4545cbc404d6"

¿Qué sigue?