Meilleures pratiques pour l’écriture des avis de sécurité de référentiels

À propos des avis de sécurité pour les référentiels

Les avis de sécurité des référentiels permettent aux gestionnaires de dépôts publics de discuter d’une faille de sécurité dans un projet et de la résoudre en privé. Après avoir collaboré sur un correctif, ils peuvent publier l’avis de sécurité pour rendre publique la vulnérabilité de sécurité auprès de la communauté du projet. En publiant des avis de sécurité, les chargés de maintenance des dépôts facilitent la mise à jour des dépendances de package pour leur communauté et la recherche de l’impact des vulnérabilités de sécurité. Pour plus d’informations, consultez À propos des avis de sécurité des référentiels.

Nous vous recommandons d’utiliser la syntaxe de la GitHub Advisory Database, en particulier la mise en forme de la version, quand vous écrivez un avis de sécurité de référentiel ou que vous apportez une contribution de la communauté à un avis de sécurité global.

Si vous respectez la syntaxe de la GitHub Advisory Database, en particulier quand vous définissez les versions affectées :

• Quand vous publiez votre avis de référentiel, nous pouvons ajouter votre avis à la GitHub Advisory Database en tant qu’avis « GitHub-reviewed », sans devoir demander plus d’informations.
• Dependabot a les informations nécessaires pour identifier exactement les référentiels affectés et leur envoyer des Dependabot alerts pour les avertir.
• Les membres de la communauté sont moins susceptibles de suggérer des modifications de votre avis pour corriger les informations manquantes ou incorrectes.

Vous ajoutez ou modifiez un avis de référentiel à l’aide du formulaire Brouillon d’avis de sécurité. Pour plus d’informations, consultez « Création d’un avis de sécurité de dépôt ».

Vous suggérez l’amélioration d’un avis global existant à l’aide du formulaire Améliorer un avis de sécurité. Pour plus d’informations, consultez « Modification des avis de sécurité dans la base de données d’avis de GitHub ».

Écosystème

Vous devez attribuer l’avis à l’un des écosystèmes pris en charge à l’aide du champ Écosystème. Pour plus d’informations sur les écosystèmes que nous prenons en charge, consultez Exploration des avis de sécurité dans la base de données GitHub Advisory.

Nom du package

Nous vous recommandons d’utiliser le champ Nom du package pour spécifier les packages affectés, car les informations de package sont nécessaires pour les avis « GitHub-reviewed » dans la GitHub Advisory Database. Les informations sur le package sont facultatives pour les avis de sécurité au niveau du référentiel. Toutefois, l’ajout de ces informations dès le début simplifie le processus de révision quand vous publiez votre avis de sécurité.

Versions affectées

Nous vous recommandons d’utiliser le champ Versions affectées pour spécifier les versions concernées, car ces informations sont nécessaires pour les avis « GitHub-reviewed » dans la GitHub Advisory Database. Les informations de version sont facultatives pour les avis de sécurité au niveau du référentiel. Toutefois, l’ajout de ces informations dès le début simplifie le processus de révision quand vous publiez votre avis de sécurité.

Pour plus d’informations sur la GitHub Advisory Database, consultez https://github.com/github/advisory-database.

Glossaire

•           **Plage de versions vulnérables (VVR) :** plage de versions affectées par une vulnérabilité logicielle donnée.
  

•           **Opérateur :** tout symbole indiquant la limite d’une plage de versions vulnérables.
  

•           **Format Open Source Vulnerability (OSV) :**  format avec lequel les données de la base de données de vulnérabilités GitHub Advisory Database s’efforcent d’être compatibles.
  

Syntaxe de version

• Les nombres plus petits correspondent à des versions antérieures aux nombres plus grands. par exemple, 1.0.0 est une version antérieure à 2.0.0
• Les lettres situées plus tôt dans l’alphabet correspondent à des versions antérieures à celles situées plus tard dans l’alphabet. Par exemple, 2.0.0-a est une version antérieure à 2.0.0-b.
• Toute lettre apparaissant après un nombre est considérée comme faisant partie d’une préversion ; ainsi, toute version comportant des lettres après les nombres est antérieure à une version ne comportant que des nombres dans son numéro de version. Par exemple, 2.0.0-alpha, 2.0.0-beta et 2.0.0-rc sont antérieurs à 2.0.0.
• Une version corrigée ne peut pas être inférieure au nombre le plus élevé de la plage de versions vulnérables (VVR). Par exemple, une version vulnérable est publiée et le mainteneur recommande de revenir à une version antérieure. Le mainteneur ne peut pas indiquer cette version inférieure comme version corrigée ou patchée dans le champ Fixed, car cette version est antérieure à la version vulnérable.

Opérateurs pris en charge

•           `>=` pour « supérieur ou égal à cette version ».
  

•           `>` pour « supérieur à cette version ».
  

  Avertissement

  Bien que GitHub prenne en charge l’utilisation de l’opérateur >, l’usage de cet opérateur n’est pas recommandé, car il n’est pas pris en charge par le format OSV.

•           `=` pour « égal à cette version ».
  

•           `<=` pour « inférieur ou égal à cette version ».
  

•           `<` pour « inférieur à cette version ».
  

Spécifier les versions affectées sur GitHub

Il est important de définir clairement les versions affectées pour un avis de sécurité. GitHub propose plusieurs options dans le champ Versions affectées afin de vous permettre de spécifier des plages de versions vulnérables.

Pour consulter des exemples montrant comment les versions affectées sont définies dans certains avis de sécurité existants, consultez Exemples.

• Une chaîne de version affectée valide est constituée de l’un des éléments suivants :

  • Séquence d’opérateur de limite inférieure.

  • Séquence d’opérateur de limite supérieure.

  • Séquence d’opérateurs de limite supérieure et inférieure. La borne inférieure doit apparaître en premier, suivie d’une virgule et d’une espace, puis de la borne supérieure.

  • Une séquence de version spécifique utilisant l’opérateur d’égalité (=).

  • Chaque séquence d’opérateur doit être spécifiée avec l’opérateur, un espace, puis la version. Pour en savoir plus sur les opérateurs valides, consultez Opérateurs pris en charge ci-dessus.

  • La version doit commencer par un chiffre suivi d’un nombre quelconque de chiffres, de lettres, de points, de tirets ou de traits de soulignement (tout sauf un espace ou une virgule). Pour en savoir plus sur la mise en forme des versions, consultez Syntaxe des versions ci-dessus.

  Remarque

  Les chaînes de versions affectées ne peuvent pas contenir d’espaces de début ou de fin.

• Les opérateurs de limite supérieure peuvent être inclusifs ou exclusifs, c’est-à-dire <= ou < respectivement.

• Les opérateurs de limite inférieure peuvent être inclusifs ou exclusifs, c’est-à-dire >= ou > respectivement. Toutefois, si vous publiez votre avis de référentiel et que nous convertissons votre avis de référentiel en avis global, une règle différente s’applique : les chaînes de limite inférieure doivent être inclusives, c’est-à-dire >=. L’opérateur de limite inférieure exclusif (>) est autorisé uniquement si la version est 0, par exemple > 0.

• Utilisation appropriée des espaces

  • Utilisez un espace entre un opérateur et un numéro de version.

  • N’utilisez pas d’espace dans >= ou <=.

  • N’utilisez pas d’espace entre un nombre et une virgule dans >= lower bound, <= upper bound.

  • Utilisez un espace entre une virgule et l’opérateur de borne supérieure.

  Remarque

  La limitation de la limite inférieure :

  • Est due à des incompatibilités avec le schéma OSV.
  • S’applique uniquement quand vous faites une suggestion sur un avis existant dans la GitHub Advisory Database.

• Vous ne pouvez pas spécifier plusieurs plages de versions affectées dans le même champ comme > 2.0, < 2.3, > 3.0, < 3.2. Pour spécifier plusieurs plages, vous devez créer une section Produits affectés pour chaque plage, en cliquant sur le bouton + Ajouter un autre produit affecté.

  

• Si la plage de versions affectées comprend une seule limite supérieure ou inférieure :

  • La valeur implicite est toujours > 0 si la limite inférieure n’est pas spécifiée explicitement.
  • La valeur implicite est toujours infinie si la limite supérieure n’est pas spécifiée explicitement.

Définir uniquement une borne supérieure pour une plage de versions vulnérables (VVR)

• Si vous définissez uniquement une borne supérieure, utilisez <= ou <.
• La base de données d’avis de sécurité GitHub Advisory Database utilise la base de données PyPA comme l’une de ses sources de données. Cependant, GitHub ne correspond pas exactement au format de plage de versions vulnérables (VVR) de PyPA (les avis de sécurité PyPA utilisent souvent >= 0, <= n ou >= 0, < n pour désigner des plages de versions ne comportant qu’une borne supérieure).
• Il n’est pas nécessaire d’inclure >= 0 dans une plage qui ne comporte qu’une borne supérieure.

Définir uniquement une borne inférieure pour une plage de versions vulnérables (VVR)

• L’équipe de curation des avis de sécurité ne recommande pas de définir uniquement des bornes inférieures pour un avis, sauf dans le cas des logiciels malveillants. En effet, si une version corrigée est publiée ultérieurement, les utilisateurs de cette version corrigée continueront de recevoir inutilement des alertes Dependabot alerts jusqu’à ce que l’avis soit mis à jour manuellement.
• Utilisez >= 0 pour toutes les versions

•           `> 0` n’est généralement pas utilisé.
  

Spécifier une seule version affectée

•           `= n` pour la seule version affectée
  

• Gardez à l’esprit que l’opérateur = n’inclura pas automatiquement les versions de prévisualisation publiques ou privées, mais uniquement la version spécifiée.

Erreurs courantes

• Évitez d’utiliser une plage de versions vulnérables de type < n, puis d'indiquer que n+1 est corrigée.

  •           `< n` ne doit être utilisé que lorsque `n` n’est pas vulnérable.
    

  • Dans ce cas, le VVR doit être <= n or < n+1.

• Évitez d’utiliser uniquement un nombre pour décrire des versions corrigées lorsque les numéros de version officiels contiennent des lettres. Supposons que votre logiciel comporte deux branches, linux et windows. Lorsque vous publiez 2.0.0-linux et 2.0.0-windows, utiliser < 2.0.0 comme version vulnérable marquera 2.0.0-linux et 2.0.0-windows comme vulnérables, car la logique de version interprète -linux et -windows comme des préversions. Vous devrez indiquer 2.0.0-linux, la branche apparaissant en premier dans l’ordre alphabétique, comme première version corrigée afin d’éviter que 2.0.0-linux et 2.0.0-windows soient considérées comme vulnérables.

Examples

Avis de sécurité comportant plusieurs plages de versions vulnérables (VVR) et plusieurs opérateurs

          [L’authentification TLS de la passerelle Etcd s’applique uniquement aux points de terminaison détectés dans les enregistrements DNS SRV (GHSA-wr2v-9rpq-c35q)](https://github.com/advisories/GHSA-wr2v-9rpq-c35q) et comporte deux plages de versions vulnérables :

•           `< 3.3.23`, qui comporte une borne supérieure sans borne inférieure et utilise l’opérateur `<`.
  

•           `>= 3.4.0-rc.0, <= 3.4.9`, qui comporte à la fois une borne inférieure et une borne supérieure, et utilise les opérateurs `>=` et `<=`.
  

Avis de sécurité illustrant la relation entre une préversion et une version stable

          [XWiki Platform permet des attaques XSS via le nom de XClass dans les propriétés de type chaîne (GHSA-wcg9-pgqv-xm5v)](https://github.com/advisories/GHSA-wcg9-pgqv-xm5v) et comporte quatre plages de versions vulnérables :

• >= 1.1.2, < 14.10.21
• >= 15.0-rc-1, < 15.5.5
• >= 15.6-rc-1, < 15.10.6
• = 16.0.0-rc-1

Trois de ces plages de versions vulnérables (VVR) incluent des préversions dans la plage des versions vulnérables. La dernière plage de versions vulnérables, = 16.0.0-rc-1, montre que seule la version 16.0.0-rc-1 est vulnérable, tandis que la version stable publiée ensuite, 16.0.0, ne l’est pas La logique considère 16.0.0-rc-1 et 16.0.0 comme des versions distinctes, 16.0.0-rc-1 étant une version antérieure à 16.0.0.

Le correctif de cette vulnérabilité a été publié le 24 janvier 2024 pour la version 16.0.0. Pour en savoir plus, consultez commit 27eca84 dans le référentiel xwiki/xwiki-platform . La page XWiki Platform Old Core sur le site MVN Repository montre que la version 16.0.0-rc-1 a été publiée le 22 janvier 2024, avant que le correctif ne soit ajouté à XWiki, et que la version 16.0.0 a été publiée le 29 janvier 2024, après l’intégration du correctif.

Avis de sécurité comportant des noms de branches dans les numéros de version

          [Google Guava](https://mvnrepository.com/artifact/com.google.guava/guava) compte deux branches, `android` et `jre`, dans ses versions publiées.               [Guava vulnérable à une utilisation non sécurisée du répertoire temporaire (GHSA-7g45-4rm6-3mm3)](https://github.com/advisories/GHSA-7g45-4rm6-3mm3) et [Divulgation d’informations dans Guava (GHSA-5mg8-w23w-74h3)](https://github.com/advisories/GHSA-5mg8-w23w-74h3) sont des avis de sécurité concernant des vulnérabilités qui affectent Guava. Les deux avis de sécurité définissent `32.0.0-android` comme version corrigée.

• La logique de gestion des plages de versions interprète les lettres après 32.0.0 comme des préversions ; ainsi, si vous définissez la version corrigée sur 32.0.0, les versions 32.0.0-android et 32.0.0-jre seraient toutes deux incorrectement marquées comme vulnérables.
• La logique de gestion des plages de versions interprète les lettres plus avancées dans l’alphabet comme des versions ultérieures à celles plus précoces ; ainsi, si vous définissez la version corrigée sur 32.0.0-jre, la version 32.0.0-android serait incorrectement marquée comme vulnérable.

La meilleure façon d’indiquer que 32.0.0-android et 32.0.0-jre sont tous deux corrigés consiste à utiliser 32.0.0-android comme version corrigée ; la logique interprétera alors toutes les versions qui suivent 32.0.0-android dans l’ordre alphabétique comme corrigées.