Merge pull request #807 from tschmidtb51/remediation-categories

Remediation categories

csaf_2.1/json_schema/csaf_json_schema.json

@@ -1335,9 +1335,11 @@
                   "description": "Specifies the category which this remediation belongs to.",
                   "type": "string",
                   "enum": [
+                    "fix_planned",
                     "mitigation",
                     "no_fix_planned",
                     "none_available",
+                    "optional_patch",
                     "vendor_fix",
                     "workaround"
                   ]

csaf_2.1/prose/edit/etc/bind.txt

@@ -63,6 +63,9 @@ tests-01-mndtr-30-mixed-integer-and-semantic-versioning.md
 tests-01-mndtr-31-version-range-in-product-version.md
 tests-01-mndtr-32-flag-without-product-reference.md
 tests-01-mndtr-33-multiple-flags-with-vex-justification-codes-per-product.md
+tests-01-mndtr-34-branches-recursion-depth.md
+tests-01-mndtr-35-contradicting-remediations.md
+tests-01-mndtr-36-contradicting-product-status-remediation-combination.md
 tests-02-optional.md
 tests-03-informative.md
 distributing.md

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

@@ -144,10 +144,26 @@ Secondly, the program fulfills the following for all items of:
   * If a `vuln:CWE` instance refers to a CWE category or view, the CVRF CSAF converter MUST omit this instance and output a
     warning that this CWE has been removed as its usage is not allowed in vulnerability mappings.
 * `/vulnerabilities[]/ids`: If a `vuln:ID` element is given, the CVRF CSAF converter converts it into the first item of the `ids` array.
-* `/vulnerabilities[]/remediation[]`: If no `product_ids` or `group_ids` is given,
-  the CVRF CSAF converter appends all Product IDs which are listed under `../product_status` in the arrays `known_affected`,
-  `first_affected` and `last_affected` into `product_ids`.
-  If none of these arrays exist, the CVRF CSAF converter outputs an error that no matching Product ID was found for this remediation element.
+* `/vulnerabilities[]/remediations[]`:
+  * If neither `product_ids` nor `group_ids` are given, the CVRF CSAF converter appends all Product IDs which are listed under
+    `../product_status` in the arrays `known_affected`, `first_affected` and `last_affected` into `product_ids`.
+    If none of these arrays exist, the CVRF CSAF converter outputs an error that no matching Product ID was found for this remediation element.
+  * The CVRF CSAF converter MUST convert any remediation with the type `Vendor Fix` into the category `optional_patch` if the product in
+    question is in one of the product status groups "Not Affected" or "Fixed" for this vulnerability.
+    Otherwise, the category `vendor_fix` MUST be set.
+    If multiple products are associated with the remediation - either directly or through a product group - and the products belong to
+    different product status groups, the CVRF CSAF converter MUST duplicate the remediation, change the category in one instance
+    to `optional_patch` and distribute the products accordingly as stated by the conversion rule.
+  * The CVRF CSAF converter MUST convert any remediation with the type `None Available` into the category `fix_planned`
+    if the product in question is also listed in a remediation of the type `Vendor Fix` with a `Date` in the future or no `Date` at all.
+    Consequently, the product MUST be removed from the remediation of the category `vendor_fix`.
+    If it was the last product in that remediation, the remediation MUST be removed.
+  * The CVRF CSAF converter MUST remove any product from a remediation with the type `None Available`
+    if the product in question is also listed in a remediation of the type `Vendor Fix` with a `Date` in the past or to the exact same time.
+    If it was the last product in that remediation, the remediation MUST be removed.
+  * In any other case, the CVRF CSAF converter MUST preserve the product in the remediation of the category `none_available`.
+  * The CVRF CSAF converter MUST output a warning if a remediation was added, deleted or the value of the category was changed,
+    including the products it was changed for.
 * `/vulnerabilities[]/metrics[]`:
   * For any CVSS v4 element, the CVRF CSAF converter MUST compute the `baseSeverity` from the `baseScore` according to
     the rules of the applicable CVSS standard. (CSAF CVRF v1.2 predates CVSS v4.0.)
@@ -534,7 +550,7 @@ Secondly, the program fulfills the following for all items of:
   option to use this label instead. If the TLP label changes through such conversion in a way that is not reflected in the table above, the
   the CSAF 2.0 to CSAF 2.1 converter MUST output a warning that the TLP label was taken from the distribution text. Such a warning MUST include
   both values: the converted one based on the table and the one from the distribution text.
-  > This is a common case for CSAF 2.0 documents labeled as TLP:RED but actually intended to be TLP:AMBER+STRICT.
+  > This is a common case for CSAF 2.0 documents labeled as `TLP:RED` but actually intended to be `TLP:AMBER+STRICT`.
 
   If no TLP label was given, the CSAF 2.0 to CSAF 2.1 converter SHOULD assign `TLP:CLEAR` and output a warning that the default TLP has been set.
 * `/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
@@ -550,6 +566,24 @@ Secondly, the program fulfills the following for all items of:
 
   The tool SHOULD implement an option to use the latest available CWE version at the time of the conversion that still matches.
 
+* `/vulnerabilities[]/remediations[]`:
+  * The CSAF 2.0 to CSAF 2.1 converter MUST convert any remediation with the category `vendor_fix` into the category `optional_patch`
+    if the product in question is in one of the product status groups "Not Affected" or "Fixed" for this vulnerability.
+    Otherwise, the category `vendor_fix` MUST stay the same.
+    If multiple products are associated with the remediation - either directly or through a product group - and the products belong to different
+    product status groups, the CSAF 2.0 to CSAF 2.1 converter MUST duplicate the remediation, change the category in one instance to `optional_patch`
+    and distribute the products accordingly as stated by the conversion rule.
+  * The CSAF 2.0 to CSAF 2.1 converter MUST convert any remediation with the category `none_available` into the category `fix_planned`
+    if the product in question is also listed in a remediation of the category `vendor_fix` with a `date` in the future or no `date` at all.
+    Consequently, the product MUST be removed from the remediation of the category `vendor_fix`.
+    If it was the last product in that remediation, the remediation MUST be removed.
+  * The CSAF 2.0 to CSAF 2.1 converter MUST remove any product from a remediation with the category `none_available`
+    if the product in question is also listed in a remediation of the category `vendor_fix` with a `date` in the past or to the exact same time.
+    If it was the last product in that remediation, the remediation MUST be removed.
+  * In any other case, the CSAF 2.0 to CSAF 2.1 converter MUST preserve the product in the remediation of the category `none_available`.
+  * The CSAF 2.0 to CSAF 2.1 converter MUST output a warning if a remediation was added, deleted or the value of the category was changed,
+    including the products it was changed for.
+
 > A tool MAY implement options to convert other Markdown formats to GitHub-flavored Markdown.
 
 > A tool MAY implement an additional, non-default option to output an invalid document that can be fixed afterwards. Solely in this case, any

csaf_2.1/prose/edit/src/schema-elements-02-props-04-vulnerabilities.md

@@ -630,9 +630,11 @@ Category of the remediation (`category`) of value type `string` and `enum` speci
 Valid values are:
 
 ```
+    fix_planned
     mitigation
     no_fix_planned
     none_available
+    optional_patch
     vendor_fix
     workaround
 ```
@@ -650,20 +652,56 @@ and they MAY or MAY NOT be officially sanctioned by the document producer.
 The value `vendor_fix` indicates that the remediation contains information about an official fix that
 is issued by the original author of the affected product.
 Unless otherwise noted, it is assumed that this fix fully resolves the vulnerability.
-This value contradicts with the categories `none_available` and `no_fix_planned` for the same product.
-Therefore, such a combination can't be used in the list of remediations.
+
+The value `optional_patch` indicates that the remediation contains information about an patch that
+is issued by the original author of the affected product.
+Its application is not necessary, but might be desired by the user, e.g. to calm a security scanner by
+updating a dependency to a fixed version even though the dependency in the affected version was used
+in the product in a way that the product itself was not affected.
+Unless otherwise noted, it is assumed that this does not change the state regarding the vulnerability.
+
+> This is sometimes also referred to as a "regulatory compliance patch".
 
 The value `none_available` indicates that there is currently no fix or other remediation available.
 The text in field `details` SHOULD contain details about why there is no fix or other remediation.
-The values `none_available` and `vendor_fix` are mutually exclusive per product.
 
-> An issuing party might choose to use this category to announce that a fix is currently developed.
-It is recommended that this also includes a date when a customer can expect the fix to be ready and distributed.  
+The value `fix_planned` indicates that there is a fix for the vulnerability planned but not yet ready.
+An issuing party might choose to use this category to announce that a fix is currently developed.
+The text in field `details` SHOULD contain details including a date when a customer can expect the fix to be ready and distributed.
 
 The value `no_fix_planned` indicates that there is no fix for the vulnerability and it is not planned to provide one at any time.
 This is often the case when a product has been orphaned, declared end-of-life, or otherwise deprecated.
 The text in field `details` SHOULD contain details about why there will be no fix issued.
-The values `no_fix_planned` and `vendor_fix` are mutually exclusive per product.
+
+Some category values contradict each other and thus are mutually exclusive per product.
+Therefore, such a combination MUST NOT be used in the list of remediations for the same product.
+This is independent from whether the product is referenced directly or indirectly through a product group.
+The following tables shows the allowed and prohibited combinations:
+
+| category value   | `workaround` | `mitigation` | `vendor_fix` | `optional_patch` | `none_available` | `fix_planned` | `no_fix_planned` |
+|:----------------:|:------------:|:------------:|:------------:|:----------------:|:----------------:|:-------------:|:----------------:|
+| `workaround`     | allowed      | allowed      | allowed      | prohibited       | prohibited       | allowed       | allowed          |
+| `mitigation`     | allowed      | allowed      | allowed      | prohibited       | prohibited       | allowed       | allowed          |
+| `vendor_fix`     | allowed      | allowed      | allowed      | prohibited       | prohibited       | prohibited    | prohibited       |
+| `optional_patch` | prohibited   | prohibited   | prohibited   | allowed          | prohibited       | prohibited    | prohibited       |
+| `none_available` | prohibited   | prohibited   | prohibited   | prohibited       | allowed          | prohibited    | prohibited       |
+| `fix_planned`    | allowed      | allowed      | prohibited   | prohibited       | prohibited       | allowed       | prohibited       |
+| `no_fix_planned` | allowed      | allowed      | prohibited   | prohibited       | prohibited       | prohibited    | allowed          |
+
+Some category values contradict certain product status groups.
+Therefore, such a combination MUST NOT exist in a vulnerability item for the same product.
+This is independent from whether the product is referenced directly or indirectly through a product group.
+The following tables shows the allowed, discouraged and prohibited combinations:
+
+| category value   | Affected   | Not Affected | Fixed       | Under Investigation | Recommended |
+|:----------------:|:----------:|:------------:|:-----------:|:-------------------:|:-----------:|
+| `workaround`     | allowed    | prohibited   | prohibited  | discouraged         | allowed     |
+| `mitigation`     | allowed    | prohibited   | prohibited  | discouraged         | allowed     |
+| `vendor_fix`     | allowed    | prohibited   | prohibited  | discouraged         | allowed     |
+| `optional_patch` | prohibited | allowed      | discouraged | allowed             | allowed     |
+| `none_available` | allowed    | prohibited   | prohibited  | allowed             | allowed     |
+| `fix_planned`    | allowed    | discouraged  | prohibited  | discouraged         | allowed     |
+| `no_fix_planned` | allowed    | discouraged  | prohibited  | allowed             | allowed     |
 
 ##### Vulnerabilities Property - Remediations - Date
 

csaf_2.1/prose/edit/src/tests-01-mndtr-35-contradicting-remediations.md

@@ -0,0 +1,38 @@
+### Contradicting Remediations
+
+For each item in `/vulnerabilities[]/remediations` it MUST be tested that a product is not member of contradicting remediation categories.
+This takes indirect relations through product groups into account.
+
+The relevant path for this test is:
+
+```
+  /vulnerabilities[]/remediations[]
+```
+
+*Example 1 (which fails the test):*
+
+```
+      "remediations": [
+        {
+          "category": "no_fix_planned",
+          "details": "The product is end-of-life. Therefore, no fix will be provided.",
+          "product_ids": [
+            "CSAFPID-9080700"
+          ]
+        },
+        {
+          "category": "vendor_fix",
+          "details": "Update to version >=14.3 to fix the vulnerability.",
+          "product_ids": [
+            "CSAFPID-9080700"
+          ]
+        }
+      ]
+```
+
+> The two remediations given for the product with product ID `CSAFPID-908070` contradict each other.
+
+> A tool MAY apply the conversion rules from the conformance target CSAF 2.0 to CSAF 2.1 converter if applicable or
+> remove the product from the remediation with the lower priority.
+> The priority MAY be defined as follows:
+> `vendor_fix` > `mitigation` > `workaround` > `fix_planned` > `no_fix_planned` > `optional_patch` > `none_available`

csaf_2.1/prose/edit/src/tests-01-mndtr-36-contradicting-product-status-remediation-combination.md

@@ -0,0 +1,31 @@
+### Contradicting Product Status Remediation Combination
+
+For each item in `/vulnerabilities[]/remediations` it MUST be tested that a product is not member of a contradicting product status group.
+This takes indirect relations through product groups into account.
+
+The relevant path for this test is:
+
+```
+  /vulnerabilities[]/remediations[]
+```
+
+*Example 1 (which fails the test):*
+
+```
+      "product_status": {
+        "known_not_affected": [
+          "CSAFPID-9080700"
+        ]
+      },
+      "remediations": [
+        {
+          "category": "vendor_fix",
+          "details": "Update to version >=14.3 to fix the vulnerability.",
+          "product_ids": [
+            "CSAFPID-9080700"
+          ]
+        }
+      ]
+```
+
+> For the product with product ID `CSAFPID-908070` a `vendor_fix` is given but the product was not affected at all.

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

@@ -806,3 +806,36 @@ The relevant path for this test is:
 ```
 
 > The usage of CWE-1023 is allowed with review as the "CWE entry is a Class and might have Base-level children that would be more appropriate". [cite](https://cwe.mitre.org/data/definitions/1023.html#Vulnerability_Mapping_Notes_1023)
+
+### Discouraged Product Status Remediation Combination
+
+For each item in `/vulnerabilities[]/remediations` it MUST be tested that a Product is not member of a discouraged product status group
+remediation category combination.
+This takes indirect relations through Product Groups into account.
+
+The relevant path for this test is:
+
+```
+  /vulnerabilities[]/remediations[]
+```
+
+*Example 1 (which fails the test):*
+
+```
+      "product_status": {
+        "known_not_affected": [
+          "CSAFPID-9080700"
+        ]
+      },
+      "remediations": [
+        {
+          "category": "fix_planned",
+          "details": "The fix should be available in Q4 2024.",
+          "product_ids": [
+            "CSAFPID-9080700"
+          ]
+        }
+      ]
+```
+
+> For the product with product ID `CSAFPID-908070` a fix is planned but the product was not affected at all.

csaf_2.1/test/validator/data/mandatory/oasis_csaf_tc-csaf_2_1-2024-6-1-35-01.json

@@ -0,0 +1,65 @@
+{
+  "$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": "Mandatory test: Contradicting Remediations (failing example 1)",
+    "tracking": {
+      "current_release_date": "2024-01-24T10:00:00.000Z",
+      "id": "OASIS_CSAF_TC-CSAF_2.1-2024-6-1-35-01",
+      "initial_release_date": "2024-01-24T10:00:00.000Z",
+      "revision_history": [
+        {
+          "date": "2024-01-24T10:00:00.000Z",
+          "number": "1",
+          "summary": "Initial version."
+        }
+      ],
+      "status": "final",
+      "version": "1"
+    }
+  },
+  "product_tree": {
+    "full_product_names": [
+      {
+        "product_id": "CSAFPID-9080700",
+        "name": "Product A"
+      }
+    ]
+  },
+  "vulnerabilities": [
+    {
+      "product_status": {
+        "known_affected": [
+          "CSAFPID-9080700"
+        ]
+      },
+      "remediations": [
+        {
+          "category": "no_fix_planned",
+          "details": "The product is end-of-life. Therefore, no fix will be provided.",
+          "product_ids": [
+            "CSAFPID-9080700"
+          ]
+        },
+        {
+          "category": "vendor_fix",
+          "details": "Update to version >=14.3 to fix the vulnerability.",
+          "product_ids": [
+            "CSAFPID-9080700"
+          ]
+        }
+      ]
+    }
+  ]
+}