Editor revision for TC meeting 2024-08-28

csaf_2.1/examples/aggregator/example-01-aggregator.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://docs.oasis-open.org/csaf/csaf/v2.1/aggregator_json_schema.json",
   "aggregator": {
     "category": "lister",
     "contact_details": "Example CSAF Lister can be reached at contact_us@lister.example, or via our website at https://lister.example/security/csaf/aggregator/contact.",
@@ -33,4 +34,4 @@
     }
   ],
   "last_updated": "2024-01-24T22:35:38.978Z"
-}
+}

csaf_2.1/examples/aggregator/example-02-aggregator.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://docs.oasis-open.org/csaf/csaf/v2.1/aggregator_json_schema.json",
   "aggregator": {
     "category": "aggregator",
     "contact_details": "Example Aggregator can be reached at contact_us@aggregator.example, or via our website at https://aggregator.example/security/csaf/aggregator/contact.",
@@ -39,4 +40,4 @@
     }
   ],
   "last_updated": "2024-01-24T22:35:38.978Z"
-}
+}

csaf_2.1/examples/aggregator/example-03-aggregator.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://docs.oasis-open.org/csaf/csaf/v2.1/aggregator_json_schema.json",
   "aggregator": {
     "category": "aggregator",
     "contact_details": "Example Aggregator can be reached at contact_us@aggregator.example, or via our website at https://aggregator.example/security/csaf/aggregator/contact.",
@@ -56,4 +57,4 @@
     }
   ],
   "last_updated": "2024-01-24T22:35:38.978Z"
-}
+}

csaf_2.1/examples/provider-metadata/example-01-provider-metadata.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://docs.oasis-open.org/csaf/csaf/v2.1/provider_json_schema.json",
   "canonical_url": "https://www.example.com/.well-known/csaf/provider-metadata.json",
   "distributions": [
     {
@@ -29,4 +30,4 @@
     "namespace": "https://psirt.example.com"
   },
   "role": "csaf_trusted_provider"
-}
+}

csaf_2.1/json_schema/aggregator_json_schema.json

@@ -59,13 +59,23 @@
     }
   },
   "required": [
+    "$schema",
     "aggregator",
     "aggregator_version",
     "canonical_url",
     "csaf_providers",
     "last_updated"
   ],
   "properties": {
+    "$schema": {
+      "title": "JSON schema",
+      "description": "Contains the URL of the Aggregator JSON schema which the document promises to be valid for.",
+      "type": "string",
+      "enum": [
+        "https://docs.oasis-open.org/csaf/csaf/v2.1/aggregator_json_schema.json"
+      ],
+      "format": "uri"
+    },
     "aggregator": {
       "title": "Aggregator",
       "description": "Provides information about the aggregator.",

csaf_2.1/json_schema/provider_json_schema.json

@@ -27,6 +27,7 @@
     }
   },
   "required": [
+    "$schema",
     "canonical_url",
     "last_updated",
     "list_on_CSAF_aggregators",
@@ -36,6 +37,15 @@
     "role"
   ],
   "properties": {
+    "$schema": {
+      "title": "JSON schema",
+      "description": "Contains the URL of the provider-metadata.json JSON schema which the document promises to be valid for.",
+      "type": "string",
+      "enum": [
+        "https://docs.oasis-open.org/csaf/csaf/v2.1/provider_json_schema.json"
+      ],
+      "format": "uri"
+    },
     "canonical_url": {
       "title": "Canonical URL",
       "description": "Contains the URL for this document.",
@@ -53,10 +63,26 @@
         "type": "object",
         "minProperties": 1,
         "properties": {
-          "directory_url": {
-            "title": "Directory URL",
-            "description": "Contains the base url for the directory distribution.",
-            "$ref": "#/$defs/url_t"
+          "directory": {
+            "title": "Directory",
+            "description": "Contains all information for directory-based distribution.",
+            "type": "object",
+            "required": [
+              "tlp_label",
+              "url"
+            ],
+            "properties": {
+              "tlp_label": {
+                "title": "TLP label",
+                "description": "Provides the TLP label for the directory.",
+                "$ref": "https://docs.oasis-open.org/csaf/csaf/v2.1/csaf_json_schema.json#/properties/document/properties/distribution/properties/tlp/properties/label"
+              },
+              "url": {
+                "title": "Directory URL",
+                "description": "Contains the base url for the directory-based distribution.",
+                "$ref": "#/$defs/url_t"
+              }
+            }
           },
           "rolie": {
             "title": "ROLIE",
@@ -104,15 +130,7 @@
                     "tlp_label": {
                       "title": "TLP label",
                       "description": "Provides the TLP label for the feed.",
-                      "type": "string",
-                      "enum": [
-                        "UNLABELED",
-                        "CLEAR",
-                        "GREEN",
-                        "AMBER",
-                        "AMBER+STRICT",
-                        "RED"
-                      ]
+                      "$ref": "https://docs.oasis-open.org/csaf/csaf/v2.1/csaf_json_schema.json#/properties/document/properties/distribution/properties/tlp/properties/label"
                     },
                     "url": {
                       "title": "URL of the feed",

csaf_2.1/prose/edit/src/conformance.md

@@ -51,6 +51,10 @@ The entities ("conformance targets") for which this document defines requirement
 * **CSAF SBOM matching system**: A program that connects to or is an SBOM database and is able to manage CSAF documents as required
   by CSAF management system as well as matching them to SBOM components of the SBOM database.
 * **CSAF 2.0 to CSAF 2.1 converter**: A CSAF producer which takes a CSAF 2.0 document as input and converts it into a valid CSAF 2.1 document.
+* **CSAF library**: A library that implements CSAF data capabilities.
+* **CSAF library with basic validation**: A CSAF library that also satisfies the conformance target "CSAF basic validator".
+* **CSAF library with extended validation**: A CSAF library that also satisfies the conformance target "CSAF extended validator".
+* **CSAF library with full validation**: A CSAF library that also satisfies the conformance target "CSAF full validator".
 
 ### Conformance Clause 1: CSAF document
 
@@ -64,7 +68,7 @@ A text file or data stream satisfies the "CSAF document" conformance profile if
 
 A program satisfies the "CSAF producer" conformance profile if the program:
 
-* produces output in the CSAF format, according to the conformance profile "CSAF document" .
+* produces output in the CSAF format, according to the conformance profile "CSAF document".
 * satisfies those normative requirements in section [sec](#schema-elements) and [sec](#safety-security-and-data-protection-considerations) that
   are designated as applying to CSAF producers.
 
@@ -536,6 +540,8 @@ Secondly, the program fulfills the following for all items of:
 * `/document/publisher/category`: If the value is `other`, the CSAF 2.0 to CSAF 2.1 converter SHOULD output a warning that some parties have
   been regrouped into the new value `multiplier`. An option to suppress this warning MUST exist. In addition, an option SHOULD be provided to
   set the value to `multiplier`.
+* `/document/title`: If the value contains the `/document/tracking/id`, the CSAF 2.0 to CSAF 2.1 converter MUST remove the `/document/tracking/id`
+  from the `/document/title`. In addition, separating characters including but not limited to whitespace, colon, dash and brackets MUST be removed.
 * `/vulnerabilities[]/cwes[]`: The CSAF 2.0 to CSAF 2.1 converter MUST determine the CWE specification version the given CWE was selected from by
   using the latest version that matches the `id` and `name` exactly and was published prior to the value of `/document/tracking/current_release_date`
   of the source document. If no such version exist, the first matching version published after the value of `/document/tracking/current_release_date`
@@ -549,4 +555,76 @@ Secondly, the program fulfills the following for all items of:
 > A tool MAY implement an additional, non-default option to output an invalid document that can be fixed afterwards. Solely in this case, any
 > of the rules above MAY be ignored to avoid data loss.
 
+### Conformance Clause 19: CSAF library
+
+A library satisfies the "CSAF library" conformance profile if the library:
+
+* implements all elements as data structures conforming to the syntax and semantics defined in section [sec](#schema-elements).
+* checks all elements according to the patterns provided in the JSON schema.
+* has a function that checks version ranges.
+* has a function that helps to create version ranges.
+* provides for each element functions that allow to create, add, modify and delete that element.
+* has a function that reads a CSAF document into the data structure from a
+  * file system.
+  * URL.
+  * data stream.
+* provides function for sorting the keys and sorts the keys automatically on output.
+* has a function that outputs the data structure as CSAF document
+  * on the file system.
+  * as string.
+  * into a data stream.
+* has a function to determine the filename according to [sec](#filename) and sets the filename per default when saving a CSAF document.
+* generates a new `product_id` for each new element of type `full_product_name_t` unless an ID is given during the creation.
+* generates a new `group_id` for each new element of type `product_group_id_t` unless an ID is given during the creation.
+* provides a function to retrieve all elements of type `product_id_t` with its corresponding `full_product_name_t/name` and
+  `full_product_name_t/product_identification_helper`.
+* provides a function to retrieve all `product_identification_helper` and their mapping to elements of type `product_id_t`.
+* provides a function to retrieve a VEX status mapping for all data, which includes the combination of vulnerability, product, product status
+  and, where necessary according to the profile, the impact statement respectively the action statement.
+* provides a function to generate a `full_product_name_t/name` with in `branches` through concatenating the `name` values separated by whitespace
+  of the elements along the path towards this leaf.
+* calculates the CVSS scores and severities for existing data for all CVSS versions.
+* validates the CVSS scores and severities for existing data for all CVSS versions.
+
+> The library MAY implement an option to retrieve the keys unsorted.
+
+### Conformance Clause 20: CSAF library with basic validation
+
+A CSAF library satisfies the "CSAF library with basic validation" conformance profile if the CSAF library:
+
+* satisfies the "CSAF library" conformance profile.
+* satisfies the "CSAF basic validator" conformance profile.
+* validates the CSAF document before output according to the "CSAF basic validator" and presents the validation result accordingly.
+* provide a function to validate the data structure in its current state according to the "CSAF basic validator" and presents the validation
+  result accordingly.
+
+A CSAF library does not satisfies the "CSAF library with basic validation" conformance profile if the CSAF library uses an external library or
+program for the "CSAF basic validator" part and does not enforce its presence.
+
+### Conformance Clause 21: CSAF library with extended validation
+
+A CSAF library satisfies the "CSAF library with extended validation" conformance profile if the CSAF library:
+
+* satisfies the "CSAF library" conformance profile.
+* satisfies the "CSAF extended validator" conformance profile.
+* validates the CSAF document before output according to the "CSAF extended validator" and presents the validation result accordingly.
+* provide a function to validate the data structure in its current state according to the "CSAF extended validator" and presents the validation
+  result accordingly.
+
+A CSAF library does not satisfies the "CSAF library with extended validation" conformance profile if the CSAF library uses an external library or
+program for the "CSAF extended validator" part and does not enforce its presence.
+
+### Conformance Clause 22: CSAF library with full validation
+
+A CSAF library satisfies the "CSAF library with extended validation" conformance profile if the CSAF library:
+
+* satisfies the "CSAF library" conformance profile.
+* satisfies the "CSAF full validator" conformance profile.
+* validates the CSAF document before output according to the "CSAF full validator" and presents the validation result accordingly.
+* provide a function to validate the data structure in its current state according to the "CSAF full validator" and presents the validation
+  result accordingly.
+
+A CSAF library does not satisfies the "CSAF library with full validation" conformance profile if the CSAF library uses an external library or
+program for the "CSAF full validator" part and does not enforce its presence.
+
 -------

csaf_2.1/prose/edit/src/frontmatter.md

@@ -7,7 +7,7 @@
 
 ## Committee Specification Draft 01
 
-## 31 July 2024
+## 28 August 2024
 
 #### This stage:
 https://docs.oasis-open.org/csaf/csaf/v2.1/csd01/csaf-v2.1-csd01.md (Authoritative) \
@@ -71,7 +71,7 @@ When referencing this specification the following citation format should be used
 
 **[csaf-v2.1]**
 
-_Common Security Advisory Framework Version 2.1_. Edited by Stefan Hagen, and Thomas Schmidt. 31 July 2024. OASIS Committee Specification Draft 01. https://docs.oasis-open.org/csaf/csaf/v2.1/csd01/csaf-v2.1-csd01.html. Latest stage: https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html.
+_Common Security Advisory Framework Version 2.1_. Edited by Stefan Hagen, and Thomas Schmidt. 28 August 2024. OASIS Committee Specification Draft 01. https://docs.oasis-open.org/csaf/csaf/v2.1/csd01/csaf-v2.1-csd01.html. Latest stage: https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html.
 
 
 -------

csaf_2.1/prose/edit/src/introduction-02-terminology-glossary.md

@@ -53,6 +53,18 @@ CSAF extended validator
 CSAF full validator
 :    A CSAF extended validator that additionally performs informative tests.
 
+CSAF library
+:    A library that implements CSAF data capabilities.
+
+CSAF library with basic validation
+:    A CSAF library that also satisfies the conformance target "CSAF basic validator".
+
+CSAF library with extended validation
+:    A CSAF library that also satisfies the conformance target "CSAF extended validator".
+
+CSAF library with full validation
+:    A CSAF library that also satisfies the conformance target "CSAF full validator".
+
 CSAF management system
 :    program that is able to manage CSAF documents and is able to display their details as required by CSAF viewer.
 

csaf_2.1/prose/edit/src/revision-history.md

@@ -17,4 +17,5 @@ toc:
 | csaf-v2.0-wd20240529-dev | 2024-05-29 | Stefan Hagen and Thomas Schmidt | Next Editor Revision |
 | csaf-v2.0-wd20240626-dev | 2024-06-26 | Stefan Hagen and Thomas Schmidt | Next Editor Revision |
 | csaf-v2.0-wd20240731-dev | 2024-07-31 | Stefan Hagen and Thomas Schmidt | Next Editor Revision |
+| csaf-v2.0-wd20240828-dev | 2024-08-28 | Stefan Hagen and Thomas Schmidt | Next Editor Revision |
 -------

csaf_2.1/prose/edit/src/safety-security-and-data-protection.md

@@ -18,9 +18,12 @@ Thus, for security reasons, CSAF producers and consumers SHALL adhere to the fol
 * Deeply nested markup can cause a stack overflow in the Markdown processor [cite](#GFMENG).
   To reduce this risk, CSAF consumers SHALL use a Markdown processor that is hardened against such attacks.
   **Note**: One example is the GitHub fork of the `cmark` Markdown processor [cite](#GFMCMARK).
-* To reduce the risk posed by possibly malicious CSAF files that do contain arbitrary HTML (including, for example, javascript: links),
-  CSAF consumers SHALL either disable HTML processing (for example, by using an option such as the --safe option in the cmark Markdown processor)
+* To reduce the risk posed by possibly malicious CSAF files that do contain arbitrary HTML (including, for example, `data:image/svg+xml`),
+  CSAF consumers SHALL either disable HTML processing (for example, by using the `--safe` option in the `cmark` Markdown processor)
   or run the resulting HTML through an HTML sanitizer.
+* To reduce the risk posed by possibly malicious links within a CSAF document (including, for example, `javascript:` links),
+  CSAF consumers SHALL either remove all actions from links (for example, by displaying them as standard text)
+or render only those actionable that are known to be safe (for example, determining that via the media type).
 CSAF consumers that are not prepared to deal with the security implications of formatted messages SHALL NOT attempt to
 render them and SHALL instead fall back to the corresponding plain text messages. As also any other programming code can
 be contained within a CSAF document, CSAF consumers SHALL ensure that none of the values of a CSAF document is run as code.

csaf_2.1/prose/edit/src/tests-02-optional.md

@@ -679,3 +679,29 @@ The relevant path for this test is:
 ```
 
 > The first and second revision have the same timestamp.
+
+### Document Tracking ID in Title
+
+It MUST be tested that the `/document/title` does not contain the `/document/tracking/id`.
+
+The relevant path for this test is:
+
+```
+  /document/title
+```
+
+*Example 1 (which fails the test):*
+
+```
+    "title": "OASIS_CSAF_TC-CSAF_2.1-2024-6-2-22-01: Optional test: Document Tracking ID in Title (failing example 1)",
+    "tracking": {
+      // ...
+      "id": "OASIS_CSAF_TC-CSAF_2.1-2024-6-2-22-01",
+      // ...
+    }
+```
+
+> The document title contains the document tracking id.
+
+> A tool MAY remove the document tracking id from the document title.
+> It SHOULD also remove any separating characters including whitespace, colon, dash and brackets.

csaf_2.1/test/validator/data/optional/oasis_csaf_tc-csaf_2_1-2024-6-2-22-01.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://docs.oasis-open.org/csaf/csaf/v2.1/csaf_json_schema.json",
+  "document": {
+    "category": "csaf_base",
+    "csaf_version": "2.1",
+    "distribution": {
+      "tlp": {
+        "label": "CLEAR"
+      }
+    },
+    "publisher": {
+      "category": "other",
+      "name": "OASIS CSAF TC",
+      "namespace": "https://csaf.io"
+    },
+    "title": "OASIS_CSAF_TC-CSAF_2.1-2024-6-2-22-01: Optional test: Document Tracking ID in Title (failing example 1)",
+    "tracking": {
+      "current_release_date": "2024-01-21T10:00:00.000Z",
+      "id": "OASIS_CSAF_TC-CSAF_2.1-2024-6-2-22-01",
+      "initial_release_date": "2024-01-21T10:00:00.000Z",
+      "revision_history": [
+        {
+          "date": "2024-01-21T10:00:00.000Z",
+          "number": "1",
+          "summary": "Initial version."
+        }
+      ],
+      "status": "final",
+      "version": "1"
+    }
+  }
+}