Gérer les avis innersource

Pour plus d’informations sur le fonctionnement des avis innersource et sur les personnes qui peuvent les créer, consultez Innersource advisories.

Prerequisites

Les avis Innersource ne peuvent être créés qu’au sein des entreprises disposant d’une licence GitHub Code Security ou GitHub Advanced Security active.

Créer des avis innersource

Pour créer un conseil InnerSource :

Créez et installez un GitHub App disposant de l’autorisation enterprise_innersource_vulnerabilities.
Générer un jeton associé à l’application disposant de l’accès write à cette autorisation.
Créez une description de la vulnérabilité à l’aide du format OSV, puis POST envoyez-la au point de terminaison /enterprises/{enterprise}/innersource-vulnerabilities/sync de l’API REST.

Chacune de ces étapes est décrite plus en détail ci-dessous.

Enregistrez un GitHub App appartenant à votre entreprise, et accordez-lui l’autorisation enterprise_innersource_vulnerabilities avec un accès read and write. Consultez « Inscription d’une application GitHub ».

Après avoir inscrit l’application, installez-la sur votre entreprise afin qu’elle puisse agir au nom de l’entreprise.

Étape 2 : Générer un jeton d’accès

Authentifiez-vous avec l’installation GitHub App pour générer un jeton d’accès pour l’installation. Ce jeton porte l’autorisation enterprise_innersource_vulnerabilities et est utilisé pour authentifier vos demandes auprès de l’API REST. Consultez « Génération d’un jeton d’accès d’installation pour une application GitHub ».

Étape 3 : Télécharger une description de l’avis

Décrivez la vulnérabilité au format OSV, puis POST la charge utile à /enterprises/{enterprise}/innersource-vulnerabilities/sync, en utilisant le jeton d’accès d’installation pour vous authentifier. La charge utile identifie le package affecté et la plage de versions vulnérables. Si une version corrigée est disponible, incluez un champ fixed avec le numéro de version afin que Dependabot puisse ouvrir des pull requests pour mettre à jour les dépôts affectés.

Pour plus d’informations sur le schéma consultatif, consultez Points de terminaison d’API REST pour les avis de sécurité.

Utilisation des recommandations InnerSource

Une fois que vous avez créé un avis innersource, les référentiels de l’entreprise qui utilisent le composant concerné recevront des alertes et des mises à jour.

Assurez-vous que les référentiels de votre entreprise ont Dependabot alerts et les mises à jour activés. Vous pouvez appliquer cela à grande échelle à l’aide d’une configuration de sécurité. Consultez « Création d’une configuration de sécurité personnalisée ».
Regardez la page des Dependabot alerts référentiels dépendants pour obtenir une nouvelle alerte sur le composant concerné. L’alerte comportera un libellé distinct « Innersource » afin de la distinguer des alertes d’avis de sécurité open source.
Si la charge utile de l’avis incluait un champ fixed avec un numéro de version correspondant à un paquet disponible, Dependabot créera également une pull request mettant à jour le fichier manifeste du gestionnaire de paquets. Consultez « Configuration de mises à jour de version Dependabot ».

Retrait des avis sur les ressources internes

Lorsqu’il n’existe pas de versions plus vulnérables d’un composant concerné en cours d’utilisation ou si un avis est remplacé, il peut être utile de le retirer.

Pour retirer un avis, utilisez le même point de terminaison d’API REST que l’étape de création, mais ajustez la charge utile pour inclure une withdrawn clé, dont la valeur est un date-time champ indiquant quand la vulnérabilité a été retirée.

Prise en charge et limitations du format OSV

GitHub accepte les vulnérabilités au format OSV (Open Source Vulnerability) via l’API de synchronisation des vulnérabilités innersource. Bien qu’il GitHub s’efforce de la compatibilité avec la spécification OSV, il existe des différences entre le schéma OSV standard et ce qui GitHub nécessite ou prend en charge.

Version de schéma OSV prise en charge

GitHub prend en charge les versions de schéma OSV compatibles avec ~> 1.0 (par exemple, 1.0.0 via 1.x.x). La version de schéma recommandée est 1.4.0.

Formatage des entrées affectées

La spécification OSV permet à une seule entrée affected de contenir plusieurs ranges et plusieurs versions pour le même paquet. GitHub normalise ces éléments en interne en les fractionnant en entrées distinctes :

| norme OSV | GitHub Comportement | |---|---| | Une seule affected entrée peut contenir plusieurs ranges | Accepted. Chaque plage est traitée comme une plage de versions vulnérable distincte. | | Une seule affected entrée peut contenir plusieurs versions | Accepted. Chaque version est traitée comme une correspondance exacte (= x.y.z) et traitée comme une plage de versions vulnérable distincte. | | Une seule affected entrée peut mélanger ranges et versions | Accepted. Les intervalles et les versions sont séparés en entrées distinctes en interne. | | Une SEMVER plage peut contenir plusieurs introduced/fixed paires | Accepted. Plusieurs intervalles disjoints (par exemple, [1.0.0, 1.0.2) et [3.0.0, 3.2.5)) dans une plage unique sont pris en charge. |

Types de plages pris en charge

Type d’intervalle	Support
`ECOSYSTEM`
Entièrement pris en charge. Prend en charge les événements `introduced`, `fixed` et `last_affected`.
`SEMVER`
Entièrement pris en charge. Prend en charge les événements `introduced`, `fixed` et `last_affected`. L’événement `last_affected` est interprété comme un `<=` comparateur de borne supérieure.
`GIT`
Non pris en charge. Les plages basées sur des commits Git ne sont pas traitées.

Remarque

Pour les plages ECOSYSTEM, un seul événement introduced et un seul événement fixed (ou last_affected) par plage est pris en charge. Si vous devez exprimer plusieurs plages de versions disjointes pour le même package, utilisez des entrées distinctes affected ou des plages distinctes.

          Les plages `SEMVER` prennent en charge plusieurs paires `introduced`/`fixed` au sein d'une même plage (par exemple, `[1.0.0, 1.0.2)` et `[3.0.0, 3.2.5)` dans un même tableau d'événements).

fixed et last_affectedne peut pas apparaître ensemble dans la même plage. Utilisez l’un ou l’autre, avec une préférence pour fixed.

Champs obligatoires

La spécification OSV traite plusieurs champs comme facultatifs, mais GitHub les requiert. Les demandes manquantes dans ces champs sont rejetées avec une erreur 422.

| Champ | spécification OSV | GitHub Exigence | |---|---|---| | id | Obligatoire | Obligatoire. Utilisé comme identificateur externe pour la vulnérabilité. | | severity tableau | Optional | Obligatoire. Doit contenir au moins une entrée CVSS_V3 ou CVSS_V4 avec une chaîne score non vide (par exemple, CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H). Les demandes sans entrée CVSS valide sont rejetées. | | affected[].package.ecosystem | Obligatoire | Doit être un écosystème pris en charge | | affected[].ranges ou affected[].versions | Au moins une obligatoire | Au moins une plage ou version doit être présente pour la mise en correspondance des alertes |

Champs facultatifs avec dérivation automatique

Champ	Comportement
`database_specific.severity`	Si elle est fournie, utilisée comme étiquette de gravité qualitative (`critical`, `high`, `moderate`ou `low`). En cas d’absence, la gravité est automatiquement dérivée du score de vecteur CVSS.
`summary`	S'il est absent, la valeur du champ `id` est utilisée à la place.
`details`	En cas d’absence, revient à `summary` ou `id`.

Types de gravité pris en charge

Type de gravité	Support
`CVSS_V3`
Pris en charge. Doit être une chaîne de vecteur CVSS 3.1 valide.
`CVSS_V4`
Pris en charge. Doit être une chaîne de vecteur CVSS 4.0 valide.
Autres types
Non pris en charge. Génère une erreur d’analyse.

Types de référence pris en charge

Type de référence	Support
`ADVISORY`	Supported
`WEB`	Supported
`FIX`	Supported
`ARTICLE`	Supported
`REPORT`	Supported
`PACKAGE`	Pris en charge (mappé vers l'emplacement du code source)
`EVIDENCE`	Pris en charge (ignoré lors du traitement)
`DETECTION`
Non pris en charge. Supprimé pendant le traitement.

Prise en charge des alias

Format d’alias	Support
`CVE-YYYY-NNNNN`
Pris en charge. Extrait comme identifiant CVE. Seul le premier alias CVE est utilisé.
Autres formats (GHSA, PYSEC, etc.)
Non pris en charge. Retiré au cours du traitement.

Remarque

Si le champ de vulnérabilité id commence par GHSA-, il est reconnu comme identificateur GHSA. Toutefois, les entrées GHSA dans le aliases tableau sont supprimées et non conservées.

Contraintes de taille de champ

La spécification OSV ne définit pas de longueurs de chaîne maximales pour un champ , toutes les chaînes ne sont pas liées. Toutefois, GitHub applique des limites de taille de champ en fonction de son schéma de base de données interne. Ces limites ne peuvent pas être assouplies sans interrompre la synchronisation avec GitHub Enterprise Server, qui conserve son propre schéma compatible.

Les soumissions dépassant ces limites sont rejetées avec une erreur descriptive 422 indiquant quel champ a dépassé la limite et la longueur réelle fournie (par exemple). affected[0].first_patched_version is 63 characters (max 50)

| Champ OSV | Correspond à | Limite standard d’OSV | GitHub Limite | Unit | |---|---|---|---|---| | summary | vulnerabilities.summary | Aucune limite (≤120 caractères recommandés) | 1 024 | octets | | id | vulnerabilities.external_id | Aucune limite | 2 048 | caractères | | aliases[] (Entrée CVE) | vulnerabilities.cve_id | Aucune limite | 20 | caractères | | severity[].score (CVSS v3) | vulnerabilities.cvss_v3 | Aucune limite | 255 | octets | | severity[].score (CVSS v4) | vulnerabilities.cvss_v4 | Aucune limite | 255 | caractères | | affected[].package.ecosystem | vulnerable_version_ranges.ecosystem | Aucune limite | 20 | caractères | | affected[].package.name | vulnerable_version_ranges.affects | Aucune limite | 255 | caractères | | affected[].ranges[].events[].fixed | vulnerable_version_ranges.fixed_in | Aucune limite | 50 | caractères | | Plage de versions vulnérables calculée | vulnerable_version_ranges.requirements | Aucune limite | 65,535 | octets |

Remarque

La fixed_in limite (première version corrigée) de 50 caractères est la contrainte la plus couramment rencontrée. Certains écosystèmes utilisent des chaînes de version préliminaire longues (p. ex., 1.0.0-alpha.gamma.delta.epsilon.zeta.eta.theta) qui dépassent cette limite.

varchar les colonnes sont validées par nombre de caractères ; varbinary et text les colonnes sont validées par taille d’octet (pertinentes pour les caractères UTF-8 multioctets).

Ces limites sont limitées par la GitHub Enterprise Server compatibilité de schéma. L’élargissement des colonnes sur GitHub sans modifications correspondantes dans GHES provoquerait des échecs de synchronisation des avis de sécurité entre les environnements.

Mappage de l’écosystème

GitHub associe les noms d’écosystème OSV à ses identifiants internes d’écosystème. Les écosystèmes suivants sont pris en charge :

| Écosystème OSV | GitHub Écosystème | |---|---| | npm | npm | | PyPI | pip | | RubyGems | RubyGems | | Maven | Maven | | NuGet | NuGet | | Packagist | Compositeur | | Go | Go | | crates.io | Rust | | Hex | Erlang | | Pub | Pub | | SwiftURL | Swift | | GitHub Actions | GitHub Actions |

Exemple : charge utile OSV minimale pour la génération d’alertes

Voici une charge utile OSV minimale qui contient tous les champs requis pour GitHub créer une Dependabot alerte :

{
  "schema_version": "1.4.0",
  "id": "EXAMPLE-2024-001",
  "modified": "2024-01-15T10:00:00Z",
  "summary": "Example vulnerability in example-package",
  "details": "A detailed description of the vulnerability.",
  "aliases": ["CVE-2024-12345"],
  "severity": [
    {
      "type": "CVSS_V3",
      "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
    }
  ],
  "affected": [
    {
      "package": {
        "ecosystem": "npm",
        "name": "example-package"
      },
      "ranges": [
        {
          "type": "ECOSYSTEM",
          "events": [
            { "introduced": "0" },
            { "fixed": "1.2.3" }
          ]
        }
      ]
    }
  ],
  "database_specific": {
    "severity": "Critical"
  },
  "references": [
    { "type": "ADVISORY", "url": "https://example.com/advisory" }
  ],
  "published": "2024-01-15T10:00:00Z"
}

Limitations connues

100 vulnérabilités maximales par requête. L’API de synchronisation accepte au maximum 100 vulnérabilités dans une seule requête.
Aucun type de plage GIT. Les plages de versions basées sur la validation Git ne sont pas prises en charge.
Types d’événements distincts par gamme ECOSYSTEM. Chaque plage ECOSYSTEM prend en charge un introduced et un événement de limite supérieure (fixed ou last_affected). Plusieurs introduced/fixed paires dans une plage unique ECOSYSTEM ne sont pas prises en charge : utilisez des plages distinctes ou des entrées distinctes affected à la place. (Cette limitation ne s’applique pas aux SEMVER plages qui prennent en charge plusieurs paires d’événements.)
fixed et last_affected s’excluent mutuellement. Une même plage ne peut pas contenir à la fois les événements fixed et last_affected. Utilisez l’un ou l’autre.
Compatibilité de synchronisation GHES. Les limites de taille des champs (par exemple fixed_in à 50 caractères) sont imposées par les exigences de compatibilité du schéma GitHub Enterprise Server.

Dans cet article

Prerequisites

Créer des avis innersource

Étape 1 : Créer un GitHub App

Étape 2 : Générer un jeton d’accès

Étape 3 : Télécharger une description de l’avis

Utilisation des recommandations InnerSource

Retrait des avis sur les ressources internes

Prise en charge et limitations du format OSV

Version de schéma OSV prise en charge

Formatage des entrées affectées

Types de plages pris en charge

Champs obligatoires

Champs facultatifs avec dérivation automatique

Types de gravité pris en charge

Types de référence pris en charge

Prise en charge des alias

Contraintes de taille de champ

Mappage de l’écosystème

Exemple : charge utile OSV minimale pour la génération d’alertes

Limitations connues