Hardware and Software

csaf_2.1/prose/edit/src/additional-conventions.md

@@ -79,4 +79,131 @@ The `/product_tree` uses a nested structure for `branches`. Along a single path
 /product_tree/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/branches[]/product
 ```
 
+## Hardware and Software within the Product Tree
+
+If a product consists of hardware and software, the hardware part MUST be presented as one product in the product tree and the software part as another one.
+To form the overall product, both parts MUST be combined through a relationship.
+
+*Examples 1:*
+
+```
+  "product_tree": {
+    "branches": [
+      {
+        "branches": [
+          {
+            "branches": [
+              {
+                "category": "product_version",
+                "name": "1.0",
+                "product": {
+                  "name": "Example Company Controller A 1.0",
+                  "product_id": "CSAFPID-908070601",
+                  "product_identification_helper": {
+                    "serial_numbers": [
+                      "143-D-354"
+                    ]
+                  }
+                }
+              }
+            ],
+            "category": "product_name",
+            "name": "Controller A"
+          },
+          {
+            "branches": [
+              {
+                "category": "product_version",
+                "name": "4.1",
+                "product": {
+                  "name": "Example Company Controller A Firmware 4.1",
+                  "product_id": "CSAFPID-908070602",
+                  "product_identification_helper": {
+                    "hashes": [
+                      {
+                        "file_hashes": [
+                          {
+                            "algorithm": "sha256",
+                            "value": "3fb9d502d096b1dfbcdfe60eed80ddecd98c8771bf21a82bbe1752735c4dc9e2"
+                          }
+                        ],
+                        "filename": "a_4-1.bin"
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "category": "product_version",
+                "name": "4.2",
+                "product": {
+                  "name": "Example Company Controller A Firmware 4.2",
+                  "product_id": "CSAFPID-908070603",
+                  "product_identification_helper": {
+                    "hashes": [
+                      {
+                        "file_hashes": [
+                          {
+                            "algorithm": "sha256",
+                            "value": "0a853ce2337f0608489ac596a308dc5b7b19d35a52b10bf31261586ac368b175"
+                          }
+                        ],
+                        "filename": "a_4-2.bin"
+                      }
+                    ]
+                  }
+                }
+              }
+            ],
+            "category": "product_name",
+            "name": "Controller A Firmware"
+          }
+        ],
+        "category": "vendor",
+        "name": "Example Company"
+      }
+    ],
+    "relationships": [
+      {
+        "category": "installed_on",
+        "full_product_name": {
+          "name": "Example Company Controller A Firmware 4.1 installed on Example Company Controller A 1.0",
+          "product_id": "CSAFPID-908070604"
+        },
+        "product_reference": "CSAFPID-908070602",
+        "relates_to_product_reference": "CSAFPID-908070601"
+      },
+      {
+        "category": "installed_on",
+        "full_product_name": {
+          "name": "Example Company Controller A Firmware 4.2 installed on Example Company Controller A 1.0",
+          "product_id": "CSAFPID-908070605"
+        },
+        "product_reference": "CSAFPID-908070603",
+        "relates_to_product_reference": "CSAFPID-908070601"
+      }
+    ]
+  }
+```
+
+> This requirement is important to allow for correct matching.
+> The serial number `143-D-354` identifies the `Example Company Controller A 1.0` which is in this example the hardware in its version 1.0.
+> The hash `3fb9d502d096b1dfbcdfe60eed80ddecd98c8771bf21a82bbe1752735c4dc9e2` identifies the software in the version 4.1;
+> the hash `0a853ce2337f0608489ac596a308dc5b7b19d35a52b10bf31261586ac368b175` identifies the software in the version 4.2.
+> The relationships combine the software and hardware part and form new products.
+> These are used e.g. to assign the product status in the vulnerability section.
+>
+> A matching tool searches in a first step for the product identification helper, e.g the serial number in an asset database to identify
+> the asset that has this specific hardware and matches the software separately in a second step.
+>
+> Representing the software version as a child element under elements representing hardware unsettles the consumer whether the version
+> applies to the software or hardware.
+> Also, this would violate the rule regarding the full identification of a product by the `product_identification_helper` from section
+> [sec](#full-product-name-type-product-identification-helper).
+>
+> Based on the CVE statistics up to and including the year 2024, in the majority of cases the vulnerabilities reside in software or
+> are remediated via software.
+> Having multiple products with the same `product_identification_helper` in different `product_status` for the same vulnerability
+> would make it undecidable for machines what the `product_status` actually is.
+
 -------

csaf_2.1/prose/edit/src/schema-elements-01-defs-03-full-product-name.md

@@ -76,6 +76,13 @@ and `x_generic_uris`, one is mandatory.
     }
 ```
 
+A helper to identify the product SHALL identify the product described by the `name` in its entirety.
+A matching algorithm has to be able to rely on the `product_identification_helper` information during the matching without having to
+check e.g. the branches hierarchy leading to the product.
+
+> Therefore, it is, for example, prohibited to omit the version from the CPE if a `product_version` was given in branches hierarchy
+> leading to the product.
+
 ##### Full Product Name Type - Product Identification Helper - CPE
 
 Common Platform Enumeration representation (`cpe`) of value type `string` of 5 or more characters with `pattern` (regular expression):

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

@@ -919,3 +919,122 @@ The relevant path for this test is:
 > The CSAF document is `TLP:CLEAR` but a sharing group is given.
 
 > A tool MAY remove the property `sharing_group` as a quick fix.
+
+### Hardware and Software
+
+For each product containing at least one of the Product Identification Helpers `serial_numbers` or `model_numbers` it MUST be tested that a relationship exists referencing this product.
+
+> This tests detects a potential situation where hardware and software have been mixed in the `product_tree`.
+> Note: This test will fail if the CSAF document contains in its `product_tree` only hardware.
+> However, this is expected and considered a good reason for the test to fail.
+> This does not make the CSAF document invalid.
+
+The relevant paths for this test are:
+
+```
+  /product_tree/branches[](/branches[])*/product/product_id
+  /product_tree/full_product_names[]/product_id
+  /product_tree/relationships[]/full_product_name/product_id
+```
+
+*Example 1 (which fails the test):*
+
+```
+  "product_tree": {
+    "branches": [
+      {
+        "branches": [
+          {
+            "branches": [
+              {
+                "category": "product_version",
+                "name": "4.1",
+                "product": {
+                  "name": "Example Company Controller A Firmware 4.1",
+                  "product_id": "CSAFPID-908070601",
+                  "product_identification_helper": {
+                    "serial_numbers": [
+                      "143-D-354"
+                    ]
+                  }
+                }
+              }
+            ],
+            "category": "product_name",
+            "name": "Controller A"
+          }
+        ],
+        "category": "vendor",
+        "name": "Example Company"
+      }
+    ]
+  }
+```
+
+> The `product_tree` mentions the hardware product Example Company Controller A and combines it with the Firmware version 4.1.
+
+### Use of same Product Identification Helper for different Products
+
+For each Product Identification Helper category it MUST be tested that the same value is not used for multiple products in this category.
+
+> This test detects a potentially incorrect constructed product tree.
+> Note: This test will fail if the CSAF document contains in its `product_tree` the old and new name of a product that was renamed.
+> However, this is expected and considered a good reason for the test to fail.
+> This does not make the CSAF document invalid.
+
+The relevant paths for this test are:
+
+```
+  /product_tree/branches[](/branches[])*/product/product_identification_helper
+  /product_tree/full_product_names[]/product_id/product_identification_helper
+  /product_tree/relationships[]/full_product_name/product_id/product_identification_helper
+```
+
+*Example 1 (which fails the test):*
+
+```
+  "product_tree": {
+    "branches": [
+      {
+        "branches": [
+          {
+            "branches": [
+              {
+                "category": "product_version",
+                "name": "1.0",
+                "product": {
+                  "name": "Example Company Product A 1.0",
+                  "product_id": "CSAFPID-908070601",
+                  "product_identification_helper": {
+                    "serial_numbers": [
+                      "143-D-354"
+                    ]
+                  }
+                }
+              },
+              {
+                "category": "product_version",
+                "name": "2.0",
+                "product": {
+                  "name": "Example Company Product A 2.0",
+                  "product_id": "CSAFPID-908070602",
+                  "product_identification_helper": {
+                    "serial_numbers": [
+                      "143-D-354"
+                    ]
+                  }
+                }
+              }
+            ],
+            "category": "product_name",
+            "name": "Product A"
+          }
+        ],
+        "category": "vendor",
+        "name": "Example Company"
+      }
+    ]
+  }
+```
+
+> Both products are identified by the same serial number `143-D-354`.

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

@@ -0,0 +1,61 @@
+{
+  "$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": "Optional test: Hardware and Software (failing example 1)",
+    "tracking": {
+      "current_release_date": "2024-01-24T10:00:00.000Z",
+      "id": "OASIS_CSAF_TC-CSAF_2.1-2024-6-2-31-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": {
+    "branches": [
+      {
+        "branches": [
+          {
+            "branches": [
+              {
+                "category": "product_version",
+                "name": "4.1",
+                "product": {
+                  "name": "Example Company Controller A Firmware 4.1",
+                  "product_id": "CSAFPID-908070601",
+                  "product_identification_helper": {
+                    "serial_numbers": [
+                      "143-D-354"
+                    ]
+                  }
+                }
+              }
+            ],
+            "category": "product_name",
+            "name": "Controller A"
+          }
+        ],
+        "category": "vendor",
+        "name": "Example Company"
+      }
+    ]
+  }
+}