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.

Sicherheitslücken

Ein zentraler Bestandteil der Lieferkettensicherheit ist der Abgleich des Inhalts einer Stückliste (BOM), also aller Komponenten eines Produkts, mit Datenbanken bekannter Schwachstellen.

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

Erkennen

BOMnipotent erkennt selbst keine neuen Schwachstellen. Ein Tool, das in Kombination mit BOMnipotent verwendet werden kann, ist grype . Es verwendet eine BOM als Eingabe und erstellt eine Liste der Schwachstellen als Ausgabe. Das grype-Tutorial enthält weitere Informationen zur Verwendung. Es können aber auch andere Tools verwendet werden, solange sie Output im CycloneDX JSON Format erstellen können.

Mit dem BOMnipotent-Client können Sie den Inhalt einer BOM direkt ausgeben und an grype weiterleiten.

bomnipotent_client bom get "Your Project" "1.0.0" | grype --output cyclonedx-json=/home/vuln.cdx.json

bomnipotent_client bom get "Your Project" "1.0.0" | grype -o cyclonedx-json=/home/vuln.cdx.json

Dadurch werden die Softwarekomponenten anhand mehrerer Datenbanken geprüft und die Ergebnisse in das CycloneDX eingepflegt. Anschließend werden alle Ergebnisse in einer Datei namens “vuln.cdx.json” (oder einem anderen von Ihnen angegebenen Namen) gespeichert.

Grype hat derzeit einen kleinen bekannten Fehler , der dazu führt, dass die Version der Hauptkomponente beim Hinzufügen der Schwachstellen vergessen wird. Dies ist problematisch, da BOMnipotent die Version zur eindeutigen Identifizierung eines Produkts benötigt. Eine mögliche Problemumgehung besteht darin, die Version erneut zum Dokument hinzuzufügen, beispielsweise über jq '.metadata.component.version = "<VERSION>"' "vuln.cdx.json" > "vuln_with_version.cdx.json". Ab BOMnipotent v0.3.1 können Sie die Version stattdessen direkt beim Hochladen der Schwachstelle angeben, wie unten beschrieben.

Aktualisieren

Der Befehl zum Aktualisieren der mit einer BOM verknüpften Schwachstellen lautet:

bomnipotent_client vulnerability update /home/your_project/vuln.cdx.json

[INFO] Updated vulnerabilities of BOM 'Your Project:1.0.0'.

Das Argument “<VULNERABILITIES>” muss ein Pfad zu einer Datei im CycloneDX JSON-Format sein.

Idealerweise enthält diese Datei den Namen und die Version der zugehörigen BOM. In diesem Fall werden diese automatisch gelesen. Falls einer der Werte fehlt (z. B. aufgrund eines bekannten Fehlers in grype/), können Sie ihn mit einem optionalen Argument angeben:

bomnipotent_client vulnerability update /home/your_project/vuln_wrong_metadata.cdx.json --name="Your Project" --version="1.0.0"

bomnipotent_client vulnerability update /home/your_project/vuln_wrong_metadata.cdx.json -n "Your Project" -v "1.0.0"

[INFO] Updated vulnerabilities of BOM 'Your Project:1.0.0'.

Schwachstellen sollten regelmäßig aktualisiert werden. Dadurch werden alle vorherigen Schwachstellen, die mit einer BOM verknüpft sind, vollständig ersetzt. Das hochgeladene CycloneDX-Dokument muss daher eine vollständige Liste aller bekannten Schwachstellen enthalten.

Sie können Schwachstellen nur für eine BOM aktualisieren, die auf dem Server vorhanden ist:

bomnipotent_client vulnerability update /home/your_project/vuln_wrong_metadata.cdx.json --name=Schlagsahne --version=2.7.1;
bomnipotent_client vulnerability update /home/your_project/vuln_wrong_metadata.cdx.json --version=1.0.1;

bomnipotent_client vulnerability update /home/your_project/vuln_wrong_metadata.cdx.json -n Schlagsahne -v 2.7.1;
bomnipotent_client vulnerability update /home/your_project/vuln_wrong_metadata.cdx.json -v 1.0.1;

[ERROR] Received response:
404 Not Found
BOM 'Schlagsahne:2.7.1' not found in database.
[ERROR] Received response:
404 Not Found
BOM 'Your Project:1.0.1' not found in database.

Auflisten

Der Abschnitt zum Auflisten von Schwachstellen in der Dokumentation für Verbraucher behandelt die meisten Aspekte der Auflistung von Schwachstellen.

Ein Aspekt, der dort nicht erwähnt wird, ist die Option “–unassessed”. Damit listet der BOMnipotent-Client nur Schwachstellen auf, denen kein CSAF-Dokument mit Status “final” zugeordnet ist.

Damit diese Zuordnung geschehen kann, muss das CSAF Dokument Produktname und Produktversion für die BOM in seinen Branches enthalten.

bomnipotent_client vulnerability list --unassessed

bomnipotent_client vulnerability list -u

[INFO] 
╭──────────────┬─────────────────┬─────────────────────┬────────────────────────────┬───────┬──────────┬───────────┬──────────────────╮
│ Product Name │ Product Version │ Vulnerability       │ Description                │ Score │ Severity │ TLP       │ CSAF Assessments │
├──────────────┼─────────────────┼─────────────────────┼────────────────────────────┼───────┼──────────┼───────────┼──────────────────┤
│ Best Project │ 3.1.4           │ GHSA-qg5g-gv98-5ffh │ rustls network-reachable p │       │ medium   │ TLP:GREEN │                  │
│              │                 │                     │ anic in `Acceptor::accept` │       │          │           │                  │
╰──────────────┴─────────────────┴─────────────────────┴────────────────────────────┴───────┴──────────┴───────────┴──────────────────╯
[ERROR] Found 1 unassessed vulnerabilities.

In diesem Modus beendet der BOMnipotent Client den Vorgang mit einem Fehlercode genau dann wenn nicht bewertete Schwachstellen vorliegen. Dies erleichtert die Integration dieses Aufrufs in Ihre regelmäßige CI/CD.

Sie können diese Option frei mit der Angabe eines Produktnamens oder einer Version kombinieren:

bomnipotent_client vulnerability list --name="Your Project" --version="1.0.0" --unassessed

bomnipotent_client vulnerability list -n "Your Project" -v "1.0.0" -u

[INFO] No unassessed vulnerabilities found

CSAF Dokumente

Ein Common Security Advisory Framework (CSAF)-Dokument ist die Antwort eines Herstellers auf eine neu entdeckte Sicherheitslücke. Es ist ein maschinenlesbares Format, welches Informationen darüber verbreitet, wie Nutzer Ihres Produkts reagieren sollten: Muss auf eine neuere Version aktualisiert werden? Muss eine Konfiguration geändert werden? Ist Ihr Produkt überhaupt betroffen oder ruft es den betroffenen Teil der anfälligen Bibliothek möglicherweise nie auf?

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

Hochladen

Um ein CSAF-Dokument hochzuladen, rufen Sie

bomnipotent_client csaf upload /home/your_project/advisory.json

[INFO] Uploaded CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory'.

Bevor Ihr CSAF-Dokument hochgeladen wird, prüft der BOMnipotent Client, ob es gemäß dem OASIS CSAF-Standard gültig ist.

Konfliktbehandlung

CSAF Dokumente werden durch ihren, nun ja, Identifikator identifiziert, welcher eindeutig sein muss. Der Versuch, ein weiteres Dokuement mit derselben ID hochzuladen, resultiert in einem Fehler:

bomnipotent_client csaf upload /home/your_project/advisory.json

[ERROR] Received response:
409 Conflict
CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory' 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 csaf upload /home/your_project/advisory.json --on-existing=skip

bomnipotent_client csaf upload /home/your_project/advisory.json -o skip

[INFO] 

bomnipotent_client csaf upload /home/your_project/advisory.json --on-existing=replace

bomnipotent_client csaf upload /home/your_project/advisory.json -o replace

[INFO] Modified CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory'.

Auflisten

Sie können das Ergebnis des Vorgangs mit

bomnipotent_client csaf list

[INFO] 
╭────────────────────────────┬────────────────────────────┬─────────────────────────┬─────────────────────────┬────────┬───────────╮
│ ID                         │ Title                      │ Initial Release         │ Current Release         │ Status │ TLP       │
├────────────────────────────┼────────────────────────────┼─────────────────────────┼─────────────────────────┼────────┼───────────┤
│ ghsa-qg5g-gv98-5ffh_adviso │ Network-reachable panic in │ 2025-01-01 10:11:12 UTC │ 2025-01-01 10:11:12 UTC │ final  │ TLP:AMBER │
│ ry                         │  Your Product              │                         │                         │        │           │
╰────────────────────────────┴────────────────────────────┴─────────────────────────┴─────────────────────────┴────────┴───────────╯

Alle Daten stammen aus dem CSAF-Dokument.

Falls das Dokument nicht den optionalen TLP-Labeleintrag enthält, wird es mit dem für den Server konfigurierten Default-TLP behandelt.

...┬────────┬─────────╮
...│ Status │ TLP     │
...┼────────┼─────────┤
...│ final  │ Default │
...┴────────┴─────────╯

Ändern

Wenn sich der Status Ihres Dokuments ändert, Sie es neu klassifizieren möchten oder neue Informationen vorliegen, können Sie es ändern. Um die neue Version hochzuladen, rufen Sie Folgendes auf:

bomnipotent_client csaf modify /home/your_project/advisory.json

[INFO] Modified CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory'.

Der Befehl kann sogar die ID vom CSAF Dokument modifizieren. Da die bisheriger ID in diesem Fall nicht aus dem neuen Dokument abgeleitet werden kann, muss sie als optionales Argument angegeben werden:

bomnipotent_client csaf modify <PATH/TO/CSAF> --id=<OLD-ID>

bomnipotent_client csaf modify <PATH/TO/CSAF> -i <OLD-ID>

Löschen

Um ein CSAF-Dokument von Ihrem Server zu löschen (was Sie wirklich nur tun sollten, falls etwas komplett schiefgelaufen ist), rufen Sie einfach Folgendes auf:

bomnipotent_client csaf delete ghsa-qg5g-gv98-5ffh_advisory

[INFO] Deleted CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory'.

Berechtigungen

In BOMnipotent sind Berechtigungen nicht direkt mit Benutzerkonten, sondern mit Rollen verknüpft. Der Abschnitt zur Rollenverwaltung beschreibt, wie diese Verknüpfung verwaltet wird, und der Abschnitt zur Rollenzuweisung erläutert, wie Rollen (und damit letztlich Berechtigungen) Benutzern zugewiesen werden.

Der Server verfügt über mehrere Berechtigungen im Code, von denen einige fest programmiert, andere konfigurierbar sind. Alle werden hier erläutert. Informationen zum Erstellen einer Berechtigung, die einer Rolle zugeordnet ist, finden Sie im entsprechenden Abschnitt .

Die Berechtigungen lassen sich gedanklich in Berechtigungen für Konsumenten , Manager und einige Sonderberechtigungen für Administratoren unterteilen.

Berechtigungen für Konsumenten

Ihre Kunden sind in der Regel mit einem oder mehreren Ihrer Produkte verknüpft. Sie möchten alle Arten von Dokumenten und Informationen zu diesem Produkt einsehen, haben aber nicht automatisch Anspruch auf Informationen zu anderen Produkten.

PRODUCT_ACCESS

Eine Berechtigung mit dem Wert “PRODUCT_ACCESS(<PRODUCT>)” gewährt Leseberechtigung für alle mit “<PRODUCT>” verknüpften Dokumente. Dies umfasst alle Stücklisten (BOMs) dieses Produkts, alle damit verbundenen Schwachstellen und alle CSAF-Dokumente zu diesem Produkt.

Beispielsweise könnte eine Rolle mit dem Wert “PRODUCT_ACCESS(BOMnipotent)” alle mit BOMnipotent verknüpften Dokumente (und nur diese) einsehen.

Dem Sternchen-Operator “*” kann als Globbing-Platzhalter für Produktnamen genutzt werden. Dabei entspricht das Sternchen einer beliebigen Anzahl von Symbolen. Beispielsweise würde die Berechtigung “PRODUCT_ACCESS(BOM*ent)” sowohl auf “BOMnipotent” als auch auf die (fiktiven) Produkte “BOMent” und “BOM-burárum-ent” zutreffen, nicht jedoch auf “BOMtastic” (da letzteres nicht auf “ent” endet).

Folglich ermöglicht “PRODUCT_ACCESS(*)” die Anzeige aller Dokumente.

Berechtigungen für Manager

Für Dokumentmanager ist die Situation in der Regel umgekehrt: Sie benötigen die Berechtigung, die Datenbankinhalte nicht nur anzuzeigen, sondern auch zu ändern. Ihr Umfang ist typischerweise nicht auf ein bestimmtes Produkt, sondern auf einen bestimmten Dokumenttyp beschränkt. Daher wird die Trennung der Managerberechtigungen aus einer anderen Perspektive betrachtet.

BOM_MANAGEMENT

Diese Berechtigung ermöglicht das Hochladen, Ändern und Löschen von Stücklisten (BOMs). Sie gewährt automatisch auch die Berechtigung zur Anzeige aller gehosteten Stücklisten.

VULN_MANAGEMENT

Diese Berechtigung ermöglicht das Aktualisieren und Anzeigen der Liste der Schwachstellen, die mit einer BOM verknüpft sind.

CSAF_MANAGEMENT

Diese Berechtigung ermöglicht das Hochladen, Ändern und Löschen von CSAF-Dokumenten (Common Security Advisory Framework). Sie gewährt außerdem automatisch Anzeigeberechtigungen für alle gehosteten CSAF-Dokumente.

ROLE_MANAGEMENT

Mit dieser Berechtigung kann ein Benutzer die Berechtigungen von Rollen ändern . Dies kann weitreichende Folgen haben, da die Änderungen potenziell viele Benutzer betreffen.

USER_MANAGEMENT

Diese Berechtigung ist erforderlich, um Benutzer anzuzeigen, oder ihre Anfragen zur Kontoerstellung zu gewähren oder abzulehnen . Sie wird auch benötigt, um Nutzern Rollen zuzuweisen .

Sonderberechtigungen für Administratoren

BOMnipotent kennt die feststehende Rolle “admin”. Diese Rolle verfügt stets über alle Berechtigungen, die Benutzern erteilt werden können. Darüber hinaus gibt es einige Aufgaben, die nur von Benutzern mit der Administratorrolle ausgeführt werden können: – Nur Administratoren können die Administratorrolle anderen Benutzern zuweisen oder entziehen . Ein spezieller temporärer Administratormechanismus ermöglicht die Erstellung des ersten Administrators für einen neu erstellten BOMnipotent Server. – Nur Administratoren können den Abonnementschlüssel für eine BOMnipotent Server Instanz (de)aktivieren .

Rollenverwaltung

BOMnipotent verwendet ein rollenbasiertes Zugriffsmodell (RBAC), bei dem Benutzer Rollen und Rollen Berechtigungen zugeordnet werden. Während Berechtigungen in BOMnipotent größtenteils fest kodiert sind, können Rollen (fast) frei verwaltet werden. Dieser Abschnitt erklärt, wie das geht.

Um Rollen und ihre Berechtigungen zu ändern oder anzuzeigen, benötigt Ihr Benutzerkonto die Berechtigung ROLE_MANAGEMENT.

Standardrollen

Beim ersten Start Ihres BOMnipotent Servers werden in der Datenbank mehrere kreativ benannte Standardrollen angelegt:

• “bom_manager” mit der Berechtigung BOM_MANAGEMENT.
• “csaf_manager” mit der Berechtigung CSAF_MANAGEMENT.
• “role_manager” mit der Berechtigung ROLE_MANAGEMENT.
• “user_manager” mit der Berechtigung USER_MANAGEMENT.
• “vuln_manager”, mit der Berechtigung VULN_MANAGEMENT.

Sie können diese Rollen nach Belieben ändern oder löschen; es handelt sich lediglich um Vorschläge.

Wenn Ihnen diese Rollen nicht gefallen, können Sie sie mit den folgenden Aufrufen löschen:

bomnipotent_client role-permission remove bom_manager BOM_MANAGEMENT;
bomnipotent_client role-permission remove csaf_manager CSAF_MANAGEMENT;
bomnipotent_client role-permission remove role_manager ROLE_MANAGEMENT;
bomnipotent_client role-permission remove user_manager USER_MANAGEMENT;
bomnipotent_client role-permission remove vuln_manager VULN_MANAGEMENT;

[INFO] Removed permission BOM_MANAGEMENT from role bom_manager.
[INFO] Removed permission CSAF_MANAGEMENT from role csaf_manager.
[INFO] Removed permission ROLE_MANAGEMENT from role role_manager.
[INFO] Removed permission USER_MANAGEMENT from role user_manager.
[INFO] Removed permission VULN_MANAGEMENT from role vuln_manager.

Admin-Rolle

Es gibt eine spezielle Rolle namens “admin”, die nicht in den anderen Rollen aufgeführt ist. Der Grund dafür ist, dass sie nicht Teil der Datenbank, sondern des BOMnipotent-Codes selbst ist. Daher kann sie nicht geändert werden.

bomnipotent_client role-permission remove admin BOM_MANAGEMENT

[ERROR] Received response:
422 Unprocessable Entity
Cannot modify admin role permissions.

Die Administratorrolle verfügt über alle Berechtigungen, die erteilt werden können, und dann noch einige weitere .

Auflisten

Um alle Rollen und die zugehörigen Berechtigungen aufzulisten, rufen Sie Folgendes auf:

bomnipotent_client role-permission list

[INFO] 
╭──────────────┬─────────────────┬─────────────────────────╮
│ Role         │ Permission      │ Last Updated            │
├──────────────┼─────────────────┼─────────────────────────┤
│ bom_manager  │ BOM_MANAGEMENT  │ 2025-01-01 10:11:12 UTC │
│ csaf_manager │ CSAF_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ role_manager │ ROLE_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ user_manager │ USER_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ vuln_manager │ VULN_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
╰──────────────┴─────────────────┴─────────────────────────╯

Die Ausgabe kann nach Rolle oder Berechtigung gefiltert werden:

bomnipotent_client role-permission list --role=bom_manager --permission=BOM_MANAGEMENT

bomnipotent_client role-permission list -r bom_manager -p BOM_MANAGEMENT

[INFO] 
╭─────────────┬────────────────┬─────────────────────────╮
│ Role        │ Permission     │ Last Updated            │
├─────────────┼────────────────┼─────────────────────────┤
│ bom_manager │ BOM_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
╰─────────────┴────────────────┴─────────────────────────╯

Hinzufügen

Da Rollen ohne Berechtigungen bedeutungslos sind, werden sie immer paarweise verwendet. Es gibt keinen speziellen Mechanismus zum Erstellen einer neuen Rolle. Stattdessen existiert eine Rolle dadurch, dass ihr eine Berechtigung hinzugefügt wird.

Die Syntax zum Hinzufügen einer Berechtigung zu einer Rolle lautet:

bomnipotent_client role-permission add rick_role "PRODUCT_ACCESS(BOMnipotent)"

[INFO] Added permission PRODUCT_ACCESS(BOMnipotent) to role rick_role.

Sie könnten beispielsweise mehrere Berechtigungen in den Rollen “doc_manager” und “access_manager” zusammenfassen:

bomnipotent_client role-permission add doc_manager BOM_MANAGEMENT;
bomnipotent_client role-permission add doc_manager CSAF_MANAGEMENT;
bomnipotent_client role-permission add doc_manager VULN_MANAGEMENT;
bomnipotent_client role-permission add access_manager ROLE_MANAGEMENT;
bomnipotent_client role-permission add access_manager USER_MANAGEMENT;

[INFO] Added permission BOM_MANAGEMENT to role doc_manager.
[INFO] Added permission CSAF_MANAGEMENT to role doc_manager.
[INFO] Added permission VULN_MANAGEMENT to role doc_manager.
[INFO] Added permission ROLE_MANAGEMENT to role access_manager.
[INFO] Added permission USER_MANAGEMENT to role access_manager.

Falls Sie die Standardrollen wie oben beschrieben entfernt haben, erhalten Sie damit folgenden Zustand:

bomnipotent_client role-permission list

[INFO] 
╭────────────────┬─────────────────┬─────────────────────────╮
│ Role           │ Permission      │ Last Updated            │
├────────────────┼─────────────────┼─────────────────────────┤
│ access_manager │ ROLE_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ access_manager │ USER_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ doc_manager    │ BOM_MANAGEMENT  │ 2025-01-01 10:11:12 UTC │
│ doc_manager    │ CSAF_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ doc_manager    │ VULN_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
╰────────────────┴─────────────────┴─────────────────────────╯

Falls die hinzuzufügende Berechtigung nicht existiert oder fehlerhaft ist, erhalten Sie eine Fehlermeldung:

bomnipotent_client role-permission add clam_manager CLAM_MANAGEMENT

[ERROR] Received response:
422 Unprocessable Entity
Failed to parse permission: Invalid UserPermission string: CLAM_MANAGEMENT

Entfernen

Um eine Berechtigung aus einer Rolle zu entfernen, rufen Sie einfach Folgendes auf:

bomnipotent_client role-permission remove rick_role "PRODUCT_ACCESS(BOMnipotent)"

[INFO] Removed permission PRODUCT_ACCESS(BOMnipotent) from role rick_role.

Sobald Sie die letzte Rolle aus einer Berechtigung entfernt haben, existiert diese nicht mehr.

Um Hoppla-Momente zu vermeiden, unterstützt BOMnipotent nicht das Löschen ganzer Stapel von Rollenberechtigungen.

Existenz

Der Sub-Befehl "exist" prüft, wie viele Einträge auf dem Server mit bestimmten Filtern übereinstimmt. Er ist für alle Befehle verfügbar, die den "list" Sub-Befehl akzeptieren, und akzeptiert dieselben Filter.

Basierend auf dem Ausgabeformat gibt der Client Folgendes aus:

• Normaler Modus: Ein Satz, der die Anzahl der gefundenen Objekte enthält.
• code: Den String "200", falls mindestens ein Element gefunden wurde, oder "404", falls keine gefunden wurden.
• raw: Die Anzahl der Einträge, die gefunden wurden.

bomnipotent_client role-permission exist --role=bom_manager

bomnipotent_client role-permission exist -r bom_manager

[INFO] The server contains 1 role permission(s) matching the filters.

Nutzerverwaltung

Der erste Schritt beim Anlegen eines neuen Benutzers ist die Beantragung eines neuen Kontos. Dieser Schritt wird an anderer Stelle beschrieben, da er sowohl für Manager als auch für Konsumenten relevant ist.

Aus Sicht von BOMnipotent ist ein Benutzer verknüpft mit einer eindeutigen E-Mail-Adresse als Kennung, und einem öffentlichen Schlüssel zur Authentifizierung. Dies sind alle Daten, die bei der Erstellung eines neuen Benutzerkontos gesendet werden.

Nach der Beantragung eines neuen Kontos obliegt es einem Benutzermanager, die Anfrage zu genehmigen oder abzulehnen.

Für die meisten Benutzerinteraktionen, einschließlich der Auflistung, benötigen Sie die Berechtigung USER_MANAGEMENT.

Auflisten

Um alle Benutzer in Ihrer Datenbank aufzulisten, rufen Sie

bomnipotent_client user list

[INFO] 
╭────────────────────────┬───────────┬─────────────────────────┬───────────┬─────────────────────────╮
│ Username               │ Status    │ Expires                 │ User Type │ Last Updated            │
├────────────────────────┼───────────┼─────────────────────────┼───────────┼─────────────────────────┤
│ admin@example.com      │ APPROVED  │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
│ example_robot          │ REQUESTED │ 2025-01-01 10:11:12 UTC │ ROBOT     │ 2025-01-01 10:11:12 UTC │
│ other_user@example.com │ REQUESTED │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
│ user@example.com       │ VERIFIED  │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
╰────────────────────────┴───────────┴─────────────────────────┴───────────┴─────────────────────────╯

So können Sie die E-Mail-Adressen und die Stati der Benutzer einsehen.

Ein Benutzer ohne den Status “APPROVED” hat keine besonderen Berechtigungen, unabhängig von zugewiesenen Rollen.

Jedem Benutzer ist außerdem ein Ablaufdatum zugeordnet. Ab diesem Zeitpunkt wird der öffentliche Schlüssel ungültig und muss erneuert werden. Die Gültigkeitsdauer eines Schlüssels kann in der Serverkonfiguration frei konfiguriert werden.

Die Liste der Nutzer kann nach Nutzername oder Genehmigungsstatus gefiltert werden, oder danach, ob das Nutzerkonto abgelaufen ist:

bomnipotent_client user list --user=admin@example.com --status=APPROVED --expired=false

bomnipotent_client user list -u admin@example.com -s APPROVED -e false

[INFO] 
╭───────────────────┬──────────┬─────────────────────────┬───────────┬─────────────────────────╮
│ Username          │ Status   │ Expires                 │ User Type │ Last Updated            │
├───────────────────┼──────────┼─────────────────────────┼───────────┼─────────────────────────┤
│ admin@example.com │ APPROVED │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
╰───────────────────┴──────────┴─────────────────────────┴───────────┴─────────────────────────╯

Das “true” Argument für den “expired” Filter ist optional:

bomnipotent_client user list --expired=true;
bomnipotent_client user list --expired # does the same

bomnipotent_client user list -e true;
bomnipotent_client user list -e # does the same

[INFO] 
╭──────────┬────────┬─────────┬───────────┬──────────────╮
│ Username │ Status │ Expires │ User Type │ Last Updated │
├──────────┼────────┼─────────┼───────────┼──────────────┤
[INFO] 
╭──────────┬────────┬─────────┬───────────┬──────────────╮
│ Username │ Status │ Expires │ User Type │ Last Updated │
├──────────┼────────┼─────────┼───────────┼──────────────┤

Genehmigen oder Ablehnen

Wenn Sie die Benutzeranfrage erwartet haben, können Sie sie genehmigen:

bomnipotent_client user approve user@example.com

[INFO] Changed status of user@example.com to APPROVED.

Falls der Nutzer noch nicht bestätigt hat, Zugriff auf die Email Adresse zu haben, dann lehnt der Server die Genehmigung ab. Falls Sie absolut sicher sind, dass Sie wissen was Sie tun, können Sie dieses Verhalten mit der ‘–allow-unverified’ Option überschreiben (es gibt keine Kurzformen für Befehle die Sicherheitsmaßnahmen überschreiben):

bomnipotent_client user approve other_user@example.com --allow-unverified

[INFO] Changed status of other_user@example.com to APPROVED.

Falls das Konto zu einem Roboter gehört, kann es nicht verifiziert werden. In diesem Fall können Sie es mit der ’ –robot’ Option genehmigen:

bomnipotent_client user approve example_robot --robot

bomnipotent_client user approve example_robot -r

[INFO] Changed status of example_robot to APPROVED.

Wichtig: Sie sollten absolut sicher sein, dass dies das Konto ist, welches Sie genehmigen wollen.

Analog dazu können Sie diesem Benutzer stattdessen keinen Zugriff gewähren:

bomnipotent_client user deny unwanted@example.com

[INFO] Changed status of unwanted@example.com to DENIED.

Im Gegensatz zum Genehmigen ist es dieser Aktion egal, welchen Status das Konto vor der Ablehnung hatte.

Es ist möglich, einem bereits genehmigten Benutzer den Zugriff wieder zu verweigern, wodurch das Konto effektiv widerrufen wird.

Ein Nutzer, dessen vorherige Anfrage für einen Nutzeraccount abgelehnt wurde, kann keine weiteren Nutzeraccounts anfragen.

Entfernen

Wenn Sie ein Benutzerkonto vollständig löschen möchten, rufen Sie

bomnipotent_client user remove unwanted@example.com

[INFO] Deleted user 'unwanted@example.com'.

Dies löscht zusätzlich alle dem Benutzer zugewiesenen Rollen.

Existenz

Der Sub-Befehl "exist" prüft, wie viele Einträge auf dem Server mit bestimmten Filtern übereinstimmt. Er ist für alle Befehle verfügbar, die den "list" Sub-Befehl akzeptieren, und akzeptiert dieselben Filter.

Basierend auf dem Ausgabeformat gibt der Client Folgendes aus:

• Normaler Modus: Ein Satz, der die Anzahl der gefundenen Objekte enthält.
• code: Den String "200", falls mindestens ein Element gefunden wurde, oder "404", falls keine gefunden wurden.
• raw: Die Anzahl der Einträge, die gefunden wurden.

bomnipotent_client user exist --status=APPROVED

bomnipotent_client user exist -s APPROVED

[INFO] The server contains 4 user(s) matching the filters.

Rollenzuweisung

Rollen verbinden Benutzer mit Berechtigungen. Das Hinzufügen oder Entfernen von Rollen steuert indirekt, in welchem ​​Umfang Benutzer mit Ihrer BOMnipotent Server Instanz interagieren können.

Zu Ihrer Bequemlichkeit werden beim ersten Start des BOMnipotent-Servers mehrere Standardrollen angelegt. BOMnipotent kennt außerdem die Administratorrolle , die eine besondere Behandlung erhält.

Um Benutzerrollen zu ändern oder anzuzeigen, benötigt Ihr Benutzerkonto die Berechtigung USER_MANAGEMENT.

Auflisten

Um alle Rollen aller Benutzer aufzulisten, rufen Sie

bomnipotent_client user-role list

[INFO] 
╭───────────────────┬──────────────┬─────────────────────────╮
│ Username          │ Role         │ Last Updated            │
├───────────────────┼──────────────┼─────────────────────────┤
│ admin@example.com │ admin        │ 2025-01-01 10:11:12 UTC │
│ example_robot     │ bom_manager  │ 2025-01-01 10:11:12 UTC │
│ example_robot     │ vuln_manager │ 2025-01-01 10:11:12 UTC │
│ user@example.com  │ rick_role    │ 2025-01-01 10:11:12 UTC │
╰───────────────────┴──────────────┴─────────────────────────╯

Die Ausgabe kann nach Nutzer oder Rolle gefiltert werden:

bomnipotent_client user-role list --user=admin@example.com --role=admin

bomnipotent_client user-role list -u admin@example.com -r admin

[INFO] 
╭───────────────────┬───────┬─────────────────────────╮
│ Username          │ Role  │ Last Updated            │
├───────────────────┼───────┼─────────────────────────┤
│ admin@example.com │ admin │ 2025-01-01 10:11:12 UTC │
╰───────────────────┴───────┴─────────────────────────╯

Hinzufügen

Um einem Benutzer eine neue Rolle hinzuzufügen, rufen Sie

bomnipotent_client user-role add user@example.com rick_role

[INFO] Added role to user.

Der Benutzeraccount muss zu diesem Zeitpunkt bereits auf dem Server existieren, die Rolle jedoch nicht.

Nur Benutzer mit der Admin-Rolle können anderen Benutzern die Admin-Rolle zuweisen.

Entfernen

Um einem Benutzer eine Rolle zu entfernen, rufen Sie Folgendes auf:

bomnipotent_client user-role remove user@example.com rick_role

[INFO] Removed role rick_role from user user@example.com.

Wenn eine der beiden Rollen nicht vorhanden ist, wird ein Fehler angezeigt:

bomnipotent_client user-role remove admin@example.com wrong_role;
bomnipotent_client user-role remove wrong_user admin

[ERROR] Received response:
404 Not Found
User with username 'admin@example.com' does not have role wrong_role.
[ERROR] Received response:
404 Not Found
No user with username 'wrong_user' was found: Record not found

Nur Benutzer mit der Admin-Rolle können die Admin-Rolle von anderen Benutzern entfernen.

Existenz

Der Sub-Befehl "exist" prüft, wie viele Einträge auf dem Server mit bestimmten Filtern übereinstimmt. Er ist für alle Befehle verfügbar, die den "list" Sub-Befehl akzeptieren, und akzeptiert dieselben Filter.

Basierend auf dem Ausgabeformat gibt der Client Folgendes aus:

• Normaler Modus: Ein Satz, der die Anzahl der gefundenen Objekte enthält.
• code: Den String "200", falls mindestens ein Element gefunden wurde, oder "404", falls keine gefunden wurden.
• raw: Die Anzahl der Einträge, die gefunden wurden.

bomnipotent_client user-role exist --role=bom_manager

bomnipotent_client user-role exist -r bom_manager

[INFO] The server contains 1 user role(s) matching the filters.