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".
Warning
É importante lembrar que os atestados de artefatos não são uma garantia de que um artefato seja seguro. Em vez disso, os atestados de artefato vinculam você ao código-fonte e às instruções de criação que os produziram. Cabe a você definir os critérios de sua política, avaliá-la avaliando o conteúdo e tomar uma decisão embasada sobre riscos ao consumir software.
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
-
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
-
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
-
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
-
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
ouacme.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 formatosha256:HEX_DIGEST
. Se seu fluxo de trabalho usardocker/build-push-action
, você poderá usar a saídadigest
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
-
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
-
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âmetrosbom-path
deve ser definido como o caminho do arquivo de SBOM que você gerou.
Gerar um atestado de SBOM para imagens de contêiner
-
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
-
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
ouacme.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 formatosha256:HEX_DIGEST
. Se seu fluxo de trabalho usardocker/build-push-action
, você poderá usar a saídadigest
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
Note
Esses comandos presumem que você esteja em um ambiente online. Se você estiver em um ambiente offline ou desconectado, consulte "Verificação de atestados offline."
Para obter mais informações, consulte a seção attestation
do manual do GitHub CLI.