Gerar e validar a procedência do build

Esta página fornece instruções sobre como gerar a procedência do build, consulte a o resultado e validá-lo.

A procedência do build é uma coleção de dados verificáveis sobre um build. Os metadados de procedência incluem detalhes como os resumos das imagens criadas, os locais de origem de entrada, os argumentos e a duração do build. É possível usar essas informações para garantir que os artefatos criados que você está usando sejam exatos e confiáveis, criados por fontes e desenvolvedores confiáveis.

O Cloud Build oferece suporte à geração de procedências de build que atendam Garantia de nível 3 da cadeia de suprimentos para artefatos de software (SLSA) com base no especificações para a versão 0.1 da SLSA e 1,0.

Como parte da compatibilidade com a especificação SLSA v1.0, o Cloud Build fornece detalhes de buildType na procedência do build. É possível usar o esquema buildType para entender o modelo parametrizado usado no processo de build, incluindo os valores registrados pelo Cloud Build e a origem desses valores. Para mais informações, consulte buildType v1 do Cloud Build.

Limitações

• O Cloud Build só gera a procedência de build para artefatos armazenados no Artifact Registry.
• Para ter a procedência do SLSA v1.0 e v0.1, você precisa criar usando acionadores. Se você iniciar um build manualmente, usando o método gcloud CLI, o Cloud Build fornece apenas procedência do SLSA v0.1.

Antes de começar

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

   Enable the APIs

2. Para usar os exemplos de linha de comando neste guia, instale e configure o SDK Google Cloud.

   Observação: se você já instalou o SDK Google Cloud, verifique se tem a versão mais recente disponível executando gcloud components update.

3. Tenha o código-fonte à mão.

4. Ter um repositório no Artifact Registry.

Gerar a procedência do build

As instruções a seguir explicam como gerar a procedência do build para imagens de contêiner armazenadas no Artifact Registry:

1. No arquivo de configuração do build, adicione o campo images para configurar Cloud Build para armazenar as imagens criadas no Artifact Registry após a conclusão do build.

   O Cloud Build não poderá gerar procedência se você enviar a imagem ao Artifact Registry usando uma etapa docker push explícita.

   O snippet a seguir mostra uma configuração de build para criar uma imagem de contêiner e armazená-la em um repositório do Docker no 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']
   

   Em que:

   • LOCATION: o local regional ou multirregional do repositório.
   • PROJECT_ID: é seu ID do projeto no Google Cloud.
   • REPOSITORY: o nome do repositório do Artifact Registry
   • IMAGE: o nome da imagem do contêiner.

   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"
     ]
     }
   

   Em que:

   • LOCATION: o local regional ou multirregional. para seu repositório.
   • PROJECT_ID: é seu ID do projeto no Google Cloud.
   • REPOSITORY: o nome do repositório do Artifact Registry
   • IMAGE: o nome da imagem do contêiner.

2. Na seção options da configuração do build, adicione o a opção requestedVerifyOption e definida com o valor VERIFIED.

   Essa configuração ativa a geração de procedências e configura o Cloud Build para verificar se os metadados de procedência estão presentes. Construções só será marcado como bem-sucedido se a procedência for gerada.

   YAML

   options:
     requestedVerifyOption: VERIFIED
   

   JSON

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

3. Comece o build.

Ver a origem do build

Nesta seção, explicamos como ver os metadados de procedência do build criados pelo Cloud Build. É possível buscar essas informações para fins de auditoria.

É possível acessar os metadados de origem do build para contêineres usando o painel lateral Security insights no console do Google Cloud ou a CLI gcloud.

Console

O painel lateral Insights de segurança oferece uma visão geral de alto nível dos informações de artefatos armazenados no Artifact Registry.

Para acessar o painel Insights de segurança:

1. Abra a página Histórico de builds no console do Google Cloud:

   Abrir a página "Histórico de criações"

2. Selecione o projeto e clique em Abrir.

3. No menu suspenso Região, selecione a região em que você executou ser construído.

4. Na tabela com os builds, localize a linha com o build para o qual você querem acessar insights de segurança.

5. Na coluna Insights de segurança, clique em Visualizar.

   O painel Insights de segurança do artefato selecionado é exibido.

   O card Build mostra detalhes de origem e um link. Você pode consultar o snippet de procedência clicando no ícone de link.

Para saber mais sobre o painel lateral e como usar o Cloud Build para para proteger a cadeia de suprimentos de software, consulte Acessar insights de segurança do build.

CLI da gcloud

Para visualizar os metadados de procedência das imagens de contêiner, execute o seguinte comando:

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

Substitua:

• LOCATION: o local regional ou multirregional do repositório.
• PROJECT_ID: é seu ID do projeto no Google Cloud.
• REPOSITORY: o nome do repositório do Artifact Registry.
• IMAGE: o nome da imagem do contêiner.
• HASH: o valor de hash sha256 da imagem. Você pode encontrar isso na saída do build.
• FORMAT: uma configuração opcional em que é possível especificar um formato de saída.

Exemplo de saída

A procedência do build é semelhante a esta:

      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'
    

Alguns pontos importantes a serem observados neste exemplo:

• Origem: o build foi acionado em um repositório do GitHub.

• Referência de objeto: os campos denominados digest e fileHash se referem ao mesmo objeto. O campo digest incluído na saída de exemplo é codificado na base 16 (codificado em hexadecimal). Se você estiver usando a procedência da SLSA versão 0.1, seu A saída usa o campo fileHash codificado em base 64.

• Assinaturas: se você estiver usando a procedência da SLSA versão 0.1, sua saída contém duas assinaturas no campo envelope. A primeira assinatura, que tem o nome de chave provenanceSigner, usa uma assinatura conforme DSSE (formatada com codificação pré-autenticação (PAE)), que pode ser verificada em políticas de autorização binária. Recomendamos que você use esta assinatura em novos usos do procedência. A segunda assinatura, que tem o nome de chave builtByGCB, é fornecida para uso legado.

• Contas de serviço: as assinaturas que são incluídas automaticamente nos A procedência do Cloud Build ajuda a verificar o serviço de build executou um build. Também é possível configurar o Cloud Build para gravar metadados verificáveis sobre a conta de serviço usada para iniciar um build. Para mais informações, consulte Assinar imagens de contêiner com cosign.

• Payload: o exemplo de origem mostrado nesta página é abreviado para facilitar a leitura. A saída real será mais longa, porque o payload é uma versão codificada em base64 de todos os metadados de procedência.

Conferir a procedência dos artefatos que não são de contêiner

O Cloud Build gera a procedência da SLSA metadados para aplicativos autônomos Java (Maven), Python e Node.js (npm) quando você faz upload dos artefatos do build para o Artifact Registry. Você pode recuperar o os metadados de procedência fazendo uma chamada direta à API.

1. Para gerar os metadados de procedência dos artefatos, execute um build com o Cloud Build. Use um dos seguintes guias:

   • Criar aplicativos Java independentes
   • Criar aplicativos Python independentes
   • Crie aplicativos Node.js independentes

   Quando o build for concluído, observe o BuildID.

2. Recupere metadados de procedência executando a seguinte chamada de API no seu terminal, em que PROJECT_ID é o ID associado à seu projeto do Google Cloud:

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

   É necessário usar uma chamada de API para acessar os metadados de procedência desse tipo. de artefato. Os metadados de origem de artefatos que não são de contêiner não são exibidos no console do Google Cloud nem acessíveis pela CLI gcloud.

3. Nas ocorrências do seu projeto, pesquise por BuildID para encontrar as informações de procedência associadas a um artefato de build.

Validar procedência

Nesta seção, explicamos como validar a procedência do build para imagens de contêiner.

A validação da origem do build ajuda você a:

• confirmar se os artefatos de build estão sendo gerados de fontes e builders confiáveis
• garantir que os metadados de procedência que descrevem seu processo de build sejam completos e autênticos

Para mais informações, consulte Proteger builds.

Validar a procedência usando o verificador da SLSA

O verificador SLSA é uma ferramenta da CLI de código aberto para validando a integridade do build com base nas especificações de SLSA.

Se o verificador encontrar problemas, ele vai retornar mensagens de erro detalhadas para ajudar você atualizar seu processo de build e mitigar riscos.

Para usar o verificador SLSA:

1. Instale a versão 2.1 ou mais recente do repositório slsa-verifier:

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

2. Na CLI, defina uma variável para o identificador de imagem:

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

   Substitua os valores de marcador no comando pelo seguinte:

   • LOCATION: local regional ou multirregional.
   • PROJECT_ID: ID do projeto do Google Cloud
   • REPOSITORY: nome do repositório.
   • IMAGE: nome da imagem.
   • HASH: o valor de hash sha256 da imagem. Você pode encontrar isso na saída do build.

3. Autorize a gcloud CLI para que o verificador de SLSA possa acessar seus dados de procedência:

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

4. Extraia a procedência da imagem e armazene-a como JSON:

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

5. Verifique a procedência:

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

   Em que:

   • SOURCE é o URI do repositório de origem da imagem; por exemplo, github.com/my-repo/my-application.
   • BUILDER_ID: o ID exclusivo do builder, por exemplo, https://cloudbuild.googleapis.com/GoogleHostedWorker

   Se você quiser imprimir a procedência validada para uso em um mecanismo de políticas, use o comando anterior com a flag --print-provenance.

   O resultado será parecido com este: PASSED: Verified SLSA provenance ou FAILED: SLSA verification failed: <error details>.

Para mais informações sobre sinalizações opcionais, consulte opções.

Validar metadados de procedência com a CLI gcloud

Se você quiser verificar se os metadados de procedência do build não foram adulterados, siga estas etapas para validar a procedência:

1. Crie um novo diretório e acesse-o.

   mkdir provenance && cd provenance
   

2. Usando as informações do campo keyid, acesse a chave 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. O payload contém a representação JSON da procedência, codificada em base64url. Decodifique os dados e armazene-os em um arquivo.

   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
   

   Os tipos de origem da SLSA versão 0.1 e 1.0 são armazenados quando disponíveis. Se você quer filtrar pela versão 1.0, mude o predicateType para usar https://slsa.dev/provenance/v1. Exemplo:

   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. O envelope também contém a assinatura sobre a procedência. Decodifique os dados e armazene-os em um arquivo.

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

   Se você quiser filtrar pela versão 1.0, mude o predicateType para usar https://slsa.dev/provenance/v1. Exemplo:

   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. O comando acima faz referência à primeira assinatura de procedência (.provenance_summary.provenance[0].envelope.signatures[0]), assinada pela chave provenanceSigner. O payload é assinado sobre o envelope formatado em PAE. Para verificá-lo, execute este comando e transforme a procedência no formato PAE esperado de "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body.

   Observação: se você estiver verificando a segunda assinatura (.provenance_summary.provenance[0].envelope.signatures[1].sig com o nome da chave builtByGCB), pule esta etapa e verifique o arquivo provenance.json que você já armazenou.

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

6. Valide a assinatura.

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

   Após a validação, a saída é Verified OK.

A seguir

• Configurar o Cloud Build para acompanhar quem inicia um build
• Usar a verificação de vulnerabilidades no pipeline do Cloud Build
• Saiba mais sobre o Software Delivery Shield