Skip to content

Commit

Permalink
Support multiple purl identifiers in product_identification_helper
Browse files Browse the repository at this point in the history 
This allows a vendor to specify multiple purl identifiers for a single
component (present as a product version branch in the product tree).
Multiple purls may identify the same component but point to different
locations from where that component may be available. Thus, it is mandatory
that if multiple purls are present in a single
product_identification_helper object, they must only differ in their
qualifiers. Otherwise they should be set up as different product
tree branches.
  • Loading branch information
@mprpic
mprpic committed Oct 29, 2024
1 parent 395fbfe commit f6e7b8c
Show file tree
Hide file tree
Showing 6 changed files with 72 additions and 36 deletions.
20 changes: 13 additions & 7 deletions csaf_2.1/json_schema/csaf_json_schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -247,13 +247,19 @@
"minLength": 1
}
},
"purl": {
"title": "package URL representation",
"description": "The package URL (purl) attribute refers to a method for reliably identifying and locating software packages external to this specification.",
"type": "string",
"format": "uri",
"pattern": "^pkg:[A-Za-z\\.\\-\\+][A-Za-z0-9\\.\\-\\+]*\\/.+",
"minLength": 7
"purls": {
"title": "List of package URLs",
"description": "Contains a list of package URLs (purl).",
"type": "array",
"minItems": 1,
"items": {
"title": "package URL representation",
"description": "The package URL (purl) attribute refers to a method for reliably identifying and locating software packages external to this specification.",
"type": "string",
"format": "uri",
"pattern": "^pkg:[A-Za-z\\.\\-\\+][A-Za-z0-9\\.\\-\\+]*/.+",
"minLength": 7
}
},
"sbom_urls": {
"title": "List of SBOM URLs",
Expand Down
2 changes: 1 addition & 1 deletion csaf_2.1/prose/edit/etc/section-display-to-label.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
"3.1.3.3.1": "full-product-name-type-product-identification-helper-cpe",
"3.1.3.3.2": "full-product-name-type-product-identification-helper-hashes",
"3.1.3.3.3": "full-product-name-type-product-identification-helper-model-numbers",
"3.1.3.3.4": "full-product-name-type-product-identification-helper-purl",
"3.1.3.3.4": "full-product-name-type-product-identification-helper-purls",
"3.1.3.3.5": "full-product-name-type-product-identification-helper-sbom-urls",
"3.1.3.3.6": "full-product-name-type-product-identification-helper-serial-numbers",
"3.1.3.3.7": "full-product-name-type-product-identification-helper-skus",
Expand Down
8 changes: 4 additions & 4 deletions csaf_2.1/prose/edit/etc/section-label-to-display.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@
"full-product-name-type-product-identification-helper-generic-uris": "3.1.3.3.8",
"full-product-name-type-product-identification-helper-hashes": "3.1.3.3.2",
"full-product-name-type-product-identification-helper-model-numbers": "3.1.3.3.3",
"full-product-name-type-product-identification-helper-purl": "3.1.3.3.4",
"full-product-name-type-product-identification-helper-purls": "3.1.3.3.4",
"full-product-name-type-product-identification-helper-sbom-urls": "3.1.3.3.5",
"full-product-name-type-product-identification-helper-serial-numbers": "3.1.3.3.6",
"full-product-name-type-product-identification-helper-skus": "3.1.3.3.7",
Expand Down Expand Up @@ -250,9 +250,9 @@
"vulnerabilities-property-ids": "3.2.4.6",
"vulnerabilities-property-involvements": "3.2.4.7",
"vulnerabilities-property-metrics": "3.2.4.8",
"vulnerabilities-property-metrics-content": "3.2.4.8.1",
"vulnerabilities-property-metrics-products": "3.2.4.8.2",
"vulnerabilities-property-metrics-source": "3.2.4.8.3",
"vulnerabilities-property-metrics-content": "3.2.4.8.1",
"vulnerabilities-property-metrics-products": "3.2.4.8.2",
"vulnerabilities-property-metrics-source": "3.2.4.8.3",
"vulnerabilities-property-notes": "3.2.4.9",
"vulnerabilities-property-product-status": "3.2.4.10",
"vulnerabilities-property-references": "3.2.4.11",
Expand Down
40 changes: 22 additions & 18 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 @@ -41,7 +41,7 @@ Product ID (`product_id`) holds a value of type Product ID (`product_id_t`).

Helper to identify the product (`product_identification_helper`) of value type `object` provides in its properties at least
one method which aids in identifying the product in an asset database.
Of the given eight properties `cpe`, `hashes`, `model_numbers`, `purl`, `sbom_urls`, `serial_numbers`, `skus`,
Of the given eight properties `cpe`, `hashes`, `model_numbers`, `purls`, `sbom_urls`, `serial_numbers`, `skus`,
and `x_generic_uris`, one is mandatory.

```
Expand All @@ -51,27 +51,27 @@ and `x_generic_uris`, one is mandatory.
"cpe": {
// ...
},
"hashes": [
"hashes": {
// ...
],
"model_numbers": [
},
"model_numbers": {
// ...
],
"purl": {
},
"purls": {
// ...
},
"sbom_urls": [
"sbom_urls": {
// ...
],
"serial_numbers": [
},
"serial_numbers": {
// ...
],
"skus": [
},
"skus": {
// ...
],
"x_generic_uris": [
},
"x_generic_uris": {
// ...
]
}
}
}
```
Expand Down Expand Up @@ -239,9 +239,10 @@ Two `*` MUST NOT follow each other.
IC25T060ATCS05-0
```
##### Full Product Name Type - Product Identification Helper - purl
##### Full Product Name Type - Product Identification Helper - purls
The package URL (purl) representation (`purl`) is a `string` of 7 or more characters with `pattern` (regular expression):
List of purls (`purls`) of value type `array` with 1 or more items contains a list of package URL (purl) identifiers.
A purl is a `string` of 7 or more characters that meets the criteria of `pattern` (regular expression):
```
^pkg:[A-Za-z\\.\\-\\+][A-Za-z0-9\\.\\-\\+]*\\/.+
Expand All @@ -252,8 +253,11 @@ The package URL (purl) representation (`purl`) is a `string` of 7 or more charac
> CSAF uses only the canonical form of purl to conform with section 3.3 of [cite](#RFC3986).
> Therefore, URLs starting with `pkg://` are considered invalid.
This package URL (purl) attribute refers to a method for reliably identifying and locating software packages external to this specification.
See [cite](#PURL) for details.
A package URL (purl) attribute refers to a method for reliably identifying and locating software packages external to this specification.
See [cite](#PURL) for details. Multiple purls can be specified to allow for identifiers to locate identical components in different locations.
If multiple purls are specified, they MUST only differ in their qualifiers. Otherwise, separate product branches should
be used to differentiate between the components.
##### Full Product Name Type - Product Identification Helper - SBOM URLs
Expand Down
32 changes: 28 additions & 4 deletions csaf_2.1/prose/edit/src/tests-01-mndtr-13-purl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ It MUST be tested that given purl is valid.
The relevant paths for this test are:

```
/product_tree/branches[](/branches[])*/product/product_identification_helper/purl
/product_tree/full_product_names[]/product_identification_helper/purl
/product_tree/relationships[]/full_product_name/product_identification_helper/purl
/product_tree/branches[](/branches[])*/product/product_identification_helper/purls[]
/product_tree/full_product_names[]/product_identification_helper/purls[]
/product_tree/relationships[]/full_product_name/product_identification_helper/purls[]
```

*Example 1 (which fails the test):*
Expand All @@ -19,11 +19,35 @@ The relevant paths for this test are:
"name": "Product A",
"product_id": "CSAFPID-9080700",
"product_identification_helper": {
"purl": "pkg:maven/@1.3.4"
"purls": [
"pkg:maven/@1.3.4"
]
}
}
]
}
```

> Any valid purl has a name component.
It MUST also be tested that if more than one purl is specified, they can only differ in their qualifiers.

*Example 2 (which fails the test):*

```
"product_tree": {
"full_product_names": [
{
"name": "Product A",
"product_id": "CSAFPID-9080700",
"product_identification_helper": {
"purls": [
"pkg:maven/org.example.blue/logging@1.3.4",
"pkg:maven/org.example.blue/audit@1.3.4"
]
}
}
]
}
```
> The two purls differ in the name component.
6 changes: 4 additions & 2 deletions csaf_2.1/test/validator/data/mandatory/oasis_csaf_tc-csaf_2_1-2024-6-1-13-01.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,11 @@
"name": "Product A",
"product_id": "CSAFPID-9080700",
"product_identification_helper": {
"purl": "pkg:maven/@1.3.4"
"purls": [
"pkg:maven/@1.3.4"
]
}
}
]
}
}
}

0 comments on commit f6e7b8c

Please sign in to comment.