BOMs

Stücklisten (Bills of Materials, BOMs) stehen im Mittelpunkt der Funktionalität und des Namens von BOMnipotents. Eine BOM ist eine Liste aller Komponenten, aus denen ein Produkt besteht. Im Kontext der Cybersicherheit ist die Software-BOM (SBOM) die bekannteste Variante, BOMs ermöglichen aber auch allgemeinere Überlegungen.

Für BOM-Interaktionen, die über das Lesen hinausgehen, benötigen Sie die Berechtigung BOM_MANAGEMENT. Im Abschnitt zur Verwaltung von Zugriffsrechten wird beschrieben, wie diese erteilt wird.

Hochladen

Um eine BOM hochzuladen, rufen Sie Folgendes auf:

bomnipotent_client bom upload /home/your_project/sbom.cdx.json

[INFO] Uploaded BOM 'Your Project:1.0.0'.

BOMnipotent erwartet seine BOM im strukturierten CycloneDX JSON-Format.

Im Syft-Tutorial erfahren Sie, wie Sie eine BOM für Ihr Produkt erstellen.

Der BOMnipotent Client ließt die Datei unter dem angegebenen Pfad und lädt ihren Inhalt hoch. Die BOM kann dann von Konsumenten mit entsprechenden Berechtigungen eingesehen werden.

BOMs für Konsumenten beschreibt, wie die BOMs auf dem Server aufgelistet und heruntergeladen werden.

Um eine BOM zur Datenbank hinzuzufügen, benötigt der BOMnipotent Client einige zusätzliche Informationen: einen Namen, eine Version und optional ein TLP-Label. Name und Version können entweder abgeleitet (empfohlen) oder wie unten beschrieben überschrieben werden.

Name und Version

Ableitung (empfohlen)

BOMnipotent verwendet Name und Version zur Identifizierung einer Stückliste. Diese werden aus den bereitgestellten CycloneDX-JSON-Feldern “metadata.component.name” und “metadata.component.version” abgeleitet. Gemäß der CycloneDX-Spezifikation ist das Feld “metadata.component” jedoch optional.

Wenn keine Version angegeben ist, verwendet BOMnipotent stattdessen das Datum von “metadata.timestamp”, sofern verfügbar.

Um Komplikationen zu vermeiden, wird empfohlen, beim Generieren der Stückliste Name und Version anzugeben, wie im Syft-Tutorial beschrieben.

Überschreiben (nicht besonders empfohlen)

Falls Ihrer BOM aus irgendeinem Grund ein Name oder eine Version fehlt oder diese fehlerhaft ist, bietet der BOMnipotent Client die Möglichkeit, dies über Befehlszeilenargumente zu beheben:

bomnipotent_client bom upload /home/your_project/dev_env_sbom.cdx.json --name-overwrite="Other Project" --version-overwrite="2.7.1"

bomnipotent_client bom upload /home/your_project/dev_env_sbom.cdx.json -n "Other Project" -v "2.7.1"

[WARN] Warning: Overwriting name with 'Other Project'. The data stored on the server will differ from the provided file.
[WARN] Warning: Overwriting version with '2.7.1'. The data stored on the server will differ from the provided file.
[INFO] Uploaded BOM 'Other Project:2.7.1'.

Wichtig: Der BOMnipotent Client ändert in diesem Fall die Daten, bevor sie an den Server gesendet werden. Die lokale Datei wird nicht geändert, da dies zu weit gehen würde. Das bedeutet, dass Ihre lokale Datei und die Daten auf dem Server nicht mehr synchron sind. Schlimmer noch: Falls Sie Ihre BOM signiert haben, ist Ihre Signatur nun ungültig.

Falls Sie diese Option nutzen, wird daher empfehlen, die BOM umgehend vom Server herunterzuladen (wie in BOMs für Verbraucher beschrieben) und Ihre lokale Datei durch das Ergebnis zu ersetzen.

TLP-Klassifizierung

Für Konsumenten verwaltet BOMnipotent den Datenzugriff über das Traffic Light Protocol (TLP) . Das CycloneDX-Format unterstützt derzeit keine Dokumentklassifizierung.

Um BOMnipotent mitzuteilen, wie ein Dokument klassifiziert werden soll, haben Sie zwei Möglichkeiten:

1. Legen Sie in der Serverkonfiguration ein Default-TLP-Label fest. Dieses wird dann für alle BOMs ohne weitere Spezifikationen verwendet.
2. Geben Sie eine TLP-Klassifizierung per Kommandozeilenargument an:

bomnipotent_client bom upload /home/your_project/container_sbom.cdx.json --tlp=WHITE # This makes the BOM public.

bomnipotent_client bom upload /home/your_project/container_sbom.cdx.json -t WHITE # This makes the BOM public.

[INFO] Uploaded BOM 'Your Project Container:1.2.3'.

Falls Sie keines von beiden tun, behandelt BOMnipotent alle nicht klassifizierten Dokumente so, als wären sie mit dem Label TLP:RED gekennzeichnet, und gibt jedes Mal eine Warnung aus, wenn dies erforderlich ist.

Konfliktbehandlung

Die Kombination aus Name und Version der Hauptkomponente einer BOM muss eindeutig sein. Der Versuch, ein weiteres Dokuement mit derselben Kombination hochzuladen, resultiert in einem Fehler.

bomnipotent_client bom upload /home/your_project/sbom.cdx.json

[ERROR] Received response:
409 Conflict
BOM 'Your Project:1.0.0' already exists in the database.

Sie können dieses Verhalten mit der “on-existing” Option überschreiben, und BOMnipotent anweisen, Dokumente im Konfliktfall entweder zu überspringen oder zu ersetzen:

bomnipotent_client bom upload /home/your_project/sbom.cdx.json --on-existing=skip

bomnipotent_client bom upload /home/your_project/sbom.cdx.json -o skip

[INFO] 

bomnipotent_client bom upload /home/your_project/sbom.cdx.json --on-existing=replace

bomnipotent_client bom upload /home/your_project/sbom.cdx.json -o replace

[INFO] Modified BOM 'Your Project:1.0.0'.

Ändern

Im einfachsten Fall funktioniert das Ändern einer vorhandenen Stückliste ähnlich wie das Hochladen einer neuen.

bomnipotent_client bom modify /home/your_project/sbom.cdx.json

[INFO] Modified BOM 'Your Project:1.0.0'.

Dadurch werden Name und Version des Dokuments abgeleitet und der vorhandene Inhalt auf dem Server überschrieben. Sollten die Daten auf dem Server nicht vorhanden sein, wird ein 404-Fehler “Nicht gefunden” zurückgegeben.

TLP-Label ändern

Wenn der Stückliste zuvor ein TLP-Label zugewiesen wurde, wird dieses durch eine Änderung des Inhalts nicht automatisch geändert.

Wenn Sie ein neues TLP-Label angeben möchten, können Sie dies über das folgende Argument tun:

bomnipotent_client bom modify /home/your_project/sbom.cdx.json --tlp=AMBER

bomnipotent_client bom modify /home/your_project/sbom.cdx.json -t AMBER

[INFO] Modified BOM 'Your Project:1.0.0'.

Wenn sich der Inhalt der Stückliste nicht geändert hat und Sie nur das TLP-Label ändern möchten, müssen Sie das Dokument nicht erneut hochladen. Anstatt einen Dateipfad anzugeben, können Sie Name und Version der neu zu klassifizierenden BOM angeben:

bomnipotent_client bom modify --name="Other Project" --version="2.7.1" --tlp=GREEN

bomnipotent_client bom modify -n "Other Project" -v "2.7.1" -t GREEN

[INFO] Modified BOM 'Other Project:2.7.1'.

Wenn Sie als TLP-Label “none”, “default” oder “unlabelled” angeben, wird jede vorhandene Klassifizierung entfernt und der Server greift auf das Default-TLP-Label der Serverkonfiguration zurück:

bomnipotent_client bom modify /home/your_project/sbom.cdx.json --tlp=none
bomnipotent_client bom modify /home/your_project/sbom.cdx.json --tlp=default # Does the same
bomnipotent_client bom modify /home/your_project/sbom.cdx.json --tlp=unlabeled # Does the same

bomnipotent_client bom modify /home/your_project/sbom.cdx.json -t none
bomnipotent_client bom modify /home/your_project/sbom.cdx.json -t default # Does the same
bomnipotent_client bom modify /home/your_project/sbom.cdx.json -t unlabeled # Does the same

[INFO] Modified BOM 'Your Project:1.0.0'.
[INFO] Modified BOM 'Your Project:1.0.0'.
[INFO] Modified BOM 'Your Project:1.0.0'.

Name oder Version ändern

Wenn das hochgeladene Dokument einen anderen Namen oder eine andere Version hat als die zu ändernden Daten, müssen Sie diese Informationen dem BOMnipotent-Client mithilfe der folgenden Befehlszeilenargumente mitteilen:

bomnipotent_client bom modify /home/your_project/dev_env_sbom.cdx.json --name="Other Project" --version="2.7.1"

bomnipotent_client bom modify /home/your_project/dev_env_sbom.cdx.json -n "Other Project" -v "2.7.1"

[INFO] Modified BOM 'Your Development Environment:1.2.3'.

BOMnipotent leitet die neuen Daten aus dem von Ihnen bereitgestellten Dokument ab und ändert die Datenbankeinträge entsprechend.

Name oder Version überschreiben (nicht empfohlen)

Wie beim Hochladen können Sie den im lokalen Dokument gespeicherten Namen und/oder die Version überschreiben:

bomnipotent_client bom modify /home/your_project/dev_env_sbom.cdx.json --name-overwrite="Fearsome Breadcrump" --version-overwrite="6.2.8"

[WARN] Warning: Overwriting name with 'Fearsome Breadcrump'. The data stored on the server will differ from the provided file.
[WARN] Warning: Overwriting version with '6.2.8'. The data stored on the server will differ from the provided file.
[INFO] Modified BOM 'Fearsome Breadcrump:6.2.8'.

Wichtig: Wie beim Hochladen werden die JSON-Daten vor dem Hochladen auf den Server geändert! Es gelten die gleichen Dinge zu bedenken.

Wenn die Daten auf dem Server einen anderen Namen und/oder eine andere Version haben als im Dokument angegeben, können Sie die Angabe mit einem Überschreiben der Daten kombinieren:

bomnipotent_client bom modify /home/your_project/dev_env_sbom.cdx.json --name="Fearsome Breadcrump" --version="6.2.8" --name-overwrite="Best Project" --version-overwrite="3.1.4"

bomnipotent_client bom modify /home/your_project/dev_env_sbom.cdx.json -n "Fearsome Breadcrump" -v "6.2.8" --name-overwrite="Best Project" --version-overwrite="3.1.4"

[WARN] Warning: Overwriting name with 'Best Project'. The data stored on the server will differ from the provided file.
[WARN] Warning: Overwriting version with '3.1.4'. The data stored on the server will differ from the provided file.
[INFO] Modified BOM 'Best Project:3.1.4'.

Das Ändern von Name und/oder Version ohne Angabe des vollständigen Dokuments ist nicht unterstützt.

Löschen

Das Löschen einer BOM ist sehr einfach:

bomnipotent_client bom delete "Best Project" "3.1.4"

[INFO] Successfully deleted BOM 'Best Project:3.1.4'.

Falls die BOM nicht existiert, gibt der Server den Fehler 404 “Nicht gefunden” zurück. Ist sie vorhanden, wird sie aus der Datenbank entfernt.

Alle Komponenten und Sicherheitslücken, die mit der BOM assoziiert sind, werden ebenfalls gelöscht.