From de4193c331e4f688df28eaa5848483c39f8dfb88 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Tue, 11 Jul 2023 14:23:10 -0500 Subject: [PATCH 01/28] Initial checkin of 1.6 attestation support Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 446 +++++++++++++++++++++++++++++++++++++ 1 file changed, 446 insertions(+) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 726fbf03..3243832d 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -105,6 +105,452 @@ "title": "Formulation", "description": "Describes how a component or service was manufactured or deployed. This is achieved through the use of formulas, workflows, tasks, and steps, which declare the precise steps to reproduce along with the observed formulas describing the steps which transpired in the manufacturing process." }, + "declarations": { + "type": "object", + "title": "Declarations", + "description": "", + "additionalProperties": false, + "properties": { + "standards": { + "type": "array", + "title": "Standards", + "description": "", + "items": { + "type": "object", + "title": "Standard", + "description": "", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "name": { + "type": "string", + "title": "Name", + "description": "The name of the standard" + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the standard" + }, + "version": { + "type": "string", + "title": "Version", + "description": "A version of the standard" + }, + "owner": { + "type": "string", + "title": "Owner", + "description": "The owner of the standard" + }, + "requirements": { + "type": "array", + "title": "Requirements", + "description": "The requirements that make up the standard", + "items": { + "type": "object", + "title": "Requirement", + "description": "", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "identifier": { + "type": "string", + "title": "Identifier", + "description": "The identifier used in the standard to identify a specific requirement" + }, + "title": { + "type": "string", + "title": "Title", + "description": "The title of the requirement" + }, + "text": { + "type": "string", + "title": "Text", + "description": "The textual content of the requirement" + }, + "opencre": { + "type": "string", + "format": "iri-reference", + "title": "OWASP OpenCRE", + "description": "URL to the Common Requirements Enumeration" + }, + "parent": { + "$ref": "#/definitions/refLinkType", + "title": "Parent BOM Reference", + "description": "The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements." + }, + "externalReferences": { + "type": "array", + "items": {"$ref": "#/definitions/externalReference"}, + "title": "External References", + "description": "External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." + } + } + } + }, + "levels": { + "type": "array", + "title": "Levels", + "description": "", + "items": { + "type": "object", + "title": "Level", + "description": "", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "identifier": { + "type": "string", + "title": "Identifier", + "description": "The identifier used in the standard to identify a specific level" + }, + "title": { + "type": "string", + "title": "Title", + "description": "The title of the level" + }, + "description": { + "type": "string", + "title": "Description", + "description": "The description of the level" + }, + "requirements": { + "type": "array", + "title": "Requirements", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + } + } + } + }, + "externalReferences": { + "type": "array", + "items": {"$ref": "#/definitions/externalReference"}, + "title": "External References", + "description": "External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." + } + } + } + }, + "assessors": { + "type": "array", + "title": "Assessors", + "description": "", + "items": { + "type": "object", + "title": "Assessor", + "description": "", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "type": { + "type": "string", + "enum": [ + "self", + "purchaser", + "independent" + ], + "title": "Type", + "description": "" + }, + "organization": { + "$ref": "#/definitions/organizationalEntity", + "title": "Organization", + "description": "" + } + } + } + }, + "attestations": { + "type": "array", + "title": "Attestations", + "description": "", + "items": { + "additionalProperties": false, + "properties": { + "targets": { + "type": "array", + "title": "Targets", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + }, + "assessor": { + "$ref": "#/definitions/refLinkType", + "title": "Assessor", + "description": "" + }, + "map": { + "type": "array", + "title": "Map", + "description": "", + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "requirement": { + "$ref": "#/definitions/refLinkType", + "title": "Requirement", + "description": "" + }, + "claims": { + "type": "array", + "title": "Claims", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + }, + "counterClaims": { + "type": "array", + "title": "Claims", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + }, + "conformance": { + "type": "number", + "minimum": 0, + "maximum": 1, + "title": "Conformance", + "description": "The conformance to a requirement from 0 - 1, where 1 is 100% conformance." + }, + "mitigationStrategy": { + "type": "array", + "title": "Mitigation Strategy", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + }, + "confidence": { + "type": "object", + "title": "Confidence", + "description": "", + "additionalProperties": false, + "properties": { + "score": { + "type": "number", + "minimum": 0, + "maximum": 1, + "title": "Score", + "description": "The confidence of the attestation from 0 - 1, where 1 is 100% confidence." + }, + "rationale": { + "type": "string", + "title": "Rationale", + "description": "" + } + } + } + } + } + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." + } + } + } + }, + "claims": { + "type": "array", + "title": "Claims", + "description": "", + "items": { + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "target": { + "$ref": "#/definitions/refLinkType", + "title": "Target", + "description": "" + }, + "predicate": { + "type": "string", + "title": "Predicate", + "description": "" + }, + "mitigationStrategy": { + "type": "array", + "title": "Mitigation Strategy", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + }, + "reasoning": { + "type": "string", + "title": "Reasoning", + "description": "" + }, + "evidence": { + "type": "array", + "title": "Evidence", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + }, + "counterEvidence": { + "type": "array", + "title": "Counter Evidence", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + }, + "externalReferences": { + "type": "array", + "items": {"$ref": "#/definitions/externalReference"}, + "title": "External References", + "description": "External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." + } + } + } + }, + "evidence": { + "type": "array", + "title": "Evidence", + "description": "", + "items": { + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "type": { + "type": "string", + "title": "Type", + "description": "TODO - make this extensible - see valid-attestations-1.6.json for notes" + }, + "description": { + "type": "string", + "title": "Description", + "description": "" + }, + "data": { + "type": "string", + "title": "Description", + "description": "", + "additionalProperties": false, + "properties": { + "contents": { + "type": "object", + "title": "Data Contents", + "description": "The contents or references to the contents of the data being described.", + "additionalProperties": false, + "properties": { + "attachment": { + "title": "Data Attachment", + "description": "An optional way to include textual or encoded data.", + "$ref": "#/definitions/attachment" + }, + "url": { + "type": "string", + "title": "Data URL", + "description": "The URL to where the data can be retrieved.", + "format": "iri-reference" + } + } + } + } + }, + "created": { + "type": "string", + "format": "date-time", + "title": "Created", + "description": "" + }, + "expires": { + "type": "string", + "format": "date-time", + "title": "Expires", + "description": "" + }, + "author": { + "$ref": "#/definitions/organizationalContact", + "title": "Author", + "description": "" + }, + "reviewer": { + "$ref": "#/definitions/organizationalContact", + "title": "Reviewer", + "description": "" + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." + } + } + } + }, + "targets": { + "type": "object", + "title": "Targets", + "description": "", + "additionalProperties": false, + "properties": { + "organizations": { + "type": "array", + "title": "Organizations", + "description": "", + "items": {"$ref": "#/definitions/organizationalEntity"} + }, + "contacts": { + "type": "array", + "title": "Contacts", + "description": "", + "items": {"$ref": "#/definitions/organizationalContact"} + }, + "components": { + "type": "array", + "title": "Components", + "description": "", + "items": {"$ref": "#/definitions/component"} + }, + "services": { + "type": "array", + "title": "Services", + "description": "", + "items": {"$ref": "#/definitions/service"} + } + } + }, + "affirmation": { + "type": "object", + "title": "Affirmation", + "additionalProperties": false, + "properties": { + "text": { + + } + } + } + } + }, "properties": { "type": "array", "title": "Properties", From 2a62ac30517304a6cd877676f996b609a019cbdc Mon Sep 17 00:00:00 2001 From: "steve.springett" Date: Tue, 1 Aug 2023 14:57:35 -0500 Subject: [PATCH 02/28] Updates at the end of todays call --- schema/bom-1.6.schema.json | 40 +++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 3243832d..8e946f51 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -289,11 +289,10 @@ "items": { "additionalProperties": false, "properties": { - "targets": { - "type": "array", - "title": "Targets", - "description": "", - "items": { "$ref": "#/definitions/refLinkType" } + "summary": { + "type": "string", + "title": "Summary", + "description": "" }, "assessor": { "$ref": "#/definitions/refLinkType", @@ -326,17 +325,30 @@ "items": { "$ref": "#/definitions/refLinkType" } }, "conformance": { - "type": "number", - "minimum": 0, - "maximum": 1, + "type": "object", "title": "Conformance", - "description": "The conformance to a requirement from 0 - 1, where 1 is 100% conformance." - }, - "mitigationStrategy": { - "type": "array", - "title": "Mitigation Strategy", "description": "", - "items": { "$ref": "#/definitions/refLinkType" } + "additionalProperties": false, + "properties": { + "score": { + "type": "number", + "minimum": 0, + "maximum": 1, + "title": "Score", + "description": "The conformance to a requirement from 0 - 1, where 1 is 100% conformance." + }, + "rationale": { + "type": "string", + "title": "Rationale", + "description": "" + }, + "mitigationStrategy": { + "type": "array", + "title": "Mitigation Strategy", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + } + } }, "confidence": { "type": "object", From 4a64108e1b1e6e0fe8fa8132cb8bf69582398507 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Mon, 28 Aug 2023 16:44:57 -0500 Subject: [PATCH 03/28] Moved standards out from declarations into definitions. Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 287 +++++++++++++++++++------------------ 1 file changed, 149 insertions(+), 138 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 3243832d..2091e048 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -111,144 +111,6 @@ "description": "", "additionalProperties": false, "properties": { - "standards": { - "type": "array", - "title": "Standards", - "description": "", - "items": { - "type": "object", - "title": "Standard", - "description": "", - "additionalProperties": false, - "properties": { - "bom-ref": { - "$ref": "#/definitions/refType", - "title": "BOM Reference", - "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." - }, - "name": { - "type": "string", - "title": "Name", - "description": "The name of the standard" - }, - "description": { - "type": "string", - "title": "Description", - "description": "A description of the standard" - }, - "version": { - "type": "string", - "title": "Version", - "description": "A version of the standard" - }, - "owner": { - "type": "string", - "title": "Owner", - "description": "The owner of the standard" - }, - "requirements": { - "type": "array", - "title": "Requirements", - "description": "The requirements that make up the standard", - "items": { - "type": "object", - "title": "Requirement", - "description": "", - "additionalProperties": false, - "properties": { - "bom-ref": { - "$ref": "#/definitions/refType", - "title": "BOM Reference", - "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." - }, - "identifier": { - "type": "string", - "title": "Identifier", - "description": "The identifier used in the standard to identify a specific requirement" - }, - "title": { - "type": "string", - "title": "Title", - "description": "The title of the requirement" - }, - "text": { - "type": "string", - "title": "Text", - "description": "The textual content of the requirement" - }, - "opencre": { - "type": "string", - "format": "iri-reference", - "title": "OWASP OpenCRE", - "description": "URL to the Common Requirements Enumeration" - }, - "parent": { - "$ref": "#/definitions/refLinkType", - "title": "Parent BOM Reference", - "description": "The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements." - }, - "externalReferences": { - "type": "array", - "items": {"$ref": "#/definitions/externalReference"}, - "title": "External References", - "description": "External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." - } - } - } - }, - "levels": { - "type": "array", - "title": "Levels", - "description": "", - "items": { - "type": "object", - "title": "Level", - "description": "", - "additionalProperties": false, - "properties": { - "bom-ref": { - "$ref": "#/definitions/refType", - "title": "BOM Reference", - "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." - }, - "identifier": { - "type": "string", - "title": "Identifier", - "description": "The identifier used in the standard to identify a specific level" - }, - "title": { - "type": "string", - "title": "Title", - "description": "The title of the level" - }, - "description": { - "type": "string", - "title": "Description", - "description": "The description of the level" - }, - "requirements": { - "type": "array", - "title": "Requirements", - "description": "", - "items": { "$ref": "#/definitions/refLinkType" } - } - } - } - }, - "externalReferences": { - "type": "array", - "items": {"$ref": "#/definitions/externalReference"}, - "title": "External References", - "description": "External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." - }, - "signature": { - "$ref": "#/definitions/signature", - "title": "Signature", - "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." - } - } - } - }, "assessors": { "type": "array", "title": "Assessors", @@ -551,6 +413,22 @@ } } }, + "definitions": { + "type": "object", + "title": "Definitions", + "description": "", + "additionalProperties": false, + "properties": { + "standards": { + "type": "array", + "title": "Standards", + "description": "Defines standards which may consist of regulations, industry or organizational-specific standards, maturity models, and best practices which can be evaluated against or attested to.", + "items": { + "$ref": "#/definitions/standard" + } + } + } + }, "properties": { "type": "array", "title": "Properties", @@ -4236,6 +4114,139 @@ } } }, + "standard": { + "type": "object", + "title": "Standard", + "description": "", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "name": { + "type": "string", + "title": "Name", + "description": "The name of the standard" + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the standard" + }, + "version": { + "type": "string", + "title": "Version", + "description": "A version of the standard" + }, + "owner": { + "type": "string", + "title": "Owner", + "description": "The owner of the standard" + }, + "requirements": { + "type": "array", + "title": "Requirements", + "description": "The requirements that make up the standard", + "items": { + "type": "object", + "title": "Requirement", + "description": "", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "identifier": { + "type": "string", + "title": "Identifier", + "description": "The identifier used in the standard to identify a specific requirement" + }, + "title": { + "type": "string", + "title": "Title", + "description": "The title of the requirement" + }, + "text": { + "type": "string", + "title": "Text", + "description": "The textual content of the requirement" + }, + "opencre": { + "type": "string", + "format": "iri-reference", + "title": "OWASP OpenCRE", + "description": "URL to the Common Requirements Enumeration" + }, + "parent": { + "$ref": "#/definitions/refLinkType", + "title": "Parent BOM Reference", + "description": "The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements." + }, + "externalReferences": { + "type": "array", + "items": {"$ref": "#/definitions/externalReference"}, + "title": "External References", + "description": "External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." + } + } + } + }, + "levels": { + "type": "array", + "title": "Levels", + "description": "", + "items": { + "type": "object", + "title": "Level", + "description": "", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "identifier": { + "type": "string", + "title": "Identifier", + "description": "The identifier used in the standard to identify a specific level" + }, + "title": { + "type": "string", + "title": "Title", + "description": "The title of the level" + }, + "description": { + "type": "string", + "title": "Description", + "description": "The description of the level" + }, + "requirements": { + "type": "array", + "title": "Requirements", + "description": "", + "items": { "$ref": "#/definitions/refLinkType" } + } + } + } + }, + "externalReferences": { + "type": "array", + "items": {"$ref": "#/definitions/externalReference"}, + "title": "External References", + "description": "External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." + } + } + }, "signature": { "$ref": "jsf-0.82.schema.json#/definitions/signature", "title": "Signature", From 53ff77d2c6146897ea14500a0a9f3446571a5ff6 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Mon, 28 Aug 2023 19:58:48 -0500 Subject: [PATCH 04/28] Removing invalid types Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 2 -- 1 file changed, 2 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index e3042202..1e94f62f 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -1723,7 +1723,6 @@ ] }, "governance": { - "type": "object", "title": "Data Governance", "$ref": "#/definitions/dataGovernance" }, @@ -3026,7 +3025,6 @@ "type": "string" }, "governance": { - "type": "object", "title": "Data Governance", "$ref": "#/definitions/dataGovernance" } From f73a14a12dd4b91a7c79c1ef6a4690a7d37561c6 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Mon, 28 Aug 2023 20:01:56 -0500 Subject: [PATCH 05/28] adding missing type Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 1 + 1 file changed, 1 insertion(+) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 1e94f62f..2c733040 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -149,6 +149,7 @@ "title": "Attestations", "description": "", "items": { + "type": "object", "additionalProperties": false, "properties": { "summary": { From e70a6e38f4c8309327aa9807547ce96bf376311d Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Mon, 28 Aug 2023 20:55:58 -0500 Subject: [PATCH 06/28] Added missing type Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 1 + 1 file changed, 1 insertion(+) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 2c733040..54184306 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -249,6 +249,7 @@ "title": "Claims", "description": "", "items": { + "type": "object", "additionalProperties": false, "properties": { "bom-ref": { From 8f86882b49b8eb5f295e103319d4f44150766090 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Mon, 28 Aug 2023 21:28:18 -0500 Subject: [PATCH 07/28] Added missing type Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 1 + 1 file changed, 1 insertion(+) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 54184306..5bad4307 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -309,6 +309,7 @@ "title": "Evidence", "description": "", "items": { + "type": "object", "additionalProperties": false, "properties": { "bom-ref": { From 52506bbff0b526eb658db8c21879f50ed1f89353 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Mon, 28 Aug 2023 23:05:03 -0500 Subject: [PATCH 08/28] Correcting object type Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 5bad4307..103f673e 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -328,7 +328,7 @@ "description": "" }, "data": { - "type": "string", + "type": "object", "title": "Description", "description": "", "additionalProperties": false, From 8f0557e710e07e91a639d2467a8374465b06ffd4 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Tue, 26 Sep 2023 13:52:19 -0500 Subject: [PATCH 09/28] Added descriptions that were developed by the working group. Minor changes to schema to include some changes and omissions. Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 178 +++++++++++++++++++++++-------------- 1 file changed, 109 insertions(+), 69 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 103f673e..305937ae 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -108,13 +108,13 @@ "declarations": { "type": "object", "title": "Declarations", - "description": "", + "description": "The list of declarations which describe the conformance to standards. Each declaration may include attestations, claims, and evidence.", "additionalProperties": false, "properties": { "assessors": { "type": "array", "title": "Assessors", - "description": "", + "description": "The list of assessors evaluating claims and determining conformance to requirements and confidence in that assessment.", "items": { "type": "object", "title": "Assessor", @@ -126,20 +126,15 @@ "title": "BOM Reference", "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." }, - "type": { - "type": "string", - "enum": [ - "self", - "purchaser", - "independent" - ], - "title": "Type", - "description": "" + "thirdParty": { + "type": "boolean", + "title": "Third Party", + "description": "The boolean indicating if the assessor is outside the organization generating claims. A value of false indicates a self assessor." }, "organization": { "$ref": "#/definitions/organizationalEntity", "title": "Organization", - "description": "" + "description": "The entity issuing the assessment." } } } @@ -147,7 +142,7 @@ "attestations": { "type": "array", "title": "Attestations", - "description": "", + "description": "The list of attestations asserted by an assessor that maps requirements to claims.", "items": { "type": "object", "additionalProperties": false, @@ -160,12 +155,12 @@ "assessor": { "$ref": "#/definitions/refLinkType", "title": "Assessor", - "description": "" + "description": "The `bom-ref` to the assessor asserting the attestation." }, "map": { "type": "array", "title": "Map", - "description": "", + "description": "The grouping of requirements to claims and the attestors declaired conformance and confidence thereof.", "items": { "type": "object", "additionalProperties": false, @@ -173,24 +168,24 @@ "requirement": { "$ref": "#/definitions/refLinkType", "title": "Requirement", - "description": "" + "description": "The `bom-ref` to the requirement being attested to." }, "claims": { "type": "array", "title": "Claims", - "description": "", + "description": "The list of `bom-ref` to the claims being attested to.", "items": { "$ref": "#/definitions/refLinkType" } }, "counterClaims": { "type": "array", "title": "Claims", - "description": "", + "description": "The list of `bom-ref` to the counter claims being attested to.", "items": { "$ref": "#/definitions/refLinkType" } }, "conformance": { "type": "object", "title": "Conformance", - "description": "", + "description": "The conformance of the claim meeting a requirement.", "additionalProperties": false, "properties": { "score": { @@ -198,17 +193,17 @@ "minimum": 0, "maximum": 1, "title": "Score", - "description": "The conformance to a requirement from 0 - 1, where 1 is 100% conformance." + "description": "The conformance of the claim within [0,1], where 1 is 100% confidence." }, "rationale": { "type": "string", "title": "Rationale", - "description": "" + "description": "The rationale for the score of conformance." }, "mitigationStrategy": { "type": "array", "title": "Mitigation Strategy", - "description": "", + "description": "The description of the mitigation strategy if conformance is not `1`.", "items": { "$ref": "#/definitions/refLinkType" } } } @@ -216,7 +211,7 @@ "confidence": { "type": "object", "title": "Confidence", - "description": "", + "description": "The confidence of the claim meeting the requirement.", "additionalProperties": false, "properties": { "score": { @@ -224,12 +219,12 @@ "minimum": 0, "maximum": 1, "title": "Score", - "description": "The confidence of the attestation from 0 - 1, where 1 is 100% confidence." + "description": "The confidence of the claim within [0,1], where 1 is 100% confidence." }, "rationale": { "type": "string", "title": "Rationale", - "description": "" + "description": "The rationale for the confidence score." } } } @@ -247,7 +242,7 @@ "claims": { "type": "array", "title": "Claims", - "description": "", + "description": "The list of claims.", "items": { "type": "object", "additionalProperties": false, @@ -260,34 +255,34 @@ "target": { "$ref": "#/definitions/refLinkType", "title": "Target", - "description": "" + "description": "The `bom-ref` to a target representing a specific system, application, API, module, team, person, process, business unit, company, etc... that this claim is being applied to." }, "predicate": { "type": "string", "title": "Predicate", - "description": "" + "description": "The specific statement or assertion about the target." }, "mitigationStrategy": { "type": "array", "title": "Mitigation Strategy", - "description": "", + "description": "The written explanation of how any weaknesses in the evidence will be mitigated.", "items": { "$ref": "#/definitions/refLinkType" } }, "reasoning": { "type": "string", "title": "Reasoning", - "description": "" + "description": "The written explanation of why the evidence provided substantiates the claim." }, "evidence": { "type": "array", "title": "Evidence", - "description": "", + "description": "The array of references to evidence that supports this claim.", "items": { "$ref": "#/definitions/refLinkType" } }, "counterEvidence": { "type": "array", "title": "Counter Evidence", - "description": "", + "description": "The array of references to counterEvidence that undermines this claim.", "items": { "$ref": "#/definitions/refLinkType" } }, "externalReferences": { @@ -307,7 +302,7 @@ "evidence": { "type": "array", "title": "Evidence", - "description": "", + "description": "The list of evidence.", "items": { "type": "object", "additionalProperties": false, @@ -325,12 +320,12 @@ "description": { "type": "string", "title": "Description", - "description": "" + "description": "The written description of what this evidence is and how it was created." }, "data": { "type": "object", "title": "Description", - "description": "", + "description": "The output or analysis that supports claims.", "additionalProperties": false, "properties": { "contents": { @@ -341,13 +336,13 @@ "properties": { "attachment": { "title": "Data Attachment", - "description": "An optional way to include textual or encoded data.", + "description": "The optional way to include textual or encoded data.", "$ref": "#/definitions/attachment" }, "url": { "type": "string", "title": "Data URL", - "description": "The URL to where the data can be retrieved.", + "description": "The URL where the data can be retrieved.", "format": "iri-reference" } } @@ -358,23 +353,23 @@ "type": "string", "format": "date-time", "title": "Created", - "description": "" + "description": "The date and time (timestamp) when the evidence was created." }, "expires": { "type": "string", "format": "date-time", "title": "Expires", - "description": "" + "description": "The optional date and time (timestamp) when the evidence is no longer valid." }, "author": { "$ref": "#/definitions/organizationalContact", "title": "Author", - "description": "" + "description": "The author of the evidence." }, "reviewer": { "$ref": "#/definitions/organizationalContact", "title": "Reviewer", - "description": "" + "description": "The reviewer of the evidence." }, "signature": { "$ref": "#/definitions/signature", @@ -387,31 +382,31 @@ "targets": { "type": "object", "title": "Targets", - "description": "", + "description": "The list of targets which claims are made against.", "additionalProperties": false, "properties": { "organizations": { "type": "array", "title": "Organizations", - "description": "", + "description": "The list of organizations which claims are made against.", "items": {"$ref": "#/definitions/organizationalEntity"} }, - "contacts": { + "people": { "type": "array", - "title": "Contacts", - "description": "", + "title": "People", + "description": "The list of individuals which claims are made against.", "items": {"$ref": "#/definitions/organizationalContact"} }, "components": { "type": "array", "title": "Components", - "description": "", + "description": "The list of components which claims are made against.", "items": {"$ref": "#/definitions/component"} }, "services": { "type": "array", "title": "Services", - "description": "", + "description": "The list of services which claims are made against.", "items": {"$ref": "#/definitions/service"} } } @@ -421,8 +416,55 @@ "title": "Affirmation", "additionalProperties": false, "properties": { - "text": { - + "statement": { + "type": "string", + "title": "Text", + "description": "The brief statement affirmed by an individual regarding all declarations.\n*- Notes This could be an affirmation of acceptance by a third-party auditor or receiving individual of a file.", + "examples": [ "I certify, to the best of my knowledge, that all information is correct." ] + }, + "signatories": { + "type": "array", + "title": "Signatories", + "description": "The list of signatories authorized on behalf of an organization to assert validity of this document.", + "items": { + "type": "object", + "additionalProperties": false, + "oneOf": [ + { + "required": ["signature"] + }, + { + "required": ["externalReference", "organization"] + } + ], + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The signatory's name." + }, + "role": { + "type": "string", + "title": "Role", + "description": "The signatory's role within an organization." + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." + }, + "organization": { + "$ref": "#/definitions/organizationalEntity", + "title": "Organization", + "description": "The signatory's organization." + }, + "externalReference": { + "$ref": "#/definitions/externalReference", + "title": "External Reference", + "description": "An External reference provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM." + } + } + } } } } @@ -437,7 +479,7 @@ "standards": { "type": "array", "title": "Standards", - "description": "Defines standards which may consist of regulations, industry or organizational-specific standards, maturity models, and best practices which can be evaluated against or attested to.", + "description": "The list of standards which may consist of regulations, industry or organizational-specific standards, maturity models, best practices, or any other requirements which can be evaluated against or attested to.", "items": { "$ref": "#/definitions/standard" } @@ -4130,7 +4172,7 @@ "standard": { "type": "object", "title": "Standard", - "description": "", + "description": "A standard may consist of regulations, industry or organizational-specific standards, maturity models, best practices, or any other requirements which can be evaluated against or attested to.", "additionalProperties": false, "properties": { "bom-ref": { @@ -4141,31 +4183,30 @@ "name": { "type": "string", "title": "Name", - "description": "The name of the standard" + "description": "The name of the standard. This will often be a shortened, single name of the standard." }, "description": { "type": "string", "title": "Description", - "description": "A description of the standard" + "description": "The description of the standard." }, "version": { "type": "string", "title": "Version", - "description": "A version of the standard" + "description": "The version of the standard." }, "owner": { "type": "string", "title": "Owner", - "description": "The owner of the standard" + "description": "The owner of the standard, often the entity responsible for its release." }, "requirements": { "type": "array", "title": "Requirements", - "description": "The requirements that make up the standard", + "description": "The list of requirements comprising the standard.", "items": { "type": "object", "title": "Requirement", - "description": "", "additionalProperties": false, "properties": { "bom-ref": { @@ -4176,28 +4217,28 @@ "identifier": { "type": "string", "title": "Identifier", - "description": "The identifier used in the standard to identify a specific requirement" + "description": "The unique identifier used in the standard to identify a specific requirement. This should match what is in the standard and should not be the requirements bom-ref." }, "title": { "type": "string", "title": "Title", - "description": "The title of the requirement" + "description": "The title of the requirement." }, "text": { "type": "string", "title": "Text", - "description": "The textual content of the requirement" + "description": "The textual content of the requirement." }, "opencre": { "type": "string", "format": "iri-reference", "title": "OWASP OpenCRE", - "description": "URL to the Common Requirements Enumeration" + "description": "The URL to the corresponding Common Requirements Enumeration (CRE) common requirement identifier." }, "parent": { "$ref": "#/definitions/refLinkType", "title": "Parent BOM Reference", - "description": "The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements." + "description": "The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements. Top-level requirements must not define a parent. Only child requirements should define parents." }, "externalReferences": { "type": "array", @@ -4211,11 +4252,10 @@ "levels": { "type": "array", "title": "Levels", - "description": "", + "description": "The list of levels associated with the standard. Some standards have different levels of compliance.", "items": { "type": "object", "title": "Level", - "description": "", "additionalProperties": false, "properties": { "bom-ref": { @@ -4226,22 +4266,22 @@ "identifier": { "type": "string", "title": "Identifier", - "description": "The identifier used in the standard to identify a specific level" + "description": "The identifier used in the standard to identify a specific level." }, "title": { "type": "string", "title": "Title", - "description": "The title of the level" + "description": "The title of the level." }, "description": { "type": "string", "title": "Description", - "description": "The description of the level" + "description": "The description of the level." }, "requirements": { "type": "array", "title": "Requirements", - "description": "", + "description": "The list of requirement `bom-ref`s that comprise the level.", "items": { "$ref": "#/definitions/refLinkType" } } } From 1fde9ff8868f4a4445704b6531cb02cfcfba351c Mon Sep 17 00:00:00 2001 From: "steve.springett" Date: Tue, 26 Sep 2023 14:49:28 -0500 Subject: [PATCH 10/28] Updates as of todays working group Signed-off-by: steve.springett --- schema/bom-1.6.schema.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 305937ae..6e13682b 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -150,7 +150,7 @@ "summary": { "type": "string", "title": "Summary", - "description": "" + "description": "The short description explaining the main points of the attestation." }, "assessor": { "$ref": "#/definitions/refLinkType", @@ -193,7 +193,7 @@ "minimum": 0, "maximum": 1, "title": "Score", - "description": "The conformance of the claim within [0,1], where 1 is 100% confidence." + "description": "The conformance of the claim between and inclusive of 0 and 1, where 1 is 100% confidence." }, "rationale": { "type": "string", @@ -219,7 +219,7 @@ "minimum": 0, "maximum": 1, "title": "Score", - "description": "The confidence of the claim within [0,1], where 1 is 100% confidence." + "description": "The confidence of the claim between and inclusive of 0 and 1, where 1 is 100% confidence." }, "rationale": { "type": "string", @@ -312,10 +312,10 @@ "title": "BOM Reference", "description": "An optional identifier which can be used to reference the object elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." }, - "type": { + "propertyName": { "type": "string", "title": "Type", - "description": "TODO - make this extensible - see valid-attestations-1.6.json for notes" + "description": "The reference to the property name as defined in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy/). " }, "description": { "type": "string", From d854c03ae6283cc157331ce1fcd7f7a97bc2273f Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Tue, 3 Oct 2023 22:40:23 -0500 Subject: [PATCH 11/28] Added properties and description array as a result of todays meeting Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 305937ae..cee16af7 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -4229,6 +4229,12 @@ "title": "Text", "description": "The textual content of the requirement." }, + "descriptions": { + "type": "array", + "title": "Descriptions", + "description": "The supplemental text that provides additional guidance or context to the requirement, but is not directly part of the requirement.", + "items": { "type": "string" } + }, "opencre": { "type": "string", "format": "iri-reference", @@ -4240,6 +4246,14 @@ "title": "Parent BOM Reference", "description": "The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements. Top-level requirements must not define a parent. Only child requirements should define parents." }, + "properties": { + "type": "array", + "title": "Properties", + "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is OPTIONAL.", + "items": { + "$ref": "#/definitions/property" + } + }, "externalReferences": { "type": "array", "items": {"$ref": "#/definitions/externalReference"}, From f3d54daa2f6f3cc480124e4c667bb594a941c756 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Mon, 9 Oct 2023 22:26:14 -0500 Subject: [PATCH 12/28] Updated CRE support based on conversation with CRE project. Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index dd86287c..46248ee7 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -4236,10 +4236,14 @@ "items": { "type": "string" } }, "opencre": { - "type": "string", - "format": "iri-reference", - "title": "OWASP OpenCRE", - "description": "The URL to the corresponding Common Requirements Enumeration (CRE) common requirement identifier." + "type": "array", + "title": "OWASP OpenCRE Identifier(s)", + "description": "The Common Requirements Enumeration (CRE) identifier(s). CRE is a structured and standardized framework for uniting security standards and guidelines. CRE links each section of a resource to a shared topic identifier (a Common Requirement). Through this shared topic link, all resources map to each other. Use of CRE promotes clear and unambiguous communication among stakeholders.", + "items": { + "type": "string", + "pattern": "^CRE:[0-9]+-[0-9]+$", + "examples": [ "CRE:764-507" ] + } }, "parent": { "$ref": "#/definitions/refLinkType", From 8af880d5f2ba0a107de88a920a76cedd5ba75083 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 16 Dec 2023 12:43:22 +0100 Subject: [PATCH 13/28] chore(deps): bump actions/upload-artifact from 3 to 4 (#358) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 3 to 4.
Release notes

Sourced from actions/upload-artifact's releases.

v4.0.0

What's Changed

The release of upload-artifact@v4 and download-artifact@v4 are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements.

For more information, see the @​actions/artifact documentation.

New Contributors

Full Changelog: https://github.com/actions/upload-artifact/compare/v3...v4.0.0

v3.1.3

What's Changed

Full Changelog: https://github.com/actions/upload-artifact/compare/v3...v3.1.3

v3.1.2

  • Update all @actions/* NPM packages to their latest versions- #374
  • Update all dev dependencies to their most recent versions - #375

v3.1.1

  • Update actions/core package to latest version to remove set-output deprecation warning #351

v3.1.0

What's Changed

Commits

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=actions/upload-artifact&package-manager=github_actions&previous-version=3&new-version=4)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) ---
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build_docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index a1747b34..f59c0ec4 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -29,7 +29,7 @@ jobs: run: ./gen.sh - name: Archive Schema documentation # https://github.com/actions/upload-artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: XML-Schema-documentation path: docgen/xml/docs @@ -53,7 +53,7 @@ jobs: run: ./gen.sh - name: Archive Schema documentation # https://github.com/actions/upload-artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: JSON-Schema-documentation path: docgen/json/docs From 29a9a7d7d831d634a912ac548de74bae5c41dbf8 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Thu, 21 Dec 2023 16:54:47 -0600 Subject: [PATCH 14/28] Added attestation support to XSD and added JSON and XML test cases. Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 111 +- schema/bom-1.6.xsd | 991 ++++++++++++++++-- .../resources/1.6/valid-attestation-1.6.json | 209 ++++ .../resources/1.6/valid-attestation-1.6.xml | 165 +++ 4 files changed, 1370 insertions(+), 106 deletions(-) create mode 100644 tools/src/test/resources/1.6/valid-attestation-1.6.json create mode 100644 tools/src/test/resources/1.6/valid-attestation-1.6.xml diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 76d0ef02..7ed54830 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -118,7 +118,7 @@ "items": { "type": "object", "title": "Assessor", - "description": "", + "description": "The assessor who evaluates claims and determines conformance to requirements and confidence in that assessment.", "additionalProperties": false, "properties": { "bom-ref": { @@ -160,7 +160,7 @@ "map": { "type": "array", "title": "Map", - "description": "The grouping of requirements to claims and the attestors declaired conformance and confidence thereof.", + "description": "The grouping of requirements to claims and the attestors declared conformance and confidence thereof.", "items": { "type": "object", "additionalProperties": false, @@ -193,17 +193,17 @@ "minimum": 0, "maximum": 1, "title": "Score", - "description": "The conformance of the claim between and inclusive of 0 and 1, where 1 is 100% confidence." + "description": "The conformance of the claim between and inclusive of 0 and 1, where 1 is 100% conformance." }, "rationale": { "type": "string", "title": "Rationale", - "description": "The rationale for the score of conformance." + "description": "The rationale for the conformance score." }, - "mitigationStrategy": { + "mitigationStrategies": { "type": "array", - "title": "Mitigation Strategy", - "description": "The description of the mitigation strategy if conformance is not `1`.", + "title": "Mitigation Strategies", + "description": "The list of `bom-ref` to the evidence provided describing the mitigation strategies.", "items": { "$ref": "#/definitions/refLinkType" } } } @@ -262,10 +262,10 @@ "title": "Predicate", "description": "The specific statement or assertion about the target." }, - "mitigationStrategy": { + "mitigationStrategies": { "type": "array", - "title": "Mitigation Strategy", - "description": "The written explanation of how any weaknesses in the evidence will be mitigated.", + "title": "Mitigation Strategies", + "description": "The list of `bom-ref` to the evidence provided describing the mitigation strategies. Each mitigation strategy should include an explanation of how any weaknesses in the evidence will be mitigated.", "items": { "$ref": "#/definitions/refLinkType" } }, "reasoning": { @@ -276,13 +276,13 @@ "evidence": { "type": "array", "title": "Evidence", - "description": "The array of references to evidence that supports this claim.", + "description": "The list of `bom-ref` to evidence that supports this claim.", "items": { "$ref": "#/definitions/refLinkType" } }, "counterEvidence": { "type": "array", "title": "Counter Evidence", - "description": "The array of references to counterEvidence that undermines this claim.", + "description": "The list of `bom-ref` to counterEvidence that supports this claim.", "items": { "$ref": "#/definitions/refLinkType" } }, "externalReferences": { @@ -302,7 +302,7 @@ "evidence": { "type": "array", "title": "Evidence", - "description": "The list of evidence.", + "description": "The list of evidence", "items": { "type": "object", "additionalProperties": false, @@ -315,7 +315,7 @@ "propertyName": { "type": "string", "title": "Type", - "description": "The reference to the property name as defined in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy/). " + "description": "The reference to the property name as defined in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy/)." }, "description": { "type": "string", @@ -323,28 +323,49 @@ "description": "The written description of what this evidence is and how it was created." }, "data": { - "type": "object", - "title": "Description", + "type": "array", + "title": "Data", "description": "The output or analysis that supports claims.", - "additionalProperties": false, - "properties": { - "contents": { - "type": "object", - "title": "Data Contents", - "description": "The contents or references to the contents of the data being described.", - "additionalProperties": false, - "properties": { - "attachment": { - "title": "Data Attachment", - "description": "The optional way to include textual or encoded data.", - "$ref": "#/definitions/attachment" - }, - "url": { - "type": "string", - "title": "Data URL", - "description": "The URL where the data can be retrieved.", - "format": "iri-reference" + "items": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "description": "The name of the data.", + "type": "string" + }, + "contents": { + "type": "object", + "title": "Data Contents", + "description": "The contents or references to the contents of the data being described.", + "additionalProperties": false, + "properties": { + "attachment": { + "title": "Data Attachment", + "description": "An optional way to include textual or encoded data.", + "$ref": "#/definitions/attachment" + }, + "url": { + "type": "string", + "title": "Data URL", + "description": "The URL to where the data can be retrieved.", + "format": "iri-reference" + } } + }, + "classification": { + "$ref": "#/definitions/dataClassification" + }, + "sensitiveData": { + "type": "array", + "description": "A description of any sensitive data included.", + "items": { + "type": "string" + } + }, + "governance": { + "title": "Data Governance", + "$ref": "#/definitions/dataGovernance" } } } @@ -391,12 +412,6 @@ "description": "The list of organizations which claims are made against.", "items": {"$ref": "#/definitions/organizationalEntity"} }, - "people": { - "type": "array", - "title": "People", - "description": "The list of individuals which claims are made against.", - "items": {"$ref": "#/definitions/organizationalContact"} - }, "components": { "type": "array", "title": "Components", @@ -465,15 +480,25 @@ } } } + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." } } + }, + "signature": { + "$ref": "#/definitions/signature", + "title": "Signature", + "description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)." } } }, "definitions": { "type": "object", "title": "Definitions", - "description": "", + "description": "A collection of reusable objects that are defined and may be used elsewhere in the BOM.", "additionalProperties": false, "properties": { "standards": { @@ -1551,7 +1576,7 @@ "type": { "type": "string", "title": "Type", - "description": "Specifies the type of external reference.\n\n* __vcs__ = Version Control System\n* __issue-tracker__ = Issue or defect tracking system, or an Application Lifecycle Management (ALM) system\n* __website__ = Website\n* __advisories__ = Security advisories\n* __bom__ = Bill of Materials (SBOM, OBOM, HBOM, SaaSBOM, etc)\n* __mailing-list__ = Mailing list or discussion group\n* __social__ = Social media account\n* __chat__ = Real-time chat platform\n* __documentation__ = Documentation, guides, or how-to instructions\n* __support__ = Community or commercial support\n* __distribution__ = Direct or repository download location\n* __distribution-intake__ = The location where a component was published to. This is often the same as \"distribution\" but may also include specialized publishing processes that act as an intermediary\n* __license__ = The URL to the license file. If a license URL has been defined in the license node, it should also be defined as an external reference for completeness\n* __build-meta__ = Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, etc)\n* __build-system__ = URL to an automated build system\n* __release-notes__ = URL to release notes\n* __security-contact__ = Specifies a way to contact the maintainer, supplier, or provider in the event of a security incident. Common URIs include links to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies the records containing DNS Security TXT\n* __model-card__ = A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets used to train the model, performance metrics, and other relevant data useful for ML transparency\n* __log__ = A record of events that occurred in a computer system or application, such as problems, errors, or information on current operations\n* __configuration__ = Parameters or settings that may be used by other components or services\n* __evidence__ = Information used to substantiate a claim\n* __formulation__ = Describes how a component or service was manufactured or deployed\n* __attestation__ = Human or machine-readable statements containing facts, evidence, or testimony\n* __threat-model__ = An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format\n* __adversary-model__ = The defined assumptions, goals, and capabilities of an adversary.\n* __risk-assessment__ = Identifies and analyzes the potential of future events that may negatively impact individuals, assets, and/or the environment. Risk assessments may also include judgments on the tolerability of each risk.\n* __vulnerability-assertion__ = A Vulnerability Disclosure Report (VDR) which asserts the known and previously unknown vulnerabilities that affect a component, service, or product including the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on a component, service, or product.\n* __exploitability-statement__ = A Vulnerability Exploitability eXchange (VEX) which asserts the known vulnerabilities that do not affect a product, product family, or organization, and optionally the ones that do. The VEX should include the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on the product, product family, or organization.\n* __pentest-report__ = Results from an authorized simulated cyberattack on a component or service, otherwise known as a penetration test\n* __static-analysis-report__ = SARIF or proprietary machine or human-readable report for which static analysis has identified code quality, security, and other potential issues with the source code\n* __dynamic-analysis-report__ = Dynamic analysis report that has identified issues such as vulnerabilities and misconfigurations\n* __runtime-analysis-report__ = Report generated by analyzing the call stack of a running application\n* __component-analysis-report__ = Report generated by Software Composition Analysis (SCA), container analysis, or other forms of component analysis\n* __maturity-report__ = Report containing a formal assessment of an organization, business unit, or team against a maturity model\n* __certification-report__ = Industry, regulatory, or other certification from an accredited (if applicable) certification body\n* __quality-metrics__ = Report or system in which quality metrics can be obtained\n* __codified-infrastructure__ = Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC)\n* __poam__ = Plans of Action and Milestones (POAM) compliment an \"attestation\" external reference. POAM is defined by NIST as a \"document that identifies tasks needing to be accomplished. It details resources required to accomplish the elements of the plan, any milestones in meeting the tasks and scheduled completion dates for the milestones\".\n* __other__ = Use this if no other types accurately describe the purpose of the external reference", + "description": "Specifies the type of external reference.\n\n* __vcs__ = Version Control System\n* __issue-tracker__ = Issue or defect tracking system, or an Application Lifecycle Management (ALM) system\n* __website__ = Website\n* __advisories__ = Security advisories\n* __bom__ = Bill of Materials (SBOM, OBOM, HBOM, SaaSBOM, etc)\n* __mailing-list__ = Mailing list or discussion group\n* __social__ = Social media account\n* __chat__ = Real-time chat platform\n* __documentation__ = Documentation, guides, or how-to instructions\n* __support__ = Community or commercial support\n* __distribution__ = Direct or repository download location\n* __distribution-intake__ = The location where a component was published to. This is often the same as \"distribution\" but may also include specialized publishing processes that act as an intermediary\n* __license__ = The URL to the license file. If a license URL has been defined in the license node, it should also be defined as an external reference for completeness\n* __build-meta__ = Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, etc)\n* __build-system__ = URL to an automated build system\n* __release-notes__ = URL to release notes\n* __security-contact__ = Specifies a way to contact the maintainer, supplier, or provider in the event of a security incident. Common URIs include links to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies the records containing DNS Security TXT\n* __model-card__ = A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets used to train the model, performance metrics, and other relevant data useful for ML transparency\n* __log__ = A record of events that occurred in a computer system or application, such as problems, errors, or information on current operations\n* __configuration__ = Parameters or settings that may be used by other components or services\n* __evidence__ = Information used to substantiate a claim\n* __formulation__ = Describes how a component or service was manufactured or deployed\n* __attestation__ = Human or machine-readable statements containing facts, evidence, or testimony\n* __threat-model__ = An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format\n* __adversary-model__ = The defined assumptions, goals, and capabilities of an adversary.\n* __risk-assessment__ = Identifies and analyzes the potential of future events that may negatively impact individuals, assets, and/or the environment. Risk assessments may also include judgments on the tolerability of each risk.\n* __vulnerability-assertion__ = A Vulnerability Disclosure Report (VDR) which asserts the known and previously unknown vulnerabilities that affect a component, service, or product including the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on a component, service, or product.\n* __exploitability-statement__ = A Vulnerability Exploitability eXchange (VEX) which asserts the known vulnerabilities that do not affect a product, product family, or organization, and optionally the ones that do. The VEX should include the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on the product, product family, or organization.\n* __pentest-report__ = Results from an authorized simulated cyberattack on a component or service, otherwise known as a penetration test\n* __static-analysis-report__ = SARIF or proprietary machine or human-readable report for which static analysis has identified code quality, security, and other potential issues with the source code\n* __dynamic-analysis-report__ = Dynamic analysis report that has identified issues such as vulnerabilities and misconfigurations\n* __runtime-analysis-report__ = Report generated by analyzing the call stack of a running application\n* __component-analysis-report__ = Report generated by Software Composition Analysis (SCA), container analysis, or other forms of component analysis\n* __maturity-report__ = Report containing a formal assessment of an organization, business unit, or team against a maturity model\n* __certification-report__ = Industry, regulatory, or other certification from an accredited (if applicable) certification body\n* __quality-metrics__ = Report or system in which quality metrics can be obtained\n* __codified-infrastructure__ = Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC)\n* __poam__ = Plans of Action and Milestones (POAM) compliment an \"attestation\" external reference. POAM is defined by NIST as a \"document that identifies tasks needing to be accomplished. It details resources required to accomplish the elements of the plan, any milestones in meeting the tasks and scheduled completion dates for the milestones\".\n* __electronic-signature__ An e-signature is commonly a scanned representation of a written signature or a stylized script of the persons name.\n* __digital-signature__ = A signature that leverages cryptography, typically public/private key pairs, which provides strong authenticity verification.\n* __other__ = Use this if no other types accurately describe the purpose of the external reference", "enum": [ "vcs", "issue-tracker", @@ -1591,6 +1616,8 @@ "codified-infrastructure", "quality-metrics", "poam", + "electronic-signature", + "digital-signature", "other" ] }, diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index 5e218c47..51ed8658 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -1402,6 +1402,16 @@ limitations under the License. Plans of Action and Milestones (POAM) compliment an "attestation" external reference. POAM is defined by NIST as a "document that identifies tasks needing to be accomplished. It details resources required to accomplish the elements of the plan, any milestones in meeting the tasks and scheduled completion dates for the milestones". + + + An e-signature is commonly a scanned representation of a written signature or a stylized script of the persons name. + + + + + A signature that leverages cryptography, typically public/private key pairs, which provides strong authenticity verification. + + Use this if no other types accurately describe the purpose of the external reference @@ -5402,70 +5412,923 @@ limitations under the License. - - - - - - Provides additional information about a BOM. - - - - - A list of software and hardware components. - - - - - A list of services. This may include microservices, function-as-a-service, and other types of network or intra-process services. - - - - - Provides the ability to document external references related to the BOM or - to the project the BOM describes. - - - - - Provides the ability to document dependency relationships. - - - - - Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness. The completeness of vulnerabilities expressed in a BOM may also be described. - - - - - Provides the ability to document properties in a name/value store. - This provides flexibility to include data not officially supported in the standard - without having to use additional namespaces or create extensions. Property names - of interest to the general public are encouraged to be registered in the - CycloneDX Property Taxonomy - https://github.com/CycloneDX/cyclonedx-property-taxonomy. - Formal registration is OPTIONAL. - - - - - Vulnerabilities identified in components or services. - - - - - Comments made by people, organizations, or tools about any object with - a bom-ref, such as components, services, vulnerabilities, or the BOM itself. Unlike - inventory information, annotations may contain opinion or commentary from various - stakeholders. Annotations may be inline (with inventory) or externalized via BOM-Link, - and may optionally be signed. - - - - - Describes how a component or service was manufactured or deployed. This is - achieved through the use of formulas, workflows, tasks, and steps, which declare the precise - steps to reproduce along with the observed formulas describing the steps which transpired - in the manufacturing process. + + + + + + The list of assessors evaluating claims and determining conformance to requirements and confidence in that assessment. + + + + + + + + The assessor who evaluates claims and determines conformance to requirements and confidence in that assessment. + + + + + + + + The boolean indicating if the assessor is outside the organization generating claims. A value of false indicates a self assessor. + + + + + + + The entity issuing the assessment. + + + + + + + + An optional identifier which can be used to reference the object elsewhere in the BOM. + Every bom-ref MUST be unique within the BOM. + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + + + + + + + + + + The list of attestations asserted by an assessor that maps requirements to claims. + + + + + + + + An attestation asserted by an assessor that maps requirements to claims. + + + + + + + + The short description explaining the main points of the attestation. + + + + + + + The `bom-ref` to the assessor asserting the attestation. + + + + + + + The grouping of requirements to claims and the attestors declared conformance and confidence thereof. + + + + + + + + The `bom-ref` to the requirement being attested to. + + + + + + + The list of `bom-ref` to the claims being attested to. + + + + + + + + The `bom-ref` to the claim being attested to. + + + + + + + + + + The list of `bom-ref` to the counter claims being attested to. + + + + + + + + The `bom-ref` to the counter claim being attested to. + + + + + + + + + + The conformance of the claim meeting a requirement. + + + + + + + + The conformance of the claim between and inclusive of 0 and 1, where 1 is 100% conformance. + + + + + + + + + + + + + The rationale for the score of conformance. + + + + + + + The list of `bom-ref` to the evidence provided describing the + mitigation strategies. Each mitigation strategy should include an + explanation of how any weaknesses in the evidence will be mitigated. + + + + + + + + + + + + + + + The confidence of the claim meeting the requirement. + + + + + + + + The confidence of the claim between and inclusive of 0 and 1, where 1 is 100% confidence. + + + + + + + + + + + + + The rationale for the confidence score. + + + + + + + + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + + + + + + The list of claims. + + + + + + + + + + + The `bom-ref` to a target representing a specific system, application, + API, module, team, person, process, business unit, company, etc... + that this claim is being applied to. + + + + + + + The specific statement or assertion about the target. + + + + + + + The list of `bom-ref` to the evidence provided describing the + mitigation strategies. Each mitigation strategy should include an + explanation of how any weaknesses in the evidence will be mitigated. + + + + + + + + + + + + The written explanation of why the evidence provided substantiates the claim. + + + + + + + The list of `bom-ref` to evidence that supports this claim. + + + + + + + The list of `bom-ref` to counterEvidence that supports this claim. + + + + + + Provides the ability to document external references related to the claim the BOM describes. + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + An optional identifier which can be used to reference the object elsewhere + in the BOM. Every bom-ref MUST be unique within the BOM. + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + + + + + + + + + + The list of evidence + + + + + + + + The list of evidence + + + + + + + + The reference to the property name as defined in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy/). + + + + + + + The written description of what this evidence is and how it was created. + + + + + + + The output or analysis that supports claims. + + + + + + + + The name of the data. + + + + + + + The contents or references to the contents of the data being described. + + + + + + + An optional way to include textual or encoded data. + + + + + The URL to where the data can be retrieved. + + + + + + + + + Data classification tags data according to its type, sensitivity, and value if altered, stolen, or destroyed. + + + + + + + A description of any sensitive data. + + + + + + + + + + The date and time (timestamp) when the evidence was created. + + + + + The optional date and time (timestamp) when the evidence is no longer valid. + + + + + The author of the evidence. + + + + + The reviewer of the evidence. + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + An optional identifier which can be used to reference the object elsewhere + in the BOM. Every bom-ref MUST be unique within the BOM. + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + + + + + + + + + + The list of targets which claims are made against. + + + + + + + + The list of organizations which claims are made against. + + + + + + + + + + + + The list of components which claims are made against. + + + + + + + + + + + + The list of services which claims are made against. + + + + + + + + + + + + + + + + + + The brief statement affirmed by an individual regarding all declarations. + This could be an affirmation of acceptance by a third-party auditor or receiving + individual of a file. For example: "I certify, to the best of my knowledge, that all information is correct." + + + + + + + The list of signatories authorized on behalf of an organization to assert validity of this document. + + + + + + + + + + + The signatory's name. + + + + + + + The signatory's role within an organization. + + + + + + + The signatory's organization. + + + + + + + An External reference provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM. + + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + + + A collection of reusable objects that are defined and may be used elsewhere in the BOM. + + + + + + + + + + + The list of standards which may consist of regulations, industry or organizational-specific standards, maturity models, best practices, or any other requirements which can be evaluated against or attested to. + + + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + + + + + + + A standard may consist of regulations, industry or organizational-specific standards, maturity models, best practices, or any other requirements which can be evaluated against or attested to. + + + + + + + The name of the standard. This will often be a shortened, single name of the standard. + + + + + + + The description of the standard. + + + + + + + The version of the standard. + + + + + + + The owner of the standard, often the entity responsible for its release. + + + + + + + The list of requirements comprising the standard. + + + + + + + + + + + The unique identifier used in the standard to identify a specific requirement. This should match what is in the standard and should not be the requirements bom-ref. + + + + + + + The title of the requirement. + + + + + + + The textual content of the requirement. + + + + + + + The supplemental text that provides additional guidance or context to the requirement, but is not directly part of the requirement. + + + + + + + + + + + + The Common Requirements Enumeration (CRE) identifier(s). CRE is a structured and standardized framework for uniting security standards and guidelines. CRE links each section of a resource to a shared topic identifier (a Common Requirement). Through this shared topic link, all resources map to each other. Use of CRE promotes clear and unambiguous communication among stakeholders. + + + + + + + + + + + + The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements. Top-level requirements must not define a parent. Only child requirements should define parents. + + + + + + Provides the ability to document properties in a name/value store. + This provides flexibility to include data not officially supported in the standard + without having to use additional namespaces or create extensions. Property names + of interest to the general public are encouraged to be registered in the + CycloneDX Property Taxonomy - https://github.com/CycloneDX/cyclonedx-property-taxonomy. + Formal registration is OPTIONAL. + + + + + Provides the ability to document external references related to the BOM or + to the project the BOM describes. + + + + + + + An optional identifier which can be used to reference the object elsewhere + in the BOM. Every bom-ref MUST be unique within the BOM. + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + + + + + + + + + + The list of levels associated with the standard. Some standards have different levels of compliance. + + + + + + + + The identifier used in the standard to identify a specific level. + + + + + + + The title of the level. + + + + + + + The description of the level. + + + + + + + The list of requirement `bom-ref`s that comprise the level. + + + + + + + + + + + + + An optional identifier which can be used to reference the object elsewhere + in the BOM. Every bom-ref MUST be unique within the BOM. + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + + + + + + Provides the ability to document external references related to the BOM or + to the project the BOM describes. + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + An optional identifier which can be used to reference the object elsewhere + in the BOM. Every bom-ref MUST be unique within the BOM. + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + + + + + + + + + Provides additional information about a BOM. + + + + + A list of software and hardware components. + + + + + A list of services. This may include microservices, function-as-a-service, and other types of network or intra-process services. + + + + + Provides the ability to document external references related to the BOM or + to the project the BOM describes. + + + + + Provides the ability to document dependency relationships. + + + + + Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness. The completeness of vulnerabilities expressed in a BOM may also be described. + + + + + Provides the ability to document properties in a name/value store. + This provides flexibility to include data not officially supported in the standard + without having to use additional namespaces or create extensions. Property names + of interest to the general public are encouraged to be registered in the + CycloneDX Property Taxonomy - https://github.com/CycloneDX/cyclonedx-property-taxonomy. + Formal registration is OPTIONAL. + + + + + Vulnerabilities identified in components or services. + + + + + Comments made by people, organizations, or tools about any object with + a bom-ref, such as components, services, vulnerabilities, or the BOM itself. Unlike + inventory information, annotations may contain opinion or commentary from various + stakeholders. Annotations may be inline (with inventory) or externalized via BOM-Link, + and may optionally be signed. + + + + + Describes how a component or service was manufactured or deployed. This is + achieved through the use of formulas, workflows, tasks, and steps, which declare the precise + steps to reproduce along with the observed formulas describing the steps which transpired + in the manufacturing process. + + + + + + The list of declarations which describe the conformance to standards. Each declaration may + include attestations, claims, and evidence. + + + + + + + A collection of reusable objects that are defined and may be used elsewhere in the BOM. + diff --git a/tools/src/test/resources/1.6/valid-attestation-1.6.json b/tools/src/test/resources/1.6/valid-attestation-1.6.json new file mode 100644 index 00000000..c270d49b --- /dev/null +++ b/tools/src/test/resources/1.6/valid-attestation-1.6.json @@ -0,0 +1,209 @@ +{ + "bomFormat": "CycloneDX", + "specVersion": "1.6", + "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79", + "version": 1, + "declarations": { + "assessors": [ + { + "bom-ref": "assessor-1", + "thirdParty": true, + "organization": { + "name": "Assessors Inc" + } + } + ], + "attestations": [ + { + "summary": "Attestation summary here", + "assessor": "assessor-1", + "map": [ + { + "requirement": "requirement-1", + "claims": [ "claim-1" ], + "counterClaims": [ "counterClaim-1" ], + "conformance": { + "score": 0.8, + "rationale": "Conformance rationale here", + "mitigationStrategies": [ "mitigationStrategy-1" ] + }, + "confidence": { + "score": 1, + "rationale": "Confidence rationale here" + } + } + ], + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } + ], + "claims": [ + { + "bom-ref": "claim-1", + "target": "acme-inc", + "predicate": "Predicate here", + "mitigationStrategies": [ "mitigationStrategy-1" ], + "reasoning": "Reasoning here", + "evidence": [ "evidence-1" ], + "counterEvidence": [ "counterEvidence-1" ], + "externalReferences": [ + { + "type": "issue-tracker", + "url": "https://alm.example.com" + } + ], + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } + ], + "evidence": [ + { + "bom-ref": "evidence-1", + "propertyName": "internal.com.acme.someProperty", + "description": "Description here", + "data": [ + { + "name": "Name of the data", + "contents": { + "attachment": { + "content": "Evidence here", + "contentType": "text/plain" + } + }, + "classification": "PII", + "sensitiveData": [ "Describe sensitive data here" ] + } + ], + "created": "2023-04-25T00:00:00+00:00", + "expires": "2023-05-25T00:00:00+00:00", + "author": { + "name": "Mary" + }, + "reviewer": { + "name": "Jane" + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + { + "bom-ref": "counterEvidence-1", + "propertyName": "internal.com.acme.someProperty", + "description": "Description here", + "data": [ + { + "name": "Name of the data", + "contents": { + "attachment": { + "content": "Counter evidence here", + "contentType": "text/plain" + } + }, + "classification": "Pubic", + "sensitiveData": [ "Describe sensitive data here" ] + } + ], + "created": "2023-04-25T00:00:00+00:00", + "expires": "2023-05-25T00:00:00+00:00", + "author": { + "name": "Mary" + }, + "reviewer": { + "name": "Jane" + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + { + "bom-ref": "mitigationStrategy-1", + "propertyName": "internal.com.acme.someProperty", + "description": "Description here", + "data": [ + { + "name": "Name of the data", + "contents": { + "attachment": { + "content": "Mitigation strategy here", + "contentType": "text/plain" + } + }, + "classification": "Company Confidential", + "sensitiveData": [ "Describe sensitive data here" ] + } + ], + "created": "2023-04-25T00:00:00+00:00", + "expires": "2023-05-25T00:00:00+00:00", + "author": { + "name": "Mary" + }, + "reviewer": { + "name": "Jane" + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } + ], + "targets": { + "organizations": [ + { + "bom-ref": "acme-inc", + "name": "Acme Inc" + } + ] + }, + "affirmation": { + "statement": "I certify, to the best of my knowledge, that all information is correct...", + "signatories": [ + { + "name": "Tom", + "role": "CEO", + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + { + "name": "Jerry", + "role": "COO", + "organization": { + "name": "Acme Inc" + }, + "externalReference": { + "type": "electronic-signature", + "url": "https://example.com/coo-sig.png" + } + } + ], + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } +} \ No newline at end of file diff --git a/tools/src/test/resources/1.6/valid-attestation-1.6.xml b/tools/src/test/resources/1.6/valid-attestation-1.6.xml new file mode 100644 index 00000000..1dce0ced --- /dev/null +++ b/tools/src/test/resources/1.6/valid-attestation-1.6.xml @@ -0,0 +1,165 @@ + + + + + + false + + Acme Inc + + + + + + Attestation summary here + assessor-1 + + requirement-1 + + claim-1 + + + counterClaim-1 + + + 0.8 + Conformance rationale here + + mitigations-1 + + + + 1 + Confidence rationale here + + + + + + + + + + acme-inc + Predicate here + + mitigationStrategy-1 + + Reasoning here + evidence-1 + counterEvidence-1 + + + https://alm.example.com + + + + + + + + + + internal.com.acme.someProperty + Description here + + Name of the data + + Evidence here + + PII + Describe sensitive data here + + 2023-04-25T00:00:00+00:00 + 2023-05-25T00:00:00+00:00 + + Mary + + + Jane + + + + + + + internal.com.acme.someProperty + Description here + + Name of the data + + Counter evidence here + + Public + Describe sensitive data here + + 2023-04-25T00:00:00+00:00 + 2023-05-25T00:00:00+00:00 + + Mary + + + Jane + + + + internal.com.acme.someProperty + Description here + + Name of the data + + Mitigation strategy here + + Public + Describe sensitive data here + + 2023-04-25T00:00:00+00:00 + 2023-05-25T00:00:00+00:00 + + Mary + + + Jane + + + + + + + Acme Inc + + + + + I certify, to the best of my knowledge, that all information is correct... + + + Tom + CEO + + + + + + Jerry + COO + + Acme Inc + + + https://example.com/coo-sig.png + + + + + + + + + + + + + + + \ No newline at end of file From 5be18a145aec7999776f5acbce2ce62516f9708e Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Thu, 21 Dec 2023 17:58:35 -0600 Subject: [PATCH 15/28] Added valid standard JSON and XML test cases and minor corrections to schemas. Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 10 +- schema/bom-1.6.xsd | 98 ++++++++++--------- .../resources/1.6/valid-standard-1.6.json | 73 ++++++++++++++ 3 files changed, 130 insertions(+), 51 deletions(-) create mode 100644 tools/src/test/resources/1.6/valid-standard-1.6.json diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 7ed54830..f9fcc6b4 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -4231,16 +4231,16 @@ "title": "Name", "description": "The name of the standard. This will often be a shortened, single name of the standard." }, - "description": { - "type": "string", - "title": "Description", - "description": "The description of the standard." - }, "version": { "type": "string", "title": "Version", "description": "The version of the standard." }, + "description": { + "type": "string", + "title": "Description", + "description": "The description of the standard." + }, "owner": { "type": "string", "title": "Owner", diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index 51ed8658..05748c18 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -6042,17 +6042,17 @@ limitations under the License. - + - The description of the standard. + The version of the standard. - + - The version of the standard. + The description of the standard. @@ -6170,54 +6170,60 @@ limitations under the License. - - - - The identifier used in the standard to identify a specific level. - - - - - - - The title of the level. - - - - - - - The description of the level. - - - - - - - The list of requirement `bom-ref`s that comprise the level. - - + - + + + + The identifier used in the standard to identify a specific level. + + + + + + + The title of the level. + + + + + + + The description of the level. + + + + + + + The list of requirement `bom-ref`s that comprise the level. + + + + + + + + + + + + An optional identifier which can be used to reference the object elsewhere + in the BOM. Every bom-ref MUST be unique within the BOM. + + + + + + User-defined attributes may be used on this element as long as they + do not have the same name as an existing attribute used by the schema. + + - - - - An optional identifier which can be used to reference the object elsewhere - in the BOM. Every bom-ref MUST be unique within the BOM. - - - - - - User-defined attributes may be used on this element as long as they - do not have the same name as an existing attribute used by the schema. - - diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.json b/tools/src/test/resources/1.6/valid-standard-1.6.json new file mode 100644 index 00000000..b7b1e5fd --- /dev/null +++ b/tools/src/test/resources/1.6/valid-standard-1.6.json @@ -0,0 +1,73 @@ +{ + "bomFormat": "CycloneDX", + "specVersion": "1.6", + "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79", + "version": 1, + "definitions": { + "standards": [ + { + "bom-ref": "standard-1", + "name": "Sample Standard", + "version": "1.0.0", + "description": "Description here", + "owner": "Acme Inc", + "requirements": [ + { + "bom-ref": "requirement-1", + "identifier": "v1", + "title": "Title here" + }, + { + "bom-ref": "requirement-1.1", + "identifier": "v1.1", + "title": "Title here", + "parent": "requirement-1" + }, + { + "bom-ref": "requirement-1.1.1", + "identifier": "v1.1.1", + "text": "Text of the requirement here", + "descriptions": [ + "Supplemental text here" + ], + "opencre": [ + "CRE:616-305" + ], + "parent": "requirement-1.1" + } + ], + "levels": [ + { + "bom-ref": "level-1", + "identifier": "Level 1", + "description": "Description here", + "requirements": [ + "requirement-1.1.1" + ] + }, + { + "bom-ref": "level-2", + "identifier": "Level 2", + "description": "Description here", + "requirements": [ + "requirement-1.1.1" + ] + }, + { + "bom-ref": "level-3", + "identifier": "Level 3", + "description": "Description here", + "requirements": [ + "requirement-1.1.1" + ] + } + ], + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } + ] + } +} \ No newline at end of file From 89c0088cd99174c6ebcb4660db776fd51dd11724 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Thu, 21 Dec 2023 18:02:06 -0600 Subject: [PATCH 16/28] Added valid standard JSON and XML test cases and minor corrections to schemas. Signed-off-by: Steve Springett --- .../test/resources/1.6/valid-standard-1.6.xml | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 tools/src/test/resources/1.6/valid-standard-1.6.xml diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.xml b/tools/src/test/resources/1.6/valid-standard-1.6.xml new file mode 100644 index 00000000..68272488 --- /dev/null +++ b/tools/src/test/resources/1.6/valid-standard-1.6.xml @@ -0,0 +1,59 @@ + + + + + + Sample Standard + 1.0.0 + Description here + Acme Inc + + + v1 + Title here + + + v1.1 + Title here + requirement-1 + + + v1.1.1 + Text of the requirement here + + Supplemental text here + + CRE:616-305 + requirement-1.1.1 + + + + + Level 1 + Description here + + v1.1.1 + + + + Level 2 + Description here + + v1.1.1 + + + + Level 3 + Description here + + v1.1.1 + + + + + + + + + + \ No newline at end of file From c537c581d615b7e8e4ed485ee44c3aafa54de0a6 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Thu, 21 Dec 2023 18:04:25 -0600 Subject: [PATCH 17/28] corrected parent Signed-off-by: Steve Springett --- tools/src/test/resources/1.6/valid-standard-1.6.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.xml b/tools/src/test/resources/1.6/valid-standard-1.6.xml index 68272488..530b3c08 100644 --- a/tools/src/test/resources/1.6/valid-standard-1.6.xml +++ b/tools/src/test/resources/1.6/valid-standard-1.6.xml @@ -24,7 +24,7 @@ Supplemental text here CRE:616-305 - requirement-1.1.1 + requirement-1.1 From 1bac4d62e6016d3e7faf6d4b7310f4e9e8c9b90d Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Thu, 21 Dec 2023 18:05:35 -0600 Subject: [PATCH 18/28] Corrected level ref Signed-off-by: Steve Springett --- tools/src/test/resources/1.6/valid-standard-1.6.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.xml b/tools/src/test/resources/1.6/valid-standard-1.6.xml index 530b3c08..f2cb0119 100644 --- a/tools/src/test/resources/1.6/valid-standard-1.6.xml +++ b/tools/src/test/resources/1.6/valid-standard-1.6.xml @@ -32,21 +32,21 @@ Level 1 Description here - v1.1.1 + requirement-1.1.1 Level 2 Description here - v1.1.1 + requirement-1.1.1 Level 3 Description here - v1.1.1 + requirement-1.1.1 From 423fefe397e1be4b98f6519936d128f70f7690fa Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Tue, 26 Dec 2023 20:15:16 -0600 Subject: [PATCH 19/28] Added protobuf support and test cases Signed-off-by: Steve Springett --- schema/bom-1.6.proto | 197 ++++++++++++++++++ .../1.6/valid-attestation-1.6.textproto | 179 ++++++++++++++++ .../1.6/valid-standard-1.6.textproto | 65 ++++++ 3 files changed, 441 insertions(+) create mode 100644 tools/src/test/resources/1.6/valid-attestation-1.6.textproto create mode 100644 tools/src/test/resources/1.6/valid-standard-1.6.textproto diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index e6a6c4fe..78eb7698 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -39,6 +39,10 @@ message Bom { repeated Property properties = 12; // Describes how a component or service was manufactured or deployed. This is achieved through the use of formulas, workflows, tasks, and steps, which declare the precise steps to reproduce along with the observed formulas describing the steps which transpired in the manufacturing process. repeated Formula formulation = 13; + // The list of declarations which describe the conformance to standards. Each declaration may include attestations, claims, and evidence. + repeated Declarations declarations = 14; + // A collection of reusable objects that are defined and may be used elsewhere in the BOM. + repeated Definition definitions = 15; } enum Classification { @@ -263,6 +267,10 @@ enum ExternalReferenceType { EXTERNAL_REFERENCE_TYPE_EVIDENCE = 36; // Describes how a component or service was manufactured or deployed. EXTERNAL_REFERENCE_TYPE_FORMULATION = 37; + // An e-signature is commonly a scanned representation of a written signature or a stylized script of the persons name. + EXTERNAL_REFERENCE_TYPE_ELECTRONIC_SIGNATURE = 38; + // A signature that leverages cryptography, typically public/private key pairs, which provides strong authenticity verification. + EXTERNAL_REFERENCE_TYPE_DIGITAL_SIGNATURE = 39; } enum HashAlg { @@ -1486,3 +1494,192 @@ message EnvironmentVars { string value = 2; } } + +message Declarations { + message Assessor { + // An optional identifier which can be used to reference the component elsewhere in the BOM. Uniqueness is enforced within all elements and children of the root-level bom element. + optional string bom_ref = 1; + // The boolean indicating if the assessor is outside the organization generating claims. A value of false indicates a self assessor. + optional bool thirdParty = 2; + // The entity issuing the assessment. + optional OrganizationalEntity organization = 3; + } + message Attestation { + message AttestationMap { + message AttestationConformance { + // The conformance of the claim between and inclusive of 0 and 1, where 1 is 100% conformance. + optional double score = 1; + // The rationale for the conformance score. + optional string rationale = 2; + // The list of `bom-ref` to the evidence provided describing the mitigation strategies. + repeated string mitigationStrategies = 3; + } + message AttestationConfidence { + // The confidence of the claim between and inclusive of 0 and 1, where 1 is 100% confidence. + optional double score = 1; + // The rationale for the confidence score. + optional string rationale = 2; + } + // The `bom-ref` to the requirement being attested to. + optional string requirement = 1; + // The list of `bom-ref` to the claims being attested to. + repeated string claims = 2; + // The list of `bom-ref` to the counter claims being attested to. + repeated string counterClaims = 3; + // The conformance of the claim meeting a requirement. + optional AttestationConformance conformance = 4; + // The confidence of the claim meeting the requirement. + optional AttestationConfidence confidence = 5; + } + // The short description explaining the main points of the attestation. + optional string summary = 1; + // The `bom-ref` to the assessor asserting the attestation. + optional string assessor = 2; + // The grouping of requirements to claims and the attestors declared conformance and confidence thereof. + repeated AttestationMap map = 3; + } + message Claim { + // An optional identifier which can be used to reference the component elsewhere in the BOM. Uniqueness is enforced within all elements and children of the root-level bom element. + optional string bom_ref = 1; + // The `bom-ref` to a target representing a specific system, application, API, module, team, person, process, business unit, company, etc... that this claim is being applied to. + optional string target = 2; + // The specific statement or assertion about the target. + optional string predicate = 3; + // The list of `bom-ref` to the evidence provided describing the mitigation strategies. Each mitigation strategy should include an explanation of how any weaknesses in the evidence will be mitigated. + repeated string mitigationStrategies = 4; + // The written explanation of why the evidence provided substantiates the claim. + optional string reasoning = 5; + // The list of `bom-ref` to evidence that supports this claim. + repeated string evidence = 6; + // The list of `bom-ref` to counterEvidence that supports this claim. + repeated string counterEvidence = 7; + // External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM. + repeated ExternalReference externalReferences = 8; + } + message Evidence { + message Data { + message Contents { + // An optional way to include textual or encoded data. + optional AttachedText attachment = 1; + // The URL to where the data can be retrieved. + optional string url = 2; + } + // The name of the data. + optional string name = 1; + // The contents or references to the contents of the data being described. + optional Contents contents = 2; + // Data classification tags data according to its type, sensitivity, and value if altered, stolen, or destroyed. + optional string classification = 3; + // A description of any sensitive data included. + repeated string sensitiveData = 4; + // Data Governance + optional DataGovernance governance = 5; + } + // An optional identifier which can be used to reference the component elsewhere in the BOM. Uniqueness is enforced within all elements and children of the root-level bom element. + optional string bom_ref = 1; + // The reference to the property name as defined in the CycloneDX Property Taxonomy: https://github.com/CycloneDX/cyclonedx-property-taxonomy/. + optional string propertyName = 2; + // The written description of what this evidence is and how it was created. + optional string description = 3; + // The output or analysis that supports claims. + repeated Data data = 4; + // The date and time (timestamp) when the evidence was created. + optional google.protobuf.Timestamp created = 5; + // The optional date and time (timestamp) when the evidence is no longer valid. + optional google.protobuf.Timestamp expires = 6; + // The author of the evidence. + optional OrganizationalContact author = 7; + // The reviewer of the evidence. + optional OrganizationalContact reviewer = 8; + } + message Targets { + // The list of organizations which claims are made against. + repeated OrganizationalEntity organizations = 1; + // The list of components which claims are made against. + repeated Component components = 2; + // The list of services which claims are made against. + repeated Service services = 3; + } + message Affirmation { + message Signatory { + // The signatory's name. + optional string name = 1; + // The signatory's role within an organization. + optional string role = 2; + // The signatory's organization. + optional OrganizationalEntity organization = 3; + // An External reference provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM. + optional ExternalReference externalReference = 4; + } + // The brief statement affirmed by an individual regarding all declarations. Notes: This could be an affirmation of acceptance by a third-party auditor or receiving individual of a file. + optional string statement = 1; + // The list of signatories authorized on behalf of an organization to assert validity of this document. + repeated Signatory signatories = 2; + } + // The list of assessors evaluating claims and determining conformance to requirements and confidence in that assessment. + repeated Assessor assessors = 1; + // The list of attestations asserted by an assessor that maps requirements to claims. + repeated Attestation attestations = 2; + // The list of claims. + repeated Claim claims = 3; + // The list of evidence + repeated Evidence evidence = 4; + // The list of targets which claims are made against. + optional Targets targets = 5; + // affirmation + optional Affirmation affirmation = 6; +} + +message Definition { + message Standard { + message Requirement { + // An optional identifier which can be used to reference the component elsewhere in the BOM. Uniqueness is enforced within all elements and children of the root-level bom element. + optional string bom_ref = 1; + // The unique identifier used in the standard to identify a specific requirement. This should match what is in the standard and should not be the requirements bom-ref. + optional string identifier = 2; + // The title of the requirement. + optional string title = 3; + // The textual content of the requirement. + optional string text = 4; + // The supplemental text that provides additional guidance or context to the requirement, but is not directly part of the requirement. + repeated string descriptions = 5; + // The Common Requirements Enumeration (CRE) identifier(s). CRE is a structured and standardized framework for uniting security standards and guidelines. CRE links each section of a resource to a shared topic identifier (a Common Requirement). Through this shared topic link, all resources map to each other. Use of CRE promotes clear and unambiguous communication among stakeholders. + repeated string opencre = 6; + // The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements. Top-level requirements must not define a parent. Only child requirements should define parents. + optional string parent = 7; + // Specifies optional, custom, properties + repeated Property properties = 8; + // External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM. + repeated ExternalReference externalReferences = 9; + } + message Level { + // An optional identifier which can be used to reference the component elsewhere in the BOM. Uniqueness is enforced within all elements and children of the root-level bom element. + optional string bom_ref = 1; + // The identifier used in the standard to identify a specific level. + optional string identifier = 2; + // The title of the level. + optional string title = 3; + // The description of the level. + optional string description = 4; + // The list of requirement `bom-ref`s that comprise the level. + repeated string requirements = 5; + } + // An optional identifier which can be used to reference the component elsewhere in the BOM. Uniqueness is enforced within all elements and children of the root-level bom element. + optional string bom_ref = 1; + // The name of the standard. This will often be a shortened, single name of the standard. + optional string name = 2; + // The version of the standard. + optional string version = 3; + // The description of the standard. + optional string description = 4; + // The owner of the standard, often the entity responsible for its release. + optional string owner = 5; + // The list of requirements comprising the standard. + repeated Requirement requirements = 6; + // The list of levels associated with the standard. Some standards have different levels of compliance. + repeated Level levels = 7; + // External references provide a way to document systems, sites, and information that may be relevant, but are not included with the BOM. They may also establish specific relationships within or external to the BOM. + repeated ExternalReference externalReferences = 8; + } + repeated Standard standards = 1; +} diff --git a/tools/src/test/resources/1.6/valid-attestation-1.6.textproto b/tools/src/test/resources/1.6/valid-attestation-1.6.textproto new file mode 100644 index 00000000..ca16cf57 --- /dev/null +++ b/tools/src/test/resources/1.6/valid-attestation-1.6.textproto @@ -0,0 +1,179 @@ +spec_version: "1.6" +version: 1 +serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" +declarations: { + assessors: [ + { + bom_ref: "assessor-1" + thirdParty: true + organization: { + name: "Assessors Inc" + } + } + ] + attestations: [ + { + summary: "Attestation summary here" + assessor: "assessor-1" + map: [ + { + requirement: "requirement-1" + claims: [ "claim-1" ] + counterClaims: [ "counterClaim-1" ] + conformance: { + score: 0.8, + rationale: "Conformance rationale here", + mitigationStrategies: [ "mitigationStrategy-1" ] + } + confidence: { + score: 1, + rationale: "Confidence rationale here" + } + } + ] + } + ], + claims: [ + { + bom_ref: "claim-1" + target: "acme-inc" + predicate: "Predicate here" + mitigationStrategies: [ "mitigationStrategy-1" ] + reasoning: "Reasoning here" + evidence: [ "evidence-1" ] + counterEvidence: [ "counterEvidence-1" ] + externalReferences: [ + { + type: EXTERNAL_REFERENCE_TYPE_ISSUE_TRACKER, + url: "https://alm.example.com" + } + ] + } + ] + evidence: [ + { + bom_ref: "evidence-1" + propertyName: "internal.com.acme.someProperty" + description: "Description here" + data: [ + { + name: "Name of the data" + contents: { + attachment: { + content_type: "text/plain" + value: "Evidence here" + } + } + classification: "PII", + sensitiveData: [ "Describe sensitive data here" ] + } + ] + created { + seconds: 1714003200 + nanos: 0 + } + expires { + seconds: 1712102400 + nanos: 0 + } + author: { + name: "Mary" + } + reviewer: { + name: "Jane" + } + }, + { + bom_ref: "counterEvidence-1" + propertyName: "internal.com.acme.someProperty" + description: "Description here" + data: [ + { + name: "Name of the data" + contents: { + attachment: { + content_type: "text/plain" + value: "Counter evidence here" + } + } + classification: "Pubic" + sensitiveData: [ "Describe sensitive data here" ] + } + ] + created { + seconds: 1714003200 + nanos: 0 + } + expires { + seconds: 1712102400 + nanos: 0 + } + author: { + name: "Mary" + } + reviewer: { + name: "Jane" + } + }, + { + bom_ref: "mitigationStrategy-1" + propertyName: "internal.com.acme.someProperty" + description: "Description here" + data: [ + { + name: "Name of the data" + contents: { + attachment: { + content_type: "text/plain" + value: "Mitigation strategy here" + } + } + classification: "Company Confidential" + sensitiveData: [ "Describe sensitive data here" ] + } + ] + created { + seconds: 1714003200 + nanos: 0 + } + expires { + seconds: 1712102400 + nanos: 0 + } + author: { + name: "Mary" + } + reviewer: { + name: "Jane" + } + } + ], + targets: { + organizations: [ + { + bom_ref: "acme-inc" + name: "Acme Inc" + } + ] + } + affirmation: { + statement: "I certify, to the best of my knowledge, that all information is correct..." + signatories: [ + { + name: "Tom" + role: "CEO" + }, + { + name: "Jerry" + role: "COO" + organization: { + name: "Acme Inc" + } + externalReference: { + type: EXTERNAL_REFERENCE_TYPE_ELECTRONIC_SIGNATURE + url: "https://example.com/coo-sig.png" + } + } + ] + } +} \ No newline at end of file diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.textproto b/tools/src/test/resources/1.6/valid-standard-1.6.textproto new file mode 100644 index 00000000..a9a68bc7 --- /dev/null +++ b/tools/src/test/resources/1.6/valid-standard-1.6.textproto @@ -0,0 +1,65 @@ +spec_version: "1.6", +version: 1 +serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" +definitions { + standards: [ + { + bom_ref: "standard-1" + name: "Sample Standard" + version: "1.0.0" + description: "Description here" + owner: "Acme Inc" + requirements: [ + { + bom_ref: "requirement-1" + identifier: "v1" + title: "Title here" + }, + { + bom_ref: "requirement-1.1" + identifier: "v1.1" + title: "Title here" + parent: "requirement-1" + }, + { + bom_ref: "requirement-1.1.1" + identifier: "v1.1.1" + text: "Text of the requirement here" + descriptions: [ + "Supplemental text here" + ] + opencre: [ + "CRE:616-305" + ], + parent: "requirement-1.1" + } + ] + levels: [ + { + bom_ref: "level-1" + identifier: "Level 1" + description: "Description here" + requirements: [ + "requirement-1.1.1" + ] + }, + { + bom_ref: "level-2" + identifier: "Level 2" + description: "Description here" + requirements: [ + "requirement-1.1.1" + ] + }, + { + bom_ref: "level-3" + identifier: "Level 3" + description: "Description here" + requirements: [ + "requirement-1.1.1" + ] + } + ] + } + ] +} \ No newline at end of file From 6df7182392f618131c70d9fb1c023abd887930c1 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Wed, 27 Dec 2023 00:46:06 -0600 Subject: [PATCH 20/28] Removed unnecessary type for dataGovernance ref that resulted in warnings in some parsers. Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 2 -- 1 file changed, 2 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index c9ab597d..a7f9bb05 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -1386,7 +1386,6 @@ ] }, "governance": { - "type": "object", "title": "Data Governance", "$ref": "#/definitions/dataGovernance" }, @@ -2709,7 +2708,6 @@ "type": "string" }, "governance": { - "type": "object", "title": "Data Governance", "$ref": "#/definitions/dataGovernance" } From 0044906f0c3c211472b618ec1229106df9f0fed4 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Sun, 7 Jan 2024 22:00:35 -0600 Subject: [PATCH 21/28] Updating JSON Schema for Humans to latest release. Porting template changes. Signed-off-by: Steve Springett --- docgen/json/gen.sh | 2 +- docgen/json/templates/cyclonedx/content.html | 132 +++++++++--------- docgen/json/templates/cyclonedx/schema_doc.js | 4 +- .../templates/cyclonedx/schema_doc.min.js | 2 +- .../templates/cyclonedx/section_array.html | 11 ++ 5 files changed, 79 insertions(+), 72 deletions(-) diff --git a/docgen/json/gen.sh b/docgen/json/gen.sh index e92128bc..a4e98d83 100755 --- a/docgen/json/gen.sh +++ b/docgen/json/gen.sh @@ -4,7 +4,7 @@ mkdir -p docs/{1.2,1.3,1.4,1.5,1.6} # Check to see if generate-schema-doc is executable and is in the path. If not, install JSON Schema for Humans. if ! [ -x "$(command -v generate-schema-doc)" ]; then - pip3 install json-schema-for-humans==0.44.3 + pip3 install json-schema-for-humans==0.47 fi generate () { diff --git a/docgen/json/templates/cyclonedx/content.html b/docgen/json/templates/cyclonedx/content.html index 3e880425..f5ae10c6 100644 --- a/docgen/json/templates/cyclonedx/content.html +++ b/docgen/json/templates/cyclonedx/content.html @@ -17,13 +17,17 @@ {# Display type #} {%- if not schema is combining -%} - Type: {{ type_name }} + Type: {{ type_name }} + {%- endif -%} + + {%- if schema.format -%} + Format: {{ schema.format }} {%- endif -%} {# Display default #} {%- set default_value = schema.default_value -%} {%- if default_value -%} - {{ " " }}Default: {{ default_value }} + {{ " " }}Default: {{ default_value }} {%- endif -%}
@@ -37,80 +41,72 @@ {%- elif schema.refers_to -%} {{ content(schema.refers_to_merged, True) }} {%- else -%} - {# Handle having oneOf or allOf with only one condition #} - {%- if schema.kw_all_of and (schema.kw_all_of.array_items | length) == 1 -%} - {{ content(schema.kw_all_of.array_items[0]) }} - {%- elif schema.kw_any_of and (schema.kw_any_of.array_items | length) == 1 -%} - {{ content(schema.kw_any_of.array_items[0]) }} - {%- else -%} - {%- if schema.explicit_no_additional_properties -%} - {{ " " }}No Additional Properties - {%- endif -%} - - {# Combining: allOf, anyOf, oneOf, not #} - {%- if schema.kw_all_of -%} -
{{ tabbed_section("allOf", schema.kw_all_of) }}
- {%- endif -%} - {%- if schema.kw_any_of -%} -
{{ tabbed_section("anyOf", schema.kw_any_of) }}
- {%- endif -%} - {%- if schema.kw_one_of -%} -
{{ tabbed_section("oneOf", schema.kw_one_of) }}
- {%- endif -%} - {%- if schema.kw_not -%} - {% include "section_not.html" %} - {%- endif -%} - - {# Enum and const #} - {%- if schema.kw_enum -%} -
-

Must be one of:

-
    - {%- for enum_choice in schema.kw_enum.array_items -%} -
  • {{ enum_choice.literal | python_to_json }}
  • - {%- endfor -%} -
-
- {%- endif -%} - {%- if schema.kw_const -%} - Specific value: {{ schema.kw_const.raw | python_to_json }} - {%- endif -%} + {%- if schema.explicit_no_additional_properties -%} + {{ " " }}No Additional Properties + {%- endif -%} - {# Pattern (Regular Expression) #} - {%- if schema.kw_pattern -%} - Must match regular expression: {{ schema.kw_pattern.literal | escape }} - {%- endif -%} + {# Combining: allOf, anyOf, oneOf, not #} + {%- if schema.kw_all_of -%} +
{{ tabbed_section("allOf", schema.kw_all_of) }}
+ {%- endif -%} + {%- if schema.kw_any_of -%} +
{{ tabbed_section("anyOf", schema.kw_any_of) }}
+ {%- endif -%} + {%- if schema.kw_one_of -%} +
{{ tabbed_section("oneOf", schema.kw_one_of) }}
+ {%- endif -%} + {%- if schema.kw_not -%} + {% include "section_not.html" %} + {%- endif -%} - {# Conditional subschema, or if-then-else section #} - {%- if schema.has_conditional -%} - {% include "section_conditional_subschema.html" %} - {%- endif -%} + {# Enum and const #} + {%- if schema.kw_enum -%} +
+

Must be one of:

+
    + {%- for enum_choice in schema.kw_enum.array_items -%} +
  • {{ enum_choice.literal | python_to_json }}
  • + {%- endfor -%} +
+
+ {%- endif -%} + {%- if schema.kw_const -%} + Specific value: {{ schema.kw_const.raw | python_to_json }} + {%- endif -%} - {# Required properties that are not defined under "properties". They will only be listed #} - {% include "section_undocumented_required_properties.html" %} + {# Pattern (Regular Expression) #} + {%- if schema.kw_pattern -%} + Must match regular expression: {{ schema.kw_pattern.literal | escape }} + {%- endif -%} - {# Show the requested type(s) #} - {% include "badge_type.html" %} + {# Conditional subschema, or if-then-else section #} + {%- if schema.has_conditional -%} + {% include "section_conditional_subschema.html" %} + {%- endif -%} - {# Show array restrictions #} - {%- if type_name.startswith("array") -%} - {% include "section_array.html" %} - {%- endif -%} + {# Required properties that are not defined under "properties". They will only be listed #} + {% include "section_undocumented_required_properties.html" %} - {# Display examples #} - {%- set examples = schema.examples -%} - {%- if examples -%} - {% include "section_examples.html" %} - {%- endif -%} + {# Show the requested type(s) #} + {% include "badge_type.html" %} - {# Properties, pattern properties, additional properties #} - {%- for sub_property in schema.iterate_properties -%} - {# Custom modification to remove $ properties from documentation #} - {%- if not sub_property.property_display_name.startswith("$") -%} - {% include "section_properties.html" %} - {%- endif -%} - {%- endfor -%} + {# Show array restrictions #} + {%- if type_name.startswith("array") -%} + {% include "section_array.html" %} + {%- endif -%} + {# Display examples #} + {%- set examples = schema.examples -%} + {%- if examples -%} + {% include "section_examples.html" %} {%- endif -%} + + {# Properties, pattern properties, additional properties #} + {%- for sub_property in schema.iterate_properties -%} + {# Custom modification to remove $ properties from documentation #} + {%- if not sub_property.property_display_name.startswith("$") -%} + {% include "section_properties.html" %} + {%- endif -%} + {%- endfor -%} {%- endif -%} {%- endmacro -%} \ No newline at end of file diff --git a/docgen/json/templates/cyclonedx/schema_doc.js b/docgen/json/templates/cyclonedx/schema_doc.js index be02797f..e03ce946 100644 --- a/docgen/json/templates/cyclonedx/schema_doc.js +++ b/docgen/json/templates/cyclonedx/schema_doc.js @@ -19,7 +19,7 @@ function setAnchor(anchorLinkDestination) { function anchorOnLoad() { // Added to onload on body, checks if there is an anchor link and if so, expand - let linkTarget = window.location.hash.split("?")[0].split("&")[0]; + let linkTarget = decodeURIComponent(window.location.hash.split("?")[0].split("&")[0]); if (linkTarget[0] === "#") { linkTarget = linkTarget.substr(1); } @@ -37,7 +37,7 @@ function anchorLink(linkTarget) { if($( this ).hasClass("collapse")) { $( this ).collapse("show"); } else if ($( this ).hasClass("tab-pane")) { - // We have the pane and not the the tab itself, find the tab + // We have the pane and not the tab itself, find the tab const tabToShow = $( "a[href='#" + $( this ).attr("id") + "']" ); if (tabToShow) { tabToShow.tab("show"); diff --git a/docgen/json/templates/cyclonedx/schema_doc.min.js b/docgen/json/templates/cyclonedx/schema_doc.min.js index 0d9c7882..0c58a70e 100644 --- a/docgen/json/templates/cyclonedx/schema_doc.min.js +++ b/docgen/json/templates/cyclonedx/schema_doc.min.js @@ -1 +1 @@ -function flashElement(t){myElement=document.getElementById(t),myElement.classList.add("jsfh-animated-property"),setTimeout(function(){myElement.classList.remove("jsfh-animated-property")},1e3)}function setAnchor(t){history.pushState({},"",t)}function anchorOnLoad(){let t=window.location.hash.split("?")[0].split("&")[0];"#"===t[0]&&(t=t.substr(1)),t.length>0&&anchorLink(t)}function anchorLink(t){$("#"+t).parents().addBack().filter(".collapse:not(.show), .tab-pane, [role='tab']").each(function(t){if($(this).hasClass("collapse"))$(this).collapse("show");else if($(this).hasClass("tab-pane")){const t=$("a[href='#"+$(this).attr("id")+"']");t&&t.tab("show")}else"tab"===$(this).attr("role")&&$(this).tab("show")}),setTimeout(function(){let e=document.getElementById(t);e&&(e.scrollIntoView({block:"center",behavior:"smooth"}),setTimeout(function(){flashElement(t)},500))},1e3)}$(document).on("click",'a[href^="#"]',function(t){t.preventDefault(),history.pushState({},"",this.href)}); \ No newline at end of file +function flashElement(t){(myElement=document.getElementById(t)).classList.add("jsfh-animated-property"),setTimeout(function(){myElement.classList.remove("jsfh-animated-property")},1e3)}function setAnchor(t){history.pushState({},"",t)}function anchorOnLoad(){let t=decodeURIComponent(window.location.hash.split("?")[0].split("&")[0]);"#"===t[0]&&(t=t.substr(1)),t.length>0&&anchorLink(t)}function anchorLink(t){let e=$("#"+t);e.parents().addBack().filter(".collapse:not(.show), .tab-pane, [role='tab']").each(function(t){if($(this).hasClass("collapse"))$(this).collapse("show");else if($(this).hasClass("tab-pane")){let e=$("a[href='#"+$(this).attr("id")+"']");e&&e.tab("show")}else"tab"===$(this).attr("role")&&$(this).tab("show")}),setTimeout(function(){let e=document.getElementById(t);e&&(e.scrollIntoView({block:"center",behavior:"smooth"}),setTimeout(function(){flashElement(t)},500))},1e3)}$(document).on("click",'a[href^="#"]',function(t){t.preventDefault(),history.pushState({},"",this.href)}); \ No newline at end of file diff --git a/docgen/json/templates/cyclonedx/section_array.html b/docgen/json/templates/cyclonedx/section_array.html index 1aad2e0f..15489a4b 100644 --- a/docgen/json/templates/cyclonedx/section_array.html +++ b/docgen/json/templates/cyclonedx/section_array.html @@ -7,6 +7,9 @@ {%- if schema.kw_unique_items and schema.kw_unique_items.literal == True -%} {{ restriction("All items must be unique", "unique-items", schema.kw_unique_items.html_id) }} {%- endif -%} +{%- if not schema.array_additional_items -%} + {{ " " }}No Additional Items +{%- endif -%} {%- if schema.array_items_def -%}

Each item of this array must be:

@@ -34,4 +37,12 @@

At least one of the items must be:

{{ content(schema.kw_contains) }}
+{%- endif -%} +{%- if schema.array_additional_items_def -%} +

All other items must be:

+
+
+ {{ content(schema.array_additional_items_def) }} +
+
{%- endif -%} \ No newline at end of file From deb137963c0944593a5c564b85fdd740c97248cf Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Sun, 7 Jan 2024 22:17:44 -0600 Subject: [PATCH 22/28] Initial commit for Ecma documentation generation Signed-off-by: Steve Springett --- docgen/ecma/gen.sh | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100755 docgen/ecma/gen.sh diff --git a/docgen/ecma/gen.sh b/docgen/ecma/gen.sh new file mode 100755 index 00000000..534f3cab --- /dev/null +++ b/docgen/ecma/gen.sh @@ -0,0 +1,15 @@ +#!/bin/bash +rm -f -R docs temp out +mkdir -p docs temp +cp ../../schema/bom-1.6.schema.json temp +cp ../../schema/jsf-0.82.schema.json temp +cp ../../schema/spdx.schema.json temp + +# Check to see if jsonschema2md is executable and is in the path. If not, install jsonschema2md. +if ! [ -x "$(command -v jsonschema2md)" ]; then + npm install -g @adobe/jsonschema2md +fi + +echo Generating Ecma Documentation +jsonschema2md -d temp -o docs +rm -f -R temp out From d92e58efe09a384ce1b68ff1b7808903feb26d38 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Wed, 10 Jan 2024 22:43:34 -0600 Subject: [PATCH 23/28] Refactored JSON enum descriptions to use meta:enum Signed-off-by: Steve Springett --- schema/bom-1.6.schema.json | 244 +++++++++++++++++++++++++++++++++---- 1 file changed, 217 insertions(+), 27 deletions(-) diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index a7f9bb05..ebd3baea 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -179,13 +179,14 @@ "description": "The product lifecycle(s) that this BOM represents.", "oneOf": [ { + "title": "Pre-Defined Phase", "required": ["phase"], "additionalProperties": false, "properties": { "phase": { "type": "string", "title": "Phase", - "description": "A pre-defined phase in the product lifecycle.\n\n* __design__ = BOM produced early in the development lifecycle containing inventory of components and services that are proposed or planned to be used. The inventory may need to be procured, retrieved, or resourced prior to use.\n* __pre-build__ = BOM consisting of information obtained prior to a build process and may contain source files and development artifacts and manifests. The inventory may need to be resolved and retrieved prior to use.\n* __build__ = BOM consisting of information obtained during a build process where component inventory is available for use. The precise versions of resolved components are usually available at this time as well as the provenance of where the components were retrieved from.\n* __post-build__ = BOM consisting of information obtained after a build process has completed and the resulting components(s) are available for further analysis. Built components may exist as the result of a CI/CD process, may have been installed or deployed to a system or device, and may need to be retrieved or extracted from the system or device.\n* __operations__ = BOM produced that represents inventory that is running and operational. This may include staging or production environments and will generally encompass multiple SBOMs describing the applications and operating system, along with HBOMs describing the hardware that makes up the system. Operations Bill of Materials (OBOM) can provide full-stack inventory of runtime environments, configurations, and additional dependencies.\n* __discovery__ = BOM consisting of information observed through network discovery providing point-in-time enumeration of embedded, on-premise, and cloud-native services such as server applications, connected devices, microservices, and serverless functions.\n* __decommission__ = BOM containing inventory that will be, or has been retired from operations.", + "description": "A pre-defined phase in the product lifecycle.", "enum": [ "design", "pre-build", @@ -194,11 +195,21 @@ "operations", "discovery", "decommission" - ] + ], + "meta:enum": { + "design": "BOM produced early in the development lifecycle containing inventory of components and services that are proposed or planned to be used. The inventory may need to be procured, retrieved, or resourced prior to use.", + "pre-build": "BOM consisting of information obtained prior to a build process and may contain source files and development artifacts and manifests. The inventory may need to be resolved and retrieved prior to use.", + "build": "BOM consisting of information obtained during a build process where component inventory is available for use. The precise versions of resolved components are usually available at this time as well as the provenance of where the components were retrieved from.", + "post-build": "BOM consisting of information obtained after a build process has completed and the resulting components(s) are available for further analysis. Built components may exist as the result of a CI/CD process, may have been installed or deployed to a system or device, and may need to be retrieved or extracted from the system or device.", + "operations": "BOM produced that represents inventory that is running and operational. This may include staging or production environments and will generally encompass multiple SBOMs describing the applications and operating system, along with HBOMs describing the hardware that makes up the system. Operations Bill of Materials (OBOM) can provide full-stack inventory of runtime environments, configurations, and additional dependencies.", + "discovery": "BOM consisting of information observed through network discovery providing point-in-time enumeration of embedded, on-premise, and cloud-native services such as server applications, connected devices, microservices, and serverless functions.", + "decommission": "BOM containing inventory that will be, or has been retired from operations." + } } } }, { + "title": "Custom Phase", "required": ["name"], "additionalProperties": false, "properties": { @@ -411,8 +422,22 @@ "machine-learning-model", "data" ], + "meta:enum": { + "application": "A software application. Refer to [https://en.wikipedia.org/wiki/Application_software](https://en.wikipedia.org/wiki/Application_software) for information about applications.", + "framework": "A software framework. Refer to [https://en.wikipedia.org/wiki/Software_framework](https://en.wikipedia.org/wiki/Software_framework) for information on how frameworks vary slightly from libraries.", + "library": "A software library. Refer to [https://en.wikipedia.org/wiki/Library_(computing)](https://en.wikipedia.org/wiki/Library_(computing)) for information about libraries. All third-party and open source reusable components will likely be a library. If the library also has key features of a framework, then it should be classified as a framework. If not, or is unknown, then specifying library is RECOMMENDED.", + "container": "A packaging and/or runtime format, not specific to any particular technology, which isolates software inside the container from software outside of a container through virtualization technology. Refer to [https://en.wikipedia.org/wiki/OS-level_virtualization](https://en.wikipedia.org/wiki/OS-level_virtualization).", + "platform": "A runtime environment which interprets or executes software. This may include runtimes such as those that execute bytecode or low-code/no-code application platforms.", + "operating-system": "A software operating system without regard to deployment model (i.e. installed on physical hardware, virtual machine, image, etc) Refer to [https://en.wikipedia.org/wiki/Operating_system](https://en.wikipedia.org/wiki/Operating_system).", + "device": "A hardware device such as a processor, or chip-set. A hardware device containing firmware SHOULD include a component for the physical hardware itself, and another component of type 'firmware' or 'operating-system' (whichever is relevant), describing information about the software running on the device. See also the list of [known device properties](https://github.com/CycloneDX/cyclonedx-property-taxonomy/blob/main/cdx/device.md).", + "device-driver": "A special type of software that operates or controls a particular type of device. Refer to [https://en.wikipedia.org/wiki/Device_driver](https://en.wikipedia.org/wiki/Device_driver).", + "firmware": "A special type of software that provides low-level control over a devices hardware. Refer to [https://en.wikipedia.org/wiki/Firmware](https://en.wikipedia.org/wiki/Firmware).", + "file": "A computer file. Refer to [https://en.wikipedia.org/wiki/Computer_file](https://en.wikipedia.org/wiki/Computer_file) for information about files.", + "machine-learning-model": "A model based on training data that can make predictions or decisions without being explicitly programmed to do so.", + "data": "A collection of discrete values that convey information." + }, "title": "Component Type", - "description": "Specifies the type of component. For software components, classify as application if no more specific appropriate classification is available or cannot be determined for the component. Types include:\n\n* __application__ = A software application. Refer to [https://en.wikipedia.org/wiki/Application_software](https://en.wikipedia.org/wiki/Application_software) for information about applications.\n* __framework__ = A software framework. Refer to [https://en.wikipedia.org/wiki/Software_framework](https://en.wikipedia.org/wiki/Software_framework) for information on how frameworks vary slightly from libraries.\n* __library__ = A software library. Refer to [https://en.wikipedia.org/wiki/Library_(computing)](https://en.wikipedia.org/wiki/Library_(computing))\n for information about libraries. All third-party and open source reusable components will likely be a library. If the library also has key features of a framework, then it should be classified as a framework. If not, or is unknown, then specifying library is RECOMMENDED.\n* __container__ = A packaging and/or runtime format, not specific to any particular technology, which isolates software inside the container from software outside of a container through virtualization technology. Refer to [https://en.wikipedia.org/wiki/OS-level_virtualization](https://en.wikipedia.org/wiki/OS-level_virtualization)\n* __platform__ = A runtime environment which interprets or executes software. This may include runtimes such as those that execute bytecode or low-code/no-code application platforms.\n* __operating-system__ = A software operating system without regard to deployment model (i.e. installed on physical hardware, virtual machine, image, etc) Refer to [https://en.wikipedia.org/wiki/Operating_system](https://en.wikipedia.org/wiki/Operating_system)\n* __device__ = A hardware device such as a processor, or chip-set. A hardware device containing firmware SHOULD include a component for the physical hardware itself, and another component of type 'firmware' or 'operating-system' (whichever is relevant), describing information about the software running on the device.\n See also the list of [known device properties](https://github.com/CycloneDX/cyclonedx-property-taxonomy/blob/main/cdx/device.md).\n* __device-driver__ = A special type of software that operates or controls a particular type of device. Refer to [https://en.wikipedia.org/wiki/Device_driver](https://en.wikipedia.org/wiki/Device_driver)\n* __firmware__ = A special type of software that provides low-level control over a devices hardware. Refer to [https://en.wikipedia.org/wiki/Firmware](https://en.wikipedia.org/wiki/Firmware)\n* __file__ = A computer file. Refer to [https://en.wikipedia.org/wiki/Computer_file](https://en.wikipedia.org/wiki/Computer_file) for information about files.\n* __machine-learning-model__ = A model based on training data that can make predictions or decisions without being explicitly programmed to do so.\n* __data__ = A collection of discrete values that convey information.", + "description": "Specifies the type of component. For software components, classify as application if no more specific appropriate classification is available or cannot be determined for the component.", "examples": ["library"] }, "mime-type": { @@ -473,6 +498,11 @@ "optional", "excluded" ], + "meta:enum": { + "required": "The component is required for runtime", + "optional": "The component is optional at runtime. Optional components are components that are not capable of being called due to them not be installed or otherwise accessible by any means. Components that are installed but due to configuration or other restrictions are prohibited from being called must be scoped as 'required'.", + "excluded": "Components that are excluded provide the ability to document component usage for test and other non-runtime purposes. Excluded components are not reachable within a call graph at runtime." + }, "title": "Component Scope", "description": "Specifies the scope of the component. If scope is not specified, 'required' scope SHOULD be assumed by the consumer of the BOM.", "default": "required" @@ -675,7 +705,10 @@ "description": "Specifies the optional encoding the text is represented in.", "enum": [ "base64" - ] + ], + "meta:enum": { + "base64": "Base64 is a binary-to-text encoding scheme that represents binary data in an ASCII string." + } }, "content": { "type": "string", @@ -867,7 +900,7 @@ "licenseTypes": { "type": "array", "title": "License Type", - "description": "The type of license(s) that was granted to the licensee\n\n* __academic__ = A license that grants use of software solely for the purpose of education or research.\n* __appliance__ = A license covering use of software embedded in a specific piece of hardware.\n* __client-access__ = A Client Access License (CAL) allows client computers to access services provided by server software.\n* __concurrent-user__ = A Concurrent User license (aka floating license) limits the number of licenses for a software application and licenses are shared among a larger number of users.\n* __core-points__ = A license where the core of a computer's processor is assigned a specific number of points.\n* __custom-metric__ = A license for which consumption is measured by non-standard metrics.\n* __device__ = A license that covers a defined number of installations on computers and other types of devices.\n* __evaluation__ = A license that grants permission to install and use software for trial purposes.\n* __named-user__ = A license that grants access to the software to one or more pre-defined users.\n* __node-locked__ = A license that grants access to the software on one or more pre-defined computers or devices.\n* __oem__ = An Original Equipment Manufacturer license that is delivered with hardware, cannot be transferred to other hardware, and is valid for the life of the hardware.\n* __perpetual__ = A license where the software is sold on a one-time basis and the licensee can use a copy of the software indefinitely.\n* __processor-points__ = A license where each installation consumes points per processor.\n* __subscription__ = A license where the licensee pays a fee to use the software or service.\n* __user__ = A license that grants access to the software or service by a specified number of users.\n* __other__ = Another license type.\n", + "description": "The type of license(s) that was granted to the licensee.", "items": { "type": "string", "enum": [ @@ -887,7 +920,25 @@ "subscription", "user", "other" - ] + ], + "meta:enum": { + "academic": "A license that grants use of software solely for the purpose of education or research.", + "appliance": "A license covering use of software embedded in a specific piece of hardware.", + "client-access": "A Client Access License (CAL) allows client computers to access services provided by server software.", + "concurrent-user": "A Concurrent User license (aka floating license) limits the number of licenses for a software application and licenses are shared among a larger number of users.", + "core-points": "A license where the core of a computer's processor is assigned a specific number of points.", + "custom-metric": "A license for which consumption is measured by non-standard metrics.", + "device": "A license that covers a defined number of installations on computers and other types of devices.", + "evaluation": "A license that grants permission to install and use software for trial purposes.", + "named-user": "A license that grants access to the software to one or more pre-defined users.", + "node-locked": "A license that grants access to the software on one or more pre-defined computers or devices.", + "oem": "An Original Equipment Manufacturer license that is delivered with hardware, cannot be transferred to other hardware, and is valid for the life of the hardware.", + "perpetual": "A license where the software is sold on a one-time basis and the licensee can use a copy of the software indefinitely.", + "processor-points": "A license where each installation consumes points per processor.", + "subscription": "A license where the licensee pays a fee to use the software or service.", + "user": "A license that grants access to the software or service by a specified number of users.", + "other": "Another license type." + } } }, "lastRenewal": { @@ -1012,8 +1063,14 @@ "backport", "cherry-pick" ], + "meta:enum": { + "unofficial": "A patch which is not developed by the creators or maintainers of the software being patched. Refer to [https://en.wikipedia.org/wiki/Unofficial_patch](https://en.wikipedia.org/wiki/Unofficial_patch).", + "monkey": "A patch which dynamically modifies runtime behavior. Refer to [https://en.wikipedia.org/wiki/Monkey_patch](https://en.wikipedia.org/wiki/Monkey_patch).", + "backport": "A patch which takes code from a newer version of software and applies it to older versions of the same software. Refer to [https://en.wikipedia.org/wiki/Backporting](https://en.wikipedia.org/wiki/Backporting).", + "cherry-pick": "A patch created by selectively applying commits from other versions or branches of the same software." + }, "title": "Type", - "description": "Specifies the purpose for the patch including the resolution of defects, security issues, or new behavior or functionality.\n\n* __unofficial__ = A patch which is not developed by the creators or maintainers of the software being patched. Refer to [https://en.wikipedia.org/wiki/Unofficial_patch](https://en.wikipedia.org/wiki/Unofficial_patch)\n* __monkey__ = A patch which dynamically modifies runtime behavior. Refer to [https://en.wikipedia.org/wiki/Monkey_patch](https://en.wikipedia.org/wiki/Monkey_patch)\n* __backport__ = A patch which takes code from a newer version of software and applies it to older versions of the same software. Refer to [https://en.wikipedia.org/wiki/Backporting](https://en.wikipedia.org/wiki/Backporting)\n* __cherry-pick__ = A patch created by selectively applying commits from other versions or branches of the same software." + "description": "Specifies the purpose for the patch including the resolution of defects, security issues, or new behavior or functionality." }, "diff": { "title": "Diff", @@ -1063,6 +1120,11 @@ "enhancement", "security" ], + "meta:enum": { + "defect": "A fault, flaw, or bug in software.", + "enhancement": "A new feature or behavior in software.", + "security": "A special type of defect which impacts security." + }, "title": "Type", "description": "Specifies the type of issue" }, @@ -1170,7 +1232,7 @@ "type": { "type": "string", "title": "Type", - "description": "Specifies the type of external reference.\n\n* __vcs__ = Version Control System\n* __issue-tracker__ = Issue or defect tracking system, or an Application Lifecycle Management (ALM) system\n* __website__ = Website\n* __advisories__ = Security advisories\n* __bom__ = Bill of Materials (SBOM, OBOM, HBOM, SaaSBOM, etc)\n* __mailing-list__ = Mailing list or discussion group\n* __social__ = Social media account\n* __chat__ = Real-time chat platform\n* __documentation__ = Documentation, guides, or how-to instructions\n* __support__ = Community or commercial support\n* __distribution__ = Direct or repository download location\n* __distribution-intake__ = The location where a component was published to. This is often the same as \"distribution\" but may also include specialized publishing processes that act as an intermediary\n* __license__ = The URL to the license file. If a license URL has been defined in the license node, it should also be defined as an external reference for completeness\n* __build-meta__ = Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, etc)\n* __build-system__ = URL to an automated build system\n* __release-notes__ = URL to release notes\n* __security-contact__ = Specifies a way to contact the maintainer, supplier, or provider in the event of a security incident. Common URIs include links to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies the records containing DNS Security TXT\n* __model-card__ = A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets used to train the model, performance metrics, and other relevant data useful for ML transparency\n* __log__ = A record of events that occurred in a computer system or application, such as problems, errors, or information on current operations\n* __configuration__ = Parameters or settings that may be used by other components or services\n* __evidence__ = Information used to substantiate a claim\n* __formulation__ = Describes how a component or service was manufactured or deployed\n* __attestation__ = Human or machine-readable statements containing facts, evidence, or testimony\n* __threat-model__ = An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format\n* __adversary-model__ = The defined assumptions, goals, and capabilities of an adversary.\n* __risk-assessment__ = Identifies and analyzes the potential of future events that may negatively impact individuals, assets, and/or the environment. Risk assessments may also include judgments on the tolerability of each risk.\n* __vulnerability-assertion__ = A Vulnerability Disclosure Report (VDR) which asserts the known and previously unknown vulnerabilities that affect a component, service, or product including the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on a component, service, or product.\n* __exploitability-statement__ = A Vulnerability Exploitability eXchange (VEX) which asserts the known vulnerabilities that do not affect a product, product family, or organization, and optionally the ones that do. The VEX should include the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on the product, product family, or organization.\n* __pentest-report__ = Results from an authorized simulated cyberattack on a component or service, otherwise known as a penetration test\n* __static-analysis-report__ = SARIF or proprietary machine or human-readable report for which static analysis has identified code quality, security, and other potential issues with the source code\n* __dynamic-analysis-report__ = Dynamic analysis report that has identified issues such as vulnerabilities and misconfigurations\n* __runtime-analysis-report__ = Report generated by analyzing the call stack of a running application\n* __component-analysis-report__ = Report generated by Software Composition Analysis (SCA), container analysis, or other forms of component analysis\n* __maturity-report__ = Report containing a formal assessment of an organization, business unit, or team against a maturity model\n* __certification-report__ = Industry, regulatory, or other certification from an accredited (if applicable) certification body\n* __quality-metrics__ = Report or system in which quality metrics can be obtained\n* __codified-infrastructure__ = Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC)\n* __poam__ = Plans of Action and Milestones (POAM) compliment an \"attestation\" external reference. POAM is defined by NIST as a \"document that identifies tasks needing to be accomplished. It details resources required to accomplish the elements of the plan, any milestones in meeting the tasks and scheduled completion dates for the milestones\".\n* __other__ = Use this if no other types accurately describe the purpose of the external reference", + "description": "Specifies the type of external reference.", "enum": [ "vcs", "issue-tracker", @@ -1211,7 +1273,49 @@ "quality-metrics", "poam", "other" - ] + ], + "meta:enum": { + "vcs": "Version Control System", + "issue-tracker": "Issue or defect tracking system, or an Application Lifecycle Management (ALM) system", + "website": "Website", + "advisories": "Security advisories", + "bom": "Bill of Materials (SBOM, OBOM, HBOM, SaaSBOM, etc)", + "mailing-list": "Mailing list or discussion group", + "social": "Social media account", + "chat": "Real-time chat platform", + "documentation": "Documentation, guides, or how-to instructions", + "support": "Community or commercial support", + "distribution": "Direct or repository download location", + "distribution-intake": "The location where a component was published to. This is often the same as \"distribution\" but may also include specialized publishing processes that act as an intermediary.", + "license": "The reference to the license file. If a license URL has been defined in the license node, it should also be defined as an external reference for completeness.", + "build-meta": "Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, etc)", + "build-system": "Reference to an automated build system", + "release-notes": "Reference to release notes", + "security-contact": "Specifies a way to contact the maintainer, supplier, or provider in the event of a security incident. Common URIs include links to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies the records containing DNS Security TXT.", + "model-card": "A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets used to train the model, performance metrics, and other relevant data useful for ML transparency.", + "log": "A record of events that occurred in a computer system or application, such as problems, errors, or information on current operations.", + "configuration": "Parameters or settings that may be used by other components or services.", + "evidence": "Information used to substantiate a claim.", + "formulation": "Describes how a component or service was manufactured or deployed.", + "attestation": "Human or machine-readable statements containing facts, evidence, or testimony.", + "threat-model": "An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format.", + "adversary-model": "The defined assumptions, goals, and capabilities of an adversary.", + "risk-assessment": "Identifies and analyzes the potential of future events that may negatively impact individuals, assets, and/or the environment. Risk assessments may also include judgments on the tolerability of each risk.", + "vulnerability-assertion": "A Vulnerability Disclosure Report (VDR) which asserts the known and previously unknown vulnerabilities that affect a component, service, or product including the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on a component, service, or product.", + "exploitability-statement": "A Vulnerability Exploitability eXchange (VEX) which asserts the known vulnerabilities that do not affect a product, product family, or organization, and optionally the ones that do. The VEX should include the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on the product, product family, or organization.", + "pentest-report": "Results from an authorized simulated cyberattack on a component or service, otherwise known as a penetration test.", + "static-analysis-report": "SARIF or proprietary machine or human-readable report for which static analysis has identified code quality, security, and other potential issues with the source code.", + "dynamic-analysis-report": "Dynamic analysis report that has identified issues such as vulnerabilities and misconfigurations.", + "runtime-analysis-report": "Report generated by analyzing the call stack of a running application.", + "component-analysis-report": "Report generated by Software Composition Analysis (SCA), container analysis, or other forms of component analysis.", + "maturity-report": "Report containing a formal assessment of an organization, business unit, or team against a maturity model.", + "certification-report": "Industry, regulatory, or other certification from an accredited (if applicable) certification body.", + "codified-infrastructure": "Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC).", + "quality-metrics": "Report or system in which quality metrics can be obtained.", + "poam": "Plans of Action and Milestones (POAM) compliment an \"attestation\" external reference. POAM is defined by NIST as a \"document that identifies tasks needing to be accomplished. It details resources required to accomplish the elements of the plan, any milestones in meeting the tasks and scheduled completion dates for the milestones\".", + "other": "Use this if no other types accurately describe the purpose of the external reference." + } + }, "hashes": { "type": "array", @@ -1435,8 +1539,14 @@ "bi-directional", "unknown" ], + "meta:enum": { + "inbound": "Data that enters a service.", + "outbound": "Data that exits a service.", + "bi-directional": "Data flows in and out of the service.", + "unknown": "The directional flow of data is not known." + }, "title": "Data flow direction", - "description": "Specifies the flow direction of the data. Direction is relative to the service. Inbound flow states that data enters the service. Outbound flow states that data leaves the service. Bi-directional states that data flows both ways, and unknown states that the direction is not known." + "description": "Specifies the flow direction of the data. Direction is relative to the service." }, "copyright": { @@ -1507,7 +1617,19 @@ "filename", "attestation", "other" - ] + ], + "meta:enum": { + "source-code-analysis": "Examines the source code without executing it.", + "binary-analysis": "Examines a compiled binary through reverse engineering, typically via disassembly or bytecode reversal.", + "manifest-analysis": "Examines a package management system such as those used for building software or installing software.", + "ast-fingerprint": "Examines the Abstract Syntax Tree (AST) of source code or a compiled binary.", + "hash-comparison": "Evaluates the cryptographic hash of a component against a set of pre-computed hashes of identified software.", + "instrumentation": "Examines the call stack of running applications by intercepting and monitoring application logic without the need to modify the application.", + "dynamic-analysis": "Evaluates a running application.", + "filename": "Evaluates file name of a component against a set of known file names of identified software.", + "attestation": "A testimony to the accuracy of the identify of a component made by an individual or entity.", + "other": "Any other technique." + } }, "confidence": { "type": "number", @@ -1651,7 +1773,7 @@ "aggregate": { "$ref": "#/definitions/aggregateType", "title": "Aggregate", - "description": "Specifies an aggregate type that describe how complete a relationship is.\n\n* __complete__ = The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist.\n* __incomplete__ = The relationship is incomplete. Additional relationships exist and may include constituent components, services, or dependencies.\n* __incomplete_first_party_only__ = The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented.\n* __incomplete_first_party_proprietary_only__ = The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.\n* __incomplete_first_party_opensource_only__ = The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are opensource.\n* __incomplete_third_party_only__ = The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented.\n* __incomplete_third_party_proprietary_only__ = The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.\n* __incomplete_third_party_opensource_only__ = The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource.\n* __unknown__ = The relationship may be complete or incomplete. This usually signifies a 'best-effort' to obtain constituent components, services, or dependencies but the completeness is inconclusive.\n* __not_specified__ = The relationship completeness is not specified.\n" + "description": "Specifies an aggregate type that describe how complete a relationship is." }, "assemblies": { "type": "array", @@ -1710,7 +1832,19 @@ "incomplete_third_party_opensource_only", "unknown", "not_specified" - ] + ], + "meta:enum": { + "complete": "The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist.", + "incomplete": "The relationship is incomplete. Additional relationships exist and may include constituent components, services, or dependencies.", + "incomplete_first_party_only": "The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented.", + "incomplete_first_party_proprietary_only": "The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.", + "incomplete_first_party_opensource_only": "The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are opensource.", + "incomplete_third_party_only": "The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented.", + "incomplete_third_party_proprietary_only": "The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.", + "incomplete_third_party_opensource_only": "The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource.", + "unknown": "The relationship may be complete or incomplete. This usually signifies a 'best-effort' to obtain constituent components, services, or dependencies but the completeness is inconclusive.", + "not_specified": "The relationship completeness is not specified." + } }, "property": { "type": "object", @@ -1882,12 +2016,21 @@ "info", "none", "unknown" - ] + ], + "meta:enum": { + "critical": "Critical severity", + "high": "High severity", + "medium": "Medium severity", + "low": "Low severity", + "info": "Informational warning.", + "none": "None", + "unknown": "The severity is not known" + } }, "scoreMethod": { "type": "string", "title": "Method", - "description": "Specifies the severity or risk scoring methodology or standard used.\n\n* CVSSv2 - [Common Vulnerability Scoring System v2](https://www.first.org/cvss/v2/)\n* CVSSv3 - [Common Vulnerability Scoring System v3](https://www.first.org/cvss/v3-0/)\n* CVSSv31 - [Common Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3-1/)\n* CVSSv4 - [Common Vulnerability Scoring System v4](https://www.first.org/cvss/v4-0/)\n* OWASP - [OWASP Risk Rating Methodology](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology)\n* SSVC - [Stakeholder Specific Vulnerability Categorization](https://github.com/CERTCC/SSVC) (all versions)", + "description": "Specifies the severity or risk scoring methodology or standard used.", "enum": [ "CVSSv2", "CVSSv3", @@ -1896,12 +2039,21 @@ "OWASP", "SSVC", "other" - ] + ], + "meta:enum": { + "CVSSv2": "Common Vulnerability Scoring System v2.0", + "CVSSv3": "Common Vulnerability Scoring System v3.0", + "CVSSv31": "Common Vulnerability Scoring System v3.1", + "CVSSv4": "Common Vulnerability Scoring System v4.0", + "OWASP": "OWASP Risk Rating Methodology", + "SSVC": "Stakeholder Specific Vulnerability Categorization", + "other": "Another severity or risk scoring methodology" + } }, "impactAnalysisState": { "type": "string", "title": "Impact Analysis State", - "description": "Declares the current state of an occurrence of a vulnerability, after automated or manual analysis. \n\n* __resolved__ = the vulnerability has been remediated. \n* __resolved\\_with\\_pedigree__ = the vulnerability has been remediated and evidence of the changes are provided in the affected components pedigree containing verifiable commit history and/or diff(s). \n* __exploitable__ = the vulnerability may be directly or indirectly exploitable. \n* __in\\_triage__ = the vulnerability is being investigated. \n* __false\\_positive__ = the vulnerability is not specific to the component or service and was falsely identified or associated. \n* __not\\_affected__ = the component or service is not affected by the vulnerability. Justification should be specified for all not_affected cases.", + "description": "Declares the current state of an occurrence of a vulnerability, after automated or manual analysis.", "enum": [ "resolved", "resolved_with_pedigree", @@ -1909,12 +2061,20 @@ "in_triage", "false_positive", "not_affected" - ] + ], + "meta:enum": { + "resolved": "The vulnerability has been remediated.", + "resolved_with_pedigree": "The vulnerability has been remediated and evidence of the changes are provided in the affected components pedigree containing verifiable commit history and/or diff(s).", + "exploitable": "The vulnerability may be directly or indirectly exploitable.", + "in_triage": "The vulnerability is being investigated.", + "false_positive": "The vulnerability is not specific to the component or service and was falsely identified or associated.", + "not_affected": "The component or service is not affected by the vulnerability. Justification should be specified for all not_affected cases." + } }, "impactAnalysisJustification": { "type": "string", "title": "Impact Analysis Justification", - "description": "The rationale of why the impact analysis state was asserted. \n\n* __code\\_not\\_present__ = the code has been removed or tree-shaked. \n* __code\\_not\\_reachable__ = the vulnerable code is not invoked at runtime. \n* __requires\\_configuration__ = exploitability requires a configurable option to be set/unset. \n* __requires\\_dependency__ = exploitability requires a dependency that is not present. \n* __requires\\_environment__ = exploitability requires a certain environment which is not present. \n* __protected\\_by\\_compiler__ = exploitability requires a compiler flag to be set/unset. \n* __protected\\_at\\_runtime__ = exploits are prevented at runtime. \n* __protected\\_at\\_perimeter__ = attacks are blocked at physical, logical, or network perimeter. \n* __protected\\_by\\_mitigating\\_control__ = preventative measures have been implemented that reduce the likelihood and/or impact of the vulnerability.", + "description": "The rationale of why the impact analysis state was asserted.", "enum": [ "code_not_present", "code_not_reachable", @@ -1925,7 +2085,18 @@ "protected_at_runtime", "protected_at_perimeter", "protected_by_mitigating_control" - ] + ], + "meta:enum": { + "code_not_present": "The code has been removed or tree-shaked.", + "code_not_reachable": "The vulnerable code is not invoked at runtime.", + "requires_configuration": "Exploitability requires a configurable option to be set/unset.", + "requires_dependency": "Exploitability requires a dependency that is not present.", + "requires_environment": "Exploitability requires a certain environment which is not present.", + "protected_by_compiler": "Exploitability requires a compiler flag to be set/unset.", + "protected_at_runtime": "Exploits are prevented at runtime.", + "protected_at_perimeter": "Attacks are blocked at physical, logical, or network perimeter.", + "protected_by_mitigating_control": "Preventative measures have been implemented that reduce the likelihood and/or impact of the vulnerability." + } }, "rating": { "type": "object", @@ -2054,7 +2225,7 @@ "cwes": { "type": "array", "title": "CWEs", - "description": "List of Common Weaknesses Enumerations (CWEs) codes that describes this vulnerability. For example 399 (of https://cwe.mitre.org/data/definitions/399.html)", + "description": "List of Common Weaknesses Enumerations (CWEs) codes that describes this vulnerability.", "examples": [399], "items": { "$ref": "#/definitions/cwe" @@ -2215,7 +2386,14 @@ "update", "rollback", "workaround_available" - ] + ], + "meta:enum": { + "can_not_fix": "Can not fix", + "will_not_fix": "Will not fix", + "update": "Update to a different revision or release", + "rollback": "Revert to a previous revision or release", + "workaround_available": "There is a workaround available" + } } }, "detail": { @@ -2315,7 +2493,12 @@ "affected", "unaffected", "unknown" - ] + ], + "meta:enum": { + "affected": "The version is affected by the vulnerability.", + "unaffected": "The version is not affected by the vulnerability.", + "unknown": "It is unknown (or unspecified) whether the given version is affected." + } }, "version": { "description": "A single disjunctive version identifier, for a component or service.", @@ -2508,12 +2691,12 @@ "items" : { "oneOf" : [ { - "title": "Inline Component Data", + "title": "Inline Data Information", "$ref": "#/definitions/componentData" }, { "type": "object", - "title": "Data Component Reference", + "title": "Data Reference", "additionalProperties": false, "properties": { "ref": { @@ -2652,14 +2835,21 @@ "type": { "type": "string", "title": "Type of Data", - "description": "The general theme or subject matter of the data being specified.\n\n* __source-code__ = Any type of code, code snippet, or data-as-code.\n* __configuration__ = Parameters or settings that may be used by other components.\n* __dataset__ = A collection of data.\n* __definition__ = Data that can be used to create new instances of what the definition defines.\n* __other__ = Any other type of data that does not fit into existing definitions.", + "description": "The general theme or subject matter of the data being specified.", "enum": [ "source-code", "configuration", "dataset", "definition", "other" - ] + ], + "meta:enum": { + "source-code": "Any type of code, code snippet, or data-as-code.", + "configuration": "Parameters or settings that may be used by other components.", + "dataset": "A collection of data.", + "definition": "Data that can be used to create new instances of what the definition defines.", + "other": "Any other type of data that does not fit into existing definitions." + } }, "name": { "description": "The name of the dataset.", From a9072169c05043346dfc38d895916a475b65083d Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Wed, 10 Jan 2024 22:47:44 -0600 Subject: [PATCH 24/28] Fixed unit tests Signed-off-by: Steve Springett --- tools/src/test/js/json-schema-lint-tests.js | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/src/test/js/json-schema-lint-tests.js b/tools/src/test/js/json-schema-lint-tests.js index 2afd4bcb..651ef18f 100644 --- a/tools/src/test/js/json-schema-lint-tests.js +++ b/tools/src/test/js/json-schema-lint-tests.js @@ -49,6 +49,7 @@ function getAjv(strict) { validateFormats: true, allowMatchingProperties: true, addUsedSchema: false, + keywords: ["meta:enum"], schemas: { 'http://cyclonedx.org/schema/spdx.schema.json': spdxSchema, 'http://cyclonedx.org/schema/jsf-0.82.schema.json': jsfSchema From ae45d7c52257cb6c2889c4e65c097bb736711396 Mon Sep 17 00:00:00 2001 From: Thomas Jensen Date: Mon, 11 Dec 2023 15:41:32 +0100 Subject: [PATCH 25/28] Add `source-distribution` element to `externalReferenceType` #98 Signed-off-by: Thomas Jensen --- schema/bom-1.6.proto | 2 ++ schema/bom-1.6.schema.json | 2 ++ schema/bom-1.6.xsd | 5 +++++ 3 files changed, 9 insertions(+) diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index e6a6c4fe..c803035c 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -263,6 +263,8 @@ enum ExternalReferenceType { EXTERNAL_REFERENCE_TYPE_EVIDENCE = 36; // Describes how a component or service was manufactured or deployed. EXTERNAL_REFERENCE_TYPE_FORMULATION = 37; + // URL to a source archive. + EXTERNAL_REFERENCE_TYPE_SOURCE_DISTRIBUTION = 38; } enum HashAlg { diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index ebd3baea..e1194bef 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -1244,6 +1244,7 @@ "chat", "documentation", "support", + "source-distribution", "distribution", "distribution-intake", "license", @@ -1285,6 +1286,7 @@ "chat": "Real-time chat platform", "documentation": "Documentation, guides, or how-to instructions", "support": "Community or commercial support", + "source-distribution": "URL to a source archive", "distribution": "Direct or repository download location", "distribution-intake": "The location where a component was published to. This is often the same as \"distribution\" but may also include specialized publishing processes that act as an intermediary.", "license": "The reference to the license file. If a license URL has been defined in the license node, it should also be defined as an external reference for completeness.", diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index 5e218c47..345c4862 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -1259,6 +1259,11 @@ limitations under the License. Community or commercial support
+ + + URL to a source archive + + Direct or repository download location From fff3552eb39cdc970c4d8614c0e5d19405c6a68f Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Sat, 13 Jan 2024 21:45:10 -0600 Subject: [PATCH 26/28] Added missing descriptions Signed-off-by: Steve Springett --- schema/bom-1.6.xsd | 100 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 77 insertions(+), 23 deletions(-) diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index 5e218c47..7b09b12d 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -2158,16 +2158,76 @@ limitations under the License. - - - - - - - - - - + + + + Examines the source code without executing it. + + + + + + + Examines a compiled binary through reverse engineering, typically via disassembly or bytecode reversal. + + + + + + + Examines a package management system such as those used for building software or installing software. + + + + + + + Examines the Abstract Syntax Tree (AST) of source code or a compiled binary. + + + + + + + Evaluates the cryptographic hash of a component against a set of pre-computed hashes of identified software. + + + + + + + Examines the call stack of running applications by intercepting and monitoring application logic without the need to modify the application. + + + + + + + Evaluates a running application. + + + + + + + Evaluates file name of a component against a set of known file names of identified software. + + + + + + + A testimony to the accuracy of the identify of a component made by an individual or entity. + + + + + + + Any other technique. + + + @@ -4058,55 +4118,49 @@ limitations under the License. - The rating is based on CVSS v2 standard - https://www.first.org/cvss/v2/ + Common Vulnerability Scoring System v2.0 standard as defined at https://www.first.org/cvss/v2/ - The rating is based on CVSS v3.0 standard - https://www.first.org/cvss/v3-0/ + Common Vulnerability Scoring System v3.0 standard as defined at https://www.first.org/cvss/v3-0/ - The rating is based on CVSS v3.1 standard - https://www.first.org/cvss/v3-1/ + Common Vulnerability Scoring System v3.1 standard as defined at https://www.first.org/cvss/v3-1/ - The rating is based on CVSS v4.0 standard - https://www.first.org/cvss/v4-0/ + Common Vulnerability Scoring System v4.0 standard as defined at https://www.first.org/cvss/v4-0/ - The rating is based on OWASP Risk Rating - https://owasp.org/www-community/OWASP_Risk_Rating_Methodology + OWASP Risk Rating as defined at https://owasp.org/www-community/OWASP_Risk_Rating_Methodology - The rating is based on Stakeholder Specific Vulnerability Categorization (all versions) - https://github.com/CERTCC/SSVC + Stakeholder Specific Vulnerability Categorization as defined at https://github.com/CERTCC/SSVC - Use this if the risk scoring methodology is not based on any of the options above + Another severity or risk scoring methodology From c65fed23ed228c30268d3946fa67e11e6ddb62d5 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Sat, 13 Jan 2024 21:45:56 -0600 Subject: [PATCH 27/28] Updated template to support markdown in meta:enum descriptions. Signed-off-by: Steve Springett --- docgen/json/templates/cyclonedx/content.html | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docgen/json/templates/cyclonedx/content.html b/docgen/json/templates/cyclonedx/content.html index f5ae10c6..3ad78b84 100644 --- a/docgen/json/templates/cyclonedx/content.html +++ b/docgen/json/templates/cyclonedx/content.html @@ -65,7 +65,13 @@

Must be one of:

    {%- for enum_choice in schema.kw_enum.array_items -%} -
  • {{ enum_choice.literal | python_to_json }}
  • +
  • + {%- if schema.kw_meta_enum -%}{%- endif -%} + {{ enum_choice.literal | python_to_json }} + {%- if schema.kw_meta_enum -%} + : {{ (schema.enum_description(enum_choice.literal) | get_description_literal) }} + {%- endif -%} +
  • {%- endfor -%}
From b2033e0b708d2f7e74bc0f766c3bf79caca4669a Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Sat, 13 Jan 2024 22:53:40 -0600 Subject: [PATCH 28/28] Changed opencre to openCre Signed-off-by: Steve Springett --- schema/bom-1.6.proto | 2 +- schema/bom-1.6.schema.json | 2 +- schema/bom-1.6.xsd | 2 +- tools/src/test/resources/1.6/valid-standard-1.6.json | 2 +- tools/src/test/resources/1.6/valid-standard-1.6.textproto | 2 +- tools/src/test/resources/1.6/valid-standard-1.6.xml | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index 78eb7698..ca17a107 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -1644,7 +1644,7 @@ message Definition { // The supplemental text that provides additional guidance or context to the requirement, but is not directly part of the requirement. repeated string descriptions = 5; // The Common Requirements Enumeration (CRE) identifier(s). CRE is a structured and standardized framework for uniting security standards and guidelines. CRE links each section of a resource to a shared topic identifier (a Common Requirement). Through this shared topic link, all resources map to each other. Use of CRE promotes clear and unambiguous communication among stakeholders. - repeated string opencre = 6; + repeated string openCre = 6; // The optional `bom-ref` to a parent requirement. This establishes a hierarchy of requirements. Top-level requirements must not define a parent. Only child requirements should define parents. optional string parent = 7; // Specifies optional, custom, properties diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index f9fcc6b4..b4fd4ca6 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -4281,7 +4281,7 @@ "description": "The supplemental text that provides additional guidance or context to the requirement, but is not directly part of the requirement.", "items": { "type": "string" } }, - "opencre": { + "openCre": { "type": "array", "title": "OWASP OpenCRE Identifier(s)", "description": "The Common Requirements Enumeration (CRE) identifier(s). CRE is a structured and standardized framework for uniting security standards and guidelines. CRE links each section of a resource to a shared topic identifier (a Common Requirement). Through this shared topic link, all resources map to each other. Use of CRE promotes clear and unambiguous communication among stakeholders.", diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index 05748c18..dcb729dc 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -6107,7 +6107,7 @@ limitations under the License. - + The Common Requirements Enumeration (CRE) identifier(s). CRE is a structured and standardized framework for uniting security standards and guidelines. CRE links each section of a resource to a shared topic identifier (a Common Requirement). Through this shared topic link, all resources map to each other. Use of CRE promotes clear and unambiguous communication among stakeholders. diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.json b/tools/src/test/resources/1.6/valid-standard-1.6.json index b7b1e5fd..ad6b4bab 100644 --- a/tools/src/test/resources/1.6/valid-standard-1.6.json +++ b/tools/src/test/resources/1.6/valid-standard-1.6.json @@ -30,7 +30,7 @@ "descriptions": [ "Supplemental text here" ], - "opencre": [ + "openCre": [ "CRE:616-305" ], "parent": "requirement-1.1" diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.textproto b/tools/src/test/resources/1.6/valid-standard-1.6.textproto index a9a68bc7..65b90e2a 100644 --- a/tools/src/test/resources/1.6/valid-standard-1.6.textproto +++ b/tools/src/test/resources/1.6/valid-standard-1.6.textproto @@ -28,7 +28,7 @@ definitions { descriptions: [ "Supplemental text here" ] - opencre: [ + openCre: [ "CRE:616-305" ], parent: "requirement-1.1" diff --git a/tools/src/test/resources/1.6/valid-standard-1.6.xml b/tools/src/test/resources/1.6/valid-standard-1.6.xml index f2cb0119..7a36430a 100644 --- a/tools/src/test/resources/1.6/valid-standard-1.6.xml +++ b/tools/src/test/resources/1.6/valid-standard-1.6.xml @@ -23,7 +23,7 @@ Supplemental text here - CRE:616-305 + CRE:616-305 requirement-1.1