Verificar a origem da imagem

Linux

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para informações sobre o acesso a esta versão, consulte a página de solicitação de acesso.

É possível verificar os atestados 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.

Ao configurar o pipeline do Image Builder para gerar saída no Artifact Registry e ativar as opções de verificação, o Cloud Build gera automaticamente um atestado criptográfico que descreve o código-fonte exato do pipeline, as configurações, os parâmetros de execução e a imagem de base usada durante a compilação. A verificação dessa 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 Google Cloud serviços e APIs do. Para executar código ou amostras de um ambiente de desenvolvimento local, faça a autenticação no Compute Engine com uma destas opções:

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

  Console

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

  gcloud

  1. Instale a Google Cloud CLI. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando:

     gcloud init

     Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

     Observação: se você já tiver instalado a CLI gcloud, verifique se você tem a versão mais recente executando gcloud components update.
• Defina uma região e uma zona padrão.

REST

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

Instale a Google Cloud CLI.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

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

Funções exigidas

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

• Leitor do Artifact Registry (roles/artifactregistry.reader)
• Leitor do Cloud Build (roles/cloudbuild.builds.viewer)

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 com 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 procedência

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

Console (Cloud Build)

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

1. No Google Cloud console, 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 imagem. A página de detalhes do build mostra registros para as três etapas do processo (imagebuilder-customize, imagebuilder-validate e imagebuilder-publish).

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

   Observação: a guia Artefatos do build aparece apenas se você configurar um repositório do Artifact Registry. Clique no link do artefato para abrir o pacote no repositório genérico do Artifact Registry.

4. Clique na guia Anexos para visualizar os arquivos de atestado de procedência do 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 visualizar a procedência do build diretamente no Artifact Registry:

1. No Google Cloud console, 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 de 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 visualizar os arquivos de atestação de procedência do 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 procedência como arquivos anexos junto com os tarballs de imagem genéricos.

Como o atestado é formatado como um envelope de assinatura simples (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 pacote para localizar a versão específica do ID do build que você quer verificar executando o gcloud artifacts versions list comando:

   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 repositório genérico do Artifact Registry, por exemplo, custom-os-images.
   • REPOSITORY_LOCATION: a região do 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 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 seguinte comando 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, os detalhes do repositório de roteiro, as imagens de contêiner usadas, os hashes de build e os atributos da imagem de base.