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.

List

Running the following command will list all BOMs accessible to you:

Input
bomnipotent_client bom list
Output
[INFO] 
╭────────────────────────┬─────────┬─────────────────────────┬───────────┬────────────╮
│ Product                │ Version │ Timestamp               │ TLP       │ Components │
├────────────────────────┼─────────┼─────────────────────────┼───────────┼────────────┤
│ Best Project           │ 3.1.4   │ 2025-01-01 10:11:12 UTC │ TLP:GREEN │ 75         │
│ Your Project           │ 1.0.0   │ 2025-01-01 10:11:12 UTC │ Default   │ 75         │
│ Your Project           │ 1.1.0   │ 2025-01-01 10:11:12 UTC │ Default   │ 75         │
│ Your Project Container │ 1.2.3   │ 2025-01-01 10:11:12 UTC │ TLP:WHITE │ 939        │
╰────────────────────────┴─────────┴─────────────────────────┴───────────┴────────────╯

BOMs with label TLP:WHITE / TLP:CLEAR are visible to everyone. In this example, your account has access to one BOM with label TLP:AMBER.

The command accepts the optional filters “name” and “version”:

Input (long variant)
bomnipotent_client bom list --name="Your Project" --version="1.0.0"
Input (short variant)
bomnipotent_client bom list -n "Your Project" -v "1.0.0"
Output
[INFO] 
╭──────────────┬─────────┬─────────────────────────┬─────────┬────────────╮
│ Product      │ Version │ Timestamp               │ TLP     │ Components │
├──────────────┼─────────┼─────────────────────────┼─────────┼────────────┤
│ Your Project │ 1.0.0   │ 2025-01-01 10:11:12 UTC │ Default │ 75         │
╰──────────────┴─────────┴─────────────────────────┴─────────┴────────────╯

Download

To create a local copy of all boms the server exposes to you, run:

Input
bomnipotent_client bom download /home/boms
Output
[INFO] Storing BOMs under '/home/boms'.
[INFO] Stored 4 BOM document(s) under '/home/boms'.

This will store the BOMs in the provided folder ("./boms", in this example). It will create the folder structure if it does not already exist. The BOMs are stored in files following the naming scheme {product name}_{product version}.cdx.json.

To avoid inconsistent behaviour accross operating systems, the name and version of the product are converted into lowercase, and most special characters are replaced by an underscore ‘_’. This means that, in principle, different products could lead to the same filename. In that case, BOMnipotent will display a warning instead of silently overwriting a file.

The client also downloads several files containing a hash and the filename of the hashed file.

If OpenPGP is configured on the server, the client furthermore downloads cryptografic signatures for the BOMs. They are saved in “.json.asc” files, and can for example be verified using Sequoia-PGP.

Input
tree /home/boms/
Output
/home/boms/
|-- best_project_3.1.4.cdx.json
|-- best_project_3.1.4.cdx.json.asc
|-- best_project_3.1.4.cdx.json.sha256
|-- best_project_3.1.4.cdx.json.sha512
|-- your_project_1.0.0.cdx.json
|-- your_project_1.0.0.cdx.json.asc
|-- your_project_1.0.0.cdx.json.sha256
|-- your_project_1.0.0.cdx.json.sha512
|-- your_project_1.1.0.cdx.json
|-- your_project_1.1.0.cdx.json.asc
|-- your_project_1.1.0.cdx.json.sha256
|-- your_project_1.1.0.cdx.json.sha512
|-- your_project_container_1.2.3.cdx.json
|-- your_project_container_1.2.3.cdx.json.asc
|-- your_project_container_1.2.3.cdx.json.sha256
`-- your_project_container_1.2.3.cdx.json.sha512

1 directory, 16 files

Before requesting files for download, BOMnipotent Client makes an inventory of the BOMs already present in the folder, and downloads only the missing ones.

BOMnipotent does not automatically replace existing files, even if they have changed on the server. It instead prints a warning message:

Input
bomnipotent_client bom download /home/boms
Output
[INFO] Storing BOMs under '/home/boms'.
[WARN] File '/home/boms/best_project_3.1.4.cdx.json' already exists.
The existing BOM doc has name 'BEST%PROJECT' and version '3.1.4' while the new one has name 'Best Project' and version '3.1.4'.
Note that to avoid shenangians with the filesystem, both are mapped to the same filename 'best_project_3.1.4.cdx.json'.
Skipping download to prevent data loss.
[INFO] Stored 0 BOM document(s) under '/home/boms'.

You can tell BOMnipotent that you really want this file overwritten by using the “overwrite” flag:

Input (long variant)
bomnipotent_client bom download /home/boms --overwrite
Input (short variant)
bomnipotent_client bom download /home/boms -o
Output
[INFO] Storing BOMs under '/home/boms'.
[INFO] Overwriting existing BOM document at '/home/boms/best_project_3.1.4.cdx.json'.
[INFO] Stored 1 BOM document(s) under '/home/boms'.

Analogously to the list command, the download command accepts the filters “name” and “version”, to only download a subset of BOMs:

Input (long variant)
bomnipotent_client bom download /home/boms --name="Your Project" --version="1.0.0"
Input (short variant)
bomnipotent_client bom download /home/boms -n "Your Project" -v "1.0.0"
Output
[INFO] Storing BOMs under '/home/boms'.
[INFO] Stored 1 BOM document(s) under '/home/boms'.

Get

You can directly display the contents of a single BOM to the console output by calling

Input
bomnipotent_client bom get "Your Project" "1.0.0" | grep -v "serialNumber" | head -n 16
Output
{
  "$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "version": 1,
  "metadata": {
    "timestamp": "2025-01-01T10:11:12Z",
    "tools": {
      "components": [
        {
          "type": "application",
          "author": "anchore",
          "name": "syft",
          "version": "1.36.0"
        }
      ]

This is especially useful if you want to use the contents of this BOM in a script. For example, to check for vulnerabilities in the supply chain, you could call:

Input
bomnipotent_client bom get "Your Project" "1.0.0" | grype
Output
NAME    INSTALLED  FIXED IN  TYPE        VULNERABILITY        SEVERITY  EPSS  RISK  
rustls  0.23.15    0.23.18   rust-crate  GHSA-qg5g-gv98-5ffh  Medium    N/A   N/A

Existence

The "exist" subcommand checks how many entries on the server match 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 number of entries that were found.
Input (long variant)
bomnipotent_client bom exist --name="Your Project" --version="1.0.0"
Input (short variant)
bomnipotent_client bom exist -n "Your Project" -v "1.0.0"
Output
[INFO] The server contains 1 BOM(s) matching the filters.

Match

To find out if the server hosts any CSAF documents that concern any component of your assets, you can call the “bom match” command and provide one or more paths to BOM documents. BOMnipotent then requests all accessible CSAF documents from the server and matches them against all components in all provided BOMs:

Input (available since version 1.2.0)
bomnipotent_client bom match /home/your_project/sbom.cdx.json
Output
[INFO] 
╭────────────────────────────┬────────────────────────────┬──────────────────┬──────────────────┬──────────────────────╮
│ CSAF ID                    │ Vulnerability              │ Affection Status │ Component        │ BOM Main Component   │
├────────────────────────────┼────────────────────────────┼──────────────────┼──────────────────┼──────────────────────┤
│ ghsa-qg5g-gv98-5ffh_adviso │ GHSA-qg5g-gv98-5ffh        │ known_affected   │ 'rustls:0.23.15' │ 'Your Project:1.0.0' │
│ ry                         │ Rustls network-reachable p │                  │                  │                      │
│                            │ anic                       │                  │                  │                      │
╰────────────────────────────┴────────────────────────────┴──────────────────┴──────────────────┴──────────────────────╯

Analyze

Running the command “bom analyze” and providing it with one or more filepaths to valid CycloneDX files displays the metadata of these BOMs:

Input (available since version 1.2.0)
bomnipotent_client bom analyze /home/your_project/sbom.cdx.json
Output
[INFO] 
╭──────────────┬─────────┬─────────────────────────┬─────────┬────────────╮
│ Product      │ Version │ Timestamp               │ TLP     │ Components │
├──────────────┼─────────┼─────────────────────────┼─────────┼────────────┤
│ Your Project │ 1.0.0   │ 2025-01-01 10:11:12 UTC │ Default │ 75         │
╰──────────────┴─────────┴─────────────────────────┴─────────┴────────────╯