Docker Compose

Das empfohlene und einfachste Setup für BOMnipotent Server verwendet Docker Compose .

Vorgeschlagene Dateistruktur

Die vorgeschlagene Dateistruktur im Favoritenverzeichnis 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>

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

Um die Sicherheit ins rechte Licht zu rücken: Die Compose-Datei macht den PostgreSQL-Container nicht direkt vom Internet aus erreichbar. Das Passwort wird daher nur für Aufrufe innerhalb des Containernetzwerks verwendet.

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://<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>"

# 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.

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 abgeleitet.
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-alpine3.21
    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}
    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
      - 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-alpine3.21
    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}
    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!

Ist er nicht? Bitte kontaktieren Sie mich !

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

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 unverschlüsselte Verbindungen über Port 8080 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.

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.

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.

Ausstellenrinformation

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 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 = "info" # Dies ist der Standardschweregrad

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.

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:

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 “user_expiration_period” konfiguriert werden. 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.

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), aber eine bestimmte Technik kann vom Benutzer angepasst werden.

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.