Client Installation

Um BOMnipotent Client manuell herunterzuladen, gehen Sie zu https://www.bomnipotent.de/downloads/ , wählen Sie Ihre Platform und Version, und klicken Sie auf den Download Button.

Um den Prozess weiter zu automatisieren, können Sie den Download Link direkt nutzen:

Invoke-WebRequest -Uri https://www.bomnipotent.de/downloads/raw/latest/windows/bomnipotent_client.exe -OutFile bomnipotent_client.exe

curl -O https://www.bomnipotent.de/downloads/raw/latest/macos/bomnipotent_client
chmod +x bomnipotent_client

wget https://www.bomnipotent.de/downloads/raw/latest/debian-glibc/bomnipotent_client;
chmod +x bomnipotent_client

wget https://www.bomnipotent.de/downloads/raw/latest/linux-musl/bomnipotent_client;
chmod +x bomnipotent_client

Ersetzen sie “latest” mit einem Spezifischen Versionstag, zum Beispiel “v1.0.0”, um diese statt der neuesten herunterzuladen.

Um von überall im System auf BOMnipotent Client zugreifen zu können, verschieben Sie es in einen Ordner der in ihrer PATH Umgebungsvariable enthalten ist. Dieser Schritt ist jedoch optional.

Benutzerkonto Erstellen

Die meisten Interaktion mit BOMnipotent benötigen eine Berechtigung. Die einzige Ausnahme ist der Zugriff auf Daten, welche als TLP:WHITE / TLP:CLEAR klassifiziert wurden.

Berechtigungen sind an Benutzerkonten gebunden. Weitere Informationen, wie Berechtigungen vergeben werden, befinden sich im Abschnitt über Zugriffsverwaltung .

Erstellung eine neuen Benutzerkontos

Ein neues Benutzerkonto erstellen Sie per

bomnipotent_client --domain=bomnipotent_server_of_your_choice user request user@example.com

bomnipotent_client -d bomnipotent_server_of_your_choice user request user@example.com

[INFO] Generating new key pair
[INFO] Storing secret key to '/root/.config/bomnipotent/secret_key.pem' and public key to '/root/.config/bomnipotent/public_key.pem'
[INFO] User request submitted. A verification email has been sent to your inbox. The verification link expires after 1h.

Wenn Sie dies zum ersten Mal rufen, wird es ein neues Schlüsselpaar mit dem ED25519 Algorithmus generieren. Ein Schlüsselpaar besteht aus einem öffentlichen und einem geheimen Schlüssel. Beide werden lokal in Ihrem Nutzerordner gespeichert.

Der geheime Schlüssel wird auch häufig “privater Schlüssel” genannt. Der Autor glaubt aber, dass “geheimer Schlüssel” eine treffendere Beschreibung ist, und außerdem, vor allem im Englischen, die Chance auf Verwechslung mit dem öffentlichen Schlüssel verringert.

Der öffentliche Schlüssel kann, im Prinzip, mit jeder beliebigen Person geteilt werden. Der “user request” Befehl schickt ihn an den BOMnipotent server. Der geheime Schlüssel hingegen sollte wie ein Passwort behandelt werden!

Alle nun folgenden Aufrufe vom BOMnipotent Client werden das existierende Schlüsselpaar wiederverwenden.

Die meisten Instanzen von BOMnipotent Server werden fordern, dass Sie bestätigen, dass Sie Zugriff auf die angegebene Email Adresse haben. Dafür senden diese Ihnen einen Verifizierungslink, welcher nach einer Weile abläuft.

Falls Sie das Zeitfenster verpasst haben oder etwas anderes schiefgegangen ist, schicken Sie einfach die gleiche Anfrage noch einmal an den Server. Dieser generiert dann eine neue Verifizierungsmail für Sie:

bomnipotent_client --domain=bomnipotent_server_of_your_choice user request user@example.com

bomnipotent_client -d bomnipotent_server_of_your_choice user request user@example.com

[INFO] User request re-submitted. A brand new verification email has been sent to your inbox. The verification link expires after 1h.

Nachdem Ihre Anfrage gestellt und Ihre Email verifiziert ist, müssen Sie darauf warten, dass ein Nutzermanager Sie bestätigt. Sobald das geschehen ist können Sie authentifizierte Anfragen stellen.

Falls Sie dieser Nutzermanager sind und herausfinden wollen, wie Sie Nutzer bestätigen können, konsultieren Sie den Abschnitt über Nutzerverwaltung .

Erstellung eines Roboteraccount

Nicht alle Konten sind notwendigerweise mit einem menschlichen Nutzer assoziiert. BOMnipotent ist gebaut, um in Pipelines integriert zu werden. Um ein Konto zu erstellen, welches in Automatisierung genutzt werden soll, fügen Sie der Anfrage die ‘–robot’ Option hinzu:

bomnipotent_client --domain=bomnipotent_server_of_your_choice user request example_robot --robot

bomnipotent_client -d bomnipotent_server_of_your_choice user request example_robot -r

[INFO] Generating new key pair
[INFO] Storing secret key to '/root/.config/bomnipotent/secret_key.pem' and public key to '/root/.config/bomnipotent/public_key.pem'
[INFO] Request for robot user submitted. It now needs to be confirmed by a user manager.

Dies markiert das Konto als Roboter, und verschickt keine Verifizierungsmail.

Gespeicherte Schlüssel nutzen

Falls Sie ein Schlüsselpaar im üblichen Nutzerordner (welcher auf Ihre Platform ankommt) gespeichert haben, wird BOMnipotent Client ihn automatisch lesen und nutzen.

Falls Sie stattdessen gerne einen existierenden Schlüssel wiederverwenden wollen, der an einem anderen Ord gespeichert ist, dann können Sie den Pfad als positionales Argument angeben:

bomnipotent_client --domain=bomnipotent_server_of_your_choice user request other_user@example.com /home/some_public_key.pem

bomnipotent_client -d bomnipotent_server_of_your_choice user request other_user@example.com /home/some_public_key.pem

[INFO] User request submitted. A verification email has been sent to your inbox. The verification link expires after 1h.

Damit dies funktioniert muss der Schlüssel mit dem ED25519 Algorithmus generiert worden und im PEM Format gespeichert sein. Falls Sie darauf bestehen, Ihre Schlüssel selber zu verwalten, oder falls Sie ein Beispiel sehen möchten, dann können Sie ein solches Paar am einfachsten wie folgt generieren: Rufen Sie openssl genpkey -algorithm ED25519 -out secret_key.pem um einen geheimen Schlüssel zu generieren, und dann openssl pkey -in secret_key.pem -pubout -out public_key.pem um den zugehörigen öffentlichen Schlüssel zu erstellen.

Falls Sie hier aus Versehen den Pfad zu ihrem geheimen Schlüssel angeben wirft BOMnipotent Client eine Fehlermeldung anstatt ihn zum Server zu schicken.

Authentifizierung

Authentifizierung setzt voraus, dass Sie einen Nutzeraccount beantragt haben , und dass dieser von einem Nutzermanager bestätigt wurde .

Sobald Ihr Account (also ihre Email und ihr öffentlicher Schlüssel) bestätigt ist, können Sie BOMnipotent Client Ihre Email mitgeben um eine authentifizierte Anfrage an den Server zu stellen:

bomnipotent_client --domain=<server> --user=<your-email> <command>

bomnipotent_client -d <server> -u <your-email> <command>

BOMnipotent Client ließt dann automatisch Ihren geheimen Schlüssel und nutzt ihn zur Authentifizierung.

Ihr geheimer Schlüssel wird benutzt, um die HTTP Methode, Ihre Email, einen Zeitstempel und den Haupttext der Anfrage kryptografisch zu signieren. Dies schützt gleichzeitig davor, dass andere sich als Sie ausgeben, dass Inhalte verändert werden, und vor Replay Attacks. Der geheime Schlüssel erreicht all dies, ohne jemals ihren lokalen Rechner verlassen zu müssen. Die Schönheit des Ganzen würde leider den Umfang dieser Dokumentation sprengen.

Falls Sie Ihren Schlüssel nicht im üblichen Nutzerordner speichern, müssen Sie BOMnipotent Client den Pfad per Kommandozeilenoption angeben:

bomnipotent_client --domain=bomnipotent_server_of_your_choice --user=<your-email> --secret-key=<path/to/key> <command>

bomnipotent_client -d bomnipotent_server_of_your_choice -u <your-email> -s <path/to/key> <command>

Um diese drei zusätzlichen Argumente bei jeder einzelnen Anfrage zu vermeiden, können Sie die Daten stattdessen in einer Nutzersitzung speichern.

Benutzersitzung

Anmeldung

Der BOMnipotent Client bietet mehrere globale optionale Argumente. Um diese nicht immer wieder angeben zu müssen, können Sie den session login Befehl verwenden, um sie in einer Benutzersitzung zu speichern. Dies erstellt eine Datei im lokalen Benutzerordner, die die angegebenen Parameter speichert.

bomnipotent_client --domain=bomnipotent_server_of_your_choice --user=user@example.com --output-mode=normal --secret-key=/home/some_secret_key.pem session login

bomnipotent_client -d bomnipotent_server_of_your_choice -u user@example.com -o normal -s /home/some_secret_key.pem session login

[INFO] Storing session data in /root/.config/bomnipotent/session.toml

Wann immer Sie den BOMnipotent Client von nun an aufrufen, werden diese Parameter automatisch verwendet.

Jegliche relativen Dateipfade, die Sie hierbei angeben, werden vor dem Speichern in absolute Pfade umgewandelt. Somit können Sie die Sitzungsdaten von überall auf Ihrem Computer nutzen.

Parameter überschreiben

Wenn Sie angemeldet sind und bei einem Aufruf des BOMnipotent Clients globale optionale Parameter angeben, werden diese stattdessen verwendet:

bomnipotent_client --domain=bomnipotent.wwh-soft.com health # Will contact the other server

bomnipotent_client -d bomnipotent.wwh-soft.com health # Will contact the other server

[INFO] Service is healthy

Um die im Sitzungsspeicher gespeicherten Daten dauerhaft zu ändern, melden Sie sich einfach erneut mit den neuen Parametern an.

Dies kann auch verwendet werden, um Parameter zu entfernen, indem Sie sie einfach nicht angeben:

bomnipotent_client --domain=some_other_bomnipotent_server --user=other_user@example.com session login # Will set secret-key and other non-specified options to none.

bomnipotent_client -d some_other_bomnipotent_server -u other_user@example.com session login # Will set secret-key and other non-specified options to none.

[INFO] Storing session data in /root/.config/bomnipotent/session.toml

Status

Um die Parameter der aktuellen Sitzung auszugeben, rufen Sie “session status”. Die Ausgabe ist im TOML Format (so wie die Daten auch auf Ihrem Dateisystem gespeichert sind):

bomnipotent_client session status

domain = "bomnipotent_server_of_your_choice"
user = "user@example.com"
output_mode = "Normal"
secret_key_path = "/home/some_secret_key.pem"

Falls Sie JSON bevorzugen, fügen Sie einfach die “–json” Option hinzu:

bomnipotent_client session status --json

bomnipotent_client session status -j

{
  "domain": "bomnipotent_server_of_your_choice",
  "user": "user@example.com",
  "output_mode": "Normal",
  "secret_key_path": "/home/some_secret_key.pem"
}

Falls Sie nicht eingeloggt sind, erhalten sie eine informative Ausgabe und einen leeren TOML/JSON Output:

bomnipotent_client session status

[INFO] No session data is currently stored

bomnipotent_client session status --json

bomnipotent_client session status -j

[INFO] No session data is currently stored
{}

Falls Sie diesen Befehl verwenden möchten, um programmatisch zu prüfen, ob Sitzungsdaten gespeichert sind, verwenden Sie zum Beispiel den “raw” Ausgabemodus um den Info Trace zu vermeiden, und prüfen Sie, ob die Ausgabe leer ist:

#!/bin/bash

output=$(bomnipotent_client --output-mode raw session status)
if [ -n "$output" ]; then
    echo "Found session data:"
    echo "$output"
else
    echo "Session not logged in."
fi

$output = bomnipotent_client --output-mode raw session status
if ($output) {
    Write-Output "Found session data:"
    Write-Output $output
} else {
    Write-Output "Session not logged in."
}

Abmeldung

Um alle Parameter zu entfernen, rufen Sie logout auf:

bomnipotent_client session logout

[INFO] No session is currently logged in, nothing to do.

Dies entfernt die Sitzungsdatei.

Log Level

BOMnipotent Client bietet verschiedene Schweregrade an Logs:

• error
• warn
• info (default)
• debug
• trace

Diese können wie folgt ausgewählt werden:

bomnipotent_client --log-level=<LEVEL> <COMMAND>

bomnipotent_client -l <LEVEL> <COMMAND>

Sie definieren einen minimalen Schweregrad, den eine Nachricht haben muss um ausgegeben zu werden: Mit log-level debug gibt BOMnipotent alle Nachrichten der Schweregrade error, warn, info und debug aus, aber nicht trace.

Standardmäßig schreibt BOMnipotent Client die Nachrichten zu stdout, unabhängig vom Schweregrad. Sie können es stattdessen anweisen, die Logs in eine Datei zu schreiben.

Info, Warn und Error

Der Standard-Ausgabemodus ist info. Er gibt einige Informationen aus, überflutet den Benutzer jedoch nicht mit Nachrichten.

bomnipotent_client health

[INFO] The service at https://bomnipotent_server_of_your_choice is healthy.

bomnipotent_client bom list

[INFO] 
╭────────────────────────┬─────────┬─────────────────────────┬───────────┬────────────╮
│ Product                │ Version │ Timestamp               │ TLP       │ Components │
├────────────────────────┼─────────┼─────────────────────────┼───────────┼────────────┤
│ Best Project           │ 3.1.4   │ 2025-01-01 10:11:12 UTC │ TLP:GREEN │ 75         │
│ Your Project           │ 1.0.0   │ 2025-01-01 10:11:12 UTC │ Default   │ 75         │
│ Your Project           │ 1.1.0   │ 2025-01-01 10:11:12 UTC │ Default   │ 75         │
│ Your Project Container │ 1.2.3   │ 2025-01-01 10:11:12 UTC │ TLP:WHITE │ 939        │
╰────────────────────────┴─────────┴─────────────────────────┴───────────┴────────────╯

Debug

Der Debug-Ausgabemodus gibt zusätzliche Informationen aus, die bei der Fehlersuche in der Eingabe oder Konfiguration nützlich sein können:

bomnipotent_client --log-level=debug health

bomnipotent_client -l debug health

[DEBUG] Looking for secret key
[DEBUG] The provided key is a path: /home/admin_secret_key.pem
[DEBUG] Reading secret key from provided path '/home/admin_secret_key.pem'
[DEBUG] Signing request.
[DEBUG] Assembled GET request to https://bomnipotent_server_of_your_choice/health.
[DEBUG] Call<Prepare>
[DEBUG] GET https://bomnipotent_server_of_your_choice/******
[DEBUG] Resolved: ArrayVec { len: 1, arr: [172.20.0.3:443] }
[DEBUG] Connected TcpStream to 172.20.0.3:443
[DEBUG] No cached session for DnsName("bomnipotent_server_of_your_choice")
[DEBUG] Not resuming any session
[DEBUG] Wrapped TLS
[DEBUG] Call<SendRequest>
[DEBUG] Request { method: GET, uri: https://bomnipotent_server_of_your_choice/******, version: HTTP/1.1, headers: {"accept": "*/*", "host": "bomnipotent_server_of_your_choice", "user-agent": "bomnipotent_client", "<NOTICE>": "4 HEADERS ARE REDACTED"} }
[DEBUG] Using ciphersuite TLS13_AES_256_GCM_SHA384
[DEBUG] Not resuming
[DEBUG] TLS1.3 encrypted extensions: ServerExtensions { server_name_ack: (), unknown_extensions: {}, .. }
[DEBUG] ALPN protocol is None
[DEBUG] add_parsable_certificates processed 143 valid and 0 invalid certs
[DEBUG] Loaded 143 CA certificates from the system
[DEBUG] Call<RecvResponse>
[DEBUG] Call<RecvBody>
[DEBUG] Response { status: 200, version: HTTP/1.1, headers: {"content-type": "text/plain; charset=utf-8", "content-length": "68", "date": "Wed, 01 Jan 2025 10:11:12 GMT", "<NOTICE>": "2 HEADERS ARE REDACTED"} }
[DEBUG] Call<Cleanup>
[DEBUG] Pool gone: PoolKey { scheme: "https", authority: bomnipotent_server_of_your_choice, proxy: None }
[INFO] The service at https://bomnipotent_server_of_your_choice is healthy.

Trace

Im Trace-Modus gibt BOMnipotent alles aus, was es auch nur im Geringsten interessant findet. Dies ist primär nützlich, um Fehler im Programm selbst zu identifizieren.

bomnipotent_client --log-level=trace health | grep "TRACE" | head -n 10

bomnipotent_client -l trace health | grep "TRACE" | head -n 10

[TRACE] Running command Health with args Arguments {
[TRACE] Using platform's default root certificates.
[TRACE] Resolve: bomnipotent_server_of_your_choice:443
[TRACE] Try connect TcpStream to 172.20.0.3:443
[TRACE] Try wrap in TLS
[TRACE] Sending ClientHello Message {
[TRACE] 4745 5420 2f68 6561 6c74 6820 4854 5450  GET./health.HTTP
[TRACE] 2f31 2e31 0d0a 6163 6365 7074 3a20 2a2f  /1.1..accept:.*/
[TRACE] 2a0d 0a68 6f73 743a 2062 6f6d 6e69 706f  *..host:.bomnipo
[TRACE] 7465 6e74 5f73 6572 7665 725f 6f66 5f79  tent_server_of_y

Log Datei

Um die Log Ausgabe eines BOMnipotent Client Aufrufs in einer Datei zu speichern anstatt sie auf stdout zu schreiben, rufen Sie:

bomnipotent_client --log-file=/tmp/bomnipotent.log bom list

bomnipotent_client -f /tmp/bomnipotent.log bom list

Die Ausgabe ist die Gleiche, abgesehen davon, dass sie für stdout entsprechend ihres Schweregrades eingefärbt wird, und für ide Logdatei nicht.

Falls BOMnipotent Client wiederholt mit derselben Logdatei gerufen wird, wird es diese überschreiben, falls die existierende Datei aussieht wie eine Logdatei.

Eine Datei sieht für BOMnipotent wie eine Logdatei aus, falls sie entweder leer ist, oder mindestens einen der Strings “[ERROR]”, “[WARN]”, “[INFO]”, “[DEBUG]” oder “[TRACE]” enthält.

Falls eine existierende Datei nicht wie eine Logdatei aussieht, wird BOMnipotent vorsichtigt und bricht ab:

bomnipotent_client --log-file=/home/george_r_r_martin_not_a.log bom list

bomnipotent_client -f /home/george_r_r_martin_not_a.log bom list

Failed to set log target: Log-file "/home/george_r_r_martin_not_a.log" already exists and does not look like a log-file. Aborting before overwriting any data you do not want overwritten.

Da die Befehle “bom get” / “csaf get” und “fetch” dafür gedacht sind, von Maschinen verarbeitet zu werden, schreiben sie ihre Ausgabe in stdout, selbst wenn eine Logdatei konfiguriert ist. Diese Trennung der Ausgaben macht es möglich, gleichzeitig die Daten zu verarbeiten und mögliche Fehlermeldungen zu speichern.

Ausgabemodus

Ohne das irgendein Ausgabemodus angegeben ist, schreibt BOMnipotent Client seine Lognachrichten entweder auf stdout, oder in eine konfigurierte Logdatei . Das ist großartig falls es von Menschen genutzt wird, aber nicht so praktisch für Automation. Deswegen bietet BOMnipotent Client zusätzlich die beiden Ausgabemodi “code” und “raw” an. Diese modifizieren welche Ausgabe wohin geschrieben wird.

Ausgaben

In den Ausgabemodi “code” oder “raw” wird nur der HTTP Code oder der Response Body zu stdout ausgegeben. Falls Sie eine Logdatei konfiguriert haben , werden alle Logs bis zu dem angegebenen Log-Level dort gespeichert.

Falls Sie hingegen keine Logdatei angegeben haben, will BOMnipotent Sie dennoch wissen lassen, falls etwas schiefgeht. Deswegen werden in diesem Fall Lognachrichten mit den Schweregraden “error” oder “warn” zu stderr ausgegeben.

Modi

Code

Der code-Modus gibt nur den HTTP Statuscode der Antwort aus.

bomnipotent_client --output-mode=code health

bomnipotent_client -o code health

200

Das ist besonders nützlich, wenn Sie BOMnipotent-Client in einem Skript verwendet möchten:

#!/bin/bash
set -e # Return on error
# ...other code...
bomnipotent_client \
    --output-mode=code \
    --domain=$domain \
    --log-level=debug \
    --log-file="/tmp/loggy.log" \
    session login
code=$(bomnipotent_client health)
if (( code != 200 )); then
    echo "Server at $domain is not healthy!"
    cat /tmp/loggy.log
    exit 1;
fi

Beachten Sie, dass am Ende der Ausgabe kein Zeilenumbruch oder Wagenrücklaufzeichen steht.

“Wagenrücklaufzeichen” ist tatsächlich die deutsche Übersetzung von “carriage return”. Abgefahren.

Achtung: Im Code Modus hat BOMnipotent Client immer einen Terminal Rückgabewert von 0 (was Erfolg anzeigt), egal welchen HTTP Code es zurückbekommt. Das macht es leichter, das Programm in Skripten zu verwenden, welche bei einem Fehler abbrechen.

Raw

Für Aufrufe, die auf strukturierte Daten zugreifen, gibt der raw-Modus die Daten aus dem Response Body aus, welche üblicherweise im JSON Format vorliegen.

bomnipotent_client --output-mode=raw bom list

bomnipotent_client -o raw bom list

[{"product":"Best Project","version":"3.1.4","timestamp":"2025-01-01T10:11:12Z","tlp":"TLP:GREEN","components":75},{"product":"Your Project","version":"1.0.0","timestamp":"2025-01-01T10:11:12Z","tlp":null,"components":75},{"product":"Your Project","version":"1.1.0","timestamp":"2025-01-01T10:11:12Z","tlp":null,"components":75},{"product":"Your Project Container","version":"1.2.3","timestamp":"2025-01-01T10:11:12Z","tlp":"TLP:WHITE","components":939}]

Die Ausgabe kann dann einfach von der Programmlogik analysiert und weiterverarbeitet werden.

Beachten Sie, dass am Ende der Ausgabe kein Zeilenumbruch oder Wagenrücklaufzeichen steht.