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

Toute personne disposant des autorisations d’administrateur sur un référentiel public peut créer et modifier un avis de sécurité.

À 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. »

Meilleures pratiques

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é.

• 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.
  • 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.

  • Les opérateurs valides sont =, <, <=, > ou >=.
  • 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)
  • Quand vous spécifiez une séquence de limites supérieure et inférieure, la limite inférieure doit être indiquée en premier, suivie d’une virgule et d’un espace, puis de la limite supérieure.

  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.

  Remarques : la limitation de la limite inférieure :

  • Est due à des incompatibilités avec le schéma OSV (Open Source Vulnerability).
  • 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.

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