CSAF Documents

A Common Security Advisory Framework (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

Input 
bomnipotent_client csaf upload /home/your_project/advisory.json
Output 
[INFO] Uploaded CSAF with id "ghsa-qg5g-gv98-5ffh_advisory".

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

Conflict Handling

CSAF documents are identified by their, well, identifier, which needs to be unique. Trying to upload another document with the same id results in an error:

Input 
bomnipotent_client csaf upload /home/your_project/advisory.json
Output 
[ERROR] Received response:
409 Conflict
CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory' already exists in the database.

You can override this behaviour with the “on-existing” option, telling BOMnipotent to either skip or replace conflicting documents:

Input (long variant) 
bomnipotent_client csaf upload /home/your_project/advisory.json --on-existing=skip
Input (short variant) 
bomnipotent_client csaf upload /home/your_project/advisory.json -o skip
Output 
[INFO]
Input (long variant) 
bomnipotent_client csaf upload /home/your_project/advisory.json --on-existing=replace
Input (short variant) 
bomnipotent_client csaf upload /home/your_project/advisory.json -o replace
Output 
[INFO] Modified CSAF with id "ghsa-qg5g-gv98-5ffh_advisory".

Listing

You can view the result of the operation with

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

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:

Input 
bomnipotent_client csaf modify /home/your_project/advisory.json
Output 
[INFO] Modified CSAF with id "ghsa-qg5g-gv98-5ffh_advisory".

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:

Input (long variant) 
bomnipotent_client csaf modify <PATH/TO/CSAF> --id=<OLD-ID>
Input (short variant) 
bomnipotent_client csaf modify <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:

Input 
bomnipotent_client csaf delete ghsa-qg5g-gv98-5ffh_advisory
Output 
[INFO] Deleted CSAF with id ghsa-qg5g-gv98-5ffh_advisory