Cómo generar una SBOM en GitHub Actions

Cuatro enfoques

1. Exportar el grafo de dependencias

GitHub construye un grafo de dependencias a partir de los manifiestos y lockfiles de un repositorio y puede exportarlo como SBOM SPDX. No requiere cambiar ningún workflow: abra la pestaña Insights del repositorio, elija Dependency graph y haga clic en Export SBOM. Describe el repositorio en la rama predeterminada, no un build concreto, de modo que las herramientas y los paquetes que instala un workflow no están en ella.

Para automatizarlo, utilice la API REST. GET /repos/{owner}/{repo}/dependency-graph/sbom devuelve el SPDX JSON en una sola llamada, pero GitHub lo retirará después del 13 de noviembre de 2026. Su sustituto es asíncrono: solicite un informe y después obtenga la sbom_url que devuelve. Esa URL responde 202 mientras se genera la SBOM y después redirige al archivo SPDX JSON, que GitHub conserva hasta una 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. Añadir un paso generador

Un paso del workflow ejecuta un generador sobre el espacio de trabajo o sobre una imagen. anchore/sbom-action ejecuta Syft: por defecto escanea el directorio del espacio de trabajo y genera SPDX JSON, puede escanear en su lugar una imagen de contenedor, y sube la SBOM como artefacto del workflow y la adjunta a los lanzamientos. Su README pide contents: write, además de actions: read cuando adjunta la SBOM a un lanzamiento:

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 admite spdx, spdx-json, cyclonedx o cyclonedx-json. Para escanear una imagen, sustituya path por image, por ejemplo image: ghcr.io/OWNER/app:1.0. Consulte SBOM de Docker para ver las SBOM de imagen propias de BuildKit.

Trivy y cdxgen se pueden ejecutar de la misma forma, como pasos run normales. cdxgen escribe CycloneDX; desde la versión 13, su paquete npm es @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

El momento importa. Ejecute el paso después de instalar las dependencias o no las verá. Aun así, un generador ve los archivos que tiene delante: puede faltar un paquete que un script descargó, utilizó y eliminó, o una herramienta instalada fuera de un gestor de paquetes.

3. Firmarla como atestación

Las atestaciones de artefactos de GitHub vinculan una SBOM al artefacto que describe y la firman con Sigstore. actions/attest@v4 acepta SPDX o CycloneDX JSON mediante sbom-path, hasta 16 MB. Sin sbom-path produce en su lugar procedencia de build SLSA. actions/attest-sbom está en proceso de retirada en favor de actions/attest, al que ahora envuelve. El job necesita id-token: write para obtener un certificado de firma y attestations: write para almacenar el 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 una imagen de contenedor, pase subject-name y subject-digest en lugar de subject-path, establezca push-to-registry: true y añada packages: write. Las atestaciones de artefactos funcionan en repositorios públicos con todos los planes actuales de GitHub; los repositorios privados e internos necesitan GitHub Enterprise Cloud.

Después, la CLI de GitHub comprueba quién produjo la SBOM y para qué artefacto. Las atestaciones de SBOM necesitan --predicate-type; añada --format json para ver la propia SBOM. Para una imagen, utilice oci:// seguido del nombre de la imagen en lugar de la ruta del archivo.

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

Una atestación demuestra quién produjo la SBOM y para qué artefacto. No hace que la SBOM sea más completa.

4. Registrarla durante el build

CRACI registra la SBOM mientras se ejecuta el job. Usted cambia runs-on a craci:

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

Después, un proxy que entiende de paquetes en el runner registra cada paquete que descargó el job, incluidos los paquetes restaurados desde cachés de CI y las dependencias ocultas que ningún lockfile enumera, como el código descargado por scripts de instalación. No hay ningún paso generador que colocar, de modo que desaparece la cuestión del momento. Cada SBOM, en CycloneDX o SPDX, indica su completitud por job y por caché, y la API devuelve SBOM, trazas de red y procedencia. La configuración, incluida la GitHub App de CRACI y los ajustes de red, está en la documentación de CRACI, y el significado de cada estado de completitud está en completitud de SBOM por job y por caché.

Cuál utilizar

• Un inventario rápido de un repositorio: la exportación del grafo de dependencias.
• Una SBOM de una imagen de contenedor: un paso generador sobre la imagen.
• Una prueba de quién produjo una SBOM para qué artefacto: una atestación, sobre cualquiera de las anteriores.
• Un registro de lo que el build utilizó realmente, para la respuesta a vulnerabilidades o el Cyber Resilience Act: el registro durante el build. Consulte la comparativa de herramientas de SBOM.

SBOM en GitHub Actions: preguntas frecuentes

¿Cómo genero una SBOM en GitHub Actions?

Añada un paso generador después del paso de instalación. Lo más breve es anchore/sbom-action@v0, que ejecuta Syft sobre el espacio de trabajo y sube una SBOM SPDX JSON como artefacto del workflow. Para una SBOM firmada, pase el archivo a actions/attest@v4 con sbom-path.

¿GitHub genera una SBOM automáticamente?

GitHub puede exportar el grafo de dependencias de un repositorio como SBOM SPDX, desde la pestaña Insights o la API REST. Describe los manifiestos y lockfiles del repositorio, no un build concreto, de modo que no mostrará herramientas ni paquetes que descargue un workflow.

¿Qué acción genera una SBOM en GitHub Actions?

anchore/sbom-action ejecuta Syft. Por defecto escanea el directorio del espacio de trabajo y genera SPDX JSON; puede escanear en su lugar una imagen de contenedor, sube la SBOM como artefacto del workflow y la adjunta a los lanzamientos.

¿Qué permisos necesita un workflow de SBOM?

anchore/sbom-action pide contents: write, además de actions: read para adjuntar la SBOM a un lanzamiento. Firmar con actions/attest necesita id-token: write y attestations: write, y packages: write cuando la atestación se envía a un registro de contenedores.

¿Cómo firmo una SBOM en GitHub Actions?

Utilice las atestaciones de artefactos de GitHub. actions/attest firma una SBOM SPDX o CycloneDX JSON con Sigstore y la vincula a un artefacto; verifíquela con gh attestation verify. actions/attest-sbom está en proceso de retirada en favor de actions/attest, al que ahora envuelve.

¿Cómo genero una SBOM para una imagen de contenedor en GitHub Actions?

Pase la imagen a anchore/sbom-action con la entrada image en lugar de path. Para firmarla, indique a actions/attest el nombre y el digest de la imagen mediante subject-name y subject-digest, establezca push-to-registry: true y verifíquela con gh attestation verify oci://IMAGE.

¿El workflow debe producir SPDX o CycloneDX?

El que espere la herramienta que lee la SBOM. La exportación del grafo de dependencias es solo SPDX y cdxgen escribe CycloneDX. anchore/sbom-action escribe ambos y actions/attest acepta ambos. Consulte CycloneDX vs SPDX.

¿El paso de SBOM debe ejecutarse antes o después del build?

Después de instalar las dependencias, o no las verá. Aun así, ve lo que hay en disco, no lo que el job descargó y eliminó ni lo que descargó un script. Registrar durante el build evita la cuestión del momento.