Verificar a origem da imagem

É possível verificar as atestações de procedência do build do SLSA (Níveis da cadeia de suprimentos para artefatos de software) para suas imagens de SO personalizadas e garantir a integridade da cadeia de suprimentos de software.

Quando você configura seu pipeline do Image Builder para gerar saída no Artifact Registry e ativa as opções de verificação, o Cloud Build gera automaticamente uma atestação criptográfica que descreve o código-fonte, as configurações, os parâmetros de execução e a imagem de base exatos usados durante a compilação. A verificação da procedência do build confirma que pipelines confiáveis criaram suas imagens com segurança, sem adulteração não autorizada.

Antes de começar

  • Conclua as etapas de configuração do ambiente em Preparar o ambiente.
  • Configure a autenticação, caso ainda não tenha feito isso. Com isso, você confirma sua identidade para acesso a serviços e APIs do Cloud de Confiance by S3NS . Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:

    Selecione a guia para como planeja usar as amostras nesta página:

    Console

    Quando você usa o console Cloud de Confiance para acessar serviços Cloud de Confiance by S3NS e APIs, não é necessário configurar a autenticação.

    gcloud

    1. Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

      gcloud init
  • Defina uma região e uma zona padrão.

    • REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada.

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Cloud de Confiance .

Funções exigidas

Para ter as permissões necessárias para visualizar e verificar atestados de procedência de build, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Configurar a geração de procedência

Para gerar a procedência do build, configure os blocos substitutions, options, results e artifacts no arquivo cloudbuild.yaml conforme mostrado no snippet a seguir:

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

Verificar dados de origem

É possível conferir e verificar os dados de procedência do build e os artefatos de execução usando o console Cloud de Confiance ou a Google Cloud CLI:

Console (Cloud Build)

Para conferir a procedência do build e os artefatos de saída no histórico de builds do Cloud Build:

  1. No console Cloud de Confiance , acesse a página Cloud Build.

    Acessar o Cloud Build

  2. Clique em Histórico e selecione o ID do build para a execução do pipeline de imagens. A página de detalhes do build mostra os registros das três etapas do processo (imagebuilder-customize, imagebuilder-validate e imagebuilder-publish).

  3. Clique na guia Artefatos de build para conferir a imagem exata do SO criada durante a execução.

  4. Clique na guia Anexos para conferir os arquivos de atestado de procedência SLSA assinados e os arquivos de resultados. O arquivo de resultados registra a imagem de base de origem usada durante a execução.

Console (Artifact Registry)

Para ver a procedência do build diretamente no Artifact Registry:

  1. No console do Cloud de Confiance , acesse a página Artifact Registry.

    Acessar o Artifact Registry

  2. Na lista de repositórios, clique no nome do repositório genérico.

  3. Na lista de pacotes, clique no nome do pacote da imagem do SO.

  4. Na lista de histórico de versões, clique no ID da versão (v${BUILD_ID}) da execução do pipeline.

  5. Clique na guia Anexos para conferir os arquivos de atestado de procedência SLSA assinados e os arquivos de resultados dessa versão de imagem. O arquivo de resultados registra a imagem de origem de base usada durante a execução.

gcloud

O Artifact Registry armazena registros de origem como arquivos anexos junto com os tarballs de imagens genéricas.

Como o atestado é formatado como um envelope de assinatura Dead Simple (DSSE, na sigla em inglês), o payload da declaração de procedência real dentro do JSON é codificado em base64. Para ler os detalhes, siga estas etapas usando a CLI gcloud e o utilitário jq:

  1. Liste as versões do seu pacote para localizar a versão específica do ID de build que você quer verificar executando o comando gcloud artifacts versions list:

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

    Substitua:

    • PACKAGE_NAME: o nome do pacote no repositório do Artifact Registry, por exemplo, my-custom-image.
    • REPOSITORY_NAME: o nome do seu repositório genérico do Artifact Registry, por exemplo, custom-os-images.
    • REPOSITORY_LOCATION: a região do seu repositório, por exemplo, us-central1.
    • PROJECT_ID: o ID do projeto.

  2. Consulte os metadados dos anexos que correspondem à versão do pacote de destino executando o comando gcloud artifacts attachments list:

    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

    Substitua BUILD_ID pelo identificador de versão retornado na etapa 1, por exemplo, 12345.

    Na resposta ao comando, localize a entrada de anexo cujo campo name contém build-result (com type: application/vnd.in-toto+json) e copie o caminho listado em files:, por exemplo:

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

  3. Faça o download do payload do anexo de metadados JSON do seu repositório executando o comando gcloud artifacts files download:

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

    Substitua ATTACHMENT_FILE_ID pelo caminho do anexo files: recuperado na etapa anterior.

  4. Execute o comando a seguir para isolar, decodificar em base64 e formatar o conteúdo do payload JSON:

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

    A saída contém parâmetros de formato SLSA padrão que destacam o gatilho de compilação, detalhes do repositório de receitas, imagens de contêiner usadas, hashes de build e atributos de imagem base.