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 
╭─────────────────────┬───────────────────────────┬─────────────────────────┬─────────────────────────┬────────┬───────────╮
│ 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                        │                         │                         │        │           │
╰─────────────────────┴───────────────────────────┴─────────────────────────┴─────────────────────────┴────────┴───────────╯

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.
  • after: Show only CSAF documents that were initially released after a certain datetime. The input should be in RFC3339 format, including date, time, and timezone.
  • before: Show only CSAF documents that were initially released before a certain datetime.
  • 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 --after=2023-07-01T00:00Z --year=2023 --status=final --tlp=amber
Input (short variant) 
bomnipotent_client csaf list -a 2023-07-01T00:00Z -y 2023 -s final -t amber

Download

To locally mirror all CSAF documents accessible to you, run

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

This will store th CSAF documents in the provided folder ("./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 ./csaf/
Output 
./csaf/
└── white
    └── 2022
        └── bsi-2022-0001.json

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 ./csaf white/2022/bsi-2022-0001.json

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 ./csaf
Output 
[WARN] File ./csaf/white/2023/wid-sec-w-2023-0001.json already exists.
Use the "--overwrite" flag to replace it.
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 ./csaf --overwrite
Input (short variant) 
bomnipotent_client csaf download ./csaf -o

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 <ID> | head -n 8
Output 
{
  "document" : {
    "aggregate_severity" : {
      "text" : "mittel"
    },
    "category" : "csaf_base",
    "csaf_version" : "2.0",
    "distribution" : {

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

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 csaf exists --year=2023
Input (short variant) 
bomnipotent_client csaf exists -y 2023