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.