Skip to main content

Bewährte Methoden für das Schreiben von Sicherheitsempfehlungen für Repositorys

Wenn du Sicherheitsempfehlungen erstellst oder bearbeitest, sind die bereitgestellten Informationen für andere Benutzer*innen einfacher zu verstehen, wenn du das Ökosystem, den Paketnamen und die betroffenen Versionen in den gängigen Formaten angibst.

Alle Benutzer*innen mit Administratorberechtigungen für ein Repository können Sicherheitsempfehlungen erstellen und bearbeiten.

Hinweis: Wenn du Sicherheitsforscher bist, solltest du dich direkt an die Betreuer wenden und sie bitten, Sicherheitshinweise zu erstellen oder in deinem Auftrag CVEs in Repositorys zu erstellen, die nicht von dir verwaltet werden. Wenn jedoch das private Melden von Sicherheitsrisiken für das Repository aktiviert ist, können Sie selbst ein Sicherheitsrisiko privat melden. Weitere Informationen findest du unter Privates Melden eines Sicherheitsrisikos.

Informationen zu Sicherheitsempfehlungen für Repositorys

Mithilfe von Sicherheitsempfehlungen für Repositorys können Repositoryverwalter*innen ein Sicherheitsrisiko in einem Projekt privat besprechen und beheben. Nach der Zusammenarbeit an einer Lösung können Repositoryverwalter die Sicherheitsempfehlung veröffentlichen, um das Sicherheitsrisiko öffentlich für die Community des Projekts offenzulegen. Durch die Veröffentlichung von Sicherheitsempfehlungen erleichtern Repositoryverwalter ihrer Community das Aktualisieren von Paketabhängigkeiten und das Untersuchen der Auswirkungen von Sicherheitsrisiken. Weitere Informationen findest du unter Informationen zu Sicherheitsempfehlungen für Repositorys.

Bewährte Methoden

Beim Schreiben einer Sicherheitsempfehlung oder bei Beiträgen zu einer globalen Sicherheitsempfehlung wird empfohlen, die in GitHub Advisory Database verwendete Syntax zu übernehmen, insbesondere die Versionsformatierung.

Die Verwendung der Syntax für GitHub Advisory Database hat die folgenden Vorteile, insbesondere bei der Angabe der betroffenen Versionen:

  • Wenn du die Repositoryempfehlung veröffentlichst, können wir diese zu GitHub Advisory Database mit der Bezeichnung „Von GitHub geprüft“ hinzufügen, ohne dich um weitere Informationen zu bitten.
  • Dependabot verfügt über die nötigen Informationen, um betroffene Repositorys präzise zu ermitteln und diese über Dependabot alerts zu benachrichtigen.
  • Communitymitglieder schlagen seltener Änderungen an deiner Empfehlung vor, um fehlende oder falsche Informationen zu korrigieren.

Du kannst eine Repositoryempfehlung mithilfe des Formulars Sicherheitsempfehlung entwerfen hinzufügen oder bearbeiten. Weitere Informationen findest du unter Erstellen einer Sicherheitsempfehlung für ein Repository.

Verbesserungen an einer vorhandenen globalen Empfehlung kannst du über das Formular Sicherheitsempfehlung verbessern vorschlagen. Weitere Informationen findest du unter Bearbeiten von Sicherheitshinweisen in GitHub Advisory Database.

Ökosystem

Du musst die Empfehlung einem der unterstützten Ökosysteme zuweisen, indem du das Feld Ökosystem ausfüllst. Weitere Informationen zu den von uns unterstützten Ökosystemen findest du unter Durchsuchen von Sicherheitsempfehlungen in der GitHub Advisory Database.

Screenshot: Bereich „Betroffene Produkte“ des Formulars für Sicherheitsempfehlungen. Das Feld „Ökosystem“ ist dunkelorange umrandet.

Paketname

Es wird empfohlen, über das Feld Paketname anzugeben, welche Pakete betroffen sind. Diese Paketinformationen sind für Empfehlungen mit der Bezeichnung „Von GitHub geprüft“ in GitHub Advisory Database erforderlich. Paketinformationen sind für Sicherheitsempfehlungen auf Repositoryebene optional, aber das frühzeitige Angeben dieser Informationen vereinfacht den Überprüfungsprozess beim Veröffentlichen von Sicherheitsempfehlungen.

Betroffene Versionen

Es wird empfohlen, über das Feld Betroffene Versionen anzugeben, welche Versionen betroffen sind. Diese Informationen sind für Empfehlungen mit der Bezeichnung „Von GitHub geprüft“ in GitHub Advisory Database erforderlich. Versionsinformationen sind für Sicherheitsempfehlungen auf Repositoryebene optional, aber das frühzeitige Angeben dieser Informationen vereinfacht den Überprüfungsprozess beim Veröffentlichen von Sicherheitsempfehlungen.

  • Eine gültige Zeichenfolge für betroffene Versionen besteht aus einem der folgenden Elemente:

    • Einer Operatorsequenz für die Untergrenze
    • Einer Operatorsequenz für die Obergrenze
    • Einer Operatorsequenz für die Unter- und Obergrenze
    • Einer speziellen Versionssequenz mit dem Gleichheitsoperator (=)
  • Jede Operatorsequenz muss im Format „Operator, einzelnes Leerzeichen, Version“ angegeben werden.

    • Gültige Operatoren sind =, <, <=, > oder >=.
    • Die Version muss mit einer Zahl beginnen, gefolgt von einer beliebigen Anzahl von Zahlen, Buchstaben, Punkten, Bindestrichen oder Unterstrichen (kein Leerzeichen oder Komma).
    • Wenn eine Sequenz für die Unter- und Obergrenze angegeben wird, muss zuerst die Untergrenze stehen, gefolgt von einem Komma und einem einzelnen Leerzeichen. Dann folgt die Obergrenze.

    Hinweis: Die Zeichenfolgen für betroffene Versionen dürfen keine führenden oder nachgestellten Leerzeichen enthalten.

  • Operatoren für die Obergrenze können inklusiv (<=) oder exklusiv (<) sein.

  • Operatoren für die Untergrenze können inklusiv (>=) oder exklusiv (>) sein. Wenn du deine Repositoryempfehlung veröffentlichst und diese zu einer globalen Empfehlung hochgestuft wird, gilt jedoch eine andere Regel: Zeichenfolgen für die Untergrenze dürfen nur inklusiv (>=) sein. Der exklusive Operator für die Untergrenze (>) ist nur bei 0 zulässig, also zum Beispiel > 0.

    Hinweise: Die Einschränkung für die Untergrenze

    • besteht aufgrund von Inkompatibilitäten mit dem OSV-Schema (Open Source Vulnerability).
    • gilt nur, wenn ein Vorschlag für eine vorhandene Empfehlung in GitHub Advisory Database eingereicht wird.
  • Du kannst in einem Feld nicht mehrere betroffene Versionsbereiche angeben, zum Beispiel > 2.0, < 2.3, > 3.0, < 3.2. Wenn du mehr als einen Bereich angeben möchtest, musst du für jeden Bereich einen neuen Abschnitt Betroffene Produkte erstellen. Klicke hierfür auf + Weiteres betroffenes Produkt hinzufügen.

    Screenshot: Bereich „Betroffene Produkte“ des Formulars für Sicherheitsempfehlungen. Ein Link mit der Bezeichnung „Weiteres betroffenes Produkt hinzufügen“ ist dunkelorange umrandet.

  • Wenn der betroffene Versionsbereich nur eine Ober- oder Untergrenze enthält:

    • Der implizite Wert ist immer > 0, wenn die Untergrenze nicht explizit angegeben ist.
    • Der implizite Wert ist immer unendlich, wenn die Obergrenze nicht explizit angegeben ist.

Weitere Informationen zu GitHub Advisory Database findest du unter https://github.com/github/advisory-database.