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. Você pode use essas informações para garantir que os artefatos criados precisos e confiáveis, criados por criadores e fontes 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 do suporte para a especificação SLSA v1.0, o Cloud Build oferece
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 Cloud Build buildType v1.
Limitações
- O Cloud Build só gera procedência do 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
-
Ative as APIs Cloud Build, Container Analysis, and Artifact Registry.
Para usar os exemplos de linha de comando neste guia, instale e configure o SDK Google Cloud.
Tenha o código-fonte em mãos.
Ter um repositório no Artifact Registry.
Gerar 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:
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 e armazene a imagem 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. para seu repositório.PROJECT_ID
: é seu ID do projeto no Google Cloud.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. para seu repositório.PROJECT_ID
: é seu ID do projeto no Google Cloud.REPOSITORY
: o nome do repositório do Artifact RegistryIMAGE
: o nome da imagem do contêiner.
Na seção
options
da configuração do build, adicione o a opçãorequestedVerifyOption
e definida com o valorVERIFIED
.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" } }
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 metadados de procedência de 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 Insights de segurança oferece uma visão geral de alto nível dos informações de artefatos armazenados no Artifact Registry.
Para ver o painel Insights de segurança, faça o seguinte:
Abra a página Histórico de builds 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 ser construído.
Na tabela com os builds, localize a linha com o build para o qual você querem acessar insights de segurança.
Na coluna Insights de segurança, clique em Visualizar.
O painel Insights de segurança do artefato selecionado é exibido.
O card Build mostra detalhes da procedência e um link. Você pode ver 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 de seu repositório.PROJECT_ID
: é seu ID do projeto no Google Cloud.REPOSITORY
: o nome do Artifact Registry. repositório de dados.IMAGE
: o nome da imagem do contêiner.HASH
: o valor de hash sha256 da imagem. Você pode encontrar isso na saída do seu 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:
Referência de objeto: os campos denominados
digest
efileHash
se referem ao mesmo objeto. O campodigest
incluído na saída de exemplo é codificado em base 16 (codificada em hexadecimal). Se você estiver usando a procedência da SLSA versão 0.1, seu A saída usa o campofileHash
codificado em base 64.Assinaturas: se você estiver usando a procedência da SLSA versão 0.1, seu resultado contém duas assinaturas no campo
envelope
. A primeira assinatura, que tem o nome de chaveprovenanceSigner
, usa uma Assinatura em conformidade com o DSSSE (formatado com Codificação de pré-autenticação (PAE), que pode ser verificada Autorização binária políticas. Recomendamos que você use esta assinatura em novos usos do procedência. A segunda assinatura, que tem o nome de chavebuiltByGCB
, é fornecidas 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: a procedência de exemplo exibida nesta página foi encurtada. para facilitar a leitura. A saída real será mais longa, já que o payload é um valor de base64 codificada 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.
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
.Execute a seguinte chamada de API no terminal, em que PROJECT_ID é o ID associado à sua 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'
Nas ocorrências do seu projeto, pesquise por
BuildID
para encontrar as informações de procedência associadas a cada artefato de compilação.
Validar procedência
Nesta seção, explicamos como validar a procedência do build para imagens de contêiner.
Validar a procedência do build ajuda você a:
- confirmar se os artefatos de build estão sendo gerados a partir de fontes confiáveis e construtores
- garanta que os metadados de procedência que descrevem o processo de build estejam completos e autênticos
Para mais informações, consulte Proteger builds.
Validar a procedência usando o verificador de 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:
Instale a versão 2.1 ou mais recente pelo 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 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 CloudREPOSITORY
: nome do repositório.IMAGE
: nome da imagem.HASH
: o valor de hash sha256 da imagem. Você pode encontre isso na saída do seu build.
Autorize a CLI gcloud para que o verificador de SLSA possa acessar os dados de procedência:
gcloud auth configure-docker LOCATION-docker.pkg.dev
Recupere 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, para exemplo dehttps://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 sinalização
--print-provenance
.A saída será semelhante a esta:
PASSED: Verified SLSA provenance
ouFAILED: 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 da procedência do build não foram adulterados você pode validar a procedência executando as seguintes etapas:
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 procedência do SLSA versões 0.1 e 1.0 são armazenados quando disponíveis. Se você quer filtrar pela 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 pela 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 procedência (
.provenance_summary.provenance[0].envelope.signatures[0]
), assinada pela chaveprovenanceSigner
. O payload é assinado sobre o envelope no formato 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
.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 rastrear quem inicia um build
- Usar a verificação de vulnerabilidades no pipeline do Cloud Build
- Saiba mais sobre o Software Delivery Shield