Usar atestados de artefatos para estabelecer a procedência de compilações

Sobre atestados de artefatos

Os atestados de artefatos permitem que você crie garantias de procedência e integridade infalsificáveis para o software que você cria. Por sua vez, as pessoas que consomem seu software podem verificar onde e como seu software foi criado.

Ao gerar atestados de artefato com seu software, você cria declarações assinadas criptograficamente que estabelecem a procedência do build e incluem as seguintes informações:

• Um link para o fluxo de trabalho associado ao artefato.
• O repositório, organização, ambiente, SHA de commit e evento de gatilho do artefato.
• Outras informações do token OIDC usado para estabelecer a procedência. Para obter mais informações, confira "Sobre o enrijecimento de segurança com o OpenID Connect".

Você também pode gerar atestados de artefato que incluam uma SBOM (lista de materiais de software) associada. Associar suas compilações a uma lista de dependências de código aberto usadas nelas fornece transparência e permite que os consumidores cumpram os padrões de proteção de dados.

Sobre os níveis de SLSA para atestados de artefatos

A estrutura SLSA é um padrão do setor usado para avaliar a segurança da cadeia de fornecedores. Está organizada em níveis. Cada nível representa um grau crescente de segurança e confiabilidade para uma cadeia de fornecedores de software. Os atestados de artefato em si fornecem SLSA v1.0 Build Level 2.

Isso fornece um link entre seu artefato e suas instruções de build, mas você pode dar um passo adiante 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. Para saber mais, confira Usando atestados de artefatos e fluxos de trabalho reutilizáveis para alcançar o SLSA v1 Build Level 3.

Para obter mais informações sobre os níveis de SLSA, consulte Níveis de segurança do SLSA.

Sobre o uso de Sigstore para atestados de artefatos

Para gerar atestados de artefatos, o GitHub usa o Sigstore, um projeto de código aberto que oferece uma solução abrangente para assinar e verificar artefatos de software por meio de atestados.

Repositórios públicos que geram atestados de artefatos usam a instância válida pública do Sigstore. Uma cópia do pacote Sigstore gerado é armazenada no GitHub e também gravada em um log de transparência imutável que pode ser lido publicamente na Internet.

Repositórios privados que geram atestados de artefatos usam a instância do Sigstore do GitHub. A instância do Sigstore do GitHub usa a mesma base de código que a instância válida pública do Sigstore, mas não tem um log de transparência e federa apenas com o GitHub Actions.

O que atestar

A geração de atestados por si só não traz nenhum benefício de segurança, é preciso verificar os atestados para aproveitar os benefícios. Aqui estão algumas diretrizes de como pensar sobre o que assinar e com que frequência:

Você deverá entrar:

• Software que você está liberando em que você espera que as pessoas executem gh attestation verify ....
• Binários que as pessoas executarão, pacotes dos quais as pessoas farão download ou manifestos que incluem hashes de conteúdo detalhado.

Você não deve assinar:

• Compilações frequentes que são apenas para testes automatizados.
• Arquivos individuais, como código-fonte, arquivos de documentação ou imagens incorporadas.

Sobre a verificação de atestados de artefatos

Se você consome software que publica atestados de artefatos, pode usar o GitHub CLI para verificar esses atestados. Como os atestados fornecem informações sobre onde e como o software foi desenvolvido, você pode usar essas informações para criar e aplicar políticas de segurança que elevem a segurança de sua cadeia de fornecedores. Para obter mais informações, consulte "Verificar atestados de artefatos com o GitHub CLI".

Gerar atestados de artefatos para seus builds.

Você pode usar GitHub Actions para gerar atestados de artefato que estabeleçam a origem da compilação para artefatos como binários e imagens de contêiner.

Para gerar um atestado de artefato, você deve fazer o seguinte:

• Verificar se as permissões apropriadas estão configuradas em seu fluxo de trabalho.
• Incluir uma etapa em seu fluxo de trabalho que use a ação attest-build-provenance.

Quando você executar seus fluxos de trabalho atualizados, eles criarão seus artefatos e gerarão um atestado de artefato que estabelece a origem da compilação. Você pode exibir os atestados na guia Ações do repositório. Para obter mais informações, consulte o repositório attest-build-provenance.

Gerar origem de compilação para binários

1. No fluxo de trabalho que cria o binário que você deseja atestar, adicione as permissões a seguir.

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

2. Após a etapa em que o binário foi criado, adicione a etapa a seguir.

   - name: Generate artifact attestation
     uses: actions/attest-build-provenance@v1
     with:
       subject-path: 'PATH/TO/ARTIFACT'
   

   O valor do parâmetro subject-path deve ser definido como o caminho do binário que você deseja atestar.

Gerar origem de compilação para imagens de contêiner

1. No fluxo de trabalho que cria a imagem do contêiner que você deseja atestar, adicione as permissões a seguir.

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

2. Após a etapa em que a imagem foi criada, adicione a etapa a seguir.

   - name: Generate artifact attestation
     uses: actions/attest-build-provenance@v1
     with:
       subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
       subject-digest: 'sha256:fedcba0...'
       push-to-registry: true
   

   O valor do parâmetro subject-name deve especificar o nome completo da imagem. Por exemplo, ghcr.io/user/app ou acme.azurecr.io/user/app. Não inclua uma marca como parte do nome da imagem.

   O valor do parâmetro subject-digest deve ser definido como o resumo SHA256 do assunto para o atestado, no formato sha256:HEX_DIGEST. Se seu fluxo de trabalho usar docker/build-push-action, você poderá usar a saída digest dessa etapa para fornecer o valor. Para obter mais informações sobre como usar saídas, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Gerar um atestado para uma SBOM (lista de materiais de software)

É possível gerar atestados de SBOM assinados para artefatos de fluxo de trabalho.

Para gerar um atestado para uma SBOM, você deve:

• Verificar se as permissões apropriadas estão configuradas em seu fluxo de trabalho.
• Criar uma SBOM para seu artefato. Para obter mais informações, consulte anchore-sbom-action no GitHub Marketplace.
• Incluir uma etapa em seu fluxo de trabalho que use a ação attest-sbom.

Quando você executar seus fluxos de trabalho atualizados, eles criarão seus artefatos e gerarão um atestado de SBOM. Você pode exibir os atestados na guia Ações do repositório. Para obter mais informações, consulte o repositório da ação attest-sbom.

Gerar um atestado de SBOM para binários

1. No fluxo de trabalho que cria o binário que você deseja atestar, adicione as permissões a seguir.

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

2. Após a etapa em que o binário foi criado, adicione a etapa a seguir.

   - name: Generate SBOM attestation
     uses: actions/attest-sbom@v1
     with:
       subject-path: 'PATH/TO/ARTIFACT'
       sbom-path: 'PATH/TO/SBOM'
   

   O valor do parâmetro subject-path deve ser definido como o caminho do binário descrito pela SBOM. O valor do parâmetro sbom-path deve ser definido como o caminho do arquivo de SBOM que você gerou.

Gerar um atestado de SBOM para imagens de contêiner

1. No fluxo de trabalho que cria a imagem do contêiner que você deseja atestar, adicione as permissões a seguir.

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

2. Após a etapa em que a imagem foi criada, adicione a etapa a seguir.

   - name: Generate SBOM attestation
     uses: actions/attest-sbom@v1
     with:
       subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE
       subject-digest: 'sha256:fedcba0...'
       sbom-path: 'sbom.json'
       push-to-registry: true
   

   O valor do parâmetro subject-name deve especificar o nome completo da imagem. Por exemplo, ghcr.io/user/app ou acme.azurecr.io/user/app. Não inclua uma marca como parte do nome da imagem.

   O valor do parâmetro subject-digest deve ser definido como o resumo SHA256 do assunto para o atestado, no formato sha256:HEX_DIGEST. Se seu fluxo de trabalho usar docker/build-push-action, você poderá usar a saída digest dessa etapa para fornecer o valor. Para obter mais informações sobre como usar saídas, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

   O valor do parâmetro sbom-path deve ser definido como o caminho para o arquivo de SBOM formatado em JSON que você deseja atestar.

Verificar atestados de artefatos com o GitHub CLI

Para verificar atestados de artefatos para binários, use o comando do GitHub CLI a seguir.

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME

Para verificar atestados de artefatos para imagens de contêiner, você deve fornecer o FQDN da imagem prefixado com oci:// em vez do caminho para um binário. Você pode usar o comando do GitHub CLI a seguir.

docker login ghcr.io

gh attestation verify oci://ghcr.io/ORGANIZATION_NAME/IMAGE_NAME:test -R ORGANIZATION_NAME/REPOSITORY_NAME

docker login ghcr.io

gh attestation verify oci://ghcr.io/ORGANIZATION_NAME/IMAGE_NAME:test -R ORGANIZATION_NAME/REPOSITORY_NAME

Para obter mais informações, consulte a seção attestation do manual do GitHub CLI.