Basic Usage

This section covers the basics of using the BOMnipotent Client. It is relevant for both consumers and producers of supply chain security documents.

Subsections of Basic Usage

Installing the Client

To manually download BOMnipotent Client, go to https://www.bomnipotent.de/downloads/ , select your platform and version, and click on the download button.

To automate this process further, you can access the download link directly:

​
Invoke-WebRequest -Uri https://www.bomnipotent.de/downloads/raw/latest/windows/bomnipotent_client.exe -OutFile bomnipotent_client.exe
curl -O https://www.bomnipotent.de/downloads/raw/latest/macos/bomnipotent_client
chmod +x bomnipotent_client
wget https://www.bomnipotent.de/downloads/raw/latest/debian-glibc/bomnipotent_client;
chmod +x bomnipotent_client
wget https://www.bomnipotent.de/downloads/raw/latest/linux-musl/bomnipotent_client;
chmod +x bomnipotent_client

Replace “latest” with a specific version tag, e.g. “v1.0.0”, to download that version instead of the latest.

To access BOMnipotent Client from anywhere in your system, move it into a folder that is included in your PATH environment variable. This step is optional, though.

Account Creation

Most interactions with BOMnipotent require some permission. The sole exception is accessing data classified as TLP:WHITE / TLP:CLEAR.

Permissions are linked to user accounts. For more information on how permissions are granted, see the section about Access Management .

Creating a new Account

To create a new user account, run

​
bomnipotent_client --domain=<server> user request <your-email>
bomnipotent_client -d <server> user request <your-email>

If you call this for the first time, it will create a new key pair using the ED25519 Algorithm . A key pair consists of a public and a secret key. Both are stored in your local userfolder.

​
[INFO] Generating new key pair
[INFO] Storing secret key to "/home/simon/.config/bomnipotent/secret_key.pem" and public key to "/home/simon/.config/bomnipotent/public_key.pem"
[INFO] User request submitted. It now needs to be confirmed by a user manager.

The secret key is more commonly called “private key”, but the author believes that “secret” is a more apt description and reduces the chance to confuse it with the public key.

The public key can, in principle, be shared with anyone. The “user request” call sends it to the BOMnipotent server. The secret key however should be treated like a password!

Subsequent calls to BOMnipotent Client will reuse an existing key pair.

Now that your request is made, you need to wait for a user manager of the server to approve it. After that you can start making authenticated requests .

If you are said user manager and are looking for how approve users, consult the section about User Management .

Using stored Keys

If you have a key pair stored in the default user location (which depends on your platform), BOMnipotent Client will automatically read and use it.

If you would instead like to reuse an existing stored at a different location, you can add the path as a positional argument:

​
bomnipotent_client --domain=<server> user request <your-email> <path/to/key>
bomnipotent_client -d <server> user request <your-email> <path/to/key>

For this to work the key needs to have been generated using the ED25519 Algorithm , and it needs to be stored in PEM format. If you insist on managing keys yourself, or would like to see an example, then the easiest way to generate such a pair is to call openssl genpkey -algorithm ED25519 -out secret_key.pem to generate a secret key, and then openssl pkey -in secret_key.pem -pubout -out public_key.pem to generate the corresponding public key.

If you accidently specify the path to your secret key, BOMnipotent Client will throw an error before sending it to the server.

Authenticating

Authentication requires that you have requested a user account , and that it has been approved by a user manager.

Once your account (meaning your email and public key) is approved, you can provide your email to Bomnipotent Client to make a request that can be authenticated by the server:

​
bomnipotent_client --domain=<server> --email=<your-email> <command>
bomnipotent_client -d <server> -e <your-email> <command>

BOMnipotent Client then automatically reads your secret key and uses it for authentication.

Your secret key is used to cryptographically sign the HTTP method, your email, a timestamp and the request body. This simultaneously protects your request against others impersonating you, malicious modifications and replay attacks. The secret key achieves all that without ever having to leave your local computer, the beauty of which is, sadly, beyond the scope of this documentation.

If you are not storing your keys in the default user location, you have to tell BOMnipotent Client the path to it via a command line option:

​
bomnipotent_client --domain=<server> --email=<your-email> --secret-key=<path/to/key> <command>
bomnipotent_client -d <server> -e <your-email> -s <path/to/key> <command>

To avoid providing three extra arguments to every single request, you can instead store this data in a User Session

User Session

Login

The BOMnipotent Client offers several global optional arguments. To avoid having to provide these time and time again, you can use the login command to store them in a user session:

​
bomnipotent_client --domain=<server> --email=<your-email> --output=<mode> --secret-key=<path/to/key> --trusted-root=<path/to/cert> login
bomnipotent_client -d <server> -e <your-email> -o <mode> -s <path/to/key> -t <path/to/cert> login

This will create a file in the local user folder which stores the provided parameters.

​
[INFO] Storing session data in /home/simon/.config/bomnipotent/session.toml

Whenever you call the BOMnipotent Client from now on, it will use these parameters automatically:

bomnipotent_client bom list # Will automatically reach out to the provided domain and use your authentication data.

Overwriting Parameters

If you are logged in and provide any of the global optional parameters to a BOMnipotent Client call, it will use these instead:

​
bomnipotent_client --domain=<other-server> bom list # Will contact the other server
bomnipotent_client -d <other-server> bom list # Will contact the other server

To permanently change the data stored in the session, simply login again with the new parameters.

This can also be used to remove parameters, simply by not providing them:

​
bomnipotent_client --domain=<other-server> --email=<your-email> --output=<mode> login # Will set secret-key and trusted-root to none.
bomnipotent_client -d <other-server> -e <your-email> -o <mode> login # Will set secret-key and trusted-root to none.

Status

To print the current parameters of your session, call:

bomnipotent_client session status

The output is in TOML format (which is also how it is stored on your filesystem):

​
domain = "https://localhost:62443"
email = "admin@wwh-soft.com"
secret_key_path = "/home/simon/git/bomnipotent/test_cryptofiles/admin"
trusted_root_path = "/home/simon/git/bomnipotent/test_cryptofiles/ca.crt"

If you prefer JSON, merely append the “–json” option:

​
./bomnipotent_client session status --json
./bomnipotent_client session status -j

​
{
  "domain": "https://localhost:62443",
  "email": "admin@wwh-soft.com",
  "secret_key_path": "/home/simon/git/bomnipotent/test_cryptofiles/admin",
  "trusted_root_path": "/home/simon/git/bomnipotent/test_cryptofiles/ca.crt"
}

If you are not logged in, you get an informational trace and an empty TOML/JSON output:

​
[INFO] No session data is currently stored
[INFO] No session data is currently stored
{}

If you would like to use this command to programatically check if session data exists, you can for example use the “raw” output mode to avoid the info trace, and check if the return value is empty:

​
#!/bin/bash

output=$(./bomnipotent_client --output raw session status)
if [ -n "$output" ]; then
    echo "Found session data:"
    echo "$output"
else
    echo "Session not logged in."
fi
$output = ./bomnipotent_client --output raw session status
if ($output) {
    Write-Output "Found session data:"
    Write-Output $output
} else {
    Write-Output "Session not logged in."
}

Logout

To remove all parameters, call logout:

bomnipotent_client logout

This will remove the session file.

Log Level

BOMnipotent Client offers several severity levels of logs:

  • error
  • warn
  • info (default)
  • debug
  • trace

They can be selected via:

​
bomnipotent_client --log-level=<LEVEL> <COMMAND>
bomnipotent_client -l <LEVEL> <COMMAND>

This defines the minimum severity level for a message to be logged: Choosing log level debug makes BOMnipotent print all messages of severity error, warn, info and debug, but not trace.

By default, BOMnipotent Client logs messages to stdout, regardless of severity level. You can instruct it to log to a file instead.

Info, Warn and Error

The default log-level is info. It prints some information, but does not overwhelm the user.

bomnipotent_client health
​
[INFO] Service is healthy
bomnipotent_client bom list
​
[INFO]
╭─────────────┬─────────┬─────────────────────────┬─────────┬────────────╮
│ Product     │ Version │ Timestamp               │ TLP     │ Components │
├─────────────┼─────────┼─────────────────────────┼─────────┼────────────┤
│ BOMnipotent │ 1.0.0   │ 2025-02-01 03:31:50 UTC │ Default │ 363        │
╰─────────────┴─────────┴─────────────────────────┴─────────┴────────────╯

Or, in case of an error:

​
[ERROR] Received response:
404 Not Found
BOM Volcano_1.0.0 not found in database

Debug

The debug output mode prints some additional information which may be of interest when looking for the cause of an error in the input or setup:

​
bomnipotent_client --log-level=debug health
bomnipotent_client -l debug health

​
[DEBUG] Looking for secret key
[DEBUG] The provided key is a path: /home/simon/git/bomnipotent/test_cryptofiles/admin
[DEBUG] Reading secret key from provided path "/home/simon/git/bomnipotent/test_cryptofiles/admin"
[DEBUG] Adding trusted root certificate
[DEBUG] Signing request
[DEBUG] Assembled GET request to https://localhost:62443/health
[DEBUG] starting new connection: https://localhost:62443/
[INFO] Service is healthy

Trace

In output mode trace, BOMnipotent additionally prints the module where the log message originated. This is mainly interesting for finding the cause of an error in the program itself.

​
bomnipotent_client --log-level=trace health
bomnipotent_client -l trace health

​
[bomnipotent_client] [TRACE] Running command Health with args Arguments {
    domain: Some(
        "https://localhost:62443",
    ),
    email: Some(
        "admin@wwh-soft.com",
    ),
    log_level: Some(
        Trace,
    ),
    log_file: None,
    output_mode: None,
    secret_key: Some(
        "/home/simon/git/bomnipotent/test_cryptofiles/admin",
    ),
    trusted_root: Some(
        "/home/simon/git/bomnipotent/test_cryptofiles/ca.crt",
    ),
    command: Health,
}
[bomnipotent_client::keys] [DEBUG] Looking for secret key
[bomnipotent_client::keys] [DEBUG] The provided key is a path: /home/simon/git/bomnipotent/test_cryptofiles/admin
[bomnipotent_client::keys] [DEBUG] Reading secret key from provided path "/home/simon/git/bomnipotent/test_cryptofiles/admin"
[bomnipotent_client::request] [DEBUG] Adding trusted root certificate
[reqwest::blocking::wait] [TRACE] (ThreadId(1)) park without timeout
[reqwest::blocking::client] [TRACE] (ThreadId(14)) start runtime::block_on
[bomnipotent_client::request] [DEBUG] Signing request
[bomnipotent_client::request] [DEBUG] Assembled GET request to https://localhost:62443/health
[reqwest::blocking::wait] [TRACE] wait at most 30s
[reqwest::blocking::wait] [TRACE] (ThreadId(1)) park timeout 29.999994032s
[reqwest::connect] [DEBUG] starting new connection: https://localhost:62443/
[reqwest::blocking::wait] [TRACE] wait at most 30s
[reqwest::blocking::client] [TRACE] closing runtime thread (ThreadId(14))
[reqwest::blocking::client] [TRACE] signaled close for runtime thread (ThreadId(14))
[reqwest::blocking::client] [TRACE] (ThreadId(14)) Receiver is shutdown
[reqwest::blocking::client] [TRACE] (ThreadId(14)) end runtime::block_on
[reqwest::blocking::client] [TRACE] (ThreadId(14)) finished
[reqwest::blocking::client] [TRACE] closed runtime thread (ThreadId(14))
[bomnipotent_client::output] [INFO] Service is healthy

Log File

To store the log output of a call to BOMnipotent Client in a file instead of printing it to stdout, call

​
bomnipotent_client --log-file=<PATH> <COMMAND>
bomnipotent_client -f <PATH> <COMMAND>

The output is the same, except that the stdout output is coloured according to its severity level, while the file output is not.

If BOMnipotent Client is called repeatedly with the same log-file, it will overwrite the existing contents, if the existing file looks like a log-file.

A file looks like a log-file to BOMnipotent if it is either empty or contains at least one of the strings “[ERROR]”, “[WARN]”, “[INFO]”, “[DEBUG]” or “[TRACE]”.

If an existing file does not look like a log-file, BOMnipotent gets cautious and aborts:

​
Logfile "/tmp/loggy.log" already exists and does not look like a logfile. Aborting before overwriting any data you do not want overwritten.

Because the commands “bom get” / “csaf get” as well as the “fetch” command are meant for machine-processing, they print their output to stdout even if a log-file is configured. This separation of outputs makes it possible to simultaneously process the data and store potential error messages.

Output Mode

Withouth any specifications of the output-mode, BOMnipotent Client prints its log messages either to stdout, or to a configured log-file . This is great if it used by humans, but not so useful for automation. This is why BOMnipotent Client offers the two additional output-modes “code” and “raw” . They modify which output is printed where.

Output Streams

In output-modes “code” or “raw”, only the HTTP code or the response body are printed to stdout. If you configure a log-file , any logs up to the specified log-level will be stored there.

If on the other hand you do not specify a log-file, BOMnipotent still wants you to know if something goes wrong. This is why, in this case, logs of severity “error” or “warn” are printed to stderr.

Modes

Code

The code output prints only the HTTP status code of the response to stdout.

​
bomnipotent_client --output-mode=code health
bomnipotent_client -o code health

​
200

This can come in handy if you want to use BOMnipotent Client in a script:

#!/bin/bash
set -e # Return on error
# ...other code...
./bomnipotent_client \
    --output-mode=code \
    --domain=$domain \
    --log-level=debug \
    --log-file="/tmp/loggy.log" \
    session login
code=$(./bomnipotent_client health)
if (( code != 200 )); then
    echo "Server at $domain is not healthy!"
    cat /tmp/loggy.log
    exit 1;
fi

Note that there is no newline or carriage return character at the end of the output.

Attention: In code mode, BOMnipotent Client always exits with a terminal exit code of 0 (signaling success) if it can obtain any HTTP code. This way, the program is easier to use inside scripts that return on errors.

Raw

For calls to BOMnipotent Client that access some structured data, the raw output prints the response body, which is typically data in JSON format.

​
bomnipotent_client --output-mode=raw bom list
bomnipotent_client -o raw bom list
​
[{"name":"BOMnipotent","version":"1.0.0","timestamp":"2025-01-03T05:38:03Z","tlp":null,"components":350}]

The output can then easily be parsed and processed by your program logic.

Note that there is no newline or carriage return character at the end of the output.