Usando atestados de artefatos e fluxos de trabalho reutilizáveis para alcançar o SLSA v1 Build Level 3

Note

Os atestados de artefato estão em versão beta pública e sujeitos a alterações.

Introdução

Os atestados de artefatos são uma ótima forma de garantias de procedência e integridade infalsificáveis para o software que você cria.

Mas lembre-se de que, por si só, os atestados de artefato fornecem links, como as instruções de build com as quais um artefato foi compilado, o que atende ao SLSA v1.0 Build Level 2. Para tomar uma decisão bem informada sobre risco, cabe a você seguir esses links e avaliar essas instruções de build.

Você pode avançar ainda mais nisso exigindo que os builds usem instruções de build conhecidas e verificadas. Uma ótima maneira de fazer isso é fazer com que seu build ocorra em um fluxo de trabalho reutilizável que muitos repositórios em sua organização compartilhem. Os fluxos de trabalho reutilizáveis podem fornecer isolamento entre o processo de build e o fluxo de trabalho de chamada, para atender ao SLSA v1.0 Build Level 3.

Antes de começar este guia, você deve ter familiaridade com:

Gerar atestados de artefatos Confira "Usar atestados de artefatos para estabelecer a procedência de compilações".
Escrever e usar fluxos de trabalho reutilizáveis. Confira "Reutilizar fluxos de trabalho".

Etapa 1: Configurar seus builds

Primeiro, precisamos compilar com atestados de artefatos e um fluxo de trabalho reutilizável.

Compilar com um fluxo de trabalho reutilizável

Se você ainda não estiver usando fluxos de trabalho reutilizáveis para compilar seu software, precisará executar suas etapas de build e movê-las para um fluxo de trabalho reutilizável. Para obter mais informações sobre como escrever e chamar um fluxo de trabalho reutilizável, confira "Reutilizar fluxos de trabalho".

Compilar com atestados de artefatos.

O fluxo de trabalho reutilizável que você usa para criar seu software também deve gerar atestados de artefato para estabelecer a procedência do build. Para obter mais informações, confira "Usar atestados de artefatos para estabelecer a procedência de compilações".

Quando você usa um fluxo de trabalho reutilizável para gerar atestados de artefatos, o fluxo de trabalho de chamada e o fluxo de trabalho reutilizável precisam ter as permissões a seguir.

YAML

permissions:
  attestations: write
  contents: read
  id-token: write

permissions:
  attestations: write
  contents: read
  id-token: write

Se você estiver compilando imagens de contêiner, também precisará incluir a permissão packages: write.

Etapa 2: Verificar atestados de artefato compilados com um fluxo de trabalho reutilizável

Para verificar os atestados de artefato gerados com seus builds, você pode usar gh attestation verify da CLI do GitHub.

O comando gh attestation verify exige o uso de um sinalizador --owner ou --repo. Esses sinalizadores fazem duas coisas.

Eles informam a gh attestation verify o local em que o atestado deve ser buscado. Isso será sempre o seu fluxo de trabalho de chamador.
Eles informam a gh attestation verify o local de origem do fluxo de trabalho que fez a assinatura. Esse sempre será o fluxo de trabalho que usa a ação attest-build-provenance, que pode ser um fluxo de trabalho reutilizável.

Você não pode usar sinalizadores opcionais com o comando gh attestation verify.

Se o fluxo de trabalho reutilizável não estiver no mesmo repositório que o fluxo de trabalho do chamador, use o sinalizador --signer-repo para especificar o repositório que contém o fluxo de trabalho reutilizável.
Se você quiser exigir que um fluxo de trabalho específico assine um atestado de artefato, use o sinalizador --signer-workflow para indicar o arquivo de fluxo de trabalho que deve ser usado.

Por exemplo, se o fluxo de trabalho de chamada for ORGANIZATION_NAME/REPOSITORY_NAME/.github/workflows/calling.yml e usar REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME/.github/workflows/reusable.yml , você poderá fazer:

Bash

gh attestation verify -o ORGANIZATION_NAME --signer-repo REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME PATH/TO/YOUR/BUILD/ARTIFACT-BINARY

gh attestation verify -o ORGANIZATION_NAME --signer-repo REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME PATH/TO/YOUR/BUILD/ARTIFACT-BINARY

Se você quiser especificar o fluxo de trabalho exato: