Como usar a procedência assinada e a autorização binária

Nesta página, fornecemos instruções sobre como visualizar metadados de procedência e criar implantações com o Cloud Build.

A procedência do build é uma coleção de dados verificáveis sobre um build executado pelo Cloud Build. Os metadados de procedência incluem detalhes como os resumos das imagens criadas, os locais da origem de entrada, os argumentos da compilação e a duração da compilação.

Para proteger sua cadeia de suprimentos de software, o Cloud Build registra metadados de procedência e cria atestados para imagens de contêiner no momento da criação. É possível usar os metadados de procedência para fins de auditoria e usar os atestados para controlar implantações com a autorização binária.

Limitações

O Cloud Build gera todos os recursos de autorização binária e Container Analysis no mesmo projeto. Se você executar a plataforma de implantação em outro projeto, ao configurar a autorização binária, consulte o projeto do Cloud Build ao adicionar o atestador built-by-cloud-build.

Antes de começar

  • Para ver os metadados gerados sobre a procedência da versão:

    Ative as APIs Cloud Build, Container Analysis, and Artifact Registry.

    Ative as APIs

  • Para controlar implantações com a autorização binária e ver os metadados do atestador:

    1. Ative as APIs Cloud Build, Binary Authorization, and Artifact Registry.

      Ative as APIs

    2. Configure a autorização binária na sua plataforma.

Ver a procedência do build

Nesta seção, explicamos como ver os metadados de procedência de compilação criados pelo Cloud Build.

Quando você cria uma imagem com o Cloud Build, a procedência de compilação da imagem é registrada automaticamente. É possível buscar essas informações posteriormente para fins de auditoria. Para gerar os metadados de procedência, execute um build com o Cloud Build.

Para ver os metadados de procedência, execute o seguinte comando:

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

Substitua os valores de marcador no comando pelo seguinte:

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

A saída é a procedência do contêiner, conforme descrito na especificação da procedência do SLSA. Por exemplo:

image_summary:
  digest: sha256:991ff3a4548c72e671070be2e86ff684fd0924f6b75ee60d25d85c8cdfde1293
  fully_qualified_digest: us-east1-docker.pkg.dev/PROJECT_ID/my-repo/my-image@sha256:991ff3a4548c72e671070be2e86ff684fd0924f6b75ee60d25d85c8cdfde1293
  registry: us-east1-docker.pkg.dev
  repository: my-repo
provenance_summary:
  provenance:
  - createTime: '2021-09-24T16:20:36.854156Z'
    dsseAttestation:
      envelope:
        payload: eyJfdHlwZS...
        payloadType: application/vnd.in-toto+json
        signatures:
        - keyid: projects/verified-builder/locations/global/keyRings/attestor/cryptoKeys/builtByGCB/cryptoKeyVersions/1
          sig: MEQCIHusA75t6LoyCngZ1_ACc-wWOlTThW6VKCyz75bnmSU0AiBYV50eFWQlDlp2cF-OV1u6j1_CtmrFdCNJCdyB6pYFsw==
      statement:
        predicateType: https://slsa.dev/provenance/v0.1
        provenance:
          builderConfig:
            id: https://cloudbuild.googleapis.com/Worker@v336731714
          metadata:
            buildFinishedOn: '2021-09-24T16:20:35.828284Z'
            buildInvocationId: c2f645df-f705-4aab-8d8f-ba2b1260f8ab
            buildStartedOn: '2021-09-24T16:20:23.224165401Z'
          recipe:
            arguments:
            - '@type': type.googleapis.com/google.devtools.cloudbuild.v1.BuildStep
              args:
              - build
              - --network
              - cloudbuild
              - --no-cache
              - -t
              - us-east1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag1
              ....

Se você quiser verificar se os metadados não foram adulterados, valide a procedência executando as seguintes etapas:

  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[0].dsseAttestation.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 | jq -r '.provenance_summary.provenance[0].dsseAttestation.envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin
    
  5. 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.

Controlar implantações com autorização binária

Uma política na autorização binária é um conjunto de regras que regem a implantação de imagens. É possível configurar uma regra para exigir atestados assinados digitalmente.

O Cloud Build gera e assina atestados no momento da criação. Com a autorização binária, é possível usar o atestador built-by-cloud-build para verificar os atestados e implantar apenas imagens criadas pelo Cloud Build. O atestador built-by-cloud-build é criado na primeira vez que você executa um build em um projeto.

Para permitir que apenas as imagens criadas pelo Cloud Build sejam implantadas, execute as seguintes etapas:

Console

  1. Acesse a página Autorização binária no Console do Google Cloud.

    Acesse Autorização binária.

  2. Na guia Política, clique em Editar política.

  3. Na caixa de diálogo Editar política, selecione Permitir apenas imagens que tenham sido aprovadas por todos os seguintes atestadores.

  4. Clique em Adicionar atestadores.

  5. Na caixa de diálogo Adicionar atestadores, faça o seguinte:

    1. Selecione Adicionar por projeto e nome do atestador e execute as seguintes etapas:
      1. No campo Nome do projeto, insira o projeto em que você executa o Cloud Build.
      2. Clique no campo Nome do atestador e observe que o atestador built-by-cloud-build está disponível.
      3. Clique em built-by-cloud-build.
    2. Como alternativa, selecione Adicionar por código do recurso de atestador. Em ID de recurso do atestador, insira projects/PROJECT_ID/attestors/built-by-cloud-build, substituindo PROJECT_ID pelo projeto em que o Cloud Build é executado.
  6. Clique em Add attestor.

  7. Clique em Save Policy.

gcloud

  1. Exporte a política existente para um arquivo usando o seguinte comando:

    gcloud container binauthz policy export > /tmp/policy.yaml
    
  2. Edite o arquivo da política.

  3. Edite uma das seguintes regras:

    • defaultAdmissionRule
    • clusterAdmissionRules
    • istioServiceIdentityAdmissionRules
    • kubernetesServiceAccountAdmissionRules
  4. Adicione um bloco requireAttestationsBy à regra, se ainda não houver um.

  5. No bloco requireAttestationsBy, adicione projects/<var>PROJECT_ID</var>/attestors/built-by-cloud-build, substituindo PROJECT_ID pelo projeto em que o Cloud Build é executado.

  6. Salve o arquivo de política.

  7. Importe o arquivo de política.

    gcloud container binauthz policy import /tmp/policy.yaml
    

    Veja a seguir um exemplo de arquivo de política que contém a referência ao built-by-cloud-build-attestor:

    defaultAdmissionRule:
      evaluationMode: REQUIRE_ATTESTATION
      enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
      requireAttestationsBy:
        - projects/PROJECT_ID/attestors/built-by-cloud-build
    name: projects/PROJECT_ID/policy
    

    Substitua PROJECT_ID pelo ID do projeto em que você executa o Cloud Build.

É possível ver os erros de política nas mensagens do registro de autorização binária para GKE ou Cloud Run.

Como usar o modo de simulação

No modo de simulação, a autorização binária verifica a conformidade da política sem realmente bloquear a implantação. Em vez disso, as mensagens de status de conformidade com a política são registradas no Cloud Logging. É possível usar esses registros para determinar se a política de bloqueio está funcionando corretamente e identificar falsos positivos.

Para ativar a simulação, faça o seguinte:

Console

  1. Acesse a página "Autorização binária" no Console do Google Cloud.

    Acesse Autorização binária.

  2. Clique em Editar política.

  3. Em Regra padrão ou em uma regra específica, selecione Modo de teste.

  4. Clique em Save Policy.

gcloud

  1. Exporte a política de autorização binária para um arquivo YAML:

    gcloud container binauthz policy export  > /tmp/policy.yaml
    
  2. Em um editor de texto, defina enforcementMode como DRYRUN_AUDIT_LOG_ONLY e salve o arquivo.

  3. Para atualizar a política, importe o arquivo executando o seguinte comando:

    gcloud container binauthz policy import /tmp/policy.yaml
    

É possível ver os erros de política nas mensagens do registro de autorização binária para GKE ou Cloud Run.

Ver metadados do atestador

Um atestador é criado na primeira vez que você executa um build em um projeto. O ID do atestador é projects/PROJECT_ID/attestors/built-by-cloud-build. Verifique os metadados do atestador de compilação usando o seguinte comando:

curl -X GET -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://binaryauthorization.googleapis.com/v1beta1/projects/PROJECT_ID/attestors/built-by-cloud-build

Substitua PROJECT_ID pelo projeto em que você executa o Cloud Build.

A saída contém informações sobre o atestador e as chaves públicas correspondentes. Exemplo:

name": "projects/PROJECT_ID/attestors/built-by-cloud-build",
  "userOwnedDrydockNote": {
    "noteReference": "projects/PROJECT_ID/notes/built-by-cloud-build",
    "publicKeys": [
      {
        "id": "//cloudkms.googleapis.com/v1/projects/verified-builder/locations/asia/keyRings/attestor/cryptoKeys/builtByGCB/cryptoKeyVersions/1",
        "pkixPublicKey": {
          "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMMvFxZLgIiWOLIXsaTkjTmOKcaK7\neIZrgpWHpHziTFGg8qyEI4S8O2/2wh1Eru7+sj0Sh1QxytN/KE5j3mTvYA==\n-----END PUBLIC KEY-----\n",
          "signatureAlgorithm": "ECDSA_P256_SHA256"
        }
      },
...
      }
    ],
    "delegationServiceAccountEmail": "service-942118413832@gcp-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2021-09-24T15:26:44.808914Z",
  "description": "Attestor autogenerated by build ID fab07092-30f4-4f70-caf7-4545cbc404d6"

A seguir