BOMs

Bills of Materials stand at the forefront of both BOMnipotents functionality and name. A BOM is a list of all components that make up a product. In the context of cybersecurity, the most prominent variant is the Software Bill of Materials (SBOM), but BOMs allow for more general considerations as well.

For BOM interactions beyond reading, you need the BOM_MANAGEMENT permission. The section about Access Management describes how it is granted.

Uploading

To upload a BOM, call:

bomnipotent_client bom upload <PATH/TO/BOM>

BOMnipotent expects its BOMs in the structured CycloneDX JSON format.

Consult the Syft tutorial to learn how to generate a BOM for your product.

The BOMnipotent Client will read the file at the provided path and upload its content. It can then be viewed by the consumers with appropriate permissions.

BOMs for Consumers describes how to list and download the BOMs on the server.

To add a BOM to the database, the BOMnipotent Client has to have some additional information: a name, a version, and optionally a TLP label. The identifiers name and version can either be inferred (recommended), or overwritten, as described below.

Name and Version

bomnipotent_client bom upload <PATH/TO/BOM> --name-overwrite=<NEW-NAME> --version-overwrite=<NEW-VERSION>

bomnipotent_client bom upload <PATH/TO/BOM> -n <NEW-NAME> -v <NEW-VERSION>

TLP Classification

For consumers, BOMnipotent manages access to data using the Traffic Light Protocol (TLP) . The CycloneDX Format on the other hand does not currently support document classification.

To tell BOMnipotent how to classify a document, you have two options:

1. Set a default TLP Label in the server config. This will then be used for all BOMs without further specifications.
2. Provide a tlp classification via command line argument:
   ​

   long kurz

   bomnipotent_client bom upload <PATH/TO/BOM> --tlp=<LABEL>

   bomnipotent_client bom upload <PATH/TO/BOM> -t <LABEL>

If you do neither, BOMnipotent will treat any unclassified documents as if they were labelled TLP:RED, and will log a warning every time it has to do that.

Modifying

In the simplest case, modifying an existing BOM works very much like uploading a new one.

bomnipotent_client bom modify <PATH/TO/BOM>

This will infer the name and version from the document, and overwrite the existing content on the server. If the data does not exist on the server, it will return a 404 Not Found error.

Modifying TLP Label

If a TLP label had previously been assigned to the BOM, a modification of the contents will not automatically alter it.

If you want to specify a new TLP label, you can do so via argument:

bomnipotent_client bom modify <PATH/TO/BOM> --tlp=<LABEL>

bomnipotent_client bom modify <PATH/TO/BOM> -t <LABEL>

If the contents of the BOM have not changed and you just want to modify the TLP label, you do not need to upload the document again. Instead of providing a path to a file, you can specify name and version of the BOM you want to reclassify:

bomnipotent_client bom modify --name=<NAME> --version=<VERSION> --tlp=<LABEL>

bomnipotent_client bom modify -n <name> -v <version> -t <label>

If you specify “none”, “default” or “unlabelled” as the TLP label, any existing classification will be removed, and the server falls back to the default TLP Label of the server config:

bomnipotent_client bom modify <PATH/TO/BOM> --tlp=none
bomnipotent_client bom modify <PATH/TO/BOM> --tlp=default # Does the same
bomnipotent_client bom modify <PATH/TO/BOM> --tlp=unlabelled # Does the same

bomnipotent_client bom modify <PATH/TO/BOM> -t none
bomnipotent_client bom modify <PATH/TO/BOM> -t default # Does the same
bomnipotent_client bom modify <PATH/TO/BOM> -t unlabelled # Does the same

Modifying Name or Version

If the document you are uploading has a different name or version than the data it shall modify, you need to provide that information to the BOMnipotent Client using command line arguments:

bomnipotent_client bom modify <PATH/TO/BOM> --name=<OLD-NAME> --version=<OLD-VERSION>

bomnipotent_client bom modify <PATH/TO/BOM> -n <OLD-NAME> -v <OLD-VERSION>

BOMnipotent will infer the new data from the document you provide and change the database entries accordingly.

Overwriting Name or Version (not recommended)

As with uploading, it is possible to overwrite the name and/or version stored in the local document:

bomnipotent_client bom modify <PATH/TO/BOM> --name-overwrite=<NEW-NAME> --version-overwrite=<NEW-VERSION>

Important: As with uploading, this modifies the JSON data before uploading to the server! The same caveats apply.

If the data on the server has a different name and/or version than specified in the document, you can combine the specification with an overwrite of the data:

bomnipotent_client bom modify <PATH/TO/BOM> --name=<OLD-NAME> --version=<OLD-VERSION> --name-overwrite=<NEW-NAME> --version-overwrite=<NEW-VERSION>

bomnipotent_client bom modify <PATH/TO/BOM> -n <OLD-NAME> -v <OLD-VERSION> --name-overwrite=<NEW-NAME> --version-overwrite=<NEW-VERSION>

Changing name and/or version without providing the complete document is not supported.

Deleting

Deleting a BOM is very straightforward:

bomnipotent_client bom delete <NAME> <VERSION>

If the BOM does not exist, the server will return 404 Not Found. If it does exists, it is removed from the database.

Vulnerabilities

An activity at the core of supply chain security is to compare the contents of a BOM, meaning all components of a product, to databases of known vulnerabilities.

For vulnerability interactions beyond reading, you need the VULN_MANAGEMENT permission. The section about Access Management describes how it is granted.

Detecting

BOMnipotent does not itself detect new vulnerabilities. One tool that can be used in combination with BOMnipotent is grype , which takes a BOM as input and produces a list of vulnerabilities as output. The grype tutorial contains some additional information on its usage. Other tools can be used as long as they provide output in CycloneDX JSON format .

Using the BOMnipotent Client, you can directly print the contents of a BOM and pipe it to grype.

bomnipotent_client bom get <BOM-NAME> <BOM-VERSION> | grype --output cyclonedx-json=./vuln.cdx.json

bomnipotent_client bom get <BOM-NAME> <BOM-VERSION> | grype -o cyclonedx-json=./vuln.cdx.json

This will check the software components agains several databases and add the result to the CycloneDX. It then stores all that in a file called “vuln.cdx.json” (or whichever other name you provide).

Grype currently has a small known bug that makes it forget the version of the main component when it adds the vulnerabilities. This is a bit problematic because BOMnipotent needs the version to uniquely identify a product. One possible workaround is to re-add the version to the document, for example via jq '.metadata.component.version = "<VERSION>"' "vuln.cdx.json" > "vuln_with_version.cdx.json". Starting with BOMnipotent v0.3.1 you can instead directly provide the version during the vulnerability upload, as described below.

Updating

The command to update the vulnerabilities associated with a BOM is

bomnipotent_client vulnerability update <VULNERABILITIES>

[INFO] Updated vulnerabilities of BOM vulny_0.1.0

The “<VULNERABILITIES>” argument needs to be a path to a file in CycloneDX JSON format.

Ideally, this file contains the name and version of the associated BOM, in which case they will automatically be read. If one of the values is missing (due to a known bug in grype, for example), you can provide it with an optional argument:

bomnipotent_client vulnerability update <VULNERABILITIES> --name=<NAME> --version=<VERSION>

bomnipotent_client vulnerability update <VULNERABILITIES> -n <NAME> -v <VERSION>

[INFO] Updated vulnerabilities of BOM BOMnipotent_1.0.0

Vulnerabilities are meant to updated periodically. Doing so will completely replace any previous vulnerabilities associated a BOM. The uploaded CycloneDX document thus needs to contain a full list of all known vulnerabilities.

You can only update vulnerabilities for a BOM that exists on the server:

[ERROR] Received response:
404 Not Found
BOM Schlagsahne_1.0.1 not found in database

Listing

The section about listing vulnerabilities in the documentation for consumers covers most aspects of listing vulnerabilities.

One aspect not mentioned there is the “–unassessed” option. With it, BOMnipotent Client lists only those vulnerabilities that have no CSAF document associated with it.

bomnipotent_client vulnerability list --unassessed

bomnipotent_client vulnerability list -u

╭─────────────┬─────────┬─────────────────────┬───────────────────────────┬───────┬──────────┬─────────┬─────────────────╮
│ Product     │ Version │ Vulnerability       │ Description               │ Score │ Severity │ TLP     │ CSAF Assessment │
├─────────────┼─────────┼─────────────────────┼───────────────────────────┼───────┼──────────┼─────────┼─────────────────┤
│ BOMnipotent │ 1.0.0   │ GHSA-qg5g-gv98-5ffh │ rustls network-reachable  │       │ medium   │ Default │                 │
│             │         │                     │ panic in `Acceptor::accep │       │          │         │                 │
│             │         │                     │ t`                        │       │          │         │                 │
│ vulny       │ 0.1.0   │ GHSA-qg5g-gv98-5ffh │ rustls network-reachable  │       │ medium   │ Default │                 │
│             │         │                     │ panic in `Acceptor::accep │       │          │         │                 │
│             │         │                     │ t`                        │       │          │         │                 │
╰─────────────┴─────────┴─────────────────────┴───────────────────────────┴───────┴──────────┴─────────┴─────────────────╯
[ERROR] Found 2 unassessed vulnerabilities.

In this mode, BOMnipotent Client exits with a code indicating an error if and only if there are unassessed vulnerabilites. This makes it easy to integrate this call in your periodic CI/CD.

You can freely combine this option with specifying a product name or version:

bomnipotent_client vulnerability list <NAME> <VERSION> --unassessed

bomnipotent_client vulnerability list <NAME> <VERSION>  -u

[INFO] No unassessed vulnerabilities found

CSAF Documents

A Common Security Advisory Format (CSAF) document is a vendor’s response to a newly discovered vulnerability. It is a machine-readable format to spread information on how a user of your product should react: Do they need to update to a newer version? Do they need to modify a configuration? Is your product even truly affected, or does it maybe never call the affected part of the vulnerable library?

For CSAF interactions beyond reading, you need the CSAF_MANAGEMENT permission. The sectino about Access Management describes how it is granted.

Uploading

To upload a CSAF document, call

bomnipotent_client csaf upload <PATH/TO/CSAF>

[INFO] Uploaded CSAF with id WID-SEC-W-2024-3470

Before your CSAF document is uploaded, BOMnipotent Client checks that it is valid according to the OASIS CSAF Standard .

You can view the result of the operation with

bomnipotent_client csaf list

╭─────────────────────┬───────────────────────────┬─────────────────────────┬─────────────────────────┬────────┬───────────╮
│ ID                  │ Title                     │ Initial Release         │ Current Release         │ Status │ TLP       │
├─────────────────────┼───────────────────────────┼─────────────────────────┼─────────────────────────┼────────┼───────────┤
│ WID-SEC-W-2024-3470 │ binutils: Schwachstelle e │ 2024-11-14 23:00:00 UTC │ 2024-11-17 23:00:00 UTC │ final  │ TLP:WHITE │
│                     │ rmöglicht Denial of Servi │                         │                         │        │           │
│                     │ ce                        │                         │                         │        │           │
╰─────────────────────┴───────────────────────────┴─────────────────────────┴─────────────────────────┴────────┴───────────╯

All data is taken from the CSAF document.

If the document does not have the optional TLP label entry, it is treated with the default tlp configured for the server.

...┬────────┬─────────╮
...│ Status │ TLP     │
...┼────────┼─────────┤
...│ final  │ Default │
...┴────────┴─────────╯

Modifying

When the status of your document changes, if you want to reclassify it, or if new information has come to light, you may want to modify your document. To upload the new version, call:

bomnipotent_client csaf delete <PATH/TO/CSAF>

[INFO] Modified CSAF with id BSI-2024-0001-unlabeled

The command can even modify the ID of the CSAF document. Because the old ID cannot be inferred from the new document in that case, it has to be provided as an optional argument:

bomnipotent_client csaf delete <PATH/TO/CSAF> --id=<OLD-ID>

bomnipotent_client csaf delete <PATH/TO/CSAF> -i <OLD-ID>

Deleting

To delete a CSAF document from your server (which you should really only do if something went completely wrong), simply call:

bomnipotent_client csaf delete <CSAF-ID>

[INFO] Deleted CSAF with id WID-SEC-W-2024-3470

Permissions

In BOMnipotent, permissions are not directly associated with user accounts, but rather with roles. The section about role management covers how this association is managed, and the section about role assignment explains how roles (and thus ultimately permissions) are assigned to users.

The server has several permissions embedded in its code, some of which are hardcoded, some of which are configurable, and all of which are explained here. To learn how to actually create a permission associated with a role, please refer to the section dedicated to exactly that topic.

The permissions can mentally be split into permissions associated with consumers , managers , and some special tasks reserved for admins.

Consumer Permissions

Your customers are typically associated with one or more of your products. They will want to view all types of documents and information for that particular product, but they are not automatically entitled to information about other products.

PRODUCT_ACCESS

A permission with the value “PRODUCT_ACCESS(<PRODUCT>)” grants read permissions to any document associated with “<PRODUCT>”. This includes any BOM for that product, any vulnerabilities associated with these BOMs, and any CSAF documents covering this product.

For example, a role with the “PRODUCT_ACCESS(BOMnipotent)” could view (and only view) all documents associated with BOMnipotent.

It is possible to use the asterisk operator “*” to glob product names. In that case, the asterisk matches an arbitrary number of symbols. For example, the permission “PRODUCT_ACCESS(BOM*ent)” would match “BOMnipotent” as well as the (fictional) products “BOMent” and “BOM-burárum-ent”, but not “BOMtastic” (because the latter does not end on “ent”).

Consequently, “PRODUCT_ACCESS(*)” allows the viewing of all documents.

Manager Permissions

For managers of documents, the situation is usually reversed: They need the permission to not only view but also modify the contents in the database. Their scope is typically not restricted to a specific product, but instead to a specific type of document. This is why the segregation of manager permissions takes another perspective.

BOM_MANAGEMENT

This permission allows the uploading, modifying and deleting of Bills of Materials (BOMs). It also automatically grants permission to view all hosted BOMs.

VULN_MANAGEMENT

This permission allows to update and view the list of vulnerabilities associated with any BOM.

CSAF_MANAGEMENT

Unsurprisingly, this permission allows the uploading, modifying and deleting of Common Security Advisory Format (CSAF) documents. It also automatically grants view permissions to all hosted CSAF documents.

ROLE_MANAGEMENT

With this permission, a user can modify the permissions of roles, which can have far reaching consequences, because the changes potentially affect many users.

USER_MANAGEMENT

This permission is required to approve, deny or view users, or to individually assign roles to them.

Special Admin permissions

BOMnipotent knows one hardcoded special role called “admin”. This role always has all permissions that can be given to users. Additionally, there are some tasks that can only be done by a user with the admin role:

• Only admins can give or remove the admin role to or from other users. A special tmp admin mechanism exists to create the first admin for a freshly created BOMnipotent Server.
• Only admins can (de)activate the subscription key for a BOMnipotent Server instances.

Role Management

BOMnipotent uses a role-based access model (RBAC), in which users are associated with roles, and roles with permissions. While permissions are largely hardcoded into BOMnipotent, roles can be managed (almost) freely. This section explains how to do that.

To modify or even view roles and their permissions, your user account needs the ROLE_MANAGEMENT permission.

Default Roles

When you spin up your BOMnipotent Server for the first time, it creates several colourfully named default roles in the database:

• “bom_manager”, with the BOM_MANAGEMENT permission.
• “csaf_manager”, with the CSAF_MANAGEMENT permission.
• “role_manager”, with the ROLE_MANAGEMENT permission.
• “user_manager”, with the USER_MANAGEMENT permission.
• “vuln_manager”, with the VULN_MANAGEMENT permission.

You can modify or delete these roles at will, they are merely suggestions.

If you do not like these roles, use the following calls to delete them:

bomnipotent_client role-permission remove bom_manager BOM_MANAGEMENT;
bomnipotent_client role-permission remove csaf_manager CSAF_MANAGEMENT;
bomnipotent_client role-permission remove role_manager ROLE_MANAGEMENT;
bomnipotent_client role-permission remove user_manager USER_MANAGEMENT;
bomnipotent_client role-permission remove vuln_manager VULN_MANAGEMENT;

Admin Role

There is a special role called “admin”, which is not listed among the other roles. The reason is that it is not part of the database, but of the BOMnipotent code itself. As such, it cannot be modified.

bomnipotent_client role-permission remove admin BOM_MANAGEMENT

bomnipotent_client role-permission add admin "PRODUCT_ACCESS(BOMnipotent)"

[ERROR] Received response:
422 Unprocessable Entity
Cannot modify admin role permissions

The admin role has all permissions that can be granted, and then some more .

Listing

To list all roles and their associated permissions, call:

bomnipotent_client role-permission list

╭──────────────┬─────────────────┬───────────────────────────╮
│ Role         │ Permission      │ Last Updated              │
├──────────────┼─────────────────┼───────────────────────────┤
│ bom_manager  │ BOM_MANAGEMENT  │ 2025-03-20 10:38:27.29648 │
│              │                 │ 0 UTC                     │
│ csaf_manager │ CSAF_MANAGEMENT │ 2025-03-20 10:38:27.29695 │
│              │                 │ 2 UTC                     │
│ role_manager │ ROLE_MANAGEMENT │ 2025-03-20 10:38:27.29621 │
│              │                 │ 3 UTC                     │
│ user_manager │ USER_MANAGEMENT │ 2025-03-20 10:38:27.29562 │
│              │                 │ 0 UTC                     │
│ vuln_manager │ VULN_MANAGEMENT │ 2025-03-20 10:38:27.29671 │
│              │                 │ 9 UTC                     │
╰──────────────┴─────────────────┴───────────────────────────╯

Adding

Because roles without permissions are meaningless, the two always come in pairs. There is no dedicated mechanism to create a new role: rather, you add a permission to a role, and henceforth it exists.

The syntax to add a permission to a role is

bomnipotent_client role-permission add <ROLE> <PERMISSION>

[INFO] Added permission BOM_MANAGEMENT to role

You could for example unify several permissions into the roles “doc_manager” and “access_manager”:

bomnipotent_client role-permission add doc_manager BOM_MANAGEMENT;
bomnipotent_client role-permission add doc_manager CSAF_MANAGEMENT;
bomnipotent_client role-permission add doc_manager VULN_MANAGEMENT;
bomnipotent_client role-permission add access_manager ROLE_MANAGEMENT;
bomnipotent_client role-permission add access_manager USER_MANAGEMENT;

If you have removed the default roles as described above, this leaves you with:

bomnipotent_client role-permission list

╭────────────────┬─────────────────┬───────────────────────────╮
│ Role           │ Permission      │ Last Updated              │
├────────────────┼─────────────────┼───────────────────────────┤
│ access_manager │ ROLE_MANAGEMENT │ 2025-03-20 11:05:42.06443 │
│                │                 │ 7 UTC                     │
│ access_manager │ USER_MANAGEMENT │ 2025-03-20 11:04:57.51274 │
│                │                 │ 7 UTC                     │
│ doc_manager    │ BOM_MANAGEMENT  │ 2025-03-20 11:05:55.15986 │
│                │                 │ 0 UTC                     │
│ doc_manager    │ CSAF_MANAGEMENT │ 2025-03-20 11:05:50.92466 │
│                │                 │ 9 UTC                     │
│ doc_manager    │ VULN_MANAGEMENT │ 2025-03-20 11:05:47.35620 │
│                │                 │ 9 UTC                     │
╰────────────────┴─────────────────┴───────────────────────────╯

If the permission you want to add does not exist or is malformed, you will receive an error:

bomnipotent_client role-permission add clam_manager CLAM_MANAGEMENT

[ERROR] Received response:
422 Unprocessable Entity
Failed to parse permission: Invalid UserPermission string: CLAM_MANAGEMENT

Removing

To remove a permission from a role, simply call:

bomnipotent_client role-permission remove <ROLE> <PERMISSION>

[INFO] Removed permission VULN_MANAGEMENT from role vuln_manager

Once you have removed the last role from a permission, that role does no longer exist.

To prevent oopsie-moments, BOMnipotent does not support deleting whole batches of role-permissions.

User Management

The first step when creating a new user is to request a new account. This step is described elsewhere , because it is relevant for managers and consumers alike.

From BOMnipotent’s point of view, a user is associated with a unique email address, which is used as an identifier, and a public key, which is used for authentication. This is all the data sent during the creation of a new user account.

After a new account has been requested, it is up to a user manager to approve or deny the request.

For most user interactions, including listing, you need the USER_MANAGEMENT permission.

Listing

To list all users in your database, call

bomnipotent_client user list

╭────────────────────┬───────────┬─────────────────────────┬─────────────────────────╮
│ User Email         │ Status    │ Expires                 │ Last Updated            │
├────────────────────┼───────────┼─────────────────────────┼─────────────────────────┤
│ admin@wwh-soft.com │ APPROVED  │ 2026-03-23 04:51:26 UTC │ 2025-03-22 04:51:26 UTC │
│ info@wildeheide.de │ REQUESTED │ 2026-03-23 03:52:21 UTC │ 2025-03-22 03:52:21 UTC │
╰────────────────────┴───────────┴─────────────────────────┴─────────────────────────╯

You can see the email addresses of the users and their stati.

A user that does not have the status APPROVED has no special permissions, no matter which roles they have.

An expiration date is also associated with each user, which is the point in time at which the public key is considered invalid and has to be renewed. The period for which a key is considered valid can be freely configured in the server config.

Approval or Denial

If you were expecting the user request, you can approve it via

bomnipotent_client user approve <EMAIL>

[INFO] Changed status of info@wildeheide.de to APPROVED

Analogously, you can decide agains allowing this user any special access:

bomnipotent_client user deny <EMAIL>

[INFO] Changed status of info@wildeheide.de to DENIED

It is possible to deny a user that has already been approved, effectively revoking the account.

Deleting

If you want to get rid of a user account alltogether, call

bomnipotent_client user remove <EMAIL>

[INFO] Deleted user info@wildeheide.de

Role Assignment

Roles are what connects users to permissions. Adding or removing roles to and from users indirectly controls to what extend users can interact with your BOMnipotent Server instance.

For your convenience, several default roles are created upon starting BOMnipotent Server for the first time. In addition, BOMnipotent knows of the admin role , which receives some special treatment.

To modify or even view user roles, your user account needs the USER_MANAGEMENT permission.

Listing

To list all roles of all users, call

bomnipotent_client user-role list

╭──────────────────┬─────────────┬───────────────────────────╮
│ User Email       │ User Role   │ Last Updated              │
├──────────────────┼─────────────┼───────────────────────────┤
│ info@quantumwire │ bom_manager │ 2025-03-22 04:27:33.71579 │
│                  │             │ 7 UTC                     │
│ info@wildeheide  │ bom_manager │ 2025-03-22 04:26:08.83708 │
│                  │             │ 3 UTC                     │
╰──────────────────┴─────────────┴───────────────────────────╯

Adding

To add a new role to a user, call

bomnipotent_client user-role add <EMAIL> <ROLE>

[INFO] Added role to user

The user account needs to exist on the server at this point, the role does not.

Only users with the admin role can add the admin role to other users.

Removing

To remove a role from a user, call

bomnipotent_client user-role remove <EMAIL> <ROLE>

[INFO] Removed role bom_manager from user info@wildeheide

This will show an error if either does not exist:

[ERROR] Received response:
404 Not Found
User with email info@wildeheide does not have role bom_manager

Only users with the admin role can remove the admin role from other users.