From e06981d003962808195a9042dc1220bac189588e Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Fri, 24 Mar 2023 16:51:55 -0500 Subject: [PATCH 1/3] Deprecated tool in favor of components and services used as tools. Added both current 1.5 and deprecated examples of each. Signed-off-by: Steve Springett --- schema/bom-1.5.proto | 27 ++++---- schema/bom-1.5.schema.json | 66 +++++++++++++++++-- schema/bom-1.5.xsd | 24 ++++++- .../1.5/valid-metadata-tool-1.5.json | 53 ++++++++++----- .../1.5/valid-metadata-tool-1.5.textproto | 37 ++++++++--- .../resources/1.5/valid-metadata-tool-1.5.xml | 20 +++--- .../valid-metadata-tool-deprecated-1.5.json | 26 ++++++++ ...lid-metadata-tool-deprecated-1.5.textproto | 18 +++++ .../valid-metadata-tool-deprecated-1.5.xml | 17 +++++ 9 files changed, 233 insertions(+), 55 deletions(-) create mode 100644 tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.json create mode 100644 tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.textproto create mode 100644 tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.xml diff --git a/schema/bom-1.5.proto b/schema/bom-1.5.proto index 937ea0e1..59ce1bd3 100644 --- a/schema/bom-1.5.proto +++ b/schema/bom-1.5.proto @@ -353,7 +353,7 @@ message Metadata { // The date and time (timestamp) when the document was created. optional google.protobuf.Timestamp timestamp = 1; // The tool(s) used in the creation of the BOM. - repeated Tool tools = 2; + optional Tool tools = 2; // The person(s) who created the BOM. Authors are common in BOMs created through manual processes. BOMs created through automated means may not have authors. repeated OrganizationalContact authors = 3; // The component that the BOM describes. @@ -482,15 +482,20 @@ message Swid { // Specifies a tool (manual or automated). message Tool { - // The vendor of the tool used to create the BOM. - optional string vendor = 1; - // The name of the tool used to create the BOM. - optional string name = 2; - // The version of the tool used to create the BOM. - optional string version = 3; - repeated Hash hashes = 4; - // Provides the ability to document external references related to the tool. - repeated ExternalReference external_references = 5; + // DEPRECATED - DO NOT USE - The vendor of the tool used to create the BOM. + optional string vendor = 1 [deprecated = true]; + // DEPRECATED - DO NOT USE - The name of the tool used to create the BOM. + optional string name = 2 [deprecated = true]; + // DEPRECATED - DO NOT USE - The version of the tool used to create the BOM. + optional string version = 3 [deprecated = true]; + // DEPRECATED - DO NOT USE + repeated Hash hashes = 4 [deprecated = true]; + // DEPRECATED - DO NOT USE - Provides the ability to document external references related to the tool. + repeated ExternalReference external_references = 5 [deprecated = true]; + // A list of software and hardware components used as tools + repeated Component components = 6; + // A list of services used as tools. This may include microservices, function-as-a-service, and other types of network or intra-process services. + repeated Service services = 7; } // Specifies a property @@ -595,7 +600,7 @@ message Vulnerability { // Individuals or organizations credited with the discovery of the vulnerability. optional VulnerabilityCredits credits = 14; // The tool(s) used to identify, confirm, or score the vulnerability. - repeated Tool tools = 15; + optional Tool tools = 15; // An assessment of the impact and exploitability of the vulnerability. optional VulnerabilityAnalysis analysis = 16; // affects diff --git a/schema/bom-1.5.schema.json b/schema/bom-1.5.schema.json index f2f43304..7249937d 100644 --- a/schema/bom-1.5.schema.json +++ b/schema/bom-1.5.schema.json @@ -137,11 +137,39 @@ "description": "The date and time (timestamp) when the BOM was created." }, "tools": { - "type": "array", - "title": "Creation Tools", - "description": "The tool(s) used in the creation of the BOM.", - "additionalItems": false, - "items": {"$ref": "#/definitions/tool"} + "oneOf": [ + { + "type": "object", + "title": "Creation Tools", + "description": "The tool(s) used in the creation of the BOM.", + "additionalProperties": false, + "properties": { + "components": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/component"}, + "uniqueItems": true, + "title": "Components", + "description": "A list of software and hardware components used as tools" + }, + "services": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/service"}, + "uniqueItems": true, + "title": "Services", + "description": "A list of services used as tools. This may include microservices, function-as-a-service, and other types of network or intra-process services." + } + } + }, + { + "type": "array", + "title": "Creation Tools (legacy)", + "description": "[Deprecated] The tool(s) used in the creation of the BOM.", + "additionalItems": false, + "items": {"$ref": "#/definitions/tool"} + } + ] }, "authors" :{ "type": "array", @@ -183,7 +211,7 @@ "tool": { "type": "object", "title": "Tool", - "description": "Information about the automated or manual tool used", + "description": "[Deprecated] - DO NOT USE. This will be removed in a future version. This will be removed in a future version. Use component or service instead. Information about the automated or manual tool used", "additionalProperties": false, "properties": { "vendor": { @@ -1739,7 +1767,31 @@ "title": "Creation Tools", "description": "The tool(s) used to identify, confirm, or score the vulnerability.", "additionalItems": false, - "items": {"$ref": "#/definitions/tool"} + "items": { + "properties": { + "component": { + "$ref": "#/definitions/component" + }, + "service": { + "$ref": "#/definitions/service" + }, + "tool": { + "description": "[Deprecated - Use `component` and `service` instead]", + "$ref": "#/definitions/tool" + } + }, + "oneOf":[ + { + "required": ["component"] + }, + { + "required": ["service"] + }, + { + "required": ["tool"] + } + ] + } }, "analysis": { "type": "object", diff --git a/schema/bom-1.5.xsd b/schema/bom-1.5.xsd index 357f6fd3..d9061678 100644 --- a/schema/bom-1.5.xsd +++ b/schema/bom-1.5.xsd @@ -54,9 +54,27 @@ limitations under the License. The tool(s) used in the creation of the BOM. - - - + + + + + DEPRECATED. Use tools\components or tools\services instead. + + + + + + + A list of software and hardware components used as tools. + + + + + A list of services used as tools. + + + + diff --git a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.json b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.json index 81e908a9..5331c2cc 100644 --- a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.json +++ b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.json @@ -4,23 +4,44 @@ "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79", "version": 1, "metadata": { - "tools": [ - { - "vendor": "Awesome Vendor", - "name": "Awesome Tool", - "version": "9.1.2", - "hashes": [ - { - "alg": "SHA-1", - "content": "25ed8e31b995bb927966616df2a42b979a2717f0" + "tools": { + "components": [ + { + "type": "application", + "group": "Awesome Vendor", + "name": "Awesome Tool", + "version": "9.1.2", + "hashes": [ + { + "alg": "SHA-1", + "content": "25ed8e31b995bb927966616df2a42b979a2717f0" + }, + { + "alg": "SHA-256", + "content": "a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df" + } + ] + } + ], + "services": [ + { + "provider": { + "name": "Acme Org", + "url": [ + "https://example.com" + ] }, - { - "alg": "SHA-256", - "content": "a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df" - } - ] - } - ] + "group": "com.example", + "name": "Acme Signing Server", + "description": "Signs artifacts", + "endpoints": [ + "https://example.com/sign", + "https://example.com/verify", + "https://example.com/tsa" + ] + } + ] + } }, "components": [] } diff --git a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.textproto b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.textproto index 7c3d0cb0..a8b42820 100644 --- a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.textproto +++ b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.textproto @@ -3,16 +3,35 @@ version: 1 serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" metadata { tools { - vendor: "Awesome Vendor" - name: "Awesome Tool" - version: "9.1.2" - hashes { - alg: HASH_ALG_SHA_1 - value: "25ed8e31b995bb927966616df2a42b979a2717f0" + components { + type: CLASSIFICATION_APPLICATION + group: "Awesome Vendor" + name: "Awesome Tool" + version: "9.1.2" + hashes { + alg: HASH_ALG_SHA_1 + value: "25ed8e31b995bb927966616df2a42b979a2717f0" + } + hashes { + alg: HASH_ALG_SHA_256 + value: "a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df" + } } - hashes { - alg: HASH_ALG_SHA_256 - value: "a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df" + services { + provider: { + name: "Acme Org", + url: [ + "https://example.com" + ] + }, + group: "com.example", + name: "Acme Signing Server", + description: "Signs artifacts", + endpoints: [ + "https://example.com/sign", + "https://example.com/verify", + "https://example.com/tsa" + ] } } } diff --git a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml index caf273f6..3ab15517 100644 --- a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml +++ b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml @@ -2,15 +2,17 @@ - - Awesome Vendor - Awesome Tool - 9.1.2 - - 25ed8e31b995bb927966616df2a42b979a2717f0 - a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df - - + + + Awesome Vendor + Awesome Tool + 9.1.2 + + 25ed8e31b995bb927966616df2a42b979a2717f0 + a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df + + + diff --git a/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.json b/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.json new file mode 100644 index 00000000..81e908a9 --- /dev/null +++ b/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.json @@ -0,0 +1,26 @@ +{ + "bomFormat": "CycloneDX", + "specVersion": "1.5", + "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79", + "version": 1, + "metadata": { + "tools": [ + { + "vendor": "Awesome Vendor", + "name": "Awesome Tool", + "version": "9.1.2", + "hashes": [ + { + "alg": "SHA-1", + "content": "25ed8e31b995bb927966616df2a42b979a2717f0" + }, + { + "alg": "SHA-256", + "content": "a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df" + } + ] + } + ] + }, + "components": [] +} diff --git a/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.textproto b/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.textproto new file mode 100644 index 00000000..7c3d0cb0 --- /dev/null +++ b/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.textproto @@ -0,0 +1,18 @@ +spec_version: "1.5" +version: 1 +serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" +metadata { + tools { + vendor: "Awesome Vendor" + name: "Awesome Tool" + version: "9.1.2" + hashes { + alg: HASH_ALG_SHA_1 + value: "25ed8e31b995bb927966616df2a42b979a2717f0" + } + hashes { + alg: HASH_ALG_SHA_256 + value: "a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df" + } + } +} diff --git a/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.xml b/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.xml new file mode 100644 index 00000000..caf273f6 --- /dev/null +++ b/tools/src/test/resources/1.5/valid-metadata-tool-deprecated-1.5.xml @@ -0,0 +1,17 @@ + + + + + + Awesome Vendor + Awesome Tool + 9.1.2 + + 25ed8e31b995bb927966616df2a42b979a2717f0 + a74f733635a19aefb1f73e5947cef59cd7440c6952ef0f03d09d974274cbd6df + + + + + + From 6de0ebef538f1713a0d2264fdd02df48d4493e41 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Fri, 24 Mar 2023 17:11:35 -0500 Subject: [PATCH 2/3] Updated json and xml schemas to account for tool usage in vulnerability objects. Updated vulnerability examples with new structure. Signed-off-by: Steve Springett --- schema/bom-1.5.schema.json | 58 ++++++++++--------- schema/bom-1.5.xsd | 24 +++++++- .../1.5/valid-vulnerability-1.5.json | 29 +++++----- .../1.5/valid-vulnerability-1.5.textproto | 21 ++++--- .../resources/1.5/valid-vulnerability-1.5.xml | 18 +++--- 5 files changed, 92 insertions(+), 58 deletions(-) diff --git a/schema/bom-1.5.schema.json b/schema/bom-1.5.schema.json index 7249937d..4f4c15a7 100644 --- a/schema/bom-1.5.schema.json +++ b/schema/bom-1.5.schema.json @@ -1763,35 +1763,39 @@ } }, "tools": { - "type": "array", - "title": "Creation Tools", - "description": "The tool(s) used to identify, confirm, or score the vulnerability.", - "additionalItems": false, - "items": { - "properties": { - "component": { - "$ref": "#/definitions/component" - }, - "service": { - "$ref": "#/definitions/service" - }, - "tool": { - "description": "[Deprecated - Use `component` and `service` instead]", - "$ref": "#/definitions/tool" + "oneOf": [ + { + "type": "object", + "title": "Tools", + "description": "The tool(s) used to identify, confirm, or score the vulnerability.", + "additionalProperties": false, + "properties": { + "components": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/component"}, + "uniqueItems": true, + "title": "Components", + "description": "A list of software and hardware components used as tools" + }, + "services": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/service"}, + "uniqueItems": true, + "title": "Services", + "description": "A list of services used as tools. This may include microservices, function-as-a-service, and other types of network or intra-process services." + } } }, - "oneOf":[ - { - "required": ["component"] - }, - { - "required": ["service"] - }, - { - "required": ["tool"] - } - ] - } + { + "type": "array", + "title": "Tools (legacy)", + "description": "[Deprecated] The tool(s) used to identify, confirm, or score the vulnerability.", + "additionalItems": false, + "items": {"$ref": "#/definitions/tool"} + } + ] }, "analysis": { "type": "object", diff --git a/schema/bom-1.5.xsd b/schema/bom-1.5.xsd index d9061678..6edd7578 100644 --- a/schema/bom-1.5.xsd +++ b/schema/bom-1.5.xsd @@ -2187,9 +2187,27 @@ limitations under the License. The tool(s) used to identify, confirm, or score the vulnerability. - - - + + + + + DEPRECATED. Use tools\components or tools\services instead. + + + + + + + A list of software and hardware components used as tools. + + + + + A list of services used as tools. + + + + diff --git a/tools/src/test/resources/1.5/valid-vulnerability-1.5.json b/tools/src/test/resources/1.5/valid-vulnerability-1.5.json index d6e49589..5742eed4 100644 --- a/tools/src/test/resources/1.5/valid-vulnerability-1.5.json +++ b/tools/src/test/resources/1.5/valid-vulnerability-1.5.json @@ -80,19 +80,22 @@ } ] }, - "tools": [ - { - "vendor": "Snyk", - "name": "Snyk CLI (Linux)", - "version": "1.729.0", - "hashes": [ - { - "alg": "SHA-256", - "content": "2eaf8c62831a1658c95d41fdc683cd177c147733c64a93e59cb2362829e45b7d" - } - ] - } - ], + "tools": { + "components": [ + { + "type": "application", + "group": "Snyk", + "name": "Snyk CLI (Linux)", + "version": "1.729.0", + "hashes": [ + { + "alg": "SHA-256", + "content": "2eaf8c62831a1658c95d41fdc683cd177c147733c64a93e59cb2362829e45b7d" + } + ] + } + ] + }, "analysis": { "state": "not_affected", "justification": "code_not_reachable", diff --git a/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto b/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto index 89543191..81b290ca 100644 --- a/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto +++ b/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto @@ -74,13 +74,20 @@ vulnerabilities { } } tools: { - vendor: "Snyk" - name: "Snyk CLI (Linux)" - version: "1.729.0" - hashes: { - alg: HASH_ALG_SHA_256 - value: "2eaf8c62831a1658c95d41fdc683cd177c147733c64a93e59cb2362829e45b7d" - } + components: [ + { + type: CLASSIFICATION_APPLICATION, + group: "Snyk", + name: "Snyk CLI (Linux)", + version: "1.729.0", + hashes: [ + { + alg: HASH_ALG_SHA_256 + value: "2eaf8c62831a1658c95d41fdc683cd177c147733c64a93e59cb2362829e45b7d" + } + ] + } + ] } analysis: { state: IMPACT_ANALYSIS_STATE_NOT_AFFECTED diff --git a/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml b/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml index 8120aaff..163fbb42 100644 --- a/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml +++ b/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml @@ -80,14 +80,16 @@ - - Snyk - Snyk CLI (Linux) - 1.729.0 - - 2eaf8c62831a1658c95d41fdc683cd177c147733c64a93e59cb2362829e45b7d - - + + + Snyk + Snyk CLI (Linux) + 1.729.0 + + 2eaf8c62831a1658c95d41fdc683cd177c147733c64a93e59cb2362829e45b7d + + + not_affected From bba0493f9c44faa67e436eee1fe0685c152ad6d7 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Wed, 29 Mar 2023 14:44:53 -0500 Subject: [PATCH 3/3] Added missing services to tools in test cases Signed-off-by: Steve Springett --- .../resources/1.5/valid-metadata-tool-1.5.xml | 16 ++++++++++++++++ .../resources/1.5/valid-vulnerability-1.5.json | 11 +++++++++++ .../1.5/valid-vulnerability-1.5.textproto | 11 +++++++++++ .../resources/1.5/valid-vulnerability-1.5.xml | 11 +++++++++++ 4 files changed, 49 insertions(+) diff --git a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml index 3ab15517..65a2a8a4 100644 --- a/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml +++ b/tools/src/test/resources/1.5/valid-metadata-tool-1.5.xml @@ -13,6 +13,22 @@ + + + + Acme Org + https://example.com + + com.example + Acme Signing Server + Signs artifacts + + https://example.com/sign + https://example.com/verify + https://example.com/tsa + + + diff --git a/tools/src/test/resources/1.5/valid-vulnerability-1.5.json b/tools/src/test/resources/1.5/valid-vulnerability-1.5.json index 5742eed4..73f885eb 100644 --- a/tools/src/test/resources/1.5/valid-vulnerability-1.5.json +++ b/tools/src/test/resources/1.5/valid-vulnerability-1.5.json @@ -94,6 +94,17 @@ } ] } + ], + "services": [ + { + "provider": { + "name": "Acme Inc" + }, + "name": "Acme BOM Analyzer", + "endpoints": [ + "https://example.com/analyze" + ] + } ] }, "analysis": { diff --git a/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto b/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto index 81b290ca..7f61a0a7 100644 --- a/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto +++ b/tools/src/test/resources/1.5/valid-vulnerability-1.5.textproto @@ -88,6 +88,17 @@ vulnerabilities { ] } ] + services: [ + { + provider: { + name: "Acme Inc" + }, + name: "Acme BOM Analyzer", + endpoints: [ + "https://example.com/analyze" + ] + } + ] } analysis: { state: IMPACT_ANALYSIS_STATE_NOT_AFFECTED diff --git a/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml b/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml index 163fbb42..2bff2549 100644 --- a/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml +++ b/tools/src/test/resources/1.5/valid-vulnerability-1.5.xml @@ -90,6 +90,17 @@ + + + + Acme Inf + + Acme BOM Analyzer + + https://example.com/analyze + + + not_affected