Uso de Dependency submission API

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	Mantenido por GitHub
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	Mantenido por GitHub
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/"