Nesta página, fornecemos instruções sobre como gerar a procedência do build, visualizar a saída e validar.
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 da 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ência de build que atende à garantia de nível 3 do Supply-chain Levels for Software Artifacts (SLSA) com base nas especificações da versão 0.1 e 1.0 do SLSA.
Como parte do suporte à especificação SLSA v1.0, o Cloud Build fornece
detalhes de buildType
na procedência do build. Use o esquema buildType
para entender o modelo parametrizado usado para o 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 receber a procedência do SLSA v1.0 e v0.1, é necessário criar usando gatilhos. Se você iniciar um build manualmente usando a CLI gcloud, o Cloud Build vai fornecer apenas a proveniência da SLSA v0.1.
Antes de começar
-
Enable the Cloud Build, Container Analysis, and Artifact Registry APIs.
Para usar os exemplos de linha de comando deste guia, instale e configure o SDK do Google Cloud.
Tenha o código-fonte em mãos.
Ter um repositório no Artifact Registry.
Gerar a procedência do build
As instruções a seguir explicam como gerar a procedência de build para imagens de contêiner armazenadas no Artifact Registry:
No arquivo de configuração do build, adicione o campo
images
para configurar o Cloud Build para armazenar as imagens criadas no Artifact Registry após a conclusão do build.O Cloud Build não pode gerar a procedência se você enviar a imagem para o 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
: o ID do Google Cloud projeto.REPOSITORY
: o nome do repositório do Artifact RegistryIMAGE
: 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 do repositório.PROJECT_ID
: o ID do Google Cloud projeto.REPOSITORY
: o nome do repositório do Artifact RegistryIMAGE
: o nome da imagem do contêiner.
Na seção
options
da configuração de build, adicione a opçãorequestedVerifyOption
e defina o valor comoVERIFIED
.Essa configuração ativa a geração de procedência e configura o Cloud Build para verificar se os metadados de procedência estão presentes. Os builds só serão marcados como bem-sucedidos se a procedência for gerada.
YAML
options: requestedVerifyOption: VERIFIED
JSON
{ "options": { "requestedVerifyOption": "VERIFIED" } }
Inicie a 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 procedência do build para contêineres usando o painel lateral Insights de segurança no console do Google Cloud ou a CLI gcloud.
Console
O painel lateral Security insights fornece uma visão geral de alto nível das informações de segurança para artefatos armazenados no Artifact Registry.
Para acessar o painel Insights de segurança:
Abra a página Histórico do build no console do Google Cloud:
Selecione o projeto e clique em Abrir.
No menu suspenso Região, selecione a região em que você executou o build.
Na tabela com os builds, localize a linha com o build em que você quer conferir insights de segurança.
Na coluna Insights de segurança, clique em Visualizar.
O painel Insights de segurança é exibido para o artefato selecionado.
O card Build mostra detalhes de origem e um link. Para conferir o snippet de procedência, clique no ícone de link.
Para saber mais sobre o painel lateral e como usar o Cloud Build para ajudar a proteger sua cadeia de suprimentos de software, consulte Conferir insights de segurança do build.
CLI da gcloud
Para conferir 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
: o ID do Google Cloud projeto.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 você pode 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:
Referência de objeto: os campos com os nomes
digest
efileHash
se referem ao mesmo objeto. O campodigest
incluído na saída de exemplo é codificado na base 16 (codificado em hexadecimal). Se você estiver usando a origem da versão 0.1 da SLSA, a saída vai usar o campofileHash
codificado em base 64.Assinaturas: se você estiver usando a origem da versão 0.1 da SLSA, a saída terá duas assinaturas no campo
envelope
. A primeira assinatura, que tem o nome de chaveprovenanceSigner
, 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 essa assinatura em novos usos dessa providência. A segunda assinatura, que tem o nome de chavebuiltByGCB
, é fornecida para uso legado.Contas de serviço: as assinaturas que são incluídas automaticamente na prova de origem do Cloud Build ajudam a verificar o serviço de build que executou um build. Também é possível configurar o Cloud Build para registrar 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 coassinatura.
Payload: o exemplo de procedência 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 origem de artefatos sem contêiner
O Cloud Build gera metadados de procedência de SLSA para aplicativos independentes de Go, Java (Maven), Python e Node.js (npm) quando você faz upload dos artefatos de build para o Artifact Registry. É possível recuperar os metadados de procedência fazendo uma chamada direta de API.
Para gerar os metadados de procedência dos seus artefatos, execute um build com o Cloud Build. Use um dos seguintes guias:
- Criar aplicativos Go independentes
- Criar aplicativos Java independentes
- Criar aplicativos Python independentes
- Criar aplicativos Node.js independentes
Quando o build for concluído, anote o
BuildID
.Extraia metadados de procedência executando a seguinte chamada de API no terminal, em que PROJECT_ID é o ID associado ao projeto 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 procedência 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.
Nas ocorrências do seu projeto, pesquise por
BuildID
para encontrar as informações de procedência associadas a um artefato de build.
Validar a procedência
Esta seção explica 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 do SLSA é uma ferramenta de CLI de código aberto para validar a integridade do build com base nas especificações do SLSA.
Se o verificador encontrar problemas, ele retornará mensagens de erro detalhadas para ajudar você a atualizar o processo de build e reduzir os riscos.
Para usar o verificador da SLSA:
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
Na CLI, defina uma variável para o identificador da 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 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.
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
Extraia a procedência da imagem e armazene-a como
JSON
:gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.json
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
ouFAILED: SLSA verification failed: <error details>
.
Para mais informações sobre as flags 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:
Crie um novo diretório e acesse-o.
mkdir provenance && cd provenance
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
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 0.1 e 1.0 são armazenados quando disponíveis. Se você quiser filtrar a versão 1.0, mude o
predicateType
para usarhttps://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
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 a versão 1.0, mude o
predicateType
para usarhttps://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
O comando acima faz referência à primeira assinatura de origem (
.provenance_summary.provenance[0].envelope.signatures[0]
), que é assinada pela chaveprovenanceSigner
. O payload é assinado sobre o envelope formatado em PAE. Para verificar isso, execute este comando para transformar a procedência no formato de 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
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 a segurança da cadeia de suprimentos de software