Docker Compose

The recommended and easiest setup for BOMnipotent Server uses docker compose .

Suggested File Structure

The suggested file structure in the favourite directory of your server looks like this:

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

This tutorial will walk through the files and explain them one by one.

.env

BOMnipotent server communicates with a database. Currently, only PostgreSQL is supported as a backend. The database is protected by a password. It is best practice to store the password inside a separate .env file instead of directly in the compose.yaml.

The name of the file must be “.env”, otherwise docker will not recognise it.

Your .env file should look like this:

BOMNIPOTENT_DB_PW=<your-database-password>

If you are using a versioning system to store your setup, do not forget to add “.env” to your .gitignore or analogous ignore file!

To put the security into perspective: The compose file will not directly expose the PostgreSQL container to the internet. The password is therefore only used for calls within the container network.

config.toml

BOMnipotent Server needs a configuration file, which is explained in more detail in another section .

The name of the file is arbitrary in principle, but the ready-to-deploy BOMnipotent Server docker container is set up to look for “config.toml”.

A minimal configuration looks like this:

# The db_url has the structure [db_client]://[user]:[password]@[container]:[port]/[db]
# Note that ${BOMNIPOTENT_DB_PW} references an environment variable.
db_url = "postgres://bomnipotent_user:${BOMNIPOTENT_DB_PW}@bomnipotent_db:5432/bomnipotent_db"
# Domain behind which bomnipotent server will be hosted
domain = "https://<your-domain>.<top-level>"

[tls]
# The path to your full TLS certificate chain
certificate_chain_path = "/etc/ssl/certs/<your-TLS-certificate-chain.crt>"
# The path to your secret TLS key
secret_key_path = "/etc/ssl/private/<your-secret-TLS-key>"

# Publisher data according to the CSAF Standard linked below
[provider_metadata.publisher]
name = "<Provide the name of your organsiation>"
# Namespace of your organisation, in form of a complete URL
namespace = "https://<your-domain>.<top-level>"
# This is most likely the enum variant you want
category = "vendor"
# Contact details are optional and in free form
contact_details = "<For security inquiries, please contact us at...>"

Fill in the braces with your data.

The section about TLS configuration contains more detailed information to avoid common pitfalls.

The publisher data is used to comply with the OASIS CSAF standard .

The section about provider-metadata goes into more details what the fields actually mean.

It is recommended to store your config.toml file inside a dedicated directory, “bomnipotent_config” in this example. The docker compose file will grant read access to this folder. This setup has two advantages:

• In the unlikely case of a security breach of the BOMnipotent Server container, an attacker would only have access to you config directory, and nothing else on your server.
• BOMnipotent Server will watch the directory for changes and will try to reload the configuration file if it has changed. This does not work when exposing only a single file to the docker container.

Many configuration values support hot reloading, meaning they can be modified without restarting the server.

After having set up your config.toml, you may want to copy it as for example config.toml.default, to be able to quickly restore your initial configuration. This is entirely optional, though.

compose.yaml

The compose file is where you specify the container setup. Once it is running smoothly, it does not need to be modified very often, but initially understanding it can take some time if you are new to docker.

The file needs to be called “compose.yaml”, docker can be a bit pecky otherwise.

A completely ready to deploy compose file looks like this:

# Giving the setup a name is optional, it will be derived by docker otherwise.
name: bomnipotent_server_containers

# The docker containers need to communicate, and they need a network for that.
networks:
  # This network needs a reference
  bomnipotent_network:
    # Since the containers are on the same docker host, "bridge" is a reasonable driver choice.
    driver: bridge
    # Giving the network the same name as the reference is ok.
    name: bomnipotent_network

volumes:
  # Define the volume for persistent storage of the database
  bomnipotent_data:
    driver: local
  # The server itself also needs persistence if you do not want to activate the subscription after every reboot
  bomnipotent_subscription:
    driver: local

services:
  bomnipotent_db:
    # Name of the database container
    container_name: bomnipotent_db
    deploy:
      resources:
        limits:
          # Limit the CPU usage to 0.5 cores
          cpus: "0.5"
          # Limit the memory usage to 512MB
          memory: "512M"
    environment:
      # Set the database name
      POSTGRES_DB: bomnipotent_db
      # Set the database user
      POSTGRES_USER: bomnipotent_user
      # Set the database password from the .env file variable
      POSTGRES_PASSWORD: ${BOMNIPOTENT_DB_PW}
    healthcheck:
      # Check if the database is ready
      test: ["CMD-SHELL", "pg_isready -U bomnipotent_user -d bomnipotent_db"]
      # Interval between health checks
      interval: 60s
      # Timeout for each health check
      timeout: 10s
      # Number of retries before considering the container unhealthy
      retries: 5
      # Start period before the first health check
      start_period: 10s
    # Use the specified PostgreSQL image
    # You may ddjust the container tag at will
    image: postgres:17-alpine3.21
    logging:
      # Use the local logging driver
      driver: local
      options:
        # Limit the log size to 10MB
        max-size: "10m"
        # Keep a maximum of 3 log files
        max-file: "3"
    networks:
      # Connect to the specified network
      - bomnipotent_network
    # Restart the container if it has stopped for some reason other than a user command
    restart: always
    volumes:
      # Mount the volume for persistent data storage
      - bomnipotent_data:/var/lib/postgresql/data

  bomnipotent_server:
    # Name of the server container
    container_name: bomnipotent_server
    depends_on:
      # Ensure the database service is healthy before starting the server
      bomnipotent_db:
        condition: service_healthy
    deploy:
      resources:
        limits:
          # Limit the CPU usage to 0.5 cores
          cpus: "0.5"
          # Limit the memory usage to 512MB
          memory: "512M"
    environment:
      # Pass the database password on to the server.
      BOMNIPOTENT_DB_PW: ${BOMNIPOTENT_DB_PW}
    healthcheck:
      # Check if the server is healthy
      # Your TLS certificate is most likely not valid for "localhost"
      # Hence the --insecure flag
      test: ["CMD-SHELL", "curl --fail --insecure https://localhost:8443/health || exit 1"]
      # Interval between health checks
      interval: 60s
      # Timeout for each health check
      timeout: 10s
      # Number of retries before considering the container unhealthy
      retries: 5
      # Start period before the first health check
      start_period: 10s
    # This is the official docker image running a BOMnipotent Server instance.
    image: wwhsoft/bomnipotent_server:latest
    logging:
      # Use the local logging driver
      driver: local
      options:
        # Limit the log size to 10MB
        max-size: "10m"
        # Keep a maximum of 3 log files
        max-file: "3"
    networks:
      # Connect to the specified network
      - bomnipotent_network
    ports:
      # Map port 443 on the host to port 8443 on the container
      # This allows to connect to it via encrypted communication from the internet
      - target: 8443
        published: 443
    # Restart the container if it has stopped for some reason other than a user command
    restart: always
    volumes:
      # Bind mount the config folder on the host
      - type: bind
        source: ./bomnipotent_config
        target: /etc/bomnipotent_server/configs/
        read_only: true
      # Bind mount the SSL directory
      - type: bind
        source: /etc/ssl
        target: /etc/ssl
        read_only: true
      # The subscription can be stored inside the container
      - 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

Store this as “compose.yaml”. Then, call:

docker compose --detach

docker compose -d

Your server is now up and running!

It is not? Please contact me !

Run “docker ps” to check if it is healthy.

Database URL

The “db_url” configuration does not support hot reloading. You will need to restart the server after modifying it.

BOMnipotent Server is your gateway for providing supply chain security data and managing access to it. The data itself is stored in a SQL database.

At the moment, only PostgreSQL is supported as a driver.

This database can in principle run in the same environment, in a different container, or on a remote server. BOMnipotent needs to be taught how to reach it. The parameter for providing this information in the config file is “db_url”, and the syntax is the following:

db_url = "<driver>://<user>:<password>@<domain>:<port>/<database>"

BOMnipotent will be cross with you if the string you provide does not adhere to this format.

An actual entry could for example be

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

Let’s break this down:

• The driver is “postgres”, which is the only driver currently supported.
• The username is “bomnipotent_user”, because this is the value that was provided to PostgreSQL during the setup.
• The password is read from the external variable “BOMNIPOTENT_DB_PW”, which may be provided via environment or .env file. You could also store it in the config file directly, but this is considered bad practice.
• The domain is “bomnipotent_db”, which is the name of the docker container running the database. For a database in the same environment this would instead be “localhost”, and for an external database it would be some other domain or IP address.
• The port is 5432, which is the default port that the PostgreSQL listens to. In this case the docker container is in the same docker network as the BOMnipotent Server container. Without this direct connection, you would need to map this internal port to an arbitrary external port in the docker setup, and provide this external port in the config.
• The database itself is also called “bomnipotent_db”, because this is the value that was provided to PostgreSQL during the setup.

If BOMnipotent Server cannot reach the database, it will let you know in the logs.

Server Domain

BOMnipotent Server is not only reachable per API, but also displays some static XML and HTML pages. One important example is that it may generate CSAF Provider Metadata for you. As some of these pages reference one another, the server needs to know the full domain behind which it is reachable from the internet.

The parameter is simply called “domain”. Providing a protocol is optional, “https” is assumed as a default.

The relevant part in the config file may for example look like this:

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

domain = "bomnipotent.wwh-soft.com"

TLS Config

The TLS configuration does not support hot reloading. You will need to restart the server after modifying it.

What is TLS?

This section serves to give people who never had to deal with TLS a broad understanding of the process. Feel free to skip ahead to the section about configuration .

Transport Layer Security (TLS), sometimes also called by its legacy name Secure Socket Layer (SSL), is what puts the “S” in “HTTPS”. It is a very sophisticated, smart and widely used method for end-to-end encrypting of communication over the internet, but it can also lead to a lot of head scratching.

In very broad terms, TLS works as outlined in the following paragraphs:

Your server generates a pair of secret and public key. Anyone can use the public key to either encrypt a message that only the secret key can decrypt, or to decrypt a message that was encrypted with the secret key.

When a client reaches out to your sever asking for encryption, the latter responds by sending a TLS certificate. It contains several important field:

• Your severs public key, which the client can now use to send messages only the server can read.
• The domain(s) this certificate is valid for. These are usually stored in the field “Subject Alternative Names” (SAN), and are meant to ensure that the client is really talking to the address it wanted to reach.
• A digital signature, cryptographically proving that the certificate was not altered along the way.
• Many more. Just have a look at any certificate in your browser.

The digital signature is not created with the server’s secret key, because the client does not trust that key yet. Instead, there are some (several hundred) public keys stored on your machine that belong to so called “Root Certificate Authorities”. The job of these is to sign server certificates after they have verified that the bearer of the secret key is also the owner of the domains they claim.

For practical reasons the root CAs usually do not directly sign a server certificate, but rather an intermediate certificate, which is then used to sign the final certificate.

All in all, the chain of trust thus looks like this:

1. The Client trusts the root CA.
2. The root CA trusts the intermediate CA.
3. The intermediate CA trusts the server.

Thus, the client decides to trust the server and establich an encrypted connection.

TLS Configuration

Because BOMnipotent is secure-by-default, it requires you to make at least one statement about TLS encryption. The “tls” section of your configuration file accepts the following fields:

[tls]
allow_http = false # Optional, is false by default
certificate_chain_path = "your-chain.crt"
secret_key_path = "your-key.pem"

Providing the TLS certificate paths is required if HTTP is not allowed (because the server could not offer any connection otherwise), and it is optional if HTTP is explicityl allowed by setting allow_http to true. If you set either the certificate_chain_path or the secret_key_path , you will also need to set the other. Furthermore, the server checks if there is a mismatch between the two.

allow_http

If you set this optional field to true, your BOMnipotent Server will allow unencrypted connections vie port 8080. This makes sense if your server is running behind a reverse proxy, and is communicating to it only over the local network. In this setup, the server is not directly reachable from the internet, so the reverse proxy can handle encryption for it.

Please note that the OASIS CSAF Standard requires that the access to your CSAF documents is encrypted!

secret_key_path

The value of “secret_key_path” needs to point to a file that is reachable for BOMnipotent server. One common value is:

secret_key_path = "/etc/ssl/private/<yourdomain>_private_key.key"

If your BOMnipotent Server is running inside a docker container, you may want to bind mount the container directory “/etc/ssl” to the directory with the same name on the host.

The file needs to be an ASCII-armoured secret key in PEM-Format . Luckily, this is the format you typically receive when obtaining a TLS certificate.

The contents of the file could for example look like this:

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

This is the secret key from a certificate generated for the BOMnipotent integration tests.

certificate_chain_path

Likewise, the “certificate_chain_path” needs to point to a file reachable by BOMnipotent Server. A typical location is:

certificate_chain_path = "/etc/ssl/certs/<yourdomain>-fullchain.crt"

The chain needs to contain all certificates in the chain of trust concatenated together, beginning with the one for your sever and ending with the root certificate authority.

The contents of the full certificate chain for the integration test looks like this:

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

The first certificate (“MIIB8j…”) authenticates the server, the second one (“MIIBaz…”) is that of the root CA.

There is no intermediate certificate authority here because it is not required for the tests. In your productive environemnt with real certificates you will most likely need to add an intermediate certificate in the middle.

CSAF Provider Metadata

The OASIS Standard requires that providers of CSAF documents offer a “provider-metadata.json”, which needs to follow a specific schema .

BOMnipotent strives to make it as easy as possible to fulfil this requirement. You can either generate the file from a few inputs, or provide a file for BOMnipotent to load.

Generating Data

By providing some user-specific inputs, you can make BOMnipotent generate a valid provider-metadata.json file. This is much easier than creating the file by hand, but offers somewhat less control.

The relevant section in your config file looks like this:

[provider_metadata.publisher]
name = "<name of your organsiation>"
namespace = "https://<your-domain>.<top-level>"
category = "vendor"
issuing_authority = "<Additional info>" # Optional
contact_details = "<Please contact us at...>" # Optional

Publisher Data Inputs

Name

This field requires you to provide the name of your company, organisation, or you as an individual.

Namespace

While the “name” field is primarily aimed at humans, the “namespace” is used by machines to identify your organisation across various security documents. It needs to be in URI format, including protocol, domain and top-level domain. Because it refers to your whole organisation, it should not contain a subdomain.

This is what sets the “provider_metadata.publisher.namespace” field apart from the “domain” configuration: The latter points to your instance of BOMnipotent Server, while the former is much more general.

Category

The publisher category is a machine readable classification of who you are. According to the CSAF Standard , the publisher categories allows the values “coordinator”, “discoverer”, “other”, “translator”, “user” or “vendor”. As a user of BOMnipotent Server, you are most likely a “vendor”, meaning a developer or retailer of products or a service.

Issuing Authority

This optional field can be used to clarify your connection to the hosted documents. Are you the developer and maintainer? Are you a retailer? The input is in free form.

Contact Details

This optional field allows you to offer contact details for general or security inquiries. The input is a string in free form.

Generated Document

Once you have provided the data and started the server, the generated document will host it under “your-domain/.well-known/csaf/provider-metadata.json”. You can see a live example here and a static example here:

{
    "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"
}

This file contains a ROLIE feed for all your CSAF documents, which is probably the main reason why you do not want to create this document by hand.

The “last_updated” field is generated from the last modification timestamp of your config file.

BOMnipotent assumes that you want your CSAF documents listed and mirrored on publicly available repositories. This only concerns the documents labeled TLP:WHITE / TLP:CLEAR! The aggregators do not have access to any documents classified otherwisely.

BOMnipotent helps you fulfil all requirements to be a CSAF Provider , according to the OASIS standard.

Providing Filepath

If for some reason you want to have full control of the provider-metadata document, you can provide a filepath in the config file:

[provider_metadata]
path = "<filepath>"

BOMnipotent will then read the file, check that it follows the provider-metadata json schema , and host it.

You have to provide either a path to a file, or publisher data. If you provide neither or both, the config will not be loaded.

Logging

To keep track of the history of interactions with BOMnipotent Server, every event potentially results in a log being written. These logs are printed to the standard output. If the server is running inside a docker container named “bomnipotent_server”, you can see the last 3 lines of logs by calling

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

The logs have the format “Date, Time, Timezone, Log Level, Message”.

The relevant section of your config file to manipulate logging looks like this:

[log] # This section is optional
level = "info" # This is the default severity level

The logs do not contain confidential information. For example, the notification about the database connection obfuscates username and password:

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

Severity Level

BOMnipotent Server supports five log levels:

• error
• warn
• info
• debug
• trace

Each severity level includes the log messages from the previous ones. The default severity level is “info”, meaning it prints log messages with severities “error”, “warn” and “info”.

Error

An error indicates that an operation has to be aborted. Either the user input or the configuration has to change for it to work, and it needs to be triggered again.

Common examples include:

• A requested resource is not found.
• The user does not have sufficient permissions.
• The configuration file cannot be loaded.

Warn

A warning is displayed when some input or configuration is suboptimal. The operation is still completed, but you or the user are urged to change either input or configuration.

Common examples include:

• A temporary admin is configured.
• A document without TLP classification is requested, but no default-tlp has been configured.
• You have not updated BOMnipotent for over a year.

Info

This is the default severity level for logs.

Logs with level info indicate regular events that are important, but rare enough to not overwhelm the output.

Common examples include:

• A request was made to an endpoint (although some endpoints like /health log with a lower severity than info).
• A user was authenticated.
• The config file has successfully been reloaded.

Debug

Configure debug log severity level to find errors in the configuration or user input. These logs help to understand, step by step, what the program does, and where something may go wrong.

Common exmples include:

• Responses sent to the client.
• Interactions with the database.
• The contents of a succesfully reloaded config file.

Trace

As the lowest possible severity level, trace logs contain a lot of output. In contrast to the debug level, the trace level is meant to assist in finding errors in BOMnipotent itself. It is thus unlikely that you will ever need to configure this level, because it is mainly targeted at the developer. Common examples include:

• The body of a request (truncated after 1000 characters).
• The filters applied to a database request.
• The server received a file event because someone interacted with the config file (or any adjacent file).

Temporary Admin

Only an admin can give admin permissions to a user. In order to create the first admin, you therefore need to enable these permissions via another, temporary path. This is done with the config parameter “tmp_admin”, which takes the email of a user as an input:

tmp_admin = "<email>"

The whole procedure is described in the setup instructions .

For security reasons, the rules surrounding temporary adminship are rather strict, and allow only one specific order of operations:

1. Request a new user. The “tmp_admin” parameter may not be set at this point, or the request is denied by the server. A request for a new user with the same email is also denied.
2. Mark that user as a temporary admin in the configuration. If the user does not exists, the configuration will fail to load.
3. Make the user a proper admin by approving them and adding the admin role.
4. Remove the “tmp_admin” parameter from the server configuration. The server logs will print warning messages while it is still active.

If the rules were less strict and you could designate a temporary admin before the user is registered in the database, an attacker could potentially request a new user with the correct email address and would then have admin permissions on your system.

TLP Config

CSAF documents can and in fact should be classified using the Traffic Light Protocol (TLP) . It clarifies if and with whom you can share documents that you have access to. The somewhat older TLP v1.0 standard knows four different classifications:

• TLP:RED: This document may not be disclosed to anyone else.
• TLP:AMBER: This document can be spread on a need-to-know basis within their organization and its clients.
• TLP:GREEN: This document can spread this within the recipient’s community.
• TLP:WHITE: There is no limit on disclosure.

The more current TLP v2.0 standard replaces TLP:WHITE with TLP:CLEAR, and adds the new classification TLP:AMBER+STRICT, which only allows sharing on a need-to-know basis with the recipient’s organisation, but not beyond.

Documents hosted by BOMnipotent Server that are classified as TLP:WHITE or TLP:CLEAR are visible to everyone, be they admin, completely unauthenticated user or crawler bot!

The “tlp” section of your configuration file may contain the following fields:

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

Allowing TLP v2.0

The current OASIS CSAF Standard requires documents to be classified with TLP v1.0 labels. However, many companies would prefer to use the TLP:AMBER+STRICT classification from the TLP v2.0 standard for their documents. Furthermore, the TLP v2.0 standard will become mandatory once the CSAF standard 2.1 is released.

To be fully compliant with the CSAF standard, BOMnipotent does not allow TLP v2.0 labels by default. You can, however, set the field “allow_tlp2” to true in the “tlp” section of your config file:

[tlp]
allow_tlp2 = true

If you do, both TLP v1.0 and TLP v2.0 labels will be accepted.

If you do not, and BOMnipotent encounters TLP v2.0 labels, it will silently convert TLP:CLEAR to TLP:WHITE. Because TLP:AMBER+STRICT has no direct equivalent in TLP v1.0, BOMnipotent will take the conservative approach, convert it to TLP:RED, and log a warning.

Default TLP

Classifying a CSAF document with a TLP label is optional, and a TLP classification is not even part of the CycloneDX standard for BOM documents. BOMnipotent needs to at least know if the document is labelled TLP:CLEAR / TLP:WHITE and thus publicly available, or if access to it is restricted.

It is good practice to define a TLP classification that BOMnipotent can fall back to for an unlabelled document. You can do that in your config file via:

[tlp]
default_tlp = "amber"

The deserialisation gives you some leeway: It does not consider the casing, and the “TLP:” prefix is optional. The values “amber”, “AMBER”, “tlp:amber” and “TLP:AMBER” are all recognised as TLP:AMBER.

If you do not provide a default TLP label, and BOMnipotent encounters an unlabelled document, it will default to TLP:RED and log a warning.

The default TLP label is evaluated at the time of access, not at the time of writing. Unlabelled documents remain unlabelled in the database. If at any point you change the default TLP label, you thus change it for all unlabelled documents of past and future .

User Expiration

When a request for a new user account is made, it deposits a public key in the database.

This key has an expiration data, after which it is not accepted anymore. This can be seen by calling:

./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                     │
╰───────────────────┴──────────┴───────────────────────────┴───────────────────────────╯

By default, the key is valid for a little over a year after it was requested. This time can be configured with the “user_expiration_period” parameter. As values it accepts a time period in the human readable format “ ”, where “” can be any of “year”, “month”, “week”, “day”, or their plural variants.

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"

If you really hate your users you could also use “hours”, “minutes”, seconds", “ms”, “us” or “ns” as units. BOMnipotent does not question how realistic your expectations are.

Changing this configuration does not affect the expiration dates of existing users! It will only influence how much time is given to newly requested users.

DOS Prevention

Denial of Service (DOS) attacks target programs or servers with the goal of making them unresponsive. They are notoriously hard to mitigate, because they are often based on flooding the service with otherwise legitimate requests.

BOMnipotent has several DOS prevention mechanisms in place (from disallowing any code that might crash the server to limiting the length of log outputs), but one particular technique can be tweaked by the user.

If the number of requests from a single source exceeds a limit within a time period, that source is put on a greylist for one hour, which automatically denies requests.

By default, this happens if the number of requests exceeds 100 within one minute, but you can modify this behaviour in your config file:

[dos_prevention]
limit = 50 # Default is 100
period = "30 seconds" # Default is "1 minute"

This new config would make the server react faster to a possible DOS attack, but has a higher risk to falsely classify request as an attack.