Docker Compose

Das empfohlene und einfachste Setup für BOMnipotent Server verwendet Docker Compose . Diese Variante des Setups macht BOMnipotent Server direkt vom Internet erreichbar. Falls Sie den Traffic über einen Reverse Proxy handhaben wollen, nutzen Sie stattdessen eine andere Anleitung .

Vorgeschlagene Dateistruktur

Die vorgeschlagene Dateistruktur im Lieblingsverzeichnis Ihres Servers sieht folgendermaßen aus:

├── .env
├── bomnipotent_config
│   ├── config.toml
│   └── config.toml.default
└── compose.yaml

Dieses Tutorial führt Sie durch die Dateien und erklärt sie einzeln.

.env

Der BOMnipotent-Server kommuniziert mit einer Datenbank. Derzeit wird nur PostgreSQL als Backend unterstützt. Die Datenbank ist durch ein Passwort geschützt. Es empfiehlt sich, das Passwort in einer separaten .env-Datei zu speichern, anstatt direkt im compose.yaml.

Der Name der Datei muss “.env” lauten, ansonsten erkennt Docker sie nicht.

Ihre .env-Datei sollte so aussehen:

BOMNIPOTENT_DB_PW=<Ihr-Datenbank-Passwort>
SMTP_SECRET=<Ihr-smtp-Authentifizierungs-Geheimnis>

Falls Sie ein Versionierungssystem zum Speichern Ihres Setups verwenden, vergessen Sie nicht, “.env” zu Ihrer .gitignore oder analogen Ignore-Datei hinzuzufügen!

config.toml

BOMnipotent Server benötigt eine Konfigurationsdatei, die in einem anderen Abschnitt ausführlicher erläutert wird.

Der Name der Datei ist grundsätzlich beliebig, aber der einsatzbereite Docker-Container von BOMnipotent Server ist so eingerichtet, dass er nach “config.toml” sucht.

Eine minimale Konfiguration sieht so aus:

# Die db_url hat die Struktur [db_client]://[Benutzer]:[Passwort]@[Container]:[Port]/[db]
# Beachten Sie, dass ${BOMNIPOTENT_DB_PW} auf eine Umgebungsvariable verweist.
db_url = "postgres://bomnipotent_user:${BOMNIPOTENT_DB_PW}@bomnipotent_db:5432/bomnipotent_db"
# Domain, hinter der der Bomnipotent-Server gehostet wird
domain = "https://bomnipotent.<Ihre-Domain>.<Top-Level>"

[tls]
# Der Pfad zu Ihrer vollständigen TLS-Zertifikatskette
certificate_chain_path = "/etc/ssl/certs/<Ihre-TLS-Zertifikatskette.crt>"
# Der Pfad zu Ihrem geheimen TLS-Schlüssel
secret_key_path = "/etc/ssl/private/<Ihr-geheimer-TLS-Schlüssel>"

[smtp]
# Der Nutzername für den Mail-Anbieter, üblicherweise Ihre Mail Adresse
user = "<you@yourdomain.com>"
# Der SMTP Endpunkt Ihres Mail-Anbieters
endpoint = "<your.smtp.host>"
# Das Geheimnis um sich gegenüber dem Mail-Anbieter zu authentifizierenn, üblicherweise Ihr Passwort
secret = "${SMTP_SECRET}"

# Herausgeberdaten gemäß dem unten verlinkten CSAF-Standard
[provider_metadata.publisher]
name = "<Geben Sie den Namen Ihrer Organisation an>"
# Namespace Ihrer Organisation in Form einer vollständigen URL
namespace = "https://<Ihre Domain>.<Top-Level>"
# Dies ist höchstwahrscheinlich die gewünschte Kategorie
category = "vendor"
# Kontaktdaten sind optional und in freier Form
contact_details = "<Bei Sicherheitsfragen kontaktieren Sie uns bitte unter...>"

Füllen Sie die Klammern mit Ihren Daten aus.

Der Abschnitt über TLS Konfiguration enthält detailiertere Information wie Sie übliche Fallstricke verhindern können.

Falls Sie es bevorzugen, eine lokal laufende SMTP Relay Station zu nutzen, schauen Sie sich die notwendigen Anpassungen der compose Datei an.

Die Herausgeberdaten werden verwendet, um dem OASIS CSAF-Standard zu entsprechen.

Der Abschnitt über Provider-Metadata enthält mehr Details dazu was die verschiedenen Felder bedeuten.

Es wird empfohlen, Ihre config.toml-Datei in einem dedizierten Verzeichnis zu speichern, in diesem Beispiel “bomnipotent_config”. Die Docker-Compose-Datei gewährt Lesezugriff auf diesen Ordner. Dieses Setup hat zwei Vorteile:

• Im unwahrscheinlichen Fall einer Sicherheitsverletzung des BOMnipotent Server-Containers hätte ein Angreifer nur Zugriff auf Ihr Konfigurationsverzeichnis und sonst nichts auf Ihrem Server.
• BOMnipotent Server überwacht das Verzeichnis auf Änderungen und versucht, die Konfigurationsdatei neu zu laden, wenn sie geändert wurde. Dies funktioniert nicht, wenn nur eine einzige Datei dem Docker-Container zugänglich gemacht wird.

Viele Konfigurationseinstellungen unterstützen Hot Reloading, d. h. sie können geändert werden, ohne den Server neu zu starten.

Nachdem Sie Ihre config.toml eingerichtet haben, möchten Sie sie möglicherweise beispielsweise als config.toml.default kopieren, um Ihre ursprüngliche Konfiguration schnell wiederherstellen zu können. Dies ist jedoch völlig optional.

compose.yaml

In der Compose-Datei geben Sie das Container-Setup an. Sobald es reibungslos läuft, muss es nicht mehr so ​​oft geändert werden, aber wenn Sie Docker noch nicht kennen, kann es einige Zeit dauern, bis Sie es verstanden haben.

Die Datei muss “compose.yaml” heißen, da kann Docker etwas pingelig sein.

Eine vollständig einsatzbereite Compose-Datei sieht so aus:

# Es ist optional, dem Setup einen Namen zu geben, andernfalls wird er von Docker hergeleitet.
name: bomnipotent_server_containers

# Die Docker-Container müssen kommunizieren und benötigen dafür ein Netzwerk.
networks:
  # Dieses Netzwerk benötigt eine Referenz
  bomnipotent_network:
    # Da sich die Container auf demselben Docker-Host befinden, ist "bridge" eine sinnvolle Treiberwahl.
    driver: bridge
    # Es ist in Ordnung, dem Netzwerk denselben Namen wie der Referenz zu geben.
    name: bomnipotent_network

volumes:
  # Definieren Sie das Volume für die dauerhafte Speicherung der Datenbank
  bomnipotent_data:
    driver: local
  # Der Server selbst benötigt auch noch ein Volumen falls Sie nicht das Abonnement nach jedem Neustart aktivieren wollen
  bomnipotent_subscription:
    driver: local

services:
  bomnipotent_db:
    # Name des Datenbankcontainers
    container_name: bomnipotent_db
    deploy:
      resources:
        limits:
          # Begrenzen Sie die CPU-Auslastung auf 0,5 Kerne
          cpus: "0.5"
          # Begrenzen Sie die Speicherauslastung auf 512 MB
          memory: "512M"
    environment:
      # Legen Sie den Datenbanknamen fest
      POSTGRES_DB: bomnipotent_db
      # Legen Sie den Datenbankbenutzer fest
      POSTGRES_USER: bomnipotent_user
      # Legen Sie das Datenbankkennwort aus der .env-Dateivariable fest
      POSTGRES_PASSWORD: ${BOMNIPOTENT_DB_PW}
    healthcheck:
      # Überprüfen Sie, ob die Datenbank bereit ist
      test: ["CMD-SHELL", "pg_isready -U bomnipotent_user -d bomnipotent_db"]
      # Intervall zwischen Integritätsprüfungen
      interval: 60s
      # Timeout für jede Integritätsprüfung
      timeout: 10s
      # Anzahl der Wiederholungsversuche, bevor der Container als fehlerhaft betrachtet wird
      retries: 5
      # Startzeitraum vor der ersten Integritätsprüfung
      start_period: 10s
    # Verwenden Sie das angegebene PostgreSQL-Image
    # Sie können das Container-Tag nach Belieben anpassen
    image: postgres:17
    logging:
      # Verwenden Sie den lokalen Protokollierungstreiber
      driver: local
      options:
        # Begrenzen Sie die Protokollgröße auf 10 MB
        max-size: "10m"
        # Bewahren Sie maximal 3 Protokolldateien auf
        max-file: "3"
    networks:
      # Stellen Sie eine Verbindung zum angegebenen Netzwerk her
      - bomnipotent_network
    # Starten Sie den Container neu, wenn er aus einem anderen Grund als einem Benutzerbefehl angehalten wurde
    restart: always
    volumes:
      # Mounten Sie das Volume für die dauerhafte Datenspeicherung
      - bomnipotent_data:/var/lib/postgresql/data

  bomnipotent_server:
    # Name des Servercontainers
    container_name: bomnipotent_server
    depends_on:
      # Stellen Sie sicher, dass der Datenbankdienst fehlerfrei ist, bevor Sie den Server starten
      bomnipotent_db:
        condition: service_healthy
    deploy:
      resources:
        limits:
          # Begrenzen Sie die CPU-Auslastung auf 0,5 Kerne
          cpus: "0.5"
          # Begrenzen Sie die Speicherauslastung auf 512 MB
          memory: "512M"
    environment:
      # Geben Sie das Datenbankkennwort an den Server weiter.
      BOMNIPOTENT_DB_PW: ${BOMNIPOTENT_DB_PW}
      # Geben Sie das SMTP Geheimnis an den Server weiter.
      SMTP_SECRET: ${SMTP_SECRET}
    healthcheck:
      # Prüfen Sie, ob der Server fehlerfrei ist
      # Ihr TLS-Zertifikat ist höchstwahrscheinlich für "localhost" nicht gültig
      # Daher das --insecure Flag
      test: ["CMD-SHELL", "curl --fail --insecure https://localhost:8443/health || exit 1"]
      # Intervall zwischen den Integritätsprüfungen
      interval: 60s
      # Timeout für jede Integritätsprüfung
      timeout: 10s
      # Anzahl der Wiederholungsversuche, bevor der Container als fehlerhaft betrachtet wird
      retries: 5
      # Startzeitraum vor dem ersten Integritätscheck
      start_period: 10s
    # Dies ist das offizielle Docker-Image, auf dem eine BOMnipotent-Serverinstanz ausgeführt wird.
    image: wwhsoft/bomnipotent_server:latest
    logging:
      # Verwenden Sie den lokalen Protokollierungstreiber
      driver: local
      options:
        # Begrenzen Sie die Protokollgröße auf 10 MB
        max-size: "10m"
        # Bewahren Sie maximal 3 Protokolldateien auf
        max-file: "3"
    networks:
      # Stellen Sie eine Verbindung zum angegebenen Netzwerk her
      - bomnipotent_network
    ports:
      # Ordnen Sie Port 443 auf dem Host Port 8443 auf dem Container zu
      # Dies ermöglicht die Verbindung über verschlüsselte Kommunikation 
      - target: 8443
        published: 443
    # Starten Sie den Container neu, wenn er aus einem anderen Grund als einem Benutzerbefehl angehalten wurde
    restart: always
    volumes:
      # Mounten Sie den Konfigurationsordner auf dem Host per Bind
      - type: bind
        source: ./bomnipotent_config
        target: /etc/bomnipotent_server/configs/
        read_only: true
      # Mounten Sie das SSL-Verzeichnis per Bind, damit BOMnipotent das TLS-Zertifikat und den Schlüssel findet.
      - type: bind
        source: /etc/ssl
        target: /etc/ssl
        read_only: true
      # Die Subscription darf gern in dem Container persisitert werden
      - bomnipotent_subscription:/root/.config/bomnipotent

name: bomnipotent_server_containers

networks:
  bomnipotent_network:
    driver: bridge
    name: bomnipotent_network

volumes:
  bomnipotent_data:
    driver: local
  bomnipotent_subscription:
    driver: local

services:
  bomnipotent_db:
    container_name: bomnipotent_db
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"
    environment:
      POSTGRES_DB: bomnipotent_db
      POSTGRES_USER: bomnipotent_user
      POSTGRES_PASSWORD: ${BOMNIPOTENT_DB_PW}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U bomnipotent_user -d bomnipotent_db"]
      interval: 60s
      timeout: 10s
      retries: 5
      start_period: 10s
    image: postgres:17
    logging:
      driver: local
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - bomnipotent_network
    restart: always
    volumes:
      - bomnipotent_data:/var/lib/postgresql/data

  bomnipotent_server:
    container_name: bomnipotent_server
    depends_on:
      bomnipotent_db:
        condition: service_healthy
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"
    environment:
      BOMNIPOTENT_DB_PW: ${BOMNIPOTENT_DB_PW}
      SMTP_SECRET: ${SMTP_SECRET}
    healthcheck:
      test: ["CMD-SHELL", "curl --fail --insecure https://localhost:8443/health || exit 1"]
      interval: 60s
      timeout: 10s
      retries: 5
      start_period: 10s
    image: wwhsoft/bomnipotent_server:latest
    logging:
      driver: local
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - bomnipotent_network
    ports:
      - target: 8443
        published: 443
    restart: always
    volumes:
      - type: bind
        source: ./bomnipotent_config
        target: /etc/bomnipotent_server/configs/
        read_only: true
      - type: bind
        source: /etc/ssl
        target: /etc/ssl
        read_only: true
      - bomnipotent_subscription:/root/.config/bomnipotent

Speichern Sie diese Datei als “compose.yaml”. Dann rufen Sie:

docker compose --detach

docker compose -d

Ihr Server ist jetzt einsatzbereit!

Rufen Sie “docker ps” um den Zustand des Servers zu überprüfen.

Docker Compose inkl. Reverse Proxy

Diese Variante des sehr ähnlichen Setups mit Docker Compose richtet nicht nur einen laufenden BOMnipotent-Server ein, sondern auch einen nginx Reverse-Proxy.

Vorgeschlagene Dateistruktur

Die vorgeschlagene Dateistruktur im Lieblingsverzeichnis Ihres Servers sieht folgendermaßen aus:

├── .env
├── bomnipotent_config
│   ├── config.toml
│   └── config.toml.default
├── proxy_config
│   └── conf.d
│       └── default.conf
└── compose.yaml

Dieses Tutorial führt Sie durch die Dateien und erklärt sie einzeln.

proxy_config/conf.d/default.conf

Die Verwendung von nginx als Reverse-Proxy ist lediglich ein Vorschlag. Sie können ihn durch jede andere Serversoftware Ihrer Wahl ersetzen.

Vereinfacht ausgedrückt dient der Reverse-Proxy als Tor zu Ihrem Server: Er ermöglicht Ihnen, mehrere Dienste (BOMnipotent-Server, eine Website usw.) hinter derselben IP-Adresse zu hosten. Jede Anfrage an eine Ihrer URLs landet beim Reverse-Proxy, der sie dann an den richtigen Dienst weiterleitet. So landen Sie beim Besuch von doc.bomnipotent.de auf einer anderen Website als beim Besuch von www.bomnipotent.de , obwohl beide hinter derselben IP-Adresse gehostet werden.

Nginx sucht seine Konfiguration an verschiedenen Orten. Später in der compose.yaml verwenden wir Mount-Binding, um unsere Konfiguration hinterrücks in den Nginx-Docker-Container einzuschleusen.

Sie können Folgendes als Ausgangspunkt für Ihre default.conf verwenden:

# Anfragenbegrenzung: Erlaubt bis zu 5 Anfragen pro Sekunde pro IP-Adresse, gespeichert in einem 10 MB großen Speicherbereich.
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=5r/s;

# BOMnipotent Server
server {
    # Hierdurch hört der Server auf Port 443, der typischerweise für HTTPS verwendet wird.
    listen 443 ssl http2;
    # Ersetzen Sie dies durch die tatsächliche Domain Ihres BOMnipotent Servers.
    server_name bomnipotent.your-domain.com;

    # Ersetzen Sie dies durch das tatsächliche Zertifikat Ihrer Domain.
    ssl_certificate /etc/ssl/certs/your-domain-fullchain.crt;
    # Ersetzen Sie dies durch den tatsächlichen privaten Schlüssel Ihres Zertifikats.
    ssl_certificate_key /etc/ssl/private/your-domain_private_key.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384";

    location / {
        # Anfragenbegrenzung anwenden
        limit_req zone=api_limit burst=10 nodelay;

        # Dies weist nginx an, Anfragen an Port 8080 des Docker-Containers weiterzuleiten.
        proxy_pass http://bomnipotent_server:8080;
        proxy_set_header Host $host;
        # Die folgenden Zeilen stellen sicher,
        # dass die BOMnipotent-Logs die IP des Absenders enthalten,
        # anstelle der lokalen IP des Reverse-Proxys.
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Sie möchten wahrscheinlich weitere “Server” Blöcke hinzufügen – warum sonst würden Sie sich für die Einrichtung eines Reverse-Proxy entscheiden?

.env

Der BOMnipotent-Server kommuniziert mit einer Datenbank. Derzeit wird nur PostgreSQL als Backend unterstützt. Die Datenbank ist durch ein Passwort geschützt. Es empfiehlt sich, das Passwort in einer separaten .env-Datei zu speichern, anstatt direkt im compose.yaml.

Der Name der Datei muss “.env” lauten, ansonsten erkennt Docker sie nicht.

Ihre .env-Datei sollte so aussehen:

BOMNIPOTENT_DB_PW=<Ihr-Datenbank-Passwort>
SMTP_SECRET=<Ihr-smtp-Authentifizierungs-Geheimnis>

Falls Sie ein Versionierungssystem zum Speichern Ihres Setups verwenden, vergessen Sie nicht, “.env” zu Ihrer .gitignore oder analogen Ignore-Datei hinzuzufügen!

config.toml

BOMnipotent Server benötigt eine Konfigurationsdatei, die in einem anderen Abschnitt ausführlicher erläutert wird.

Der Name der Datei ist grundsätzlich beliebig, aber der einsatzbereite Docker-Container von BOMnipotent Server ist so eingerichtet, dass er nach “config.toml” sucht.

Eine minimale Konfiguration für einen BOMnipotent Server hinter einem Reverse-Proxy sieht so aus:

# Die db_url hat die Struktur [db_client]://[Benutzer]:[Passwort]@[Container]:[Port]/[db]
# Beachten Sie, dass ${BOMNIPOTENT_DB_PW} auf eine Umgebungsvariable verweist.
db_url = "postgres://bomnipotent_user:${BOMNIPOTENT_DB_PW}@bomnipotent_db:5432/bomnipotent_db"
# Domain, hinter der der Bomnipotent-Server gehostet wird
domain = "https://bomnipotent.<Ihre-Domain>.<Top-Level>"

[tls]
# Die TLS-Verschlüsselung erfolgt über den Reverse-Proxy,
# der BOMnipotent-Server ist nicht direkt über das Internet erreichbar.
allow_http = true

[smtp]
# Der Nutzername für den Mail-Anbieter, üblicherweise Ihre Mail Adresse
user = "<you@yourdomain.com>"
# Der SMTP Endpunkt Ihres Mail-Anbieters
endpoint = "<your.smtp.host>"
# Das Geheimnis um sich gegenüber dem Mail-Anbieter zu authentifizierenn, üblicherweise Ihr Passwort
secret = "${SMTP_SECRET}"

# Herausgeberdaten gemäß dem unten verlinkten CSAF-Standard
[provider_metadata.publisher]
name = "<Geben Sie den Namen Ihrer Organisation an>"
# Namespace Ihrer Organisation in Form einer vollständigen URL
namespace = "https://<Ihre Domain>.<Top-Level>"
# Dies ist höchstwahrscheinlich die gewünschte Kategorie
category = "vendor"
# Kontaktdaten sind optional und in freier Form
contact_details = "<Bei Sicherheitsfragen kontaktieren Sie uns bitte unter...>"

Füllen Sie die Klammern mit Ihren Daten aus.

Falls Sie es bevorzugen, eine lokal laufende SMTP Relay Station zu nutzen, schauen Sie sich die notwendigen Anpassungen der compose Datei an.

Die Herausgeberdaten werden verwendet, um dem OASIS CSAF-Standard zu entsprechen.

Der Abschnitt über Provider-Metadata enthält mehr Details dazu was die verschiedenen Felder bedeuten.

Es wird empfohlen, Ihre config.toml-Datei in einem dedizierten Verzeichnis zu speichern, in diesem Beispiel “bomnipotent_config”. Die Docker-Compose-Datei gewährt Lesezugriff auf diesen Ordner. Dieses Setup hat zwei Vorteile:

• Im unwahrscheinlichen Fall einer Sicherheitsverletzung des BOMnipotent Server-Containers hätte ein Angreifer nur Zugriff auf Ihr Konfigurationsverzeichnis und sonst nichts auf Ihrem Server.
• BOMnipotent Server überwacht das Verzeichnis auf Änderungen und versucht, die Konfigurationsdatei neu zu laden, wenn sie geändert wurde. Dies funktioniert nicht, wenn nur eine einzige Datei dem Docker-Container zugänglich gemacht wird.

Viele Konfigurationseinstellungen unterstützen Hot Reloading, d. h. sie können geändert werden, ohne den Server neu zu starten.

Nachdem Sie Ihre config.toml eingerichtet haben, möchten Sie sie möglicherweise beispielsweise als config.toml.default kopieren, um Ihre ursprüngliche Konfiguration schnell wiederherstellen zu können. Dies ist jedoch völlig optional.

compose.yaml

In der Compose-Datei geben Sie das Container-Setup an. Sobald es reibungslos läuft, muss es nicht mehr so ​​oft geändert werden, aber wenn Sie Docker noch nicht kennen, kann es einige Zeit dauern, bis Sie es verstanden haben.

Die Datei muss “compose.yaml” heißen, da kann Docker etwas pingelig sein.

Eine vollständig einsatzbereite Compose-Datei sieht so aus:

# Die Namensgebung für das Setup ist optional, andernfalls wird der Name von Docker hergeleitet.
name: bomnipotent_server_containers

# Die Docker-Container müssen kommunizieren und benötigen dafür ein Netzwerk.
networks:
  # Dieses Netzwerk benötigt eine Referenz.
  bomnipotent_network:
    # Da sich die Container auf demselben Docker-Host befinden, ist "bridge" eine sinnvolle Treiberwahl.
    driver: bridge
    # Es ist zulässig, dem Netzwerk denselben Namen wie der Referenz zu geben.
    name: bomnipotent_network
  # Der Reverse-Proxy muss mit dem BOMnipotent-Server kommunizieren, nicht jedoch mit der Datenbank.
  proxy_network:
    driver: bridge
    name: proxy_network

volumes:
  # Definieren Sie das Volume für die persistente Speicherung der Datenbank.
  bomnipotent_data:
    driver: local
  # Der Server selbst benötigt ebenfalls Persistenz, wenn das Abonnement nicht nach jedem Neustart aktiviert werden soll.
  bomnipotent_subscription:
    driver: local

services:
  reverse_proxy:
    # Name des Reverse-Proxy-Containers
    container_name: reverse_proxy
    deploy:
      resources:
        limits:
          # Begrenzen Sie die CPU-Auslastung auf 0,5 Kerne.
          cpus: "0.5"
          # Begrenzen Sie die Speichernutzung auf 512 MB.
          memory: "512M"
    healthcheck:
      # Prüfen Sie, ob Nginx läuft und die Konfiguration analysieren kann.
      test: ["CMD-SHELL", "nginx -t || exit 1"]
      # Intervall zwischen Integritätsprüfungen
      interval: 60s
      # Timeout für jede Integritätsprüfung
      timeout: 10s
      # Anzahl der Wiederholungsversuche, bevor der Container als fehlerhaft eingestuft wird
      retries: 3
      # Startzeitraum vor der ersten Integritätsprüfung
      start_period: 60s
    image: nginx:latest
    logging:
      # Lokalen Protokolltreiber verwenden
      driver: local
      options:
        # Protokollgröße auf 10 MB begrenzen
        max-size: "10m"
        # Maximal 3 Protokolldateien speichern
        max-file: "3"
    networks:
      # Mit dem angegebenen Netzwerk verbinden
      - proxy_network
    ports:
      # Port 443 des Containers freigeben
      # Dies ermöglicht eine verschlüsselte Verbindung über das Internet
      - "443:443"
    # Container neu starten, falls er aus einem anderen Grund als einem Benutzerbefehl gestoppt wurde
    restart: on-failure
    volumes:
      # Bind-Mount des SSL-Verzeichnisses, damit nginx das TLS-Zertifikat und den Schlüssel findet.
      - type: bind
        source: /etc/ssl
        target: /etc/ssl
        read_only: true
      # Bind-Mount des Konfigurationsordners auf dem Host
      - type: bind
        source: ./proxy_config/conf.d
        target: /etc/nginx/conf.d
        read_only: true

  bomnipotent_db:
    # Name des Datenbankcontainers
    container_name: bomnipotent_db
    deploy:
      resources:
        limits:
          # CPU-Auslastung auf 0,5 Kerne begrenzen
          cpus: "0.5"
          # Speichernutzung auf 512 MB begrenzen
          memory: "512M"
    environment:
      # Datenbanknamen festlegen
      POSTGRES_DB: bomnipotent_db
      # Datenbankbenutzer festlegen
      POSTGRES_USER: bomnipotent_user
      # Datenbankpasswort aus der Variable der .env-Datei festlegen
      POSTGRES_PASSWORD: ${BOMNIPOTENT_DB_PW}
    healthcheck:
      # Prüfen, ob die Datenbank bereit ist
      test: ["CMD-SHELL", "pg_isready -U bomnipotent_user -d bomnipotent_db"]
      # Intervall zwischen Integritätsprüfungen
      interval: 60s
      # Timeout für jede Integritätsprüfung
      timeout: 10s
      # Anzahl der Wiederholungsversuche, bevor der Container als fehlerhaft eingestuft wird
      retries: 5
      # Startzeitraum vor der ersten Integritätsprüfung
      start_period: 10s
    # Das angegebene PostgreSQL-Image verwenden
    # Sie können den Container-Tag nach Belieben anpassen
    image: postgres:17
    logging:
      # Lokalen Logging-Treiber verwenden
      driver: local
      options:
        # Log-Größe auf 10 MB begrenzen
        max-size: "10m"
        # Maximal 3 Log-Dateien speichern
        max-file: "3"
    networks:
      # Mit dem angegebenen Netzwerk verbinden
      - bomnipotent_network
    # Container neu starten, wenn er aus einem anderen Grund als einem Benutzerbefehl gestoppt wurde.
    restart: always
    volumes:
      # Volume für persistente Datenspeicherung mounten
      - bomnipotent_data:/var/lib/postgresql/data

  bomnipotent_server:
    # Name des Server-Containers
    container_name: bomnipotent_server
    depends_on:
      # Sicherstellen, dass der Datenbankdienst fehlerfrei ist, bevor der Server gestartet wird.
      bomnipotent_db:
        condition: service_healthy
    deploy:
      resources:
        limits:
          # CPU-Auslastung auf 0,5 Kerne begrenzen.
          cpus: "0.5"
          # Speichernutzung auf 512 MB begrenzen.
          memory: "512M"
    environment:
      # Datenbankpasswort an den Server weitergeben.
      BOMNIPOTENT_DB_PW: ${BOMNIPOTENT_DB_PW}
      # Geben Sie das SMTP Geheimnis an den Server weiter.
      SMTP_SECRET: ${SMTP_SECRET}
    healthcheck:
      # Servergesundheit überprüfen
      test: ["CMD-SHELL", "curl --fail http://localhost:8080/health || exit 1"]
      # Intervall zwischen Integritätsprüfungen
      interval: 60s
      # Timeout für jede Integritätsprüfung
      timeout: 10s
      # Anzahl der Wiederholungsversuche, bevor der Container als fehlerhaft eingestuft wird
      retries: 5
      # Startzeitraum vor der ersten Integritätsprüfung
      start_period: 10s
    # Dies ist das offizielle Docker-Image, auf dem eine BOMnipotent-Serverinstanz ausgeführt wird.
    image: wwhsoft/bomnipotent_server:latest
    logging:
      # Verwenden Sie den lokalen Protokollierungstreiber
      driver: local
      options:
        # Begrenzen Sie die Protokollgröße auf 10 MB
        max-size: "10m"
        # Bewahren Sie maximal 3 Protokolldateien auf
        max-file: "3"
    networks:
      # Verbindung zwischen Server und Reverse-Proxy.
      - proxy_network
      # Verbindung zwischen Server und Datenbank.
      - bomnipotent_network
    # Starten Sie den Container neu, wenn er aus einem anderen Grund als einem Benutzerbefehl angehalten wurde
    restart: always
    volumes:
      # Mounten Sie den Konfigurationsordner auf dem Host per Bind
      - type: bind
        source: ./bomnipotent_config
        target: /etc/bomnipotent_server/configs/
        read_only: true
      # Die Subscription darf gern in dem Container persisitert werden
      - bomnipotent_subscription:/root/.config/bomnipotent

name: bomnipotent_server_containers

networks:
  bomnipotent_network:
    driver: bridge
    name: bomnipotent_network
  proxy_network:
    driver: bridge
    name: proxy_network

volumes:
  bomnipotent_data:
    driver: local
  bomnipotent_subscription:
    driver: local

services:
  reverse_proxy:
    container_name: reverse_proxy
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"
    healthcheck:
      test: ["CMD-SHELL", "nginx -t || exit 1"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 60s
    image: nginx:latest
    logging:
      driver: local
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - proxy_network
    ports:
      - "443:443"
    restart: on-failure
    volumes:
      - type: bind
        source: /etc/ssl
        target: /etc/ssl
        read_only: true
      - type: bind
        source: ./proxy_config/conf.d
        target: /etc/nginx/conf.d
        read_only: true

  bomnipotent_db:
    container_name: bomnipotent_db
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"
    environment:
      POSTGRES_DB: bomnipotent_db
      POSTGRES_USER: bomnipotent_user
      POSTGRES_PASSWORD: ${BOMNIPOTENT_DB_PW}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U bomnipotent_user -d bomnipotent_db"]
      interval: 60s
      timeout: 10s
      retries: 5
      start_period: 10s
    image: postgres:17
    logging:
      driver: local
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - bomnipotent_network
    restart: always
    volumes:
      - bomnipotent_data:/var/lib/postgresql/data

  bomnipotent_server:
    container_name: bomnipotent_server
    depends_on:
      bomnipotent_db:
        condition: service_healthy
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: "512M"
    environment:
      BOMNIPOTENT_DB_PW: ${BOMNIPOTENT_DB_PW}
      SMTP_SECRET: ${SMTP_SECRET}
    healthcheck:
      test: ["CMD-SHELL", "curl --fail http://localhost:8080/health || exit 1"]
      interval: 60s
      timeout: 10s
      retries: 5
      start_period: 10s
    image: wwhsoft/bomnipotent_server:latest
    logging:
      driver: local
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - proxy_network
      - bomnipotent_network
    restart: always
    volumes:
      - type: bind
        source: ./bomnipotent_config
        target: /etc/bomnipotent_server/configs/
        read_only: true
      - bomnipotent_subscription:/root/.config/bomnipotent

Speichern Sie diese Datei als “compose.yaml”. Dann rufen Sie:

docker compose --detach

docker compose -d

Ihr Server ist jetzt einsatzbereit!

Rufen Sie “docker ps” um den Zustand des Servers zu überprüfen.

Freistehend

Sie sind nicht gezwungen den offiziellen BOMnipotent Server Docker-Container zu verwenden. Stattdessen können Sie die BOMnipotent Server-Binärdatei herunterladen und direkt als eigenständige Anwendung ausführen.

Dieses Setup ist erst ab Version 0.4.2 sinnvoll, da der Server zuvor keine Portanpassungen und keine Protokollierung in Dateien unterstützte.

Voraussetzung: PostgreSQL

Der BOMnipotent Server benötigt eine PostgreSQL-Datenbank zur Datenspeicherung. Die Einrichtung hängt von Ihrem Server-Betriebssystem ab.

sudo apt-get install postgresql postgresql-contrib

sudo -i -u postgres

psql

CREATE USER bomnipotent_user WITH PASSWORD 'Ihr Passwort';
CREATE DATABASE bomnipotent_db OWNER bomnipotent_user;
GRANT ALL PRIVILEGES ON DATABASE bomnipotent_db TO bomnipotent_user;
\q

sudo systemctl restart postgresql;
exit

psql -U postgres

CREATE USER bomnipotent_user WITH PASSWORD 'Ihr Passwort';
CREATE DATABASE bomnipotent_db OWNER bomnipotent_user;
GRANT ALL PRIVILEGES ON DATABASE bomnipotent_db TO bomnipotent_user;
\q

docker run --name bomnipotent_db \
  -e POSTGRES_DB=bomnipotent_db \
  -e POSTGRES_USER=bomnipotent_user \
  -e POSTGRES_PASSWORD=<your-password> \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  -d postgres:latest

Empfohlene Dateistruktur

Die vorgeschlagene Dateistruktur im Lieblingsverzeichnis Ihres Servers sieht folgendermaßen aus:

├── bomnipotent_config
│   ├── .env
│   ├── config.toml
│   └── config.toml.default
└── bomnipotent_server

Diese Anleitung führt Sie durch die einzelnen Dateien und erklärt sie Schritt für Schritt.

.env

Der BOMnipotent-Server kommuniziert mit einer Datenbank. Derzeit wird nur PostgreSQL als Backend unterstützt. Die Datenbank ist durch ein Passwort geschützt. Es empfiehlt sich, das Passwort in einer separaten .env-Datei zu speichern, anstatt direkt im compose.yaml.

Der Name der Datei muss “.env” lauten, ansonsten erkennt BOMnipotent Server sie nicht.

Ihre .env-Datei sollte so aussehen:

BOMNIPOTENT_DB_PW=<Ihr-Datenbank-Passwort>
SMTP_SECRET=<Ihr-smtp-Authentifizierungs-Geheimnis>

Falls Sie ein Versionierungssystem zum Speichern Ihres Setups verwenden, vergessen Sie nicht, “.env” zu Ihrer .gitignore oder analogen Ignore-Datei hinzuzufügen!

config.toml

BOMnipotent Server benötigt eine Konfigurationsdatei, die in einem anderen Abschnitt ausführlicher erläutert wird.

Der Name der Datei ist beliebig.

Eine minimale Konfiguration sieht folgendermaßen aus:

# Die Datenbank-URL hat die Struktur [db_client]://[Benutzer]:[Passwort]@[Adresse]:[Port]/[db]
# Beachten Sie, dass ${BOMNIPOTENT_DB_PW} auf eine Umgebungsvariable verweist.
db_url = "postgres://bomnipotent_user:${BOMNIPOTENT_DB_PW}@localhost:5432/bomnipotent_db"
# Domain, hinter der der bomnipotent-Server gehostet wird
domain = "https://bomnipotent.<Ihre-Domain>.<Top-Level>"
# An den typischen Port für HTTPS binden
https_port = 443

[log]
# Server anweisen, in eine Datei statt in die Standardausgabe zu protokollieren
file = "/var/log/bomnipotent.log"

[tls]
# Pfad zu Ihrer vollständigen TLS-Zertifikatskette
certificate_chain_path = "/etc/ssl/certs/<Ihre-TLS-Zertifikatskette.crt>"
# Pfad zu Ihrem geheimen TLS-Schlüssel
secret_key_path = "/etc/ssl/private/<Ihr-geheimer-TLS-Schlüssel>"

[smtp]
# Der Nutzername für den Mail-Anbieter, üblicherweise Ihre Mail Adresse
user = "<you@yourdomain.com>"
# Der SMTP Endpunkt Ihres Mail-Anbieters
endpoint = "<your.smtp.host>"
# Das Geheimnis um sich gegenüber dem Mail-Anbieter zu authentifizierenn, üblicherweise Ihr Passwort
secret = "${SMTP_SECRET}"

# Herausgeberdaten gemäß CSAF-Standard (Link unten)
[provider_metadata.publisher]
name = "<Name Ihrer Organisation>"
# Namespace Ihrer Organisation in Form einer vollständigen URL
namespace = "https://<Ihre Domain>.<Top-Level>"
# Dies ist höchstwahrscheinlich die gewünschte Enumerationsvariante.
category = "Anbieter"
# Kontaktdaten sind optional und frei wählbar.
contact_details = "<Bei Sicherheitsanfragen kontaktieren Sie uns bitte unter...>"

Fügen Sie Ihre Daten in die Klammern ein.

Der Abschnitt zur TLS-Konfiguration enthält ausführlichere Informationen, um häufige Fehler zu vermeiden.

Falls Sie es bevorzugen, eine lokal laufende SMTP Relay Station zu nutzen, schauen Sie sich die notwendigen Anpassungen der compose Datei an.

Die Publisher-Daten werden verwendet, um den OASIS CSAF-Standard einzuhalten.

Der Abschnitt über Provider-Metadaten beschreibt die Bedeutung der Felder im Detail.

Es wird empfohlen, die Datei config.toml in einem dedizierten Verzeichnis (in diesem Beispiel “bomnipotent_config”) zu speichern. BOMnipotent Server überwacht das Verzeichnis auf Änderungen. Je weniger Dateien sich im Ordner befinden, desto weniger muss er überwachen. Der Server versucht, die Konfigurationsdatei und die .env-Datei neu zu laden, sobald sich eine davon ändert.

Viele Konfigurationseinstellungen unterstützen Hot Reloading, d. h. sie können ohne Serverneustart geändert werden.

Nachdem Sie Ihre config.toml eingerichtet haben, können Sie diese beispielsweise als config.toml.default kopieren, um Ihre ursprüngliche Konfiguration schnell wiederherstellen zu können. Dies ist jedoch völlig optional.

bomnipotent_server

Dies ist die Binärdatei, mit der BOMnipotent Server ausgeführt wird. Sie können jede Version für Ihre Serverplattform von www.bomnipotent.de herunterladen.

Grundsätzlich benötigt BOMnipotent Server lediglich den Pfad zu seiner Konfigurationsdatei. Wenn Sie die Binärdatei ausführen und den Pfad als erstes Argument angeben, haben Sie eine funktionierende Serverinstanz erstellt. Ihr Terminal ist nun jedoch dauerhaft blockiert, und der Dienst wird nach einem Systemneustart nicht neu gestartet. Der Rest dieses Abschnitts dient lediglich dazu, sicherzustellen, dass das Betriebssystem den Server ordentlich unterstützt.

Im Gegensatz BOMnipotent Client, der unter allen gängigen Betriebssystemen läuft, wird BOMnipotent Server derzeit nur unter Linux und Windows unterstützt. Wenn Sie ihn auf einem Server mit macOS hosten möchten, erstellen Sie bitte einen Issue .

[Unit]
Description=BOMnipotent Server
After=network.target

[Service]
ExecStart=/path/to/bomnipotent_server /path/to/bomnipotent_config/config.toml
WorkingDirectory=/path/to/bomnipotent_config
Restart=on-failure
User=<IhrBenutzer>

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reexec
sudo systemctl enable --now bomnipotent.service

Datenbank-URL

Die “db_url”-Konfiguration unterstützt kein Hot Reloading. Sie müssen den Server nach einer Änderung neu starten.

BOMnipotent Server ist Ihr Gateway zur Bereitstellung von Daten zur Lieferkettensicherheit und zur Verwaltung des Zugriffs darauf. Die Daten selbst werden in einer SQL-Datenbank gespeichert.

Derzeit wird nur PostgreSQL als Treiber unterstützt.

Diese Datenbank kann grundsätzlich in derselben Umgebung, in einem anderen Container oder auf einem Remote-Server ausgeführt werden. BOMnipotent muss beigebracht werden, wie es sie erreicht. Der Parameter zum Bereitstellen dieser Informationen in der Konfigurationsdatei ist “db_url”, und die Syntax ist die folgende:

db_url = "<Treiber>://<Benutzer>:<Passwort>@<Domäne>:<Port>/<Datenbank>"

BOMnipotent wird sauer auf Sie sein, wenn die von Ihnen angegebene Zeichenfolge nicht diesem Format entspricht.

Ein tatsächlicher Eintrag könnte beispielsweise lauten:

db_url = "postgres://bomnipotent_user:${BOMNIPOTENT_DB_PW}@bomnipotent_db:5432/bomnipotent_db"

Lassen Sie uns das aufschlüsseln:

• Der Treiber ist “postgres”, der einzige Treiber, welcher derzeit unterstützt wird.
• Der Benutzername lautet “bomnipotent_user”, da dies der Wert ist, der PostgreSQL während der Einrichtung bereitgestellt wurde.
• Das Passwort wird aus der externen Variable “BOMNIPOTENT_DB_PW” gelesen, die über die Umgebung oder eine .env-Datei bereitgestellt werden kann. Sie könnten es auch direkt in der Konfigurationsdatei speichern, aber das gilt als schlechte Praxis.
• Die Domäne lautet “bomnipotent_db”, das ist der Name des Docker-Containers, welcher die Datenbank ausführt. Für eine Datenbank in derselben Umgebung wäre dies stattdessen “localhost”, und für eine externe Datenbank wäre es eine andere Domäne oder IP-Adresse.
• Der Port ist 5432, der Standardport, auf den PostgreSQL lauscht. In diesem Fall befindet sich der Docker-Container im selben Docker-Netzwerk wie der BOMnipotent-Server Container. Ohne diese direkte Verbindung müssten Sie diesen internen Port im Docker-Setup einem beliebigen externen Port zuordnen und diesen externen Port in der Konfiguration angeben.
• Die Datenbank selbst wird auch “bomnipotent_db” genannt, da dies der Wert ist, der PostgreSQL während des Setups bereitgestellt wurde.

Wenn der BOMnipotent-Server die Datenbank nicht erreichen kann, werden Sie in den Logs darüber informiert.

Serverdomäne

Der BOMnipotent-Server ist nicht nur per API erreichbar, sondern zeigt auch einige statische XML- und HTML-Seiten an. Ein wichtiges Beispiel ist, dass er für Sie CSAF-Provider-Metadaten generieren kann. Da einige dieser Seiten aufeinander verweisen, muss der Server die vollständige Domäne kennen, hinter der er vom Internet aus erreichbar ist.

Der Parameter wird einfach “domain” genannt. Die Angabe eines Protokolls ist optional, “https” wird als Default angenommen.

Der entsprechende Teil in der Konfigurationsdatei kann beispielsweise so aussehen:

domain = "https://bomnipotent.wwh-soft.com"

domain = "bomnipotent.wwh-soft.com"

TLS-Konfiguration

Die TLS-Konfiguration unterstützt kein Hot Reloading. Sie müssen den Server nach der Änderung neu starten.

Was ist TLS?

Dieser Abschnitt soll Personen, die noch nie mit TLS zu tun hatten, ein allgemeines Verständnis des Prozesses vermitteln. Sie können gerne direkt zum Abschnitt über die Konfiguration springen.

Transport Layer Security (TLS), manchmal auch mit seinem alten Namen Secure Socket Layer (SSL) bezeichnet, ist für das “S” in “HTTPS” verantwortlich. Es ist eine sehr ausgereifte, intelligente und weit verbreitete Methode zur Ende-zu-Ende Verschlüsselung der Kommunikation über das Internet. Es kann aber auch zu viel Kopfzerbrechen führen.

Grob umrissen funktioniert TLS wie in den folgenden Absätzen beschrieben:

Ihr Server generiert ein Paar aus geheimem und öffentlichem Schlüssel. Jeder kann den öffentlichen Schlüssel verwenden, um entweder eine Nachricht zu verschlüsseln, die nur der geheime Schlüssel entschlüsseln kann, oder um eine Nachricht zu entschlüsseln, die mit dem geheimen Schlüssel verschlüsselt wurde.

Wenn ein Client Ihren Server kontaktiert und um Verschlüsselung bittet, antwortet dieser mit dem Senden eines TLS-Zertifikats. Es enthält mehrere wichtige Felder:

• Den öffentlichen Schlüssel Ihres Servers, mit dem der Client nun Nachrichten senden kann, die nur der Server lesen kann.
• Die Domäne(n), für die dieses Zertifikat gültig ist. Diese werden normalerweise im Feld “Subject Alternative Names” (SAN) gespeichert und sollen sicherstellen, dass der Client wirklich mit der Adresse kommuniziert, die er erreichen wollte.
• Eine digitale Signatur, die kryptografisch beweist, dass das Zertifikat unterwegs nicht verändert wurde.
• Vieles mehr. Sehen Sie sich einfach ein beliebiges Zertifikat in Ihrem Browser an.

Die digitale Signatur wird nicht mit dem geheimen Schlüssel des Servers erstellt, da der Client diesem Schlüssel noch nicht vertraut. Stattdessen sind auf Ihrem Computer einige (mehrere hundert) öffentliche Schlüssel gespeichert, die zu sogenannten “Root Certificate Authorities” oder “Stammzertifizierungsstellen” gehören. Ihre Aufgabe ist es, Serverzertifikate zu signieren, nachdem sie überprüft haben, dass der Inhaber des geheimen Schlüssels auch der Besitzer der Domänen ist, auf die sie Anspruch erheben.

Aus praktischen Gründen signieren die Stammzertifizierungsstellen normalerweise kein Serverzertifikat direkt, sondern ein Zwischenzertifikat, welches dann zum Signieren des endgültigen Zertifikats verwendet wird.

Insgesamt sieht die Vertrauenskette also folgendermaßen aus:

1. Der Client vertraut der Stammzertifizierungsstelle.
2. Die Stammzertifizierungsstelle vertraut der Zwischenzertifizierungsstelle.
3. Die Zwischenzertifizierungsstelle vertraut dem Server.

Daher entscheidet sich der Client, dem Server zu vertrauen und eine verschlüsselte Verbindung aufzubauen.

TLS-Konfiguration

Da BOMnipotent dem Secure-by-Default Prinzip folgt, fordert es von Ihnen mindestens eine Aussage zur TLS-Verschlüsselung. Der Abschnitt “tls” Ihrer Konfigurationsdatei akzeptiert die folgenden Felder:

[tls]
allow_http = false # Optional, ist standardmäßig false
certificate_chain_path = „your-chain.crt“
secret_key_path = „your-key.pem“

Die Angabe der TLS-Zertifikatpfade ist erforderlich, falls HTTP nicht erlaubt ist (da der Server sonst keine Verbindung anbieten könnte), und optional, falls HTTP ausdrücklich erlaubt ist, indem allow_http auf true gesetzt wird. Wenn Sie entweder den certificate_chain_path oder den secret_key_path festlegen, müssen Sie auch den jeweils anderen Wert festlegen. Darüber hinaus prüft der Server, ob Zertifikat und Schlüssel zusammenpassen.

allow_http

Wenn Sie dieses optionale Feld auf true setzen, lässt Ihr BOMnipotent-Server eine unverschlüsselte Verbindungen zu. Dies ist sinnvoll, falls Ihr Server hinter einem Reverse-Proxy läuft und nur über das lokale Netzwerk mit ihm kommuniziert. In diesem Setup ist der Server nicht direkt vom Internet aus erreichbar, sodass der Reverse-Proxy die Verschlüsselung für ihn übernehmen kann.

Der Default Port für HTTP ist 8080, er kann aber frei konfiguriert werden.

Bitte beachten Sie, dass der OASIS CSAF-Standard erfordert, dass der Zugriff auf Ihre CSAF-Dokumente verschlüsselt ist!

secret_key_path

Der Wert von “secret_key_path” muss auf eine Datei verweisen, die für den BOMnipotent-Server erreichbar ist. Ein gängiger Wert ist:

secret_key_path = "/etc/ssl/private/<Ihre-Domain>_private_key.key"

Wenn Ihr BOMnipotent-Server in einem Docker Container ausgeführt wird, möchten Sie vermutlich das Containerverzeichnis “/etc/ssl” an das gleichnamige Verzeichnis auf dem Host binden.

Die Datei muss ein ASCII-geschützter geheimer Schlüssel im PEM-Format sein. Glücklicherweise ist dies das Format, in dem TLS Zertifikate üblicherweise ausgestellt werden.

Der Inhalt der Datei könnte beispielsweise so aussehen:

-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIHru40FLuqgasPSWDuZhc5b2EhCGGcVC+j3DuAqiw0/m
-----END PRIVATE KEY-----

Dies ist der geheime Schlüssel aus einem Zertifikat, das für die BOMnipotent Integrationstests generiert wurde.

certificate_chain_path

Ebenso muss der “certificate_chain_path” auf eine Datei verweisen, die durch BOMnipotent Server gelesen werden kann. Ein typischer Speicherort ist:

certificate_chain_path = „/etc/ssl/certs/<Ihre-Domain>-fullchain.crt“

Die Kette muss alle Zertifikate in der Vertrauenskette zusammengefügt enthalten, beginnend mit dem Zertifikat für Ihren Server und endend mit der Stammzertifizierungsstelle.

Der Inhalt der vollständigen Zertifikatskette für den Integrationstest sieht folgendermaßen aus:

-----BEGIN CERTIFICATE-----
MIIB8jCCAaSgAwIBAgIBAjAFBgMrZXAwPTELMAkGA1UEBhMCREUxHDAaBgNVBAoT
E0JPTW5pcG90ZW50IFRlc3QgQ0ExEDAOBgNVBAMTB1Rlc3QgQ0EwHhcNMjUwMzA1
MTMxNzEwWhcNMjUwNDI0MTMxNzEwWjBFMQswCQYDVQQGEwJERTEgMB4GA1UEChMX
Qk9Nbmlwb3RlbnQgVGVzdCBTZXJ2ZXIxFDASBgNVBAMTC1Rlc3QgU2VydmVyMCow
BQYDK2VwAyEAMzw8ZVgiuP3bSwh+xcBXu62ORwakr/D+s0XQks1BTFOjgcAwgb0w
DAYDVR0TAQH/BAIwADBIBgNVHREEQTA/gglsb2NhbGhvc3SCCTEyNy4wLjAuMYIT
c3Vic2NyaXB0aW9uX3NlcnZlcoISYm9tbmlwb3RlbnRfc2VydmVyMBMGA1UdJQQM
MAoGCCsGAQUFBwMBMA4GA1UdDwEB/wQEAwIGwDAdBgNVHQ4EFgQUC/RAGubXMfx1
omYTXChtqneWDLcwHwYDVR0jBBgwFoAUStstIFLzDjBSHYSsSr9hSgRVZT4wBQYD
K2VwA0EAXN/6PpJQ0guaJq67kdKvPhgjWVdfxxeCAap8i24R39s7XxNz5x5lPyxA
DQG63NS/OED43+GfpkUguoKxfZLBBA==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIBazCCAR2gAwIBAgIBATAFBgMrZXAwPTELMAkGA1UEBhMCREUxHDAaBgNVBAoT
E0JPTW5pcG90ZW50IFRlc3QgQ0ExEDAOBgNVBAMTB1Rlc3QgQ0EwHhcNMjUwMzA1
MTMxNzEwWhcNMjUwNjEzMTMxNzEwWjA9MQswCQYDVQQGEwJERTEcMBoGA1UEChMT
Qk9Nbmlwb3RlbnQgVGVzdCBDQTEQMA4GA1UEAxMHVGVzdCBDQTAqMAUGAytlcAMh
AIoFFlU/ADa77huqAb5aBY9stDwzzDd/Tdocb9RZDBG2o0IwQDAPBgNVHRMBAf8E
BTADAQH/MA4GA1UdDwEB/wQEAwIBBjAdBgNVHQ4EFgQUStstIFLzDjBSHYSsSr9h
SgRVZT4wBQYDK2VwA0EARYL+v9oDGjaSW5MhjjpQUFXnAVMFayaKFfsfbbkmTkv4
+4SRWFb4F/UULlbbvlskSgt8jAaaTSk7tu/iX67YDw==
-----END CERTIFICATE-----

Das erste Zertifikat (“MIIB8j…”) authentifiziert den Server, das zweite (“MIIBaz…”) ist das der Stammzertifizierungsstelle.

Eine Zwischenzertifizierungsstelle gibt es hier nicht, da sie für die Tests nicht benötigt wird. In Ihrer Produktivumgebung mit echten Zertifikaten müssen Sie höchstwahrscheinlich ein Zwischenzertifikat in der Mitte einfügen.

SMTP-Einstellungen

Simple Mail Transfer Protocol (SMTP) ist das Protokoll zum Versenden von E-Mails. Im Kontext von BOMnipotent verwendet der Server es, um zu überprüfen, ob neu angefragte Benutzer Zugriff auf die von ihnen angegebene E-Mail-Adresse haben. Dazu muss der Server einen SMTP-Endpunkt erreichen.

SMTP konfigurieren

Der SMTP-Abschnitt der Konfigurationsdatei sieht folgendermaßen aus:

[smtp]
user = "you@yourdomain.com"
endpoint = "your.smtp.host"
secret = "${SMTP_SECRET}" # Optional
starttls = true # Optional, standardmäßig false

Eingaben

User / Benutzer

Der SMTP-Benutzer ist die E-Mail-Adresse, die Sie zur Authentifizierung bei Ihrem Mailserver verwenden.

Endpunkt

Der SMTP-Endpunkt teilt BOMnipotent mit, wohin die Daten gesendet werden sollen. Er kann direkt auf Ihren Mailserver oder auf ein SMTP-Relay verweisen.

Beginnt der Endpunkt mit dem Marker “smtp://”, versucht BOMnipotent Server, eine direkte Verbindung zu dieser URL herzustellen. Dies ist typischerweise bei der Verbindung mit einem lokal laufenden Relay erwünscht. Andernfalls wird eine Verbindung zu einem externen Relay hergestellt.

Geheimnis

Bei der direkten Kommunikation mit Ihrem Mailserver müssen Sie sich authentifizieren. Das Geheimnis ist entweder Ihr Passwort oder ein API-Schlüssel, falls Ihr Mail-Provider einen anbietet. Im obigen Beispiel wird das Geheimnis aus der Umgebungsvariable “SMTP_SECRET” gelesen, die zum Beispiel aus einer .env-Datei stammen kann.

Ein lokal laufendes SMTP-Relay benötigt nicht unbedingt ein Passwort zum Empfangen von E-Mails, daher ist dieses Feld optional.

STARTTLS

STARTTLS ist eine Möglichkeit, E-Mails zu verschlüsseln, die andere ist SMTPS. Seit 2018 rät die Internet Engineering Task Force von der Verwendung von STARTTLS ab . Sollte Ihr Mailserver jedoch kein SMTPS unterstützen, ist STARTTLS besser als gar keine Verschlüsselung. Daher wird es von BOMnipotent Server weiterhin unterstützt.

Benutzerverifizierung überspringen

Wenn Sie (noch) keinen Zugriff auf einen SMTP-Server haben, können Sie die SMTP-Konfiguration umgehen, indem Sie die folgende Zeilen in Ihrer config.toml hinzufügen:

[user]
skip_verification = true

Der BOMnipotent Server sendet dann keine Verifizierungs-E-Mail an neu angemeldete Benutzer. Stattdessen wird jedes Mal eine Warnmeldung ausgegeben, wenn die E-Mail nicht versendet wird, da diese Konfiguration die Sicherheit Ihres Servers beeinträchtigt.

CSAF-Provider Metadaten

Der OASIS-Standard erfordert, dass Anbieter von CSAF-Dokumenten eine “provider-metadata.json” anbieten, die einem bestimmten Schema folgen muss.

BOMnipotent ist bestrebt, die Erfüllung dieser Anforderung so einfach wie möglich zu machen. Sie können entweder die Datei aus einigen wenigen Eingaben generieren oder eine Datei bereitstellen , welche BOMnipotent laden kann.

Daten generieren

Durch die Bereitstellung einiger benutzerspezifischer Eingaben können Sie BOMnipotent dazu bringen, eine gültige provider-metadata.json Datei zu generieren. Dies ist viel einfacher als die Datei manuell zu erstellen, bietet aber etwas weniger Kontrolle.

Der relevante Abschnitt in Ihrer Konfigurationsdatei sieht folgendermaßen aus:

[provider_metadata.publisher]
name = "<Name Ihrer Organisation>"
namespace = "https://<Ihre Domain>.<Top-Level>"
category = "vendor"
issuing_authority = "<Zusätzliche Informationen>" # Optional
contact_details = "<Bitte kontaktieren Sie uns unter...>" # Optional

Dateneingaben des Herausgebers

Name

In diesem Feld müssen Sie den Namen Ihres Unternehmens, Ihrer Organisation oder Ihren Namen als Einzelperson angeben.

Namespace

Während das Feld “name” in erster Linie für Menschen gedacht ist, wird der “namespace” von Maschinen verwendet, um Ihre Organisation in verschiedenen Sicherheitsdokumenten zu identifizieren. Er muss im URI-Format vorliegen, einschließlich Protokoll, Domäne und Top-Level-Domäne. Da er sich auf Ihre gesamte Organisation bezieht, sollte er keine Subdomäne enthalten.

Das ist, was das Feld “provider_metadata.publisher.namespace” von der Konfiguration “domain” unterscheidet: Letztere verweist auf Ihre Instanz von BOMnipotent Server, während Erstere viel allgemeiner ist.

Kategorie

Die Herausgeberkategorie ist eine maschinenlesbare Klassifizierung Ihrer Organsiation. Gemäß dem CSAF-Standard sind in den Herausgeberkategorien die Werte “coordinator”, “discoverer”, “other”, “translator”, “user” oder “vendor” zulässig. Als Benutzer von BOMnipotent Server sind Sie höchstwahrscheinlich ein “vendor”, also ein Entwickler oder Weiterverkäufer von Produkten oder Dienstleistungen.

Issuing Authority / Ausstellerinformation

Das optionale Feld “issuing_authority” kann verwendet werden, um Ihre Verbindung zu den gehosteten Dokumenten zu verdeutlichen. Sind Sie der Entwickler? Sind Sie ein Händler? Die Eingabe ist in freier Form.

Kontaktdaten

In dem optionalen Feld “contact_details” können Sie Kontaktdaten für allgemeine oder Sicherheitsanfragen angeben. Die Eingabe ist in freier Form.

Generiertes Dokument

Sobald Sie die Daten bereitgestellt und den Server gestartet haben, wird das generierte Dokument unter “Ihre-Domain/.well-known/csaf/provider-metadata.json” gehostet. Sie können hier ein Live-Beispiel und hier ein statisches Beispiel sehen:

{
    "canonical_url": "https://bomnipotent.wwh-soft.com/.well-known/csaf/provider-metadata.json",
    "distributions": [
        {
            "rolie": {
                "feeds": [
                    {
                        "summary": "WHITE advisories",
                        "tlp_label": "WHITE",
                        "url": "https://bomnipotent.wwh-soft.com/.well-known/csaf/white/csaf-feed-tlp-white.json"
                    },
                    {
                        "summary": "GREEN advisories",
                        "tlp_label": "GREEN",
                        "url": "https://bomnipotent.wwh-soft.com/.well-known/csaf/green/csaf-feed-tlp-green.json"
                    },
                    {
                        "summary": "AMBER advisories",
                        "tlp_label": "AMBER",
                        "url": "https://bomnipotent.wwh-soft.com/.well-known/csaf/amber/csaf-feed-tlp-amber.json"
                    },
                    {
                        "summary": "RED advisories",
                        "tlp_label": "RED",
                        "url": "https://bomnipotent.wwh-soft.com/.well-known/csaf/red/csaf-feed-tlp-red.json"
                    },
                    {
                        "summary": "UNLABELED advisories",
                        "tlp_label": "UNLABELED",
                        "url": "https://bomnipotent.wwh-soft.com/.well-known/csaf/unlabeled/csaf-feed-tlp-unlabeled.json"
                    }
                ]
            }
        }
    ],
    "last_updated": "2025-03-06T16:13:24.632235974Z",
    "list_on_CSAF_aggregators": true,
    "metadata_version": "2.0",
    "mirror_on_CSAF_aggregators": true,
    "publisher": {
        "category": "vendor",
        "contact_details": "For security inquiries, please contact info@wwh-soft.com",
        "name": "Weichwerke Heidrich Software",
        "namespace": "https://wwh-soft.com"
    },
    "role": "csaf_provider"
}

Diese Datei enthält einen ROLIE-Feed für alle Ihre CSAF-Dokumente, was wahrscheinlich der Hauptgrund ist, warum Sie dieses Dokument nicht von Hand erstellen möchten.

Das Feld “last_updated” wird aus dem letzten Modifizierungszeitstempel Ihrer Konfigurationsdatei generiert.

BOMnipotent geht davon aus, dass Sie Ihre CSAF-Dokumente auf öffentlich verfügbaren Repositorien aufgelistet und gespiegelt haben möchten. Dies betrifft nur die mit TLP:WHITE / TLP:CLEAR gekennzeichneten Dokumente! Die Aggregatoren haben keinen Zugriff auf anderweitig klassifizierte Dokumente.

BOMnipotent hilft Ihnen, alle Anforderungen zu erfüllen, um ein CSAF-Anbieter gemäß dem OASIS-Standard zu sein.

Dateipfad angeben

Wenn Sie aus irgendeinem Grund die vollständige Kontrolle über das Dokument mit den Anbietermetadaten haben möchten, können Sie in der Konfigurationsdatei einen Dateipfad angeben:

[provider_metadata]
path = "<Dateipfad>"

BOMnipotent ließt dann die Datei, überprüft, ob sie dem Anbietermetadaten-JSON-Schema entspricht, und hostet sie.

Sie müssen entweder einen Pfad zu einer Datei oder Herausgeberdaten angeben. Wenn Sie keines oder beides angeben, wird die Konfiguration nicht geladen.

Logging

Um den Verlauf der Interaktionen mit BOMnipotent Server zu verfolgen, kann jedes Ereignis potentiell dazu führen, dass ein Logeintrag geschrieben wird. Diese werden per Default in die Standardausgabe gedruckt. Wenn der Server in einem Docker Container mit dem Namen “bomnipotent_server” ausgeführt wird, können Sie die letzten 3 Zeilen der Protokolle mit folgendem Befehl anzeigen:

docker logs bomnipotent_server -n 3

2025-03-08 09:16:10 +00:00 [INFO] Database is ready.
2025-03-08 09:16:15 +00:00 [DEBUG] Header X-Auth-Email was not found in request
2025-03-08 09:16:15 +00:00 [DEBUG] Received healthcheck request from 127.0.0.1

Die Protokolle haben das Format „Datum, Uhrzeit, Zeitzone, Log-Level, Nachricht“.

Der relevante Abschnitt Ihrer Konfigurationsdatei zur Manipulation der Protokollierung sieht folgendermaßen aus:

[log] # Dieser Abschnitt ist optional
level = "debug" # Der Defaultwert ist "info"
file = "/var/log/bomnipotent.log" # Der Default ist, nach stdout zu loggen

Die Protokolle enthalten keine vertraulichen Informationen. Beispielsweise verschleiert die Benachrichtigung über die Datenbankverbindung Benutzername und Passwort:

2025-03-08 09:16:10 +00:00 [INFO] Creating connection pool for database: postgres://[user]:[password]@database:5432/bomnipotent_db

Schweregrad

BOMnipotent Server unterstützt fünf Schweregrade für Logs:

• error
• warn
• info
• debug
• trace

Jede Schweregradebene enthält die Log Einträge der vorherigen. Der Standardschweregrad ist “info”, es werden also Logeintröge mit den Schweregraden “error”, “warn” und “info” ausgegeben.

Error

Ein Fehler zeigt an, dass ein Vorgang abgebrochen werden muss. Damit er funktioniert, muss entweder die Benutzereingabe oder die Konfiguration geändert werden, und er muss erneut ausgelöst werden.

Gängige Beispiele sind:

• Eine angeforderte Ressource wurde nicht gefunden.
• Der Benutzer verfügt nicht über ausreichende Berechtigungen.
• Die Konfigurationsdatei kann nicht geladen werden.

Warn

Eine Warnung wird angezeigt, wenn eine Eingabe oder Konfiguration nicht optimal ist. Der Vorgang wird trotzdem abgeschlossen, aber Sie oder der Benutzer werden aufgefordert, entweder die Eingabe oder die Konfiguration zu ändern.

Gängige Beispiele sind:

• Ein temporärer Administrator ist konfiguriert.
• Ein Dokument ohne TLP-Klassifizierung wird angefordert, aber es wurde kein Standard-TLP konfiguriert.
• Sie haben BOMnipotent seit über einem Jahr nicht aktualisiert.

Info

Dies ist der Standardschweregrad für Protokolle.

Protokolle mit dem Level “info” weisen auf regelmäßige Ereignisse hin, die wichtig, aber selten genug sind, um die Ausgabe nicht zu überlasten.

Gängige Beispiele sind:

• Eine Anforderung wurde an einen Endpunkt gestellt (einige Endpunkte wie /health loggen mit einem niedrigeren Schweregrad als “info”).
• Ein Benutzer wurde authentifiziert.
• Die Konfigurationsdatei wurde erfolgreich neu geladen.

Debug

Konfigurieren Sie das Log Level des “debug”, um Fehler in der Konfiguration oder der Benutzereingabe zu finden. Die Logs helfen dabei, Schritt für Schritt zu verstehen, was das Programm tut, und wo etwas schiefgehen kann.

Gängige Beispiele sind:

• An den Client gesendete Antworten.
• Interaktionen mit der Datenbank.
• Der Inhalt einer erfolgreich neu geladenen Konfigurationsdatei.

Trace

Als niedrigstmöglicher Schweregrad geben Trace-Protokolle sehr viel aus. Im Gegensatz zum Debug-Level soll das Trace-Level dabei helfen, Fehler in BOMnipotent selbst zu finden. Es ist daher unwahrscheinlich, dass Sie dieses Level jemals konfigurieren müssen, da es sich hauptsächlich an den Entwickler richtet.

Gängige Beispiele sind:

• Der Text einer Anfrage (nach 1000 Zeichen abgeschnitten).
• Die auf eine Datenbankanfrage angewendeten Filter.
• Der Server hat ein Dateiereignis empfangen, weil jemand mit der Konfigurationsdatei (oder einer angrenzenden Datei) interagiert hat.

Logdatei

Falls Sie einen gültigen Pfad für “file” im Abschnitt “log” Ihrer Config Datei angeben, dann druckt BOMnipotent Server die Ausgabe dorthin anstatt in die Standardausgabe. Das ist primär nützlich, falls Sie den Server außerhalb von jeglichem Container laufen lassen.

[log]
file = "/var/log/bomnipotent.log"

Falls die Datei bereits existiert, wird BOMnipotent Server sie bei einem Neustart gnadenlos überschreiben, falls es die entsprechenden Berechtigungen hat.

Temporäre Adminrechte

Nur ein Administrator kann einem Benutzer Administratorrechte erteilen. Um den ersten Administrator zu erstellen, müssen Sie diese Rechte daher über einen anderen, temporären Pfad aktivieren. Dies geschieht mit dem Konfigurationsparameter “tmp_admin”, der die E-Mail-Adresse eines Benutzers als Eingabe verwendet:

[user]
tmp_admin = "<email>"

Das gesamte Verfahren ist in der Anleitung zum Aufsetzen des Servers beschrieben.

Aus Sicherheitsgründen sind die Regeln für die temporäre Administratorrolle recht streng und erlauben nur eine bestimmte Reihenfolge der Vorgänge:

1. Fordern Sie einen neuen Benutzer an. Der Parameter “tmp_admin” darf an dieser Stelle noch nicht in der Konfigurationsdatei stehen, da die Anforderung sonst vom Server abgelehnt wird. Eine Anforderung für einen neuen Benutzer mit derselben E-Mail-Adresse wird ebenfalls abgelehnt.
2. Markieren Sie diesen Benutzer in der Konfiguration als temporären Administrator. Wenn der Benutzer nicht existiert, kann die Konfiguration nicht geladen werden.
3. Machen Sie den Benutzer zu einem richtigen Administrator, indem Sie ihn genehmigen und die Administratorrolle hinzufügen.
4. Entfernen Sie den Parameter “tmp_admin” aus der Serverkonfiguration. Die Serverprotokolle geben Warnmeldungen aus, solange er noch aktiv ist.

Wenn die Regeln weniger streng wären und Sie einen temporären Administrator festlegen könnten, bevor der Benutzer in der Datenbank registriert wird, könnte ein Angreifer möglicherweise einen neuen Benutzer mit der richtigen E-Mail-Adresse anfordern und hätte dann Administratorrechte auf Ihrem System.

TLP Konfiguration

CSAF-Dokumente können und sollten mit dem Traffic Light Protocol (TLP) klassifiziert werden. Es klärt, ob und mit wem Sie Dokumente teilen können, auf die Sie Zugriff haben. Der etwas ältere TLP v1.0-Standard kennt vier verschiedene Klassifizierungen:

• TLP:RED: Dieses Dokument darf nicht an andere weitergegeben werden.
• TLP:AMBER: Dieses Dokument kann nach dem Need-to-know-Prinzip innerhalb der Organisation und an deren Kunden verbreitet werden.
• TLP:GREEN: Dieses Dokument kann innerhalb der Community des Empfängers verbreitet werden.
• TLP:WHITE: Es gibt keine Einschränkung hinsichtlich der Weitergabe.

Der aktuellere TLP v2.0-Standard ersetzt TLP:WHITE durch TLP:CLEAR und fügt die neue Klassifizierung TLP:AMBER+STRICT hinzu, die nur die Weitergabe an die Organisation des Empfängers auf Need-to-know-Basis erlaubt, aber nicht darüber hinaus.

Von BOMnipotent Server gehostete Dokumente, die als TLP:WHITE oder TLP:CLEAR klassifiziert sind, sind für jeden sichtbar, egal ob Administrator, völlig unauthentifizierter Benutzer oder Crawler-Bot!

Der Abschnitt “tlp” Ihrer Konfigurationsdatei kann die folgenden Felder enthalten:

[tlp]
allow_tlp2 = true # Der Default ist false
default_tlp = "amber+strict" # Der Default ist "red"

TLP v2.0 zulassen

Der aktuelle OASIS CSAF-Standard erfordert, dass Dokumente mit einem TLP v1.0 Label klassifiziert werden. Viele Unternehmen würden jedoch lieber die TLP:AMBER+STRICT Klassifizierung aus dem TLP v2.0 Standard für ihre Dokumente verwenden. Darüber hinaus wird der TLP v2.0-Standard verbindlich , sobald der CSAF-Standard 2.1 veröffentlicht wird.

Um vollständig mit dem CSAF-Standard kompatibel zu sein, lässt BOMnipotent standardmäßig keine TLP v2.0 Beschriftungen zu. Sie können jedoch das Feld “allow_tlp2” im Abschnitt “tlp” Ihrer Konfigurationsdatei auf “true” setzen:

[tlp]
allow_tlp2 = true

Wenn Sie dies tun, werden sowohl TLP v1.0 als auch TLP v2.0 Label akzeptiert.

Wenn Sie dies hingegen nicht tun und BOMnipotent auf TLP v2.0 Beschriftungen stößt, konvertiert es TLP:CLEAR stillschweigend in TLP:WHITE. Da TLP:AMBER+STRICT in TLP v1.0 kein direktes Äquivalent hat, wählt BOMnipotent den konservativen Ansatz, konvertiert es in TLP:RED und protokolliert eine Warnung.

Default-TLP

Die Klassifizierung eines CSAF-Dokuments mit einem TLP-Label ist optional, und eine TLP-Klassifizierung ist nicht einmal Teil des CycloneDX-Standards für BOM-Dokumente. BOMnipotent muss zumindest wissen, ob das Dokument mit TLP:CLEAR / TLP:WHITE gekennzeichnet und somit öffentlich verfügbar ist, oder ob der Zugriff darauf eingeschränkt ist.

Es empfiehlt sich, eine TLP-Klassifizierung zu definieren, auf die BOMnipotent für ein nicht gekennzeichnetes Dokument zurückgreifen kann. Sie können dies in Ihrer Konfigurationsdatei über den folgenden Eintrag tun:

[tlp]
default_tlp = "amber"

Die Deserialisierung gibt Ihnen etwas Spielraum: Sie berücksichtigt die Groß-/Kleinschreibung nicht und das Präfix „TLP:“ ist optional. Die Werte „amber“, „AMBER“, „tlp:amber“ und „TLP:AMBER“ werden alle als TLP:AMBER erkannt.

Wenn Sie kein Standard-TLP-Label angeben und BOMnipotent auf ein unbeschriftetes Dokument stößt, wird standardmäßig TLP:RED verwendet und eine Warnung ausgegeben.

Das Default-TLP Label wird zum Zeitpunkt des Zugriffs ausgewertet, nicht zum Zeitpunkt des Schreibens. Unklassifizierte Dokumente bleiben in der Datenbank unklassifiziert. Wenn Sie das Default-TLP Label zu irgendeinem Zeitpunkt ändern, ändern Sie es somit für alle unklassifizierten Dokumente der Vergangenheit und Zukunft.

Benutzergültigkeitszeitraum

Wenn eine Anfrage für ein neues Benutzerkonto gestellt wird, wird ein öffentlicher Schlüssel in der Datenbank hinterlegt.

Dieser Schlüssel hat ein Ablaufdatum, nach dem er nicht mehr akzeptiert wird. Dieses können Sie sich anzeigen lassen:

./bomnipotent_client user list

╭───────────────────┬──────────┬───────────────────────────┬───────────────────────────╮
│ User Email        │ Status   │ Expires                   │ Last Updated              │
├───────────────────┼──────────┼───────────────────────────┼───────────────────────────┤
│ info@wwh-soft.com │ APPROVED │ 2026-03-03 11:30:15.62432 │ 2025-03-02 11:47:38.51048 │
│                   │          │ 5 UTC                     │ 5 UTC                     │
╰───────────────────┴──────────┴───────────────────────────┴───────────────────────────╯

Standardmäßig ist der Schlüssel nach der Anforderung etwas mehr als ein Jahr lang gültig. Diese Zeit kann mit dem Parameter “expiration_period” konfiguriert werden, welche sich unter “[user]” befindet. Als Werte akzeptiert er einen Zeitraum im menschenlesbaren Format „ “, wobei „“ die englische Zeitangabe “year”, “month”, “week”, “day” oder deren Pluralvarianten sein kann.

[user]
expiration_period = "366 days"

[user]
expiration_period = "5 years"

[user]
expiration_period = "1 month"

[user]
expiration_period = "3 weeks"

[user]
expiration_period = "5 days"

Falls Sie Ihre Benutzer wirklich hassen, können Sie auch “hours”, “minutes”, seconds", “ms”, “us” oder “ns” als Einheit verwenden. BOMnipotent stellt nicht in Frage, wie realistisch Ihre Erwartungen sind.

Das Ändern dieser Konfiguration hat keine Auswirkungen auf die Ablaufdaten bestehender Benutzer! Es beeinflusst nur, wie viel Zeit neu angeforderten Benutzern eingeräumt wird.

Löschzeitraum

Um Ihre Datenbank sauber und Ihr System DSGVO-konform zu halten, werden Nutzer, die für mehr als 30 Tage abgelaufen sind, ganz aus der Datenbank gelöscht.

Dieser Zeitraum lässt sich über den “removal_period” Parameter anpassen, welcher ebenfalls unter “[user]” zu finden ist:

[user]
removal_period = "5 days"

DoS-Prävention

Denial of Service (DoS)-Angriffe haben das Ziel, ein Programm oder einen Server unresponsiv zu machen. Sie sind bekanntermaßen schwer abzuwenden, da sie häufig darauf basieren, den Dienst mit ansonsten legitimen Anfragen zu überfluten.

BOMnipotent verfügt über mehrere DoS-Präventionsmechanismen (von der Ablehnung von Code, der den Server zum Absturz bringen könnten, bis zur Begrenzung der Länge von Protokollausgaben). Manche Techniken können vom Benutzer angepasst werden.

Nutzerspezifische DoS Prävention

Wenn die Anzahl der Anfragen von einer einzelnen Quelle innerhalb eines Zeitraums einen Grenzwert überschreitet, wird diese Quelle für eine Stunde auf eine Greylist gesetzt, welche die Anfragen dann automatisch ablehnt.

Standardmäßig geschieht dies, wenn die Anzahl der Anfragen innerhalb einer Minute 100 überschreitet, aber Sie können dieses Verhalten in Ihrer Konfigurationsdatei ändern:

[dos_prevention]
limit = 50 # Standard ist 100
period = "30 Sekunden" # Standard ist "1 Minute"

Diese neue Konfiguration würde den Server schneller auf einen möglichen DoS-Angriff reagieren lassen, birgt aber auch ein erhöhtes Risiko, Anfragen fälschlicherweise als Angriff zu werten.

Globale Request User DoS Prävention

Die HTTP-Anfrage zum Anlegen eines neuen Benutzers ist typischerweise keinem bestehenden Benutzer zugeordnet. Die benutzerspezifische DoS-Prävention verwendet zwar weiterhin die IP-Adresse der Anfrage, schützt aber nicht vor IP-Spoofing oder verteilten (D)DoS-Angriffen. Weiterhin bietet es Angreifern die Möglichkeit, die Datenbank durch Hinzufügen von Schlüsseln zu verändern.

Zum Glück ist die Anfrage nach einem neuen Benutzer etwas, was eher selten erwartet wird. Aus diesem Grund gibt es ein globales Limit für Benutzeranfragen. Die Standardwerte sind deutlich strenger, können aber ebenfalls angepasst werden:

[user.new_user_dos_prevention]
limit = 10 # Standard ist 3
period = "20 seconds" # Standard ist "10 seconds"

Da die Anfrage nicht zuverlässig mit einer Quelle assoziiert werden kann betreibt diese Prävention kein Greylisting.

Port Bindung

Während IP-Adressen zur Identifizierung Ihres Servers im Internet verwendet werden, dienen Ports zur Identifizierung der darauf laufenden Dienste. Beim Start bietet BOMnipotent ein oder zwei Dienste an: einen HTTP-Dienst für unverschlüsselte Kommunikation, einen HTTPS-Dienst für verschlüsselte Kommunikation, oder beides.

Wichtig: Verwenden Sie unverschlüsselte Kommunikation nur innerhalb eines Rechners! Reine HTTP-Kommunikation über das Internet gehört der Vergangenheit an, und das zu Recht.

Standardmäßig bietet BOMnipotent seine Dienste über die Ports 8080 und 8443 an. Dies geschieht, um Kollisionen zu vermeiden und weil es primär für die Ausführung in einem Container vorgesehen ist. Wenn Sie BOMnipotent ohne die Containerabstraktion ausführen möchten, können Sie die Dienste stattdessen über die Ports anbieten, die typischerweise mit HTTP und HTTPS verknüpft sind:

http_port = 80 # Standard ist 8080
https_port = 443 # Standard ist 8443

Jede andere vorzeichenlose 16-Bit-Zahl ist ebenfalls möglich.

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.