CSAF Documents

When a vulnerability becomes known in one of the components of a product that you use, one of the most natural questions to ask is “What do I have to do now?”. The Common Security Advisory Framework (CSAF) aims to provide an answer to that question in an automated fashion. It is a mainly machine-readable format for exchanging advisories about security vulnerabilities.

One of the main functionalities of BOMnipotent is to make distribution of CSAF documents as easy as possible. Any running instance of BOMnipotent Server acts as a “CSAF Provider” according to the OASIS standard .

List

Running the following command will give you a list of all CSAF documents accessible to you:

Input
bomnipotent_client csaf list
Output
[INFO] 
╭────────────────────────────┬────────────────────────────┬─────────────────────────┬─────────────────────────┬────────┬───────────╮
│ ID                         │ Title                      │ Initial Release         │ Current Release         │ Status │ TLP       │
├────────────────────────────┼────────────────────────────┼─────────────────────────┼─────────────────────────┼────────┼───────────┤
│ ghsa-qg5g-gv98-5ffh_adviso │ Network-reachable panic in │ 2025-01-01 10:11:12 UTC │ 2025-01-01 10:11:12 UTC │ final  │ TLP:AMBER │
│ ry                         │  Your Product              │                         │                         │        │           │
╰────────────────────────────┴────────────────────────────┴─────────────────────────┴─────────────────────────┴────────┴───────────╯

Accesible CSAF documents are those that are either labeled TLP:WHITE/TLP:CLEAR, or that concern a product that you have been granted access to.

Filter

The “csaf list” command allows quite a large number of filters, to display only some of all CSAF documents:

  • id: The ID of a CSAF document is unique, so this filter will display at most one result.
  • filename: According to the OASIS standard , CSAF IDs allow more characters than filenames. Thus, a CSAF doc’s filename is not necessarily unique.
  • before: Show only CSAF documents that were initially released before a certain datetime. The input can be of the forms “YYYY”, “YYYY-MM”, “YYYY-MM-DD”, “YYYY-MM-DD HH”, “YYYY-MM-DD HH:MM” or “YYYY-MM-DD HH:MM:SS”. If the input is less precise than seconds, it is assumend to be minimal. This means that “before 2025-08” filters for documents that were released before 2025-08-01 00:00:00. UTC is assumed as the timezone, unless you explicitly specify another one by adding an offset ("+02:00" for example) to the input.
  • after: Show only CSAF documents that were initially released after a certain datetime. If the input is less precise than seconds, it is assumed to be maximal. This means that “after 2025-08” filters for documents that were release after 2025-08-31 13:59:59.
  • year: Show only CSAF documents that were initially released within a given year.
  • status: Filter by document status. The OASIS standard lists all allowed values.
  • tlp: Show only CSAF document with a certain TLP classification. In addition to the labels of TLP1 and TLP2, “default”, “none”, “unclassified” and “unlabeled” are valid inputs here (all denoting the same thing).
Input (long variant)
bomnipotent_client csaf list --year=2025 --status=final --tlp=amber
Input (short variant)
bomnipotent_client csaf list -y 2025 -s final -t amber
Output
[INFO] 
╭────────────────────────────┬────────────────────────────┬─────────────────────────┬─────────────────────────┬────────┬───────────╮
│ ID                         │ Title                      │ Initial Release         │ Current Release         │ Status │ TLP       │
├────────────────────────────┼────────────────────────────┼─────────────────────────┼─────────────────────────┼────────┼───────────┤
│ ghsa-qg5g-gv98-5ffh_adviso │ Network-reachable panic in │ 2025-01-01 10:11:12 UTC │ 2025-01-01 10:11:12 UTC │ final  │ TLP:AMBER │
│ ry                         │  Your Product              │                         │                         │        │           │
╰────────────────────────────┴────────────────────────────┴─────────────────────────┴─────────────────────────┴────────┴───────────╯
Input (long variant)
bomnipotent_client csaf list --before=2025-03-01 --after="2024-11-08 15:44:13.26+02:00"
Input (short variant)
bomnipotent_client csaf list -b 2025-03-01 -a "2024-11-08 15:44:13.26+02:00"
Output
[INFO] 
╭────────────────────────────┬────────────────────────────┬─────────────────────────┬─────────────────────────┬────────┬───────────╮
│ ID                         │ Title                      │ Initial Release         │ Current Release         │ Status │ TLP       │
├────────────────────────────┼────────────────────────────┼─────────────────────────┼─────────────────────────┼────────┼───────────┤
│ ghsa-qg5g-gv98-5ffh_adviso │ Network-reachable panic in │ 2025-01-01 10:11:12 UTC │ 2025-01-01 10:11:12 UTC │ final  │ TLP:AMBER │
│ ry                         │  Your Product              │                         │                         │        │           │
╰────────────────────────────┴────────────────────────────┴─────────────────────────┴─────────────────────────┴────────┴───────────╯

Download

To locally mirror all CSAF documents accessible to you, run

Input
bomnipotent_client csaf download /home/csaf
Output
[INFO] Storing CSAF documents under /home/csaf

This will store th CSAF documents in the provided folder ("/home/csaf", in this example). It will create the folder structure if it does not already exist. The CSAF documents are stored in file paths following the naming scheme “{tlp}/{initial_release_year}/{csaf_id}.json”.

The filenames of CSAF documents follow a naming scheme defined by the OASIS standard : The ids are converted into lowercase, and most special characters are replaced by an underscore ‘_’. This means that, in principle, different CSAF documents could lead to the same filepath. In that case, BOMnipotent will display an error instead of silently overwriting a file.

Input
tree /home/csaf/
Output
/home/csaf/
`-- amber
    `-- 2025
        `-- ghsa-qg5g-gv98-5ffh_advisory.json

3 directories, 1 file

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

It is possible to only download a single file by providing the path as an additional argument:

Input
bomnipotent_client csaf download /home/csaf amber/2025/ghsa-qg5g-gv98-5ffh_advisory.json
Output
[INFO] Storing CSAF document under /home/csaf

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

Input
bomnipotent_client csaf download /home/csaf
Output
[INFO] Storing CSAF documents under /home/csaf
[WARN] File /home/csaf/amber/2025/ghsa-qg5g-gv98-5ffh_advisory.json already exists.
The existing CSAF doc has ID 'GHSA-QG5G-GV98-5FFH%ADVISORY' while the new one has ID 'ghsa-qg5g-gv98-5ffh_advisory'.
Note that according to the OASIS standard, both IDs are mapped to the same filename 'ghsa-qg5g-gv98-5ffh_advisory.json'.
For more information, see Section 5.1 of
https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#51-filename
Skipping download to prevent data loss.

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

Input (long variant)
bomnipotent_client csaf download /home/csaf --overwrite
Input (short variant)
bomnipotent_client csaf download /home/csaf -o
Output
[INFO] Storing CSAF documents under /home/csaf
[INFO] Overwriting existing CSAF document at '/home/csaf/amber/2025/ghsa-qg5g-gv98-5ffh_advisory.json'.

The download command accepts exactly the same filters as the list command does, allowing to only download those documents that are relevant to you.

Get

You can directly display the contents of a single CSAF doc to the consolte output by calling

Input
bomnipotent_client csaf get ghsa-qg5g-gv98-5ffh_advisory | tail -n 16
Output
          "your_project_1.1.0"
        ]
      },
      "remediations": [
        {
          "category": "vendor_fix",
          "date": "2025-01-01T11:00:00.000Z",
          "details": "Update to version 1.1.0.",
          "product_ids": [
            "your_project_1.0.0"
          ]
        }
      ]
    }
  ]
}

This is especially useful if you want to use the contents of this CSAF doc in a script.

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 csaf exist --year=2023
Input (short variant)
bomnipotent_client csaf exist -y 2023
Output
[INFO] The server does not contain any CSAF document(s) matching the filters.