Utilisation de l’API de soumission de dépendances

Remarque : La possibilité d’utiliser l’API REST pour la soumission de dépendances est actuellement en version bêta publique et est susceptible d’être modifiée.

À propos de l’API 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 ». Pour les dépendances transitives soumises via l’API API de soumission de dépendances, Dependabot ouvre automatiquement les demandes de tirage (pull requests) pour mettre à jour la dépendance parente, si une mise à jour est disponible.

Les dépendances soumises ne seront pas affichées dans la revue des dépendances ou dans les aperçus des dépendances de votre organisation.

Les dépendances sont soumises à l’API API de soumission de dépendances sous la forme d’un instantané. 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 API de soumission de dépendances, consultez « Points de terminaison d’API REST pour la soumission de dépendances ».

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

Vous pouvez utiliser l’API API de soumission de dépendances dans un workflow GitHub Actions pour soumettre des dépendances pour votre projet lorsque celui-ci est généré.

Utilisation d’actions prédéfinies

La façon la plus simple d’utiliser l’API API de soumission de dépendances consiste à ajouter une action prédéfinie à votre référentiel pour collecter et convertir la liste des dépendances au format d’instantané requis, puis soumettre 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
NuGet et autres	Action de soumission de dépendances pour la détection de composant

Remarque : Pour l’action de soumission de dépendance pour la détection de composants, les autres écosystèmes pris en charge incluent Vcpkg, Conan, Conda, Crates, ainsi que NuGet.

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 soumet la liste à l’API 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@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

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 :

Générer une liste de dépendances pour votre projet.
Convertir la liste des dépendances au format d’instantané accepté par l’API API de soumission de dépendances. Pour plus d’informations sur le format, consultez les paramètres du corps pour le point de terminaison d’API « Créer une capture instantanée de dépôt » dans « Points de terminaison d’API REST pour la soumission de dépendances ».
Soumettre la liste des dépendances au format approprié à l’API API de soumission de dépendances.

GitHub Enterprise Server gère le Kit de ressources de soumission de dépendances, une bibliothèque TypeScript pour vous aider à créer votre propre action GitHub et soumettre des dépendances à l’API 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 et identificateurs de package). 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

Vous pouvez utiliser GitHub Actions pour générer une nomenclature SBOM. 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 API de soumission de dépendances avec l’une des actions suivantes afin de pouvoir recevoir des Dependabot alerts sur toutes les dépendances présentant 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 API de soumission de dépendances

Par exemple, le workflow de SPDX Dependency Submission Action suivant calcule les dépendances pour un référentiel, génère une nomenclature SBOM exportable au format SPDX 2.2 et la soumet à l’API 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/"