Software Bill of Materials -Dateien werden mit einer REST-API hochgeladen

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 4 Minuten Lesedauer

    • Lesen Sie sich die folgenden Informationen durch, bevor Sie Software Bill of Materials -Dateien mit einer API hochladen.

    Mithilfe der REST API

    Zum Hochladen einer SBOM-Datei mit einer API ist die Rolle sn_sbom_core.sbom_ingest erforderlich.

    Upload-API.

    Diese API wird zum Hochladen und Erfassen einer SBOM-Datei (CycloneDX/SPDX) in Ihre Instanz verwendet.

    Version 4.0 von SBOM Core unterstützt:
    • XML und JSON in RobotDx (Versionen 1.0 bis 1.6).
    • JSON in SPX (Versionen 2.2–2.3)
    • Hinweis:
      Dateien über 32 MB werden möglicherweise nicht ordnungsgemäß geladen.

    HTTP-Methode: (POST)

    API-URL:<host_name> /api/sbom/core/upload
    Hinweis:
    <host_name>ist Ihr Instanzname ServiceNow .
    Alle folgenden Anforderungsparameter sind optional. Der Anforderungstext ist der Inhalt der SBOM-Datei. Wenn Sie DevOps als Teil Ihres Entwicklungsprozesses verwenden, sollte der Wert von „requestedBy“ „devops“ lauten. Allgemeine Informationen zu DevOps finden Sie unter Software Bill of Materials für DevOps-Dateien SBOM werden hochgeladen. Wenn der Wert für „requestedby“ „devops“ (Entwicklungsvorgänge) ist, sind die folgenden Parameter obligatorisch:
    • buildId
    • Lebenszyklusphase
    Wenn „requestedBy“ auf „devops“ festgelegt ist, werden Daten für „fetchVulenrabilityInfo“ und „fetchPackageInfo“ eingeschlossen.
    • buildId: Von Ihnen gesendete Zeichenfolge
    • Lebenszyklusphase: Zwei Werte: „Produktion“ oder „Vorproduktion“.
    • fetchVulenrabilityInfo: t/f
    • fetchPackageInfo-t/f
    Anforderungsparameter Mögliche Werte Beschreibung
    Produktmodell-ID Sys-ID Sys-ID des Produktmodells, das der Stammanwendung des angegebenen SBOM zugeordnet werden soll.
    businessApplicationId Sys-ID Sys-ID der Geschäftsanwendung, die der Stammanwendung des angegebenen SBOM zugeordnet werden soll.
    businessApplicationName Name Ihrer Geschäftsanwendung Name der Geschäftsanwendung, die der Stammanwendung der angegebenen SBOM zugeordnet werden soll.
    sbomSource Beispiel: Ein Produkt wie Vericode Die Quelle für Ihre SBOM-Datei.
    requestedBy Ein Tool oder Name einer Methode, Jenkins. Wenn Sie „devops“ verwenden, sind „buildId“ und „lifecycleStage“ obligatorisch. Upload angefordert von
    buildId Eine anfordernde Person sendet eine Zeichenfolge. Build-ID des SBOM-Builds.
    Lebenszyklusphase „Produktion“ oder „pre_produktion“. Lebenszyklusphase der Entität.
    abrufenVulenrabilityInfo t/f Bei „wahr“ wird die Vulnerability Intelligence-Integration ausgelöst.
    abrufenPaketinformationen t/f Bei „wahr“ wird die Package Intelligence-Integration ausgelöst.
    API-Antwort für Upload: enthalten „status“ erfolgreich/fehlgeschlagen, „message“ (Zeichenfolge), „bomRecordId“ (dies ist die Sys-ID des SBOM, die über die Upload-API für einen erfolgreichen SBOM-Upload zurückgegeben wird.
    {

"result": {

"status": "success",

"message": "Queued for processing.",

"bomRecordId": "f207059b4393c290629aa597cbb8f247"

}

}

    Status-API

    Diese API ruft den Status und die Zusammenfassung einer SBOM ab, die sich in der Warteschlange zur Erfassung befindet.
    • API-URL: /api/sbom/core/upload/status
    • HTTP-Methode (GET)
    Anforderungsparameter Mögliche Werte Beschreibung
    Stücklistendatensatz-ID Sys-ID SBOM-Datensatz-ID, die über die Upload-API für einen erfolgreichen SBOM-Upload zurückgegeben wird.

    Beispiel für die Standardantwort der Status-API.

    
{
   "result": {
      "bomRecordId": "0407c0fea3e70a505df340f5251e617e",
      "uploadStatus": "processed",
      "additionalInfoStatus": "not_requested",
      "uploadSummary": {
         "components": {
            "added": 0,
            "removed": 0,
            "total": 70
         }
       }
    } 
}

    Beispiel für die Status-API-Antwort mit zusätzlichen Parametern. Wenn Sie fetchVulenrabilityInfo für diese SBOM angefordert haben, erhalten Sie die Schwachstellenaufgliederung als Teil der Antwort.

    
{
 "result": {

  "bomRecordId": "93af349b4393c290629aa597cbb8f258",

  "uploadStatus": "processed",

  "additionalInfoStatus": "complete",

  "uploadSummary": {

    "components": {
 
     "added": 0,

     "removed": 0,

     "total": 3

   },

   "vulnerabilityInfo": {

    "critical": 0,

    "high": 0,

    "medium": 0,

    "low": 0,

    "none": 0

   }

  },

  "buildId": "1"

 }

}

    Wenn Sie fetchPackageInfo für diese SBOM angefordert haben, erhalten Sie als Teil der Antwort die Anzahl der veralteten und verworfenen Elemente.

    Nachdem ein SBOM erfolgreich verarbeitet wurde, hängt es von den verwendeten Anwendungen ab, wo Sie die hochgeladenen Datensätze anzeigen.

    • Wenn Sie die SBOM -Antwort verwenden, wird der Stücklistenentitätsdatensatz in der Liste SBOM Erfassungsstatus im Modul Stücklistenwarteschlange im Arbeitsbereich SBOM angezeigt.
    • Wenn Sie SBOM Core verwenden, navigieren Sie zu SBOM-Core > Stücklisten-Erfassungsstatusan.

    Erweiterungen der unterstützten Standards SBOM und allgemeine Informationen zur Verwendung

    Version 4.0 von SBOM Core unterstützt:
    • XML und JSON in RobotDx (Versionen 1.0 bis 1.6).
    • JSON in SPX (Versionen 2.2–2.3)
    • Hinweis:
      Dateien über 32 MB werden möglicherweise nicht ordnungsgemäß geladen.
    Ab v4.0 von SBOM Core wurden die folgenden Erweiterungen vorgenommen, um die CycleDx-Standards für die Versionen 1.0 bis 1.6 zu unterstützen:
    • Importieren Sie mit der Eigenschaft (sn_sbom_core.collekt_properties) zusätzliche Informationen in Epic-SBOM-Dateien. Diese Eigenschaft ist standardmäßig deaktiviert. Aktivieren Sie die Eigenschaft, um Informationen zu importieren, die allgemein nicht unterstützt werden. Alle aus diesen Eigenschaften importierten Informationen werden in die Tabelle „SBOM-Komponenteneigenschaft“ [sn_sbom_comp_property] hochgeladen:
      • SBOM-Dateien hochgeladen
      • Metadaten
      • Individuelle Schwachstellen
      • Komponenten
    • Zeigen Sie importierte Komponentendaten für deklarierte und abgeschlossene Lizenzen für SBOM-Dateien in den Versionen 1.4 und höher von CycleneDX in zwei neuen Lizenzfeldern an:
      • Deklariert
      • Abgeschlossen
    • Die Unterstützung für SBOM-Analysen wird für die folgenden CycleneDX-Komponententypen erweitert:
      • Version 1.5: Plattform, Daten, Gerätetreiber, Modell für maschinelles Lernen
      • Version 1.6: Kryptografisch
    Version 3.0 von SBOM Core unterstützt:
    • XML und JSON in RobotDx (bis einschließlich Version 1.4).
    • JSON in SPX (bis einschließlich v2.3).

    Wenn der aufrufende Benutzer erfolgreich authentifiziert wurde und in Ihrer Instanz ServiceNow über die Rolle sn_sbom_core.sbom_ingest verfügt, können Sie von außerhalb Ihrer Instanz auf die API zugreifen, um die Daten SBOM hochzuladen.

    Nachdem die Daten hochgeladen wurden, werden sie analysiert. Bevor Daten analysiert werden, werden die folgenden Anforderungen verifiziert:

    • Bei eingehenden Daten wird geprüft, ob es sich um gültiges JSON oder XML handelt.
    • Das Stücklistenformat wird unterstützt. Ab Version 2.1 von SBOM Core werden die Formate RobotX (JSON und XML) und SPX (XML) unterstützt.
    • Es sind mindestens Felder verfügbar, damit Daten analysiert werden können.

    Nachdem diese Prüfungen verifiziert wurden, wird in der Stücklistentabelle [sn_sbom_doc] ein Eintrag mit eingehenden Daten SBOM als Anhang vorgenommen.

    Die Geschäftsregel Process BOM file wird automatisch als Ergebnis der Datensatzeinfügung und der Datenanalyse ausgelöst.
    Hinweis:
    Diese Geschäftsregel wird standardmäßig während der Installation von SBOM Core aktiviert.

    Alle in einem SBOM aufgeführten Komponenten haben einen definierten Typ.

    • Komponenten, für die SBOM -Dateien hochgeladen wurden, gelten als Stücklistenentitäten.
    • Komponenten, die als type=library aufgeführt sind, gelten als Komponenten von Drittparteien.