Generate CSAF documents populated with vulnerability results from OWASP dep-scan.
-
Run depscan with the --csaf option.
-
Depscan will check if you already have a csaf.toml file in the target directory before proceeding.
-
If you do not, the template will be generated and you will be requested to fill it out before running depscan again.
Note: You may also just run depscan again without altering the csaf.toml - this means your document will have dummy publisher data.
-
To produce a valid CSAF document, a number of fields must be included in the toml. Some you may choose to set yourself, or we will set them for you. Please see the official CSAF 2.0 standard for a full explanation of requirements. A copy of the schema is available here. See Requirements for a brief overview.
-
Run depscan with the --csaf option again.
-
This time, a CSAF document will be written to the reports directory that you specified using the --reports-dir option (default behavior creates a reports directory in your current directory).
The first time you run depscan with the --csaf option against a specific directory, a csaf.toml template will be placed in your target directory and you will be requested to fill it out before running depscan again. This is a configuration file used to set metadata fields outside the vulnerabilities section.
In order to produce a valid CSAF document, certain sections are required. An overview is below, with required components in bold.
Where a top level category, such as note is not bolded, but one of its members is, that indicates the bolded are only required if the parent category is included, e.g. a note entry must include category and text, but a valid CSAF does not require that any notes be included.:
| TOML Field | Subcategories | Comments |
|---|---|---|
| document | category title |
default category is csaf*vex category must match regex: ^[^\s\-*\.](.\*[^\s\-_\.])?$ |
| publisher | name category namespace contact_details |
valid categories: coordinator, discoverer, other, translator, user, vendor e.g. an email address |
| note | category text audience title |
valid categories: description, details, faq, general, legal_disclaimer, other, summary multiple note entries may be included under additional [note] headings |
| reference | summary url category |
multiple reference entries may be included under additional [reference] headings valid categories: self, external |
| distribution | text tlp.label tlp.url |
If tlp is included, label is required valid labels: AMBER, GREEN, RED, WHITE |
| product_tree | easy_import | We support importing a product tree from a json file, the path of which should be specified here. If you do not provide this data, we will instead try to import the root component identified by the cdxgen sbom. If neither of these attempts succeeds, the product_tree will be omitted. example |
| tracking | current_release_date initial_release_date version status id |
Please use ISO date formats if entering dates yourself. valid statuses: draft, final, interim We will generate an id consisting of date and version if you do not include this, but id is best set by you |
| tracking.revision_history | date number summary |
Leave this section alone. Depscan will add revision entries per final version (see notes on tracking). |
| depscan_version | This field is automatically updated for our use to provide backward compatibility if the TOML options change |
Feel free to preserve all fields on the toml if you may want them later. Entries without content will be omitted.
Although tracking and all of its components are required, if you do not include them, we will use the current date/time and update the version as appropriate.
Currently we only handle versioning for documents with a status of final. This means your document may fail validation if you have not yet generated an initial final version - because we only add a revision history entry for final versions. Here's what OASIS has to say on the matter:
Each Revision item which has a number of 0 or 0.y.z MUST be removed from the document if the document status is final. Versions of the document which are pre-release SHALL NOT have its own revision item. All changes MUST be tracked in the item for the next release version. Build metadata SHOULD NOT be included in the number of any revision item.
Coming soon! For now, you can validate your generated CSAFs using a JSON schema validator and the csaf 2.0 schema.
If you're looking for a cli with this functionality, I've found check-jsonschema easy to use.
pip install check-jsonschema
python check-jsonschema --schemafile contrib/csaf_2.0_schema.json path_to_your_csaf_file
Feel free to reach out to us on discord or start a discussion tagging @cerrussell on the OWASP Dep-Scan Repo.