Utilisation de l’API de soumission de dépendances

À propos de l’API de soumission de dépendances

Vous pouvez utiliser l’API REST pour envoyer des dépendances pour un projet. Cela vous permet d’ajouter des dépendances, comme celles résolues quand le logiciel est compilé ou généré, au graphique de dépendance GitHub, pour une vue d’ensemble plus complète de l’ensemble des dépendances de votre projet.

Le graphique de dépendances affiche les dépendances que vous envoyez à l’aide de l’API, en plus des dépendances identifiées à partir de fichiers manifeste ou de verrouillage dans le référentiel (par exemple un fichier package-lock.json dans un projet JavaScript). Pour plus d’informations sur l’affichage du graphe des dépendances, consultez « Exploration des dépendances d’un dépôt ».

Les dépendances envoyées reçoivent des Dependabot alerts et Dependabot security updates pour toutes les vulnérabilités connues. Vous ne recevrez des Dependabot alerts que pour les dépendances provenant de l’un des écosystèmes pris en charge pour la GitHub Advisory Database. Pour plus d'informations sur ces écosystèmes, voir « À propos de la base de données GitHub Advisory ». Les dépendances soumises seront affichées dans dependency review ou dans les dependency insights de votre organisation.

Les dépendances sont envoyées à l’API de soumission de dépendances sous la forme d’une capture instantanée. Une capture instantanée est un ensemble de dépendances associées à un SHA de commit et à d’autres métadonnées, qui reflète l’état actuel de votre dépôt pour un commit. Les captures instantanées peuvent être générées à partir de vos dépendances détectées au moment de la génération ou à partir d’une nomenclature logicielle (SBOM, software bill of materials). Il existe des GitHub Actions qui prennent en charge l’un de ces cas d’usage. Pour plus d’informations sur l’API de soumission de dépendances, consultez la documentation de l’API REST de soumission de dépendances.

Envoi de dépendances au moment de la génération

Vous pouvez utiliser l’API de soumission de dépendances dans un workflow GitHub Actions pour envoyer des dépendances pour votre projet lorsqu’il est généré.

Utilisation d’actions prédéfinies

La façon la plus simple d’utiliser l’API de soumission de dépendances consiste à ajouter une action prédéfinie à votre dépôt qui collecte et convertit la liste des dépendances au format de capture instantanée requis et envoie la liste à l’API. Les actions qui effectuent ces étapes pour différents écosystèmes sont disponibles sur GitHub Marketplace. Certaines de ces actions sont fournies par des tiers. Vous trouverez des liens vers les actions actuellement disponibles dans le tableau ci-dessous.

Écosystème	Action	Tenue à jour par GitHub
Go	Soumission de dépendance Go
Gradle	Soumission de dépendances Gradle
Maven	Soumission de dépendances Maven Dependency Tree
Fraiseuse	Soumission de dépendances Mill
Scala	Soumission de dépendances Sbt

Par exemple, le workflow Soumission de dépendance Go suivant calcule les dépendances d’une cible de génération Go (fichier Go avec une fonction main) et envoie la liste à l’API de soumission de dépendances.

name: Go Dependency Submission
on:
  push:
    branches:
      - main

# The API requires write permission on the repository to submit dependencies
permissions:
  contents: write

# Environment 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@v4

      - uses: actions/setup-go@v4
        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

Création de votre propre action

Vous pouvez également écrire votre propre action pour envoyer des dépendances pour votre projet au moment de la génération. Votre workflow doit :

1. Générer une liste de dépendances pour votre projet.
2. Convertir la liste des dépendances au format de capture instantanée accepté par l’API de soumission de dépendances. Pour plus d’informations sur le format, consultez les paramètres de corps de l’opération d’API « Créer une capture instantanée de dépôt » dans la documentation de l’API REST de soumission de dépendances.
3. Envoyer la liste mise en forme des dépendances à l’API de soumission de dépendances.

GitHub gère le Kit de ressources de soumission de dépendances, une bibliothèque TypeScript pour vous aider à créer votre propre action GitHub pour envoyer des dépendances à l’API de soumission de dépendances. Pour plus d’informations sur l’écriture d’une action, consultez « Création d’actions ».

Génération et soumission d’une nomenclature logicielle (SBOM)

Un SBOM est un inventaire formel, lisible par la machine, des dépendances d’un projet et des informations associées (par exemple, versions, identificateurs de package et licences). Les fichiers SBOM aident à réduire les risques de la chaîne logistique, car :

• ils fournissent une transparence sur les dépendances utilisées par votre dépôt
• ils permettent d’identifier les vulnérabilités au début du processus
• ils fournissent des insights sur les problèmes de conformité, de sécurité ou de qualité des licences pouvant exister dans votre codebase
• ils vous permettent de mieux respecter divers standards de protection des données

Pour générer une nomenclature SBOM, vous pouvez utiliser :

• l’interface utilisateur de GitHub. Pour plus d’informations sur l’exportation d’une nomenclature SBOM pour un dépôt en utilisant les informations du graphe de dépendances, consultez « Exportation d’une nomenclature logicielle pour votre dépôt ».
• l’API REST. Pour plus d’informations, consultez « Nomenclature logicielle (SBOM) ».
• GitHub Actions. Les actions suivantes génèrent une nomenclature SBOM pour votre dépôt et l’attachent en tant qu’artefact de workflow que vous pouvez télécharger et utiliser dans d’autres applications. Pour plus d’informations sur le téléchargement d’artefacts de workflow, consultez « Téléchargement d’artefacts de workflow ».

Action	Détails	Tenue à jour par GitHub
SBOM-generator-action	Utilise les informations de votre graphe des dépendances pour générer une nomenclature SBOM SPDX
Action SBOM Anchore	Utilise Syft pour créer des nomenclatures SBOM compatibles SPDX 2.2 avec des écosystèmes pris en charge
sbom-tool by Microsoft	Analyse vos dépendances et crée une nomenclature SBOM compatible SPDX

Vous pouvez ensuite charger et envoyer la nomenclature SBOM à l’API de soumission de dépendances avec l’une des actions suivantes afin de pouvoir recevoir des Dependabot alerts sur toutes les dépendances qui ont des vulnérabilités connues. Les actions qui apparaissent dans les deux tableaux peuvent être configurées pour générer et envoyer une nomenclature SBOM.

Action	Détails	Tenue à jour par GitHub
SPDX Dependency Submission Action	Utilise l’outil SBOM de Microsoft pour créer des nomenclatures SBOM compatibles SPDX 2.2 avec des écosystèmes pris en charge
Action SBOM Anchore	Utilise Syft pour créer des nomenclatures SBOM compatibles SPDX 2.2 avec des écosystèmes pris en charge
SBOM Dependency Submission Action	Charge une nomenclature SBOM CycloneDX sur l’API de soumission de dépendances

Par exemple, le workflow de SPDX Dependency Submission Action suivant calcule les dépendances d’un dépôt, génère une nomenclature SBOM exportable au format SPDX 2.2 et l’envoie à l’API de soumission de dépendances.

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@v4
    - 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/"