Como gerar uma SBOM no GitHub Actions

Quatro abordagens

1. Exportar o grafo de dependências

O GitHub constrói um grafo de dependências a partir dos manifestos e lockfiles de um repositório e consegue exportá-lo como SBOM SPDX. Não exige alterações ao workflow: abra o separador Insights do repositório, escolha Dependency graph e clique em Export SBOM. Descreve o repositório no branch predefinido, não um build em particular, pelo que as ferramentas e os pacotes que um workflow instala não constam dele.

Para o automatizar, use a REST API. GET /repos/{owner}/{repo}/dependency-graph/sbom devolve o SPDX JSON numa só chamada, mas o GitHub vai descontinuar este endpoint depois de 13 de novembro de 2026. A substituição é assíncrona: peça um relatório e depois obtenha o sbom_url que este devolve. Esse URL responde 202 enquanto a SBOM está a ser gerada e depois redireciona para o ficheiro SPDX JSON, que o GitHub guarda até uma semana.

# Export the dependency graph as SPDX JSON (closing down after November 13, 2026)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/dependency-graph/sbom

# The replacement: request a report; the response carries an sbom_url
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/dependency-graph/sbom/generate-report

2. Adicionar um passo de geração

Um passo do workflow executa um gerador sobre o espaço de trabalho ou uma imagem. anchore/sbom-action executa o Syft: por defeito analisa o diretório do espaço de trabalho e produz SPDX JSON, pode analisar uma imagem de contentor em vez disso, e carrega a SBOM como artefacto do workflow e anexa-a às versões. O seu README pede contents: write, mais actions: read quando anexa a SBOM a uma versão:

name: sbom
on:
  push:
    branches: [main]
  release:
    types: [published]

jobs:
  sbom:
    runs-on: ubuntu-latest
    permissions:
      contents: write # upload the SBOM
      actions: read # attach it to a release
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      # Scan the workspace after the install step
      - uses: anchore/sbom-action@v0
        with:
          path: .
          format: cyclonedx-json

format aceita spdx, spdx-json, cyclonedx ou cyclonedx-json. Para analisar uma imagem, substitua path por image, por exemplo image: ghcr.io/OWNER/app:1.0. Consulte SBOM de imagens Docker para as SBOM de imagem do próprio BuildKit.

O Trivy e o cdxgen podem ser executados da mesma forma, como passos run simples. O cdxgen escreve CycloneDX; desde a versão 13, o seu pacote npm é @cdxgen/cdxgen:

    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npm install -g @cdxgen/cdxgen --ignore-scripts
      - run: cdxgen -o bom.json .
      - uses: actions/upload-artifact@v7
        with:
          name: sbom
          path: bom.json

O momento importa. Execute o passo depois de as dependências serem instaladas, ou não as verá. Mesmo assim, um gerador vê os ficheiros que tem à frente: um pacote que um script descarregou, usou e apagou, ou uma ferramenta instalada fora de um gestor de pacotes, podem faltar.

3. Assinar como atestação

As atestações de artefactos do GitHub ligam uma SBOM ao artefacto que descreve e assinam-na com o Sigstore. actions/attest@v4 aceita SPDX ou CycloneDX JSON através de sbom-path, até 16 MB. Sem sbom-path, produz antes proveniência de build SLSA. actions/attest-sbom está a ser descontinuada em favor de actions/attest, que agora encapsula. O job precisa de id-token: write para obter um certificado de assinatura e de attestations: write para guardar o resultado:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # sign with a Sigstore certificate
      contents: read
      attestations: write # store the attestation
    steps:
      - uses: actions/checkout@v7
      - run: make build # writes dist/my-app
      - uses: anchore/sbom-action@v0
        with:
          path: .
          format: spdx-json
          output-file: sbom.spdx.json
          upload-artifact: false
      - uses: actions/attest@v4
        with:
          subject-path: dist/my-app
          sbom-path: sbom.spdx.json

Para uma imagem de contentor, passe subject-name e subject-digest em vez de subject-path, defina push-to-registry: true e acrescente packages: write. As atestações de artefactos funcionam em repositórios públicos em todos os planos atuais do GitHub; os repositórios privados e internos precisam do GitHub Enterprise Cloud.

A GitHub CLI verifica depois quem produziu a SBOM e para que artefacto. As atestações de SBOM precisam de --predicate-type; acrescente --format json para ver a própria SBOM. Para uma imagem, use oci:// seguido do nome da imagem em vez do caminho do ficheiro.

gh attestation verify dist/my-app \
  -R OWNER/REPO \
  --predicate-type https://spdx.dev/Document/v2.3

Uma atestação prova quem produziu a SBOM e para que artefacto. Não torna a SBOM mais completa.

4. Registar durante o build

O CRACI regista a SBOM enquanto o job é executado. Altera runs-on para craci:

jobs:
  build:
    runs-on: craci # was: ubuntu-latest

Um proxy que reconhece pacotes no runner regista então cada pacote que o job obteve, incluindo pacotes restaurados de caches de CI e dependências ocultas que nenhum lockfile lista, como código descarregado por scripts de instalação. Não há nenhum passo de geração para posicionar, pelo que a questão do momento desaparece. Cada SBOM, em CycloneDX ou SPDX, indica a sua completude por job e por cache, e a API devolve SBOM, traços de rede e proveniência. A configuração, incluindo a GitHub App do CRACI e as definições de rede, está na documentação do CRACI, e o significado de cada estado de completude está em completude da SBOM de jobs e caches.

Qual usar

• Um inventário rápido de um repositório: a exportação do grafo de dependências.
• Uma SBOM de uma imagem de contentor: um passo de geração sobre a imagem.
• Prova de quem produziu uma SBOM e para que artefacto: uma atestação, sobre qualquer uma das anteriores.
• Um registo do que o build realmente usou, para a resposta a vulnerabilidades ou para o Cyber Resilience Act: registo durante o build. Consulte ferramentas de SBOM comparadas.

SBOM no GitHub Actions: perguntas frequentes

Como gero uma SBOM no GitHub Actions?

Acrescente um passo de geração depois do passo de instalação. O mais curto é anchore/sbom-action@v0, que executa o Syft sobre o espaço de trabalho e carrega uma SBOM SPDX JSON como artefacto do workflow. Para uma SBOM assinada, passe o ficheiro a actions/attest@v4 com sbom-path.

O GitHub gera uma SBOM automaticamente?

O GitHub consegue exportar o grafo de dependências de um repositório como SBOM SPDX, a partir do separador Insights ou da REST API. Descreve os manifestos e lockfiles do repositório, não um build em particular, pelo que não mostra ferramentas nem pacotes que um workflow descarrega.

Que action gera uma SBOM no GitHub Actions?

anchore/sbom-action executa o Syft. Por defeito, analisa o diretório do espaço de trabalho e produz SPDX JSON; pode analisar uma imagem de contentor em vez disso, carrega a SBOM como artefacto do workflow e anexa-a às versões.

De que permissões precisa um workflow de SBOM?

anchore/sbom-action pede contents: write, mais actions: read para anexar a SBOM a uma versão. A assinatura com actions/attest precisa de id-token: write e attestations: write, e de packages: write quando a atestação é enviada para um registo de contentores.

Como assino uma SBOM no GitHub Actions?

Use as atestações de artefactos do GitHub. actions/attest assina uma SBOM SPDX ou CycloneDX JSON com o Sigstore e liga-a a um artefacto; verifique-a com gh attestation verify. actions/attest-sbom está a ser descontinuada em favor de actions/attest, que agora encapsula.

Como gero uma SBOM para uma imagem de contentor no GitHub Actions?

Passe a imagem a anchore/sbom-action com a entrada image em vez de path. Para a assinar, dê a actions/attest o nome e o digest da imagem através de subject-name e subject-digest, defina push-to-registry: true e verifique com gh attestation verify oci://IMAGE.

O workflow deve produzir SPDX ou CycloneDX?

O que a ferramenta que lê a SBOM espera. A exportação do grafo de dependências é apenas SPDX e o cdxgen escreve CycloneDX. anchore/sbom-action escreve qualquer um deles, e actions/attest aceita qualquer um. Consulte CycloneDX vs SPDX.

O passo de SBOM deve ser executado antes ou depois do build?

Depois de as dependências serem instaladas, ou não as verá. Mesmo assim, vê o que está em disco, não o que o job descarregou e removeu, nem o que um script obteve. Registar durante o build evita a questão do momento.