Verwalten von Innersource-Empfehlungen

Hintergrundinformationen zur Funktionsweise von Innersource-Empfehlungen und deren Erstellung finden Sie unter Innersource advisories.

Voraussetzungen

Innersource-Empfehlungen können nur in Unternehmen mit einer aktiven GitHub Code Security oder GitHub Advanced Security Lizenz erstellt werden.

Erstellen von Innersource-Empfehlungen

So erstellen Sie eine Innersource-Empfehlung:

Erstellen und installieren Sie eine GitHub App mit der enterprise_innersource_vulnerabilities Berechtigung.
Generieren Sie ein Token, das der App zugeordnet ist, die Zugriff auf diese Berechtigung hat write .
Erstellen Sie eine Beschreibung der Sicherheitsanfälligkeit im OSV-Format und POST sie an den REST-API-Endpunkt /enterprises/{enterprise}/innersource-vulnerabilities/sync.

Jede dieser Schritte wird unten ausführlicher beschrieben.

Schritt 1: Erstellen eines GitHub App

Registrieren Sie ein GitHub App Unternehmen, das im Besitz Ihres Unternehmens ist, und erteilen Sie ihm die enterprise_innersource_vulnerabilities Berechtigung mit read and write Zugriff. Siehe Registrieren einer GitHub-App.

Nachdem Sie die App registriert haben, installieren Sie sie in Ihrem Unternehmen, damit sie im Namen des Unternehmens handeln kann.

Schritt 2: Generieren eines Zugriffstokens

Authentifizieren Sie sich als GitHub App Installation, um ein Installationszugriffstoken zu generieren. Dieses Token trägt die enterprise_innersource_vulnerabilities Berechtigung und wird verwendet, um Ihre Anforderungen an die REST-API zu authentifizieren. Siehe Generieren eines Installationszugriffstokens für eine GitHub App.

Schritt 3: Hochladen einer Empfehlungsbeschreibung

Beschreiben Sie die Sicherheitsanfälligkeit im OSV-Format, und verwenden Sie dann POST die Nutzlast /enterprises/{enterprise}/innersource-vulnerabilities/syncfür die Authentifizierung mithilfe des Installationszugriffstokens. Die Nutzlast identifiziert das betroffene Paket und den Bereich anfälliger Versionen. Wenn eine feste Version verfügbar ist, schließen Sie ein fixed Feld mit der Versionsnummer ein, sodass Dependabot Pullanforderungen zum Aktualisieren betroffener Repositorys geöffnet werden können.

Ausführliche Informationen zum Empfehlungsschema finden Sie unter REST-API-Endpunkte für Sicherheitsempfehlungen.

Verwenden von Innersource-Empfehlungen

Nachdem Sie eine Innersource-Empfehlung erstellt haben, erhalten Repositorys im Unternehmen, die die betroffene Komponente verwenden, Warnungen und Updates.

Stellen Sie sicher, dass die Repositorys in Ihrem Unternehmen aktiviert sind und Updates aktiviert sind Dependabot alerts . Sie können dies im großen Maßstab mithilfe einer Sicherheitskonfiguration erzwingen. Siehe Erstellen einer benutzerdefinierten Sicherheitskonfiguration.
Sehen Sie sich die Seite der abhängigen Repositorys Dependabot alerts an, um eine neue Benachrichtigung über die betroffene Komponente zu erhalten. Die Warnung weist eine eindeutige Bezeichnung "Innersource" darauf auf, um sie von Open Source Empfehlungswarnungen zu unterscheiden.
Wenn Ihre Empfehlungsnutzlast ein fixed Feld mit einer Versionsnummer enthält, die einem verfügbaren Paket entspricht, wird auch eine Pullanforderung erstellt, Dependabot die die Manifestdatei des Paket-Managers aktualisiert. Siehe Konfigurieren von Dependabot-Versionsupdates.

Zurückziehen von Innersource-Empfehlungen

Wenn keine anfälligeren Versionen einer betroffenen Komponente verwendet werden, oder wenn eine Empfehlung abgelöst wird, kann es hilfreich sein, sie zurückzuziehen.

Verwenden Sie zum Zurückziehen einer Empfehlung den gleichen REST-API-Endpunkt wie der Erstellungsschritt, passen Sie die Nutzlast jedoch an, um einen withdrawn Schlüssel einzuschließen, dessen Wert ein date-time Feld ist, das angibt, wann die Sicherheitsanfälligkeit zurückgezogen wurde.

Unterstützung und Einschränkungen des OSV-Formats

GitHub akzeptiert Sicherheitsrisiken im Open Source-Sicherheitsrisikoformat (OSV) über die Synchronisierungs-API für innere Quellen. Während GitHub die Kompatibilität mit der OSV-Spezifikation angestrebt wird, gibt es Unterschiede zwischen dem standardmäßigen OSV-Schema und den GitHub Anforderungen oder Unterstützungen.

Unterstützte OSV-Schemaversion

GitHub unterstützt OSV-Schemaversionen, die mit ~> 1.0 (d. h. 1.0.0 durch 1.x.x) kompatibel sind. Die empfohlene Schemaversion ist 1.4.0.

Betroffene Eintragsformatierung

Mit der OSV-Spezifikation kann ein einzelner affected Eintrag mehrere ranges und mehrere versions für dasselbe Paket enthalten. GitHub normalisiert diese intern, indem sie in separate Einträge aufgeteilt werden:

| OSV-Standard | GitHub Verhalten | |---|---| | Ein einzelner affected Eintrag kann mehrere enthalten ranges | Accepted. Jeder Bereich wird als separater anfälliger Versionsbereich verarbeitet. | | Ein einzelner affected Eintrag kann mehrere enthalten versions | Accepted. Jede Version wird als genaue Übereinstimmung (= x.y.z) behandelt und als separater anfälliger Versionsbereich verarbeitet. | | Ein einzelner affected Eintrag kann mischen ranges und versions | Accepted. Bereiche und Versionen werden intern in separate Einträge aufgeteilt. | | Ein SEMVER Bereich kann mehrere introduced/fixed Paare enthalten. | Accepted. Mehrere zusammenhängende Intervalle (z. B. [1.0.0, 1.0.2) und [3.0.0, 3.2.5)) innerhalb eines einzelnen Bereichs werden unterstützt. |

Unterstützte Bereichstypen

Bereichstyp	Support
`ECOSYSTEM`
Vollständig unterstützt. Unterstützt `introduced`, `fixed`und `last_affected` Ereignisse.
`SEMVER`
Vollständig unterstützt. Unterstützt `introduced`, `fixed`und `last_affected` Ereignisse. Das `last_affected` Ereignis wird als Obergrenzeskomparator `<=` analysiert.
`GIT`
Nicht unterstützt. Git commit-basierte Bereiche werden nicht verarbeitet.

Hinweis

Für ECOSYSTEM Bereiche wird nur ein introduced und ein fixed (oder last_affected) Ereignis pro Bereich unterstützt. Wenn Sie mehrere nicht zusammenhängende Versionsbereiche für dasselbe Paket ausdrücken müssen, verwenden Sie separate affected Einträge oder separate Bereiche.

SEMVER Bereiche unterstützen mehrere introduced/fixed Paare innerhalb eines einzelnen Bereichs (z. B [1.0.0, 1.0.2) . und [3.0.0, 3.2.5) in einem Ereignisarray).

- fixed und last_affectedkann nicht zusammen im selben Bereich angezeigt werden. Verwenden Sie einen oder den anderen, mit Der Einstellung für fixed.

Pflichtfelder

Die OSV-Spezifikation behandelt mehrere Felder als optional, erfordert sie jedoch GitHub . Anforderungen, die diese Felder fehlen, werden mit einem Fehler von 422 abgelehnt.

| Feld | OSV-Spezifikation | GitHub Anforderung | |---|---|---| | id | Erforderlich | Required. Wird als externer Bezeichner für die Sicherheitsanfälligkeit verwendet. | | severity Array | Fakultativ | Erforderlich. Muss mindestens einen oder CVSS_V4 einen CVSS_V3 Eintrag mit einer nicht leeren score Zeichenfolge (z. CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:HB. ) enthalten. Anforderungen ohne gültigen CVSS-Eintrag werden abgelehnt. | | affected[].package.ecosystem | Erforderlich | Muss ein unterstütztes Ökosystem sein | | affected[].ranges oder affected[].versions | Mindestens ein erforderlicher | Mindestens ein Bereich oder eine Version muss für den Warnungsabgleich vorhanden sein. |

Optionale Felder mit automatischer Ableitung

Feld	Behavior
`database_specific.severity`	Wenn angegeben, wird als qualitative Schweregradbezeichnung (`critical`, `high`, , `moderate`oder `low`) verwendet. Wenn dieser Wert nicht vorhanden ist, wird der Schweregrad automatisch von der CVSS-Vektorbewertung abgeleitet .
`summary`	Falls nicht vorhanden, fällt sie auf das `id` Feld zurück.
`details`	Wenn nicht vorhanden, fällt zurück auf `summary` oder `id`.

Unterstützte Schweregradtypen

Schweregradtyp	Support
`CVSS_V3`
Unterstützt. Muss eine gültige CVSS 3.1-Vektorzeichenfolge sein.
`CVSS_V4`
Unterstützt. Muss eine gültige CVSS 4.0-Vektorzeichenfolge sein.
Andere Typen
Nicht unterstützt. Führt zu einem Analysefehler.

Unterstützte Referenztypen

Referenztyp	Support
`ADVISORY`	Unterstützt
`WEB`	Unterstützt
`FIX`	Unterstützt
`ARTICLE`	Unterstützt
`REPORT`	Unterstützt
`PACKAGE`	Unterstützt (zugeordnet am Quellcodespeicherort)
`EVIDENCE`	Unterstützt (während der Verarbeitung ignoriert)
`DETECTION`
Nicht unterstützt. Während der Verarbeitung entfernt.

Aliasunterstützung

Aliasformat	Support
`CVE-YYYY-NNNNN`
Unterstützt. Extrahiert als CVE-Bezeichner. Nur der erste CVE-Alias wird verwendet.
Andere Formate (GHSA, PYSEC usw.)
Nicht unterstützt. Während der Verarbeitung entfernt.

Hinweis

Wenn das Sicherheitsrisikofeld id mit GHSA-beginnt, wird es als GHSA-Bezeichner erkannt. GHSA-Einträge im aliases Array werden jedoch entfernt und nicht beibehalten.

Feldgrößeneinschränkungen

Die OSV-Spezifikation definiert keine maximalen Zeichenfolgenlängen für jedes Feld – alle Zeichenfolgen sind ungebunden. GitHub Erzwingt jedoch Feldgrößenbeschränkungen basierend auf seinem internen Datenbankschema. Diese Grenzwerte können nicht entspannt werden, ohne die Synchronisierung zu GitHub Enterprise Serverunterbrechen, mit der ein eigenes kompatibles Schema beibehalten wird.

Übermittlungen, die diese Grenzwerte überschreiten, werden mit einem beschreibenden 422-Fehler abgelehnt, der angibt, welches Feld den Grenzwert und die tatsächliche Länge überschritten hat (z. B affected[0].first_patched_version is 63 characters (max 50). ).

| OSV-Feld | Zuordnung zu | OSV-Standardgrenzwert | GitHub Begrenzung | Einheit | |---|---|---|---|---| | summary | vulnerabilities.summary | Kein Grenzwert (empfohlene ≤120 Zeichen) | 1.024 | Byte | | id | vulnerabilities.external_id | Keine Begrenzung | 2.048 | Zeichen | | aliases[] (CVE-Eintrag) | vulnerabilities.cve_id | Keine Begrenzung | 20 | Zeichen | | severity[].score (CVSS v3) | vulnerabilities.cvss_v3 | Keine Begrenzung | 255 | Byte | | severity[].score (CVSS v4) | vulnerabilities.cvss_v4 | Keine Begrenzung | 255 | Zeichen | | affected[].package.ecosystem | vulnerable_version_ranges.ecosystem | Keine Begrenzung | 20 | Zeichen | | affected[].package.name | vulnerable_version_ranges.affects | Keine Begrenzung | 255 | Zeichen | | affected[].ranges[].events[].fixed | vulnerable_version_ranges.fixed_in | Keine Begrenzung | 50 | Zeichen | | Berechneter anfälliger Versionsbereich | vulnerable_version_ranges.requirements | Keine Begrenzung | 65,535 | Byte |

Hinweis

Der fixed_in Grenzwert (erste gepatchte Version) von 50 Zeichen ist die am häufigsten auftretende Einschränkung. Einige Ökosysteme verwenden lange Vorabversionszeichenfolgen (z. B. 1.0.0-alpha.gamma.delta.epsilon.zeta.eta.theta), die diesen Grenzwert überschreiten.

varchar Spalten werden anhand der Zeichenanzahl überprüft; varbinary und text Spalten werden durch Bytegröße überprüft (relevant für UTF-8 Zeichen mit mehreren Byte).

Diese Grenzwerte werden durch GitHub Enterprise Server die Schemakompatibilität eingeschränkt. Das Verbreitern von Spalten ohne GitHub übereinstimmende GHES-Änderungen würde zu Beratenden Synchronisierungsfehlern zwischen Umgebungen führen.

Ökosystemzuordnung

GitHub ordnet OSV-Ökosystemnamen seinen internen Ökosystem-IDs zu. Die folgenden Ökosysteme werden unterstützt:

| OSV-Ökosystem | GitHub Ökosystem | |---|---| | npm | npm | | PyPI | pip | | RubyGems | RubyGems | | Maven | Experte | | NuGet | NuGet | | Packagist | Komponist | | Go | Go | | crates.io | Rust | | Hex | Erlang | | Pub | Pub | | SwiftURL | Swift | | GitHub Actions | GitHub Actions |

Beispiel: minimale OSV-Nutzlast für die Warnungsgenerierung

Es folgt eine minimale OSV-Nutzlast, die alle erforderlichen Felder zum GitHub Erstellen einer Dependabot Warnung enthält:

{
  "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"
}

Bekannte Einschränkungen

Maximal 100 Sicherheitsrisiken pro Anforderung. Die Synchronisierungs-API akzeptiert höchstens 100 Sicherheitsrisiken in einer einzigen Anforderung.
Kein GIT Bereichstyp. Git commitbasierte Versionsbereiche werden nicht unterstützt.
Einzelne Ereignistypen pro ÖKOSYSTEMbereich. Jeder ECOSYSTEM Bereich unterstützt ein introduced und ein oberes gebundenes Ereignis (fixed oder last_affected). Mehrere introduced/fixed Paare in einem einzigen ECOSYSTEM Bereich werden nicht unterstützt – verwenden Sie stattdessen separate Bereiche oder separate affected Einträge. (Diese Einschränkung gilt nicht für SEMVER Bereiche, die mehrere Ereignispaare unterstützen.)
fixed und last_affected schließen sich gegenseitig aus. Ein einzelner Bereich darf nicht sowohl als auch fixed``last_affected Ereignisse enthalten. Verwenden Sie eine oder die andere.
GHES-Synchronisierungskompatibilität. Feldgrößenbeschränkungen (z fixed_in . B. bei 50 Zeichen) werden durch GitHub Enterprise Server Schemakompatibilitätsanforderungen eingeschränkt.

In diesem Artikel