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 Framework (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:

Input

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;

Output

[INFO] Removed permission BOM_MANAGEMENT from role bom_manager
[INFO] Removed permission CSAF_MANAGEMENT from role csaf_manager
[INFO] Removed permission ROLE_MANAGEMENT from role role_manager
[INFO] Removed permission USER_MANAGEMENT from role user_manager
[INFO] Removed permission VULN_MANAGEMENT from role vuln_manager

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.

Input

bomnipotent_client role-permission remove admin BOM_MANAGEMENT

Output

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

List

To list all roles and their associated permissions, call:

Input

bomnipotent_client role-permission list

Output

[INFO] 
╭──────────────┬─────────────────┬─────────────────────────╮
│ Role         │ Permission      │ Last Updated            │
├──────────────┼─────────────────┼─────────────────────────┤
│ bom_manager  │ BOM_MANAGEMENT  │ 2025-01-01 10:11:12 UTC │
│ csaf_manager │ CSAF_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ role_manager │ ROLE_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ user_manager │ USER_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ vuln_manager │ VULN_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
╰──────────────┴─────────────────┴─────────────────────────╯

The output can be filtered by role or permission:

Input (long variant)

bomnipotent_client role-permission list --role=bom_manager --permission=BOM_MANAGEMENT

Input (short variant)

bomnipotent_client role-permission list -r bom_manager -p BOM_MANAGEMENT

Output

[INFO] 
╭─────────────┬────────────────┬─────────────────────────╮
│ Role        │ Permission     │ Last Updated            │
├─────────────┼────────────────┼─────────────────────────┤
│ bom_manager │ BOM_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
╰─────────────┴────────────────┴─────────────────────────╯

Add

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

Input

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

Output

[INFO] Added permission PRODUCT_ACCESS(BOMnipotent) to role

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

Input

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;

Output

[INFO] Added permission BOM_MANAGEMENT to role
[INFO] Added permission CSAF_MANAGEMENT to role
[INFO] Added permission VULN_MANAGEMENT to role
[INFO] Added permission ROLE_MANAGEMENT to role
[INFO] Added permission USER_MANAGEMENT to role

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

Input

bomnipotent_client role-permission list

Output

[INFO] 
╭────────────────┬─────────────────┬─────────────────────────╮
│ Role           │ Permission      │ Last Updated            │
├────────────────┼─────────────────┼─────────────────────────┤
│ access_manager │ ROLE_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ access_manager │ USER_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ doc_manager    │ BOM_MANAGEMENT  │ 2025-01-01 10:11:12 UTC │
│ doc_manager    │ CSAF_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
│ doc_manager    │ VULN_MANAGEMENT │ 2025-01-01 10:11:12 UTC │
╰────────────────┴─────────────────┴─────────────────────────╯

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

Input

bomnipotent_client role-permission add clam_manager CLAM_MANAGEMENT

Output

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

Remove

To remove a permission from a role, simply call:

Input

bomnipotent_client role-permission remove rick_role "PRODUCT_ACCESS(BOMnipotent)"

Output

[INFO] Removed permission PRODUCT_ACCESS(BOMnipotent) from role rick_role

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.

Existence

The "exists" subcommand checks whether or not at least one object on the server matches some filters. It is available for all commands that accept the "list" subcommand, and accepts the same filters.

Depending on the output mode, the client prints:

normal mode: a sentence including the number of found objects.
code: The string "200" if at least one item was found, or "404" if none were found.
raw: The string "true" if at least one item was found, or "false" if none were found.

Input (long variant)

bomnipotent_client role-permission exists --role=bom_manager

Input (short variant)

bomnipotent_client role-permission exists -r bom_manager

Output

[INFO] Yes, the server contains 1 role permissions matching the filters.

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 or username, 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.

List

To list all users in your database, call

Input

bomnipotent_client user list

Output

[INFO] 
╭────────────────────────┬───────────┬─────────────────────────┬───────────┬─────────────────────────╮
│ Username               │ Status    │ Expires                 │ User Type │ Last Updated            │
├────────────────────────┼───────────┼─────────────────────────┼───────────┼─────────────────────────┤
│ admin@example.com      │ APPROVED  │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
│ example_robot          │ REQUESTED │ 2025-01-01 10:11:12 UTC │ ROBOT     │ 2025-01-01 10:11:12 UTC │
│ other_user@example.com │ REQUESTED │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
│ user@example.com       │ VERIFIED  │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
╰────────────────────────┴───────────┴─────────────────────────┴───────────┴─────────────────────────╯

You can see the email addresses or usernames 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.

The list of users can be filtered by username, approval status, and whether or not they are expired:

Input (long variant)

bomnipotent_client user list --user=admin@example.com --status=APPROVED --expired=false

Input (short variant)

bomnipotent_client user list -u admin@example.com -s APPROVED -e false

Output

[INFO] 
╭───────────────────┬──────────┬─────────────────────────┬───────────┬─────────────────────────╮
│ Username          │ Status   │ Expires                 │ User Type │ Last Updated            │
├───────────────────┼──────────┼─────────────────────────┼───────────┼─────────────────────────┤
│ admin@example.com │ APPROVED │ 2025-01-01 10:11:12 UTC │ HUMAN     │ 2025-01-01 10:11:12 UTC │
╰───────────────────┴──────────┴─────────────────────────┴───────────┴─────────────────────────╯

The “true” argument for the expired filter is optional:

Input (long variant)

bomnipotent_client user list --expired=true;
bomnipotent_client user list --expired # does the same

Input (short variant)

bomnipotent_client user list -e true;
bomnipotent_client user list -e # does the same

Output

[INFO] 
╭──────────┬────────┬─────────┬───────────┬──────────────╮
│ Username │ Status │ Expires │ User Type │ Last Updated │
├──────────┼────────┼─────────┼───────────┼──────────────┤
[INFO] 
╭──────────┬────────┬─────────┬───────────┬──────────────╮
│ Username │ Status │ Expires │ User Type │ Last Updated │
├──────────┼────────┼─────────┼───────────┼──────────────┤

Approve or Deny

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

Input

bomnipotent_client user approve user@example.com

Output

[INFO] Changed status of user@example.com to APPROVED

If the user has not yet verified their email address, the server denies the approval. If you are absolutely sure that you know what you are doing, you can overwrite this behaviour with the ‘–allow-unverified’ option (there’s no short version for options that bypass security measures):

Input

bomnipotent_client user approve other_user@example.com --allow-unverified

Output

[INFO] Changed status of other_user@example.com to APPROVED

If the account belongs to a robot, it can not be verified. In that case you can approve it with the ‘–robot’ option.

Input (long variant)

bomnipotent_client user approve example_robot --robot

Input (short variant)

bomnipotent_client user approve example_robot -r

Output

[INFO] Changed status of example_robot to APPROVED

Important: You should be absolutely certain that this is the account you want to approve.

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

Input

bomnipotent_client user deny unwanted@example.com

Output

[INFO] Changed status of unwanted@example.com to DENIED

Contrary to approval, this action does not care which status the user had before the denial.

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

Remove

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

Input

bomnipotent_client user remove unwanted@example.com

Output

[INFO] Deleted user "unwanted@example.com".

This also removes all roles associated with the user.

Existence

The "exists" subcommand checks whether or not at least one object on the server matches some filters. It is available for all commands that accept the "list" subcommand, and accepts the same filters.

Depending on the output mode, the client prints:

normal mode: a sentence including the number of found objects.
code: The string "200" if at least one item was found, or "404" if none were found.
raw: The string "true" if at least one item was found, or "false" if none were found.

Input (long variant)

bomnipotent_client user exists --status=APPROVED

Input (short variant)

bomnipotent_client user exists -s APPROVED

Output

[INFO] Yes, the server contains 4 users matching the filters.

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.

List

To list all roles of all users, call

Input

bomnipotent_client user-role list

Output

[INFO] 
╭───────────────────┬──────────────┬─────────────────────────╮
│ Username          │ Role         │ Last Updated            │
├───────────────────┼──────────────┼─────────────────────────┤
│ admin@example.com │ admin        │ 2025-01-01 10:11:12 UTC │
│ example_robot     │ bom_manager  │ 2025-01-01 10:11:12 UTC │
│ example_robot     │ vuln_manager │ 2025-01-01 10:11:12 UTC │
│ user@example.com  │ rick_role    │ 2025-01-01 10:11:12 UTC │
╰───────────────────┴──────────────┴─────────────────────────╯

The output can be filtered by user or role:

Input (long variant)

bomnipotent_client user-role list --user=admin@example.com --role=admin

Input (short variant)

bomnipotent_client user-role list -u admin@example.com -r admin

Output

[INFO] 
╭───────────────────┬───────┬─────────────────────────╮
│ Username          │ Role  │ Last Updated            │
├───────────────────┼───────┼─────────────────────────┤
│ admin@example.com │ admin │ 2025-01-01 10:11:12 UTC │
╰───────────────────┴───────┴─────────────────────────╯

Add

To add a new role to a user, call

Input

bomnipotent_client user-role add user@example.com rick_role

Output

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

Remove

To remove a role from a user, call:

Input

bomnipotent_client user-role remove user@example.com rick_role

Output

[INFO] Removed role rick_role from user user@example.com

This will show an error if either does not exist:

Input

bomnipotent_client user-role remove admin@example.com wrong_role;
bomnipotent_client user-role remove wrong_user admin

Output

[ERROR] Received response:
404 Not Found
User with username "admin@example.com" does not have role wrong_role.
[ERROR] Received response:
404 Not Found
No user with username "wrong_user" was found: Record not found

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

Existence

The "exists" subcommand checks whether or not at least one object on the server matches some filters. It is available for all commands that accept the "list" subcommand, and accepts the same filters.

Depending on the output mode, the client prints:

normal mode: a sentence including the number of found objects.
code: The string "200" if at least one item was found, or "404" if none were found.
raw: The string "true" if at least one item was found, or "false" if none were found.

Input (long variant)

bomnipotent_client user-role exists --role=bom_manager

Input (short variant)

bomnipotent_client user-role exists -r bom_manager

Output

[INFO] Yes, the server contains 1 user roles matching the filters.

Access Management

Subsections of Access Management

Permissions

Consumer Permissions

PRODUCT_ACCESS

Manager Permissions

BOM_MANAGEMENT

VULN_MANAGEMENT

CSAF_MANAGEMENT

ROLE_MANAGEMENT

USER_MANAGEMENT

Special Admin permissions

Role Management

Default Roles

Admin Role

List

Add

Remove

Existence

User Management

List

Approve or Deny

Remove

Existence

Role Assignment

List

Add

Remove

Existence