Nota: La capacidad de usar la API REST para enviar dependencias actualmente está en versión beta pública y se encuentra sujeta a cambios.
Acerca de Dependency submission API
Puedes usar la API REST para enviar dependencias para un proyecto. Esto te permite agregar dependencias, como las que se resuelven cuando se compila o crea software, a la característica de gráfico de dependencias de GitHub, lo que proporciona un panorama más completo de todos las dependencias del proyecto.
El gráfico de dependencias muestra las dependencias que envías mediante la API, además de las dependencias identificadas mediante archivos de bloqueo o de manifiesto en el repositorio (por ejemplo, un archivo package-lock.json
en un proyecto de JavaScript). Para más información sobre la visualización del gráfico de dependencias, consulta "Explorar las dependencias de un repositorio".
Las dependencias enviadas recibirán Dependabot alerts y Dependabot security updates para cualquier vulnerabilidad conocida. Solo obtendrás Dependabot alerts para las dependencias que proceden de uno de los ecosistemas compatibles de GitHub Advisory Database. Las dependencias enviadas no se mostrarán en la revisión de dependencias ni en la información de las dependencias de la organización.
Las dependencias se envían a Dependency submission API en forma de instantánea. Una instantánea es un conjunto de dependencias asociadas a un SHA de confirmación y otros metadatos, que refleja el estado actual del repositorio para una confirmación. Las instantáneas se pueden generar a partir de las dependencias detectadas en tiempo de compilación o desde una lista de materiales de software (SBOM). Hay GitHub Actions que admiten cualquiera de estos casos de uso. Para más información sobre Dependency submission API, consulta la documentación de Dependency submission REST API.
Envío de dependencias en tiempo de compilación
Puedes usar Dependency submission API en un flujo de trabajo de GitHub Actions para enviar dependencias para tu proyecto cuando se compila.
Uso de acciones hechas previamente
La manera más sencilla de usar Dependency submission API es agregar una acción hecha previamente al repositorio que recopilará y convertirá la lista de dependencias al formato de instantánea requerido y enviará la lista a la API. Las acciones que completan estos pasos para varios ecosistemas están disponibles en GitHub Marketplace. Algunas de estas acciones las proporcionan terceros. Puedes encontrar vínculos a las acciones disponibles actualmente en la tabla siguiente.
Ecosistema | Acción | Mantenido por GitHub |
---|---|---|
Go | Envío de dependencias de Go | |
Gradle | Envío de dependencias de Gradle | |
Maven | Envío de dependencias del árbol de dependencias de Maven | |
Molino | Envío de dependencias de Mill | |
Scala | Envío de dependencias de SBT |
Por ejemplo, el flujo de trabajo de Envío de dependencias de Go siguiente calcula las dependencias de un destino de compilación de Go (un archivo de Go con una función main
) y envía la lista a Dependency Submission API.
name: Go Dependency Submission
on:
push:
branches:
- main
# The API requires write permission on the repository to submit dependencies
permissions:
contents: write
# Envionment variables to configure Go and Go modules. Customize as necessary
env:
GOPROXY: '' # A Go Proxy server to be used
GOPRIVATE: '' # A list of modules are considered private and not requested from GOPROXY
jobs:
go-action-detection:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: ">=1.18.0"
- name: Run snapshot action
uses: actions/go-dependency-submission@v1
with:
# Required: Define the repo path to the go.mod file used by the
# build target
go-mod-path: go-example/go.mod
#
# Optional. Define the repo path of a build target,
# a file with a `main()` function.
# If undefined, this action will collect all dependencies
# used by all build targets for the module. This may
# include Go dependencies used by tests and tooling.
go-build-target: go-example/cmd/octocat.go
Creación de una acción propia
De manera alternativa, puedes escribir tu propia acción para enviar dependencias para el proyecto en tiempo de compilación. El flujo de trabajo debe:
- Generar una lista de dependencias para el proyecto.
- Traducir la lista de dependencias al formato de instantánea que Dependency submission API acepta. Para más información sobre el formato, consulta los parámetros de cuerpo para la operación "Crear una instantánea de repositorio" de la API en la documentación de Dependency submission REST API.
- Enviar la lista de dependencias con formato a Dependency submission API.
GitHub mantiene el kit de herramientas de envío de dependencias, una biblioteca de TypeScript que te ayuda a crear tu propia acción de Acciones de GitHub para enviar dependencias a Dependency submission API. Para más información sobre cómo escribir una acción, consulta "Crear acciones".
Generación y envío de una lista de materiales de software (SBOM)
Puede usar GitHub Actions para generar una lista de materiales de software (SBOM), un inventario formal y legible por máquina de sus dependencias e información asociada. Las siguientes acciones generarán un SBOM para el repositorio y lo asociarán como un artefacto de flujo de trabajo que puede descargar y usar en otras aplicaciones. Para obtener más información sobre cómo descargar artefactos de flujo de trabajo, consulte "Descargar los artefactos del flujo de trabajo".
Acción | Detalles | |
---|---|---|
SBOM-generator-action | Usa la información del gráfico de dependencias para generar un SBOM de SPDX. | |
Acción SBOM de Anchore | Usa Syft para crear SBOM compatibles con SPDX 2.2 con los ecosistemas admitidos | |
sbom-tool de Microsoft | Examina las dependencias y crea un SBOM compatible con SPDX |
A continuación, puede cargar y enviar el SBOM a la API de envío de dependencias mediante una de las siguientes acciones para que pueda recibir Dependabot alerts en cualquier dependencia que tenga vulnerabilidades conocidas. Las acciones que aparecen en ambas tablas se pueden configurar para generar y enviar un SBOM.
Acción | Detalles | |
---|---|---|
Acción de envío de dependencia de SPDX | Usa la herramienta SBOM de Microsoft para crear SBOM compatibles con SPDX 2.2 con los ecosistemas admitidos. | |
Acción SBOM de Anchore | Usa Syft para crear SBOM compatibles con SPDX 2.2 con los ecosistemas admitidos | |
Acción de envío de dependencia de SBOM | Carga un SBOM de CycloneDX en la API de envío de dependencias |
Por ejemplo, el siguiente flujo de trabajo de Acción de envío de dependencia de SPDX calcula las dependencias para un repositorio, genera un SBOM exportable en formato SPDX 2.2 y lo envía a la API de envío de dependencias.
name: SBOM upload
on:
workflow_dispatch:
push:
branches: ["main"]
jobs:
SBOM-upload:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: write
steps:
- uses: actions/checkout@v3
- name: Generate SBOM
# generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation
run: |
curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
chmod +x $RUNNER_TEMP/sbom-tool
$RUNNER_TEMP/sbom-tool generate -b . -bc . -pn $ -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
- uses: actions/upload-artifact@v3
with:
name: sbom
path: _manifest/spdx_2.2
- name: SBOM upload
uses: advanced-security/spdx-dependency-submission-action@v0.0.1
with:
filePath: "_manifest/spdx_2.2/"