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
bomnipotent_client csaf upload /home/your_project/advisory.json
[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:
bomnipotent_client csaf upload /home/your_project/advisory.json
[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:
bomnipotent_client csaf upload /home/your_project/advisory.json --on-existing=skip
bomnipotent_client csaf upload /home/your_project/advisory.json -o skip
[INFO]
bomnipotent_client csaf upload /home/your_project/advisory.json --on-existing=replace
bomnipotent_client csaf upload /home/your_project/advisory.json -o replace
[INFO] Modified CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory'.
Listing
You can view the result of the operation with
bomnipotent_client csaf list
[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:
bomnipotent_client csaf modify /home/your_project/advisory.json
[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:
bomnipotent_client csaf modify <PATH/TO/CSAF> --id=<OLD-ID>
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:
bomnipotent_client csaf delete ghsa-qg5g-gv98-5ffh_advisory
[INFO] Deleted CSAF with id 'ghsa-qg5g-gv98-5ffh_advisory'.