Required Configs

This section explains all parameters which you need to set in order for BOMnipotent Server to start. This required data is specific to you and your setup, which is why it is impossible to assume a meaningful default here.

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:

The Client trusts the root CA.
The root CA trusts the intermediate CA.
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:

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.

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.