Skip to content

Commit

Permalink
Merge pull request #857 from tschmidtb51/hardware-software
Browse files Browse the repository at this point in the history 
Hardware and Software
  • Loading branch information
@tschmidtb51
tschmidtb51 authored Jan 29, 2025
2 parents 9394660 + fbcbfb8 commit 119cc42
Show file tree
Hide file tree
Showing 14 changed files with 1,094 additions and 1 deletion.
127 changes: 127 additions & 0 deletions csaf_2.1/prose/edit/src/additional-conventions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
-------
7 changes: 7 additions & 0 deletions csaf_2.1/prose/edit/src/schema-elements-01-defs-03-full-product-name.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
119 changes: 119 additions & 0 deletions csaf_2.1/prose/edit/src/tests-02-optional.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
61 changes: 61 additions & 0 deletions csaf_2.1/test/validator/data/optional/oasis_csaf_tc-csaf_2_1-2024-6-2-31-01.json
View file
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
}
Loading

0 comments on commit 119cc42

Please sign in to comment.