Grundlegende Nutzung

Dieser Abschnitt behandelt die grundlegende Nutzung von BOMnipotent Client. Sie ist sowohl relevant für Konsumenten als auch Produzenten von Dokumenten zur Lieferkettensicherheit.

Unterabschnitte von Grundlegende Nutzung

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=<Server> user request <Ihre-Email>
bomnipotent_client -d <Server> user request <Ihre-Email>

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.

​
[INFO] Generating new key pair
[INFO] Storing secret key to "/home/simon/.config/bomnipotent/secret_key.pem" and public key to "/home/simon/.config/bomnipotent/public_key.pem"
[INFO] User request submitted. It now needs to be confirmed by a user manager.

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.

Jetzt, da Ihre Anfrage gestellt ist, müssen Sie darauf warten, dass ein Nutzermanager sie bestätigt. Danach 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 .

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=<Server> user request <Ihre-Email> <Pfad/zum/Schlüssel>
bomnipotent_client -d <Server> user request <Ihre-Email> <Pfad/zum/Schlüssel>

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> --email=<Ihre-Email> <Kommando>
bomnipotent_client -d <Server> -e <Ihre-Email> <Kommando>

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=<Server> --email=<Ihre-Email> --secret-key=<Pfad/zum/Schlüssel> <Kommando>
bomnipotent_client -d <Server> -e <Ihre-Email> -s <Pfad/zum/Schlüssel> <Kommando>

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 Anmeldebefehl verwenden, um sie in einer Benutzersitzung zu speichern:

​
bomnipotent_client --domain=<Server> --email=<Ihre-Email> --output=<Modus> --secret-key=<Pfad/zum/Schlüssel> --trusted-root=<Pfad/zum/Zertifikat> login
bomnipotent_client -d <Server> -e <Ihre-Email> -o <Modus> -s <Pfad/zum/Schlüssel> -t <Pfad/zum/Zertifikat> login

Dies erstellt eine Datei im lokalen Benutzerordner, die die angegebenen Parameter speichert.

​
[INFO] Storing session data in /home/simon/.config/bomnipotent/session.toml

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

bomnipotent_client bom list # Wird automatisch die angegebene Domain kontaktieren und Ihre Authentifizierungsdaten verwenden.

Parameter überschreiben

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

​
bomnipotent_client --domain=<anderer-Server> bom list # Wird den andereren Server kontaktieren
bomnipotent_client -d <anderer-Server> bom list # Wird den andereren Server kontaktieren

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=<anderer-Server> --email=<Ihre-Email> --output=<mode> login # Setzt secret-key und trusted-root zurück.
bomnipotent_client -d <anderer-Server> -e <Ihre-Email> -o <Modus> login # Setzt secret-key und trusted-root zurück.

Status

Um die Parameter der aktuellen Sitzung auszugeben, rufen Sie:

bomnipotent_client session status

Die Ausgabe ist im TOML Format (so wie die Daten auch auf Ihrem Dateisystem gespeichert sind):

​
domain = "https://localhost:62443"
email = "admin@wwh-soft.com"
secret_key_path = "/home/simon/git/bomnipotent/test_cryptofiles/admin"
trusted_root_path = "/home/simon/git/bomnipotent/test_cryptofiles/ca.crt"

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

​
./bomnipotent_client session status --json
./bomnipotent_client session status -j

​
{
  "domain": "https://localhost:62443",
  "email": "admin@wwh-soft.com",
  "secret_key_path": "/home/simon/git/bomnipotent/test_cryptofiles/admin",
  "trusted_root_path": "/home/simon/git/bomnipotent/test_cryptofiles/ca.crt"
}

Falls Sie nicht eingeloggt sind, erhalten sie einen informativen Trace und einen leeren TOML/JSON Output:

​
[INFO] No session data is currently stored
[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 raw session status)
if [ -n "$output" ]; then
    echo "Found session data:"
    echo "$output"
else
    echo "Session not logged in."
fi
$output = ./bomnipotent_client --output 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 logout

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> <BEFEHL>
bomnipotent_client -l <LEVEL> <BEFEHL>

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] Service is healthy
bomnipotent_client bom list
​
[INFO]
╭─────────────┬─────────┬─────────────────────────┬─────────┬────────────╮
│ Product     │ Version │ Timestamp               │ TLP     │ Components │
├─────────────┼─────────┼─────────────────────────┼─────────┼────────────┤
│ BOMnipotent │ 1.0.0   │ 2025-02-01 03:31:50 UTC │ Default │ 363        │
╰─────────────┴─────────┴─────────────────────────┴─────────┴────────────╯

Oder, falls ein Fehler auftritt:

​
[ERROR] Received response:
404 Not Found
BOM Volcano_1.0.0 not found in database

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/simon/git/bomnipotent/test_cryptofiles/admin
[DEBUG] Reading secret key from provided path "/home/simon/git/bomnipotent/test_cryptofiles/admin"
[DEBUG] Adding trusted root certificate
[DEBUG] Signing request
[DEBUG] Assembled GET request to https://localhost:62443/health
[DEBUG] starting new connection: https://localhost:62443/
[INFO] Service is healthy

Trace

Im Trace-Modus gibt BOMnipotent zusätzlich das Modul aus, aus dem die Nachricht stammt. Dies ist primär nützlich, um Fehler im Programm selbst zu identifizieren.

​
bomnipotent_client --log-level=trace health
bomnipotent_client -l trace health

​
[bomnipotent_client] [TRACE] Running command Health with args Arguments {
    domain: Some(
        "https://localhost:62443",
    ),
    email: Some(
        "admin@wwh-soft.com",
    ),
    log_level: Some(
        Trace,
    ),
    log_file: None,
    output_mode: None,
    secret_key: Some(
        "/home/simon/git/bomnipotent/test_cryptofiles/admin",
    ),
    trusted_root: Some(
        "/home/simon/git/bomnipotent/test_cryptofiles/ca.crt",
    ),
    command: Health,
}
[bomnipotent_client::keys] [DEBUG] Looking for secret key
[bomnipotent_client::keys] [DEBUG] The provided key is a path: /home/simon/git/bomnipotent/test_cryptofiles/admin
[bomnipotent_client::keys] [DEBUG] Reading secret key from provided path "/home/simon/git/bomnipotent/test_cryptofiles/admin"
[bomnipotent_client::request] [DEBUG] Adding trusted root certificate
[reqwest::blocking::wait] [TRACE] (ThreadId(1)) park without timeout
[reqwest::blocking::client] [TRACE] (ThreadId(14)) start runtime::block_on
[bomnipotent_client::request] [DEBUG] Signing request
[bomnipotent_client::request] [DEBUG] Assembled GET request to https://localhost:62443/health
[reqwest::blocking::wait] [TRACE] wait at most 30s
[reqwest::blocking::wait] [TRACE] (ThreadId(1)) park timeout 29.999994032s
[reqwest::connect] [DEBUG] starting new connection: https://localhost:62443/
[reqwest::blocking::wait] [TRACE] wait at most 30s
[reqwest::blocking::client] [TRACE] closing runtime thread (ThreadId(14))
[reqwest::blocking::client] [TRACE] signaled close for runtime thread (ThreadId(14))
[reqwest::blocking::client] [TRACE] (ThreadId(14)) Receiver is shutdown
[reqwest::blocking::client] [TRACE] (ThreadId(14)) end runtime::block_on
[reqwest::blocking::client] [TRACE] (ThreadId(14)) finished
[reqwest::blocking::client] [TRACE] closed runtime thread (ThreadId(14))
[bomnipotent_client::output] [INFO] Service is healthy

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=<PFAD> <BEFEHL>
bomnipotent_client -f <PFAD> <BEFEHL>

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:

​
Logfile "/tmp/loggy.log" already exists and does not look like a logfile. 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
​
[{"name":"BOMnipotent","version":"1.0.0","timestamp":"2025-01-03T05:38:03Z","tlp":null,"components":350}]

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.