Criar atestados com o Coupon

Neste tutorial, descrevemos como configurar e usar um Cupom para criar atestados de autorização binária.

Visão geral do Cupom

O Cupom é uma ferramenta de código aberto que executa um conjunto de verificações nas imagens de contêiner antes de criar atestados de autorização binária para as imagens. O cupom tem um cliente e um componente do servidor. O cliente de cupons é executado como uma etapa extra no pipeline de criação, após a etapa de criação da imagem. Quando a etapa de criação do cliente de cupons é executada, ele envia a imagem ao servidor de cupons, que executa as verificações. Você define quais verificações serão executadas, além de outros critérios, no arquivo de configuração do servidor de cupons.

Neste tutorial, mostramos como usar a verificação de Cupom snakeoil para testar se há vulnerabilidades em imagens. Para ativar a verificação no arquivo de configuração, configure a opção fail-on como um limite de vulnerabilidade, conforme mostrado mais adiante neste tutorial.

Depois que a verificação de snakeoil for concluída, se todas as vulnerabilidades identificadas estiverem abaixo do limite, o servidor do cupom criará o atestado de autorização binária para a imagem. Se qualquer uma das vulnerabilidades identificadas atingir ou exceder o limite, o servidor do cupom não criará um atestado.

No momento da implantação da imagem do contêiner, sem um atestado verificado, o aplicador de autorização binária não permitirá que ela seja implantada.

Observação: neste tutorial, você criará o servidor do cupom e o implantará no Cloud Run. Mas se preferir hospedar um servidor do cupom pré-criado no Google Kubernetes Engine (GKE), ele também estará disponível como um contêiner click-to-deploy no Google Cloud Marketplace. Para mais informações, consulte Como executar o servidor de cupons no GKE.

Objetivos

Neste guia, você irá:

1. Configurar o servidor de cupons no Cloud Run.
2. Configurar o cliente de cupons.
3. Usará o cupom em exemplos de pipeline de criação.

Custos

Neste guia, usamos os seguintes produtos do Google Cloud.

• Container Registry
• Artifact Analysis
• Cloud Build
• Cloud Key Management Service
• Cloud Run

Use a Calculadora de preços para gerar uma estimativa de custo com base no uso previsto.

Antes de começar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. Enable the Cloud Build, Container Registry, Artifact Analysis, Cloud KMS, Cloud Run, and Identity and Access Management APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

9. Enable the Cloud Build, Container Registry, Artifact Analysis, Cloud KMS, Cloud Run, and Identity and Access Management APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

12. Recomendamos que você configure a autorização binária com o Google Kubernetes Engine. Neste tutorial, descrevemos como criar um atestado. Para usar a aplicação no momento da implantação para verificar o atestado e implantar a imagem associada, a autorização binária precisará ser configurada. Configure a política para exigir atestados. É possível Configurar a política no Console do Google Cloud ou na linha de comando.

13. Armazene o projeto do Google Cloud em uma variável de ambiente.

    Observação: esse ID de projeto é usado em todo este documento.

      export PROJECT_ID=PROJECT_ID
    

    Substitua PROJECT_ID pela ID do seu projeto.

14. Defina o ID do projeto para os comandos gcloud:

    gcloud config set project ${PROJECT_ID}

15. Especifique o número do projeto em uma variável de ambiente para etapas futuras:

    export PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" \
      --format='value(project_number)')

Configurar o Servidor de cupons

Nas etapas a seguir, você configurará o servidor de cupons.

Criar uma chave de assinatura do Cloud Key Management Service

Nesta seção, você criará a chave que o servidor de cupons usa para criar um atestado de autorização binária.

1. Crie um keyring:

   gcloud kms keyrings create KEY_RING\
      --location global
   

   Substitua KEY_RING por um nome de keyring, como voucher-key-ring.

2. Crie uma chave de assinatura:

   gcloud kms keys create KEY_NAME \
     --keyring KEY_RING \
     --location global \
     --purpose "asymmetric-signing" \
     --default-algorithm "rsa-sign-pkcs1-4096-sha512"
   

   Substitua KEY_NAME por um nome de chave, como voucher-key.

   Observação: o cupom é compatível apenas com algoritmos de resumo SHA512.

3. Armazene o ID do recurso da versão da chave do Cloud Key Management Service:

   export KMS_RESOURCE_ID=projects/$PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/1
   

4. Conceda o papel cloudkms.signer à conta de serviço do mecanismo de execução do Compute Engine.

   Nesta etapa, você concederá o papel cloudkms.signer à conta de serviço que executa servidor de cupons. Isso permitirá que o servidor de cupons assine os atestados com as chaves do Cloud Key Management Service. Para isso, execute este comando:

   gcloud kms keys add-iam-policy-binding\
     KEY_NAME --keyring=KEY_RING\
     --location=global\
     --member=serviceAccount:${PROJECT_NUMBER}[e-mail]\
     --role=roles/cloudkms.signer
   

Criar a nota do Artifact Analysis

Nesta seção, você criará a nota.

1. Armazene o ID da nota:

   export NOTE_ID=snakeoil
   

2. Armazene o URI da nota:

   export NOTE_URI=projects/$PROJECT_ID/notes/$NOTE_ID
   

3. Crie o payload da solicitação:

   cat > /tmp/note_payload.json << EOM
   {
     "name": "${NOTE_URI}",
     "attestation": {
       "hint": {
         "human_readable_name": "voucher note for snakeoil check"
       }
     }
   }
   EOM
   

4. Crie a nota:

   curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $(gcloud --project ${PROJECT_ID} auth print-access-token)"  \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     --data-binary @/tmp/note_payload.json  \
   "https://containeranalysis.googleapis.com/v1/projects/${PROJECT_ID}/notes/?noteId=${NOTE_ID}"
   

Criar e configurar o servidor de cupons

Nesta configuração única, você recebe, configura e cria a imagem do servidor de cupons. Em seguida, armazene-a no Container Registry.

1. Clone o repositório do cupom:

   git clone https://github.com/grafeas/voucher.git
   cd voucher/
   

   Esse repositório contém:

   • Código-fonte para criar o servidor de cupons.
   • Código-fonte para criar o cliente de cupons.
   • Exemplos que demonstram como usar o cupom.

2. Atualize o arquivo de configuração do servidor de cupons.

   Linux

   Crie o arquivo de configuração do servidor de cupons a partir de um modelo, substituindo e pelos valores definidos acima. Para isso, execute o seguinte comando:

    cat tutorials/cloudrun/config.toml.template \
       | sed -e "s?<PROJECT_ID>?${PROJECT_ID}?g" \
       | sed -e "s?<KMS_KEY_NAME>?${KMS_RESOURCE_ID}?g" \
         > tutorials/cloudrun/config.toml
   

   Outros SOs

   1. Edite o arquivo tutorials/cloudrun/config.toml.template.

      • Substitua <PROJECT_ID> pelo valor em ${PROJECT_ID}.
      • Substitua <KMS_KEY_NAME> pelo valor em ${KMS_RESOURCE_ID}.

   2. Salve o arquivo como tutorials/cloudrun/config.toml.

3. Veja o arquivo de configuração do servidor de cupons:

   cat tutorials/cloudrun/config.toml
   

   Você verá a saída que contém o seguinte:

   failon = "high"
   

   No arquivo de configuração, a opção failon está definida como high. Esta configuração configura o servidor de cupons para realizar uma verificação de vulnerabilidades em uma imagem. Se a imagem contiver vulnerabilidades com gravidade HIGH, a verificação falhará e o servidor de cupons não criará o atestado de autorização binária. Para mais informações sobre as configurações de fail-on, consulte Falha: falha nas vulnerabilidades.

4. Crie e faça o upload da imagem do contêiner do servidor de cupons:

   Nesta seção, você executará o pipeline do Cloud Build que cria a imagem do contêiner do servidor de cupons. A criação também faz upload da imagem do servidor de cupons para gcr.io/$PROJECT_ID/voucher-server.

   gcloud  builds submit --config ./tutorials/cloudrun/cloudbuild-server.yaml
   

Implantar o servidor de cupons no Cloud Run

1. Selecione uma região.

   Para ver uma lista de regiões disponíveis, consulte Como ver uma lista de regiões disponíveis. Crie uma variável para armazenar a região selecionada:

   export REGION=REGION
   

   Substitua REGION pelo nome da região em que você planeja implantar o servidor de cupons.

2. Implantar o servidor de cupons no Cloud Run.

   gcloud run deploy --image gcr.io/${PROJECT_ID}/voucher-server \
     --platform managed voucher-server \
     --region ${REGION} \
     --no-allow-unauthenticated
   

   A saída será exibida assim:

   Service [voucher-server] revision [voucher-server-00001-caw] has been deployed and is serving 100 percent of traffic.
   Service URL: https://voucher-server-4wjtm2amga-uc.a.run.app
   

3. Armazene o URL do serviço de servidor de cupons:

   export SERVER_SERVICE_URL=$(gcloud run services describe voucher-server --platform managed --region ${REGION} --format='value(status.url)')
   

Configurar o cliente de cupons

Nas etapas a seguir, você configurará o cliente de cupons.

1. Crie a conta de serviço do invocador para o cliente de cupons:

   gcloud iam service-accounts create INVOKER_ACCOUNT_NAME
   

   Substitua INVOKER_ACCOUNT_NAME por um nome para a conta de serviço do invocador, como voucher-invoker.

2. Especifique a conta de serviço:

   export INVOKER_SERVICE_ACCOUNT=INVOKER_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

3. Conceda o papel run.invoker à conta de serviço do invocador do seu projeto.

   Conceda permissão à sua conta de serviço do invocador para invocar o servidor de cupons no Cloud Run. Para fazer isso, digite este comando:

   gcloud run services add-iam-policy-binding voucher-server \
     --member serviceAccount:$INVOKER_SERVICE_ACCOUNT \
     --role roles/run.invoker \
     --platform managed \
     --region ${REGION}
   

4. Conceda o papel iam.serviceAccountTokenCreator à conta de serviço do invocador do Cloud Build.

   Nesta seção, você concede à conta de serviço do Cloud Build permissão para representar a conta de serviço do invocador. Assim, o cliente de cupons tem permissão para enviar solicitações ao servidor de cupons durante a criação. Para fazer isso, digite este comando:

   gcloud iam service-accounts add-iam-policy-binding $INVOKER_SERVICE_ACCOUNT \
     --member=serviceAccount:$[e-mail] \
     --role=roles/iam.serviceAccountTokenCreator
   

Usar o cupom para verificar se há vulnerabilidades em imagens

Nesta seção, você verá dois exemplos de pipelines do Cloud Build. Nos dois pipelines, é possível criar uma imagem e usar o cupom para verificar se há vulnerabilidades.

Caso de falha

Nesta seção, o pipeline de criação de exemplo falha ao criar um atestado. A imagem que você criou, baseada no Debian 9, contém pelo menos uma vulnerabilidade de gravidade HIGH. A opção fail-on no servidor de cupons config.toml está configurada para falhar nas vulnerabilidades de gravidade HIGH. Nesse caso, o servidor de cupons não cria um atestado de autorização binária.

1. Execute o pipeline de criação:

   gcloud builds submit \
     --substitutions=_SERVICE_URL=$SERVER_SERVICE_URL,_SERVICE_ACCOUNT=$INVOKER_SERVICE_ACCOUNT \
     --config=tutorials/cloudrun/examples/cloudbuild-bad.yaml tutorials/cloudrun/examples
   

2. Pesquise o registro na última criação para ver as descobertas do cupom snakeoil:

   Console

   1. Anote o ID da criação mais recente.

   2. No Console do Google Cloud, acesse a página Histórico de criação.

      Acesse Histórico de criação

   3. Em Criação, clique no item que contém os primeiros caracteres do ID da criação.

   4. Clique em Ver criações brutas.

   5. Pesquise por snakeoil usando seu navegador.

      A saída será exibida assim:

      "name":"snakeoil","error":"vulnerable to 14 vulnerabilities"
      

   gcloud

   1. Salve o ID da criação:

      export BUILD_ID=$(gcloud builds list --limit=1 --format="value('ID')")
      

   2. Pesquise o registro da criação inserindo o seguinte comando:

       gcloud builds log ${BUILD_ID} | grep "snakeoil"
      

      A saída será assim:

      "name":"snakeoil","error":"vulnerable to 14 vulnerabilities"
      

Caso de sucesso

Nesta seção, o exemplo de pipeline de criação cria um atestado. Todas as vulnerabilidades identificadas são classificadas abaixo do limite de fail-on para que a verificação seja aprovada no pipeline e crie o atestado.

Observação: talvez você veja resultados diferentes. Talvez essa criação não consiga criar um atestado se, em algum momento no futuro, a verificação de vulnerabilidades identificar novas vulnerabilidades classificadas com gravidade HIGH.

1. Execute o canal:

   gcloud builds submit\
     --substitutions=_SERVICE_URL=$SERVER_SERVICE_URL,_SERVICE_ACCOUNT=$INVOKER_SERVICE_ACCOUNT\
     --config=tutorials/cloudrun/examples/cloudbuild-good.yaml tutorials/cloudrun/examples
   

   Observação: essa criação pode falhar inicialmente ao criar o atestado. Isso ocorre porque pode levar alguns minutos para que as permissões que você concedeu anteriormente neste tutorial sejam propagadas no servidor de cupons. Para resolver isso, execute o comando de criação novamente.

2. Pesquise o registro na última criação para ver as descobertas do cupom snakeoil:

   Console

   1. Anote o ID da criação mais recente.

   2. No Console do Google Cloud, acesse a página Histórico de criação.

      Acesse Histórico de criação

   3. Em Criação, clique no item que contém os primeiros caracteres do ID da criação.

   4. Clique em Ver criações brutas.

   5. Pesquise por snakeoil usando seu navegador.

      A saída será exibida assim:

      "name":"snakeoil","success":true,"attested":true
      

   gcloud

   1. Salve o ID da criação mais recente:

      export BUILD_ID=$(gcloud builds list --limit=1 --format="value('ID')")
      

   2. Pesquise o registro da criação inserindo o seguinte comando:

       gcloud builds log ${BUILD_ID} | grep "snakeoil"
      

      A saída será assim:

      "name":"snakeoil","success":true,"attested":true
      

Limpar

Para limpar os recursos usados neste documento, exclua o projeto da seguinte maneira:

gcloud projects delete ${PROJECT_ID}

Crie um atestador

Para criar uma política que exija os atestados criados usando o método descrito neste guia, primeiro você precisa criar um atestador.

Para criar um atestador, faça o seguinte:

1. Recupere o material de chave pública da chave do Cloud KMS criada anteriormente neste guia:

   gcloud kms keys versions get-public-key 1 \
   --key KEY_NAME \
   --keyring KEY_RING \
   --location global \
   --output-file OUTPUT_PATH
   

   • KEY_NAME: o nome da chave
   • KEY_RING: é o nome do keyring
   • OUTPUT_PATH: um caminho de arquivo, por exemplo, my-key.pem

2. Crie um atestador usando o material da chave pública no arquivo e a observação que você criou anteriormente neste guia. É possível criar um atestador usando o Console do Google Cloud ou a CLI gcloud.

3. Crie uma política que exija atestados e forneça o atestador que você criou nesta seção. É possível criar uma política usando o console do Google Cloud ou da CLI gcloud

Criar um atestado

Para criar um atestado usando o atestador, consulte Criar um atestado usando o Cloud KMS.

A seguir

• Configurar a política de autorização binária para exigir atestados usando a ferramenta de linha de comando ou o Console do Google Cloud.
• Criar a autorização binária do atestador para verificar o atestado no momento da implantação usando a ferramenta de linha de comando ou o Console do Google Cloud.
• Ver a documentação de cupons no GitHub.
• Saiba mais sobre Autorização binária.
• Saiba mais sobre o Artifact Analysis e a verificação de vulnerabilidades.
• Saiba mais sobre o Cloud Key Management Service.