From 8956b98e6de82f9e38a60c42572f2343866f128a Mon Sep 17 00:00:00 2001 From: Matt Rutkowski Date: Wed, 24 May 2023 15:50:27 -0500 Subject: [PATCH] Update JSON schema to latest versions of CycloneDX v1.5-dev and SPDX 2.3.1 development (#32) * Minor cleanup of license command constants Signed-off-by: Matt Rutkowski * Update the v1.5 development schema to most recent Signed-off-by: Matt Rutkowski * Update the SPDX 2.3.1 development JSON schema Signed-off-by: Matt Rutkowski --------- Signed-off-by: Matt Rutkowski --- README.md | 34 +- cmd/license.go | 42 +- .../cyclonedx/1.5/bom-1.5-dev.schema.json | 809 +++++++++++++++++- resources/schema/spdx/2.3.1/spdx-schema.json | 12 +- 4 files changed, 840 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 3d64eacf..b230aa85 100644 --- a/README.md +++ b/README.md @@ -545,9 +545,11 @@ The `query` command does not support output results. #### Query examples -##### Example: Select a JSON object +##### Example: Extract the top-level `component` information from an SBOM -In this example, only the `--from` clause is needed to select an object. The `--select` clause is omitted which is equivalent to using the "select all" wildcard character `*` which returns all fields and values from the object. +This example effectively extracts the first-order package manifest from the SBOM. + +In this example, only the `--from` clause is needed to select an object. The `--select` clause is omitted which is equivalent to using the "select all" wildcard character `*` which returns all fields and values from the `component` object. ```bash ./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --from metadata.component @@ -556,7 +558,7 @@ In this example, only the `--from` clause is needed to select an object. The `- is equivalent to using the wildcard character (which may need to be enclosed in single or double quotes depending on your shell): ```bash -./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --select '*' --from metadata.component +./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --select '*' --from metadata.component --quiet ``` ```json @@ -586,9 +588,31 @@ is equivalent to using the wildcard character (which may need to be enclosed in ... ``` -##### Example: Select fields from JSON object +##### Example: Extract the `supplier` of the SBOM + +In this example, the `--from` clause references the top-level `metadata.supplier` object. + +```bash +./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --from metadata.supplier --quiet +``` + +```json +{ + "contact": [ + { + "email": "distribution@example.com" + } + ], + "name": "Example Co. Distribution Dept.", + "url": [ + "https://example.com/software/" + ] +} +``` + +##### Example: Extract just the SBOM component's `name` and `version` -In this example, the `--from` clause references the singleton JSON object `component` found under the top-level `metadata` object. It then reduces the resultant JSON object to only return the `name` and `value` fields and their values as requested on the `--select` clause. +In this example, the `--from` clause references the singleton JSON object `component` found under the top-level `metadata` object. It then reduces the resultant JSON object to only return the `name` and `value` fields and their values as requested on the `--select` clause. ```bash ./sbom-utility query --select name,version --from metadata.component -i examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json diff --git a/cmd/license.go b/cmd/license.go index c2a380a1..fd54add5 100644 --- a/cmd/license.go +++ b/cmd/license.go @@ -48,8 +48,16 @@ const ( LC_TYPE_EXPRESSION ) -// Declare a fixed-sized array for LC type names -var LC_TYPE_NAMES = [...]string{"invalid", "id", "name", "expression"} +// LicenseChoice - corresponding (name) values for license choice types +const ( + LC_VALUE_INVALID = "invalid" + LC_VALUE_ID = "id" + LC_VALUE_NAME = "name" + LC_VALUE_EXPRESSION = "expression" +) + +// Declare a fixed-sized array for LC type name indexed lookup +var LC_TYPE_NAMES = [...]string{LC_VALUE_INVALID, LC_VALUE_ID, LC_VALUE_NAME, LC_VALUE_EXPRESSION} const ( LC_LOC_UNKNOWN = iota @@ -59,12 +67,6 @@ const ( LC_LOC_SERVICES ) -const ( - LC_VALUE_ID = "id" - LC_VALUE_NAME = "name" - LC_VALUE_EXPRESSION = "expression" -) - var CDX_LICENSE_LOCATION_NAMES = map[int]string{ LC_LOC_UNKNOWN: "unknown", LC_LOC_METADATA_COMPONENT: "metadata.component", @@ -75,18 +77,18 @@ var CDX_LICENSE_LOCATION_NAMES = map[int]string{ // Note: the "License" property is used as hashmap key type LicenseInfo struct { - UsagePolicy string `json:"usage-policy"` - LicenseChoiceTypeValue int `json:"license-type-value"` - LicenseChoiceType string `json:"license-type"` - License string `json:"license"` - ResourceName string `json:"resource-name"` - BomRef string `json:"bom-ref"` - BomLocationValue int `json:"bom-location-value"` - BomLocation string `json:"bom-location"` - LicenseChoice schema.CDXLicenseChoice - Policy LicensePolicy - Component schema.CDXComponent - Service schema.CDXService + UsagePolicy string `json:"usage-policy"` + LicenseChoiceTypeValue int `json:"license-type-value"` + LicenseChoiceType string `json:"license-type"` + License string `json:"license"` + ResourceName string `json:"resource-name"` + BomRef string `json:"bom-ref"` + BomLocationValue int `json:"bom-location-value"` + BomLocation string `json:"bom-location"` + LicenseChoice schema.CDXLicenseChoice // Do not marshal + Policy LicensePolicy // Do not marshal + Component schema.CDXComponent // Do not marshal + Service schema.CDXService // Do not marshal } // License hashmap diff --git a/resources/schema/cyclonedx/1.5/bom-1.5-dev.schema.json b/resources/schema/cyclonedx/1.5/bom-1.5-dev.schema.json index f2f43304..eba1fbc8 100644 --- a/resources/schema/cyclonedx/1.5/bom-1.5-dev.schema.json +++ b/resources/schema/cyclonedx/1.5/bom-1.5-dev.schema.json @@ -87,7 +87,7 @@ "items": {"$ref": "#/definitions/compositions"}, "uniqueItems": true, "title": "Compositions", - "description": "Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness." + "description": "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." }, "vulnerabilities": { "type": "array", @@ -137,11 +137,39 @@ "description": "The date and time (timestamp) when the BOM was created." }, "tools": { - "type": "array", - "title": "Creation Tools", - "description": "The tool(s) used in the creation of the BOM.", - "additionalItems": false, - "items": {"$ref": "#/definitions/tool"} + "oneOf": [ + { + "type": "object", + "title": "Creation Tools", + "description": "The tool(s) used in the creation of the BOM.", + "additionalProperties": false, + "properties": { + "components": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/component"}, + "uniqueItems": true, + "title": "Components", + "description": "A list of software and hardware components used as tools" + }, + "services": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/service"}, + "uniqueItems": true, + "title": "Services", + "description": "A list of services used as tools. This may include microservices, function-as-a-service, and other types of network or intra-process services." + } + } + }, + { + "type": "array", + "title": "Creation Tools (legacy)", + "description": "[Deprecated] The tool(s) used in the creation of the BOM.", + "additionalItems": false, + "items": {"$ref": "#/definitions/tool"} + } + ] }, "authors" :{ "type": "array", @@ -183,7 +211,7 @@ "tool": { "type": "object", "title": "Tool", - "description": "Information about the automated or manual tool used", + "description": "[Deprecated] - DO NOT USE. This will be removed in a future version. This will be removed in a future version. Use component or service instead. Information about the automated or manual tool used", "additionalProperties": false, "properties": { "vendor": { @@ -293,13 +321,17 @@ "framework", "library", "container", + "platform", "operating-system", "device", + "device-driver", "firmware", - "file" + "file", + "machine-learning-model", + "data" ], "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* __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* __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.", + "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.", "examples": ["library"] }, "mime-type": { @@ -477,6 +509,17 @@ "$ref": "#/definitions/releaseNotes", "title": "Release notes", "description": "Specifies optional release notes." + }, + "modelCard": { + "$ref": "#/definitions/modelCard", + "title": "Machine Learning Model Card" + }, + "data": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/componentData"}, + "title": "Data", + "description": "This object SHOULD be specified for any component of type `data` and MUST NOT be specified for other component types." }, "properties": { "type": "array", @@ -1028,7 +1071,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* __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* __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* __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* __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* __other__ = Use this if no other types accurately describe the purpose of the external reference", "enum": [ "vcs", "issue-tracker", @@ -1041,11 +1084,26 @@ "documentation", "support", "distribution", + "distribution-intake", "license", "build-meta", "build-system", "release-notes", "security-contact", + "model-card", + "attestation", + "threat-model", + "vulnerability-assertion", + "exploitability-statement", + "pentest-report", + "static-analysis-report", + "dynamic-analysis-report", + "runtime-analysis-report", + "component-analysis-report", + "maturity-report", + "certification-report", + "codified-infrastructure", + "quality-metrics", "other" ] }, @@ -1145,12 +1203,17 @@ "title": "Crosses Trust Boundary", "description": "A boolean value indicating if use of the service crosses a trust zone or boundary. A value of true indicates that by using the service, a trust boundary is crossed. A value of false indicates that by using the service, a trust boundary is not crossed." }, + "trustZone": { + "type": "string", + "title": "Trust Zone", + "description": "The name of the trust zone the service resides in." + }, "data": { "type": "array", "additionalItems": false, - "items": {"$ref": "#/definitions/dataClassification"}, - "title": "Data Classification", - "description": "Specifies the data classification." + "items": {"$ref": "#/definitions/serviceData"}, + "title": "Data", + "description": "Specifies information about the data including the directional flow of data and the data classification." }, "licenses": { "type": "array", @@ -1192,7 +1255,7 @@ } } }, - "dataClassification": { + "serviceData": { "type": "object", "title": "Hash Objects", "required": [ @@ -1202,18 +1265,52 @@ "additionalProperties": false, "properties": { "flow": { - "$ref": "#/definitions/dataFlow", + "$ref": "#/definitions/dataFlowDirection", "title": "Directional Flow", "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." }, "classification": { + "$ref": "#/definitions/dataClassification" + }, + "name": { + "type": "string", + "title": "Name", + "description": "Name for the defined data", + "examples": [ + "Credit card reporting" + ] + }, + "description": { "type": "string", - "title": "Classification", - "description": "Data classification tags data according to its type, sensitivity, and value if altered, stolen, or destroyed." + "title": "Description", + "description": "Short description of the data content and usage", + "examples": [ + "Credit card information being exchanged in between the web app and the database" + ] + }, + "source": { + "type": "array", + "additionalItems": false, + "items": { + "type": "string", + "format": "iri-reference" + }, + "title": "Source", + "description": "The URI, URL, or BOM-Link of the components or services the data came in from" + }, + "destination": { + "type": "array", + "additionalItems": false, + "items": { + "type": "string", + "format": "iri-reference" + }, + "title": "Destination", + "description": "The URI, URL, or BOM-Link of the components or services the data is sent to" } } }, - "dataFlow": { + "dataFlowDirection": { "type": "string", "enum": [ "inbound", @@ -1239,13 +1336,172 @@ } } }, - "componentEvidence": { "type": "object", "title": "Evidence", "description": "Provides the ability to document evidence collected through various forms of extraction or analysis.", "additionalProperties": false, "properties": { + "identity": { + "type": "object", + "description": "Evidence that substantiates the identity of a component.", + "required": [ "field" ], + "additionalProperties": false, + "properties": { + "field": { + "type": "string", + "enum": [ + "group", "name", "version", "purl", "cpe", "swid", "hash" + ], + "title": "Field", + "description": "The identity field of the component which the evidence describes." + }, + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1, + "title": "Confidence", + "description": "The overall confidence of the evidence from 0 - 1, where 1 is 100% confidence." + }, + "methods": { + "type": "array", + "title": "Methods", + "description": "The methods used to extract and/or analyze the evidence.", + "additionalItems": false, + "items": { + "type": "object", + "required": [ + "technique" , + "confidence" + ], + "additionalProperties": false, + "properties": { + "technique": { + "title": "Technique", + "description": "The technique used in this method of analysis.", + "type": "string", + "enum": [ + "source-code-analysis", + "binary-analysis", + "manifest-analysis", + "ast-fingerprint", + "hash-comparison", + "instrumentation", + "dynamic-analysis", + "filename", + "attestation", + "other" + ] + }, + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1, + "title": "Confidence", + "description": "The confidence of the evidence from 0 - 1, where 1 is 100% confidence. Confidence is specific to the technique used. Each technique of analysis can have independent confidence." + }, + "value": { + "type": "string", + "title": "Value", + "description": "The value or contents of the evidence." + } + } + } + }, + "tools": { + "type": "array", + "uniqueItems": true, + "additionalItems": false, + "items": { + "$ref": "#/definitions/refType" + }, + "title": "BOM References", + "description": "The object in the BOM identified by its bom-ref. This is often a component or service, but may be any object type supporting bom-refs. Tools used for analysis should already be defined in the BOM, either in the metadata/tools, components, or formulation." + } + } + }, + "occurrences": { + "type": "array", + "title": "Occurrences", + "description": "Evidence of individual instances of a component spread across multiple locations.", + "additionalItems": false, + "items": { + "required": [ "location" ], + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the occurrence elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "location": { + "type": "string", + "title": "Location", + "description": "The location or path to where the component was found." + } + } + } + }, + "callstack": { + "type": "object", + "description": "Evidence of the components use through the callstack.", + "additionalProperties": false, + "properties": { + "frames": { + "type": "array", + "title": "Methods", + "additionalItems": false, + "items": { + "type": "object", + "required": [ + "module" + ], + "additionalProperties": false, + "properties": { + "package": { + "title": "Package", + "description": "A package organizes modules into namespaces, providing a unique namespace for each type it contains.", + "type": "string" + }, + "module": { + "title": "Module", + "description": "A module or class that encloses functions/methods and other code.", + "type": "string" + }, + "function": { + "title": "Function", + "description": "A block of code designed to perform a particular task.", + "type": "string" + }, + "parameters": { + "title": "Parameters", + "description": "Optional arguments that are passed to the module or function.", + "type": "array", + "additionalItems": false, + "items": { + "type": "string" + } + }, + "line": { + "title": "Line", + "description": "The line number the code that is called resides on.", + "type": "integer" + }, + "column": { + "title": "Column", + "description": "The column the code that is called resides.", + "type": "integer" + }, + "fullFilename": { + "title": "Full Filename", + "description": "The full path and filename of the module.", + "type": "string" + } + } + } + } + } + }, "licenses": { "type": "array", "additionalItems": false, @@ -1268,10 +1524,15 @@ ], "additionalProperties": false, "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the composition elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, "aggregate": { "$ref": "#/definitions/aggregateType", "title": "Aggregate", - "description": "Specifies an aggregate type that describe how complete a relationship is." + "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" }, "assemblies": { "type": "array", @@ -1291,6 +1552,15 @@ "title": "BOM references", "description": "The bom-ref identifiers of the components or services being described. Dependencies refer to a relationship whereby an independent constituent part requires another independent constituent part. References do not cascade to transitive dependencies. References are explicit for the specified dependency only." }, + "vulnerabilities": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string" + }, + "title": "BOM references", + "description": "The bom-ref identifiers of the vulnerabilities being described." + }, "signature": { "$ref": "#/definitions/signature", "title": "Signature", @@ -1305,7 +1575,11 @@ "complete", "incomplete", "incomplete_first_party_only", + "incomplete_first_party_proprietary_only", + "incomplete_first_party_opensource_only", "incomplete_third_party_only", + "incomplete_third_party_proprietary_only", + "incomplete_third_party_opensource_only", "unknown", "not_specified" ] @@ -1487,11 +1761,12 @@ "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* OWASP - [OWASP Risk Rating Methodology](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology)", + "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)", "enum": [ "CVSSv2", "CVSSv3", "CVSSv31", + "CVSSv4", "OWASP", "other" ] @@ -1668,13 +1943,41 @@ "detail": { "type": "string", "title": "Details", - "description": "If available, an in-depth description of the vulnerability as provided by the source organization. Details often include examples, proof-of-concepts, and other information useful in understanding root cause." + "description": "If available, an in-depth description of the vulnerability as provided by the source organization. Details often include information useful in understanding root cause." }, "recommendation": { "type": "string", - "title": "Details", + "title": "Recommendation", "description": "Recommendations of how the vulnerability can be remediated or mitigated." }, + "workaround": { + "type": "string", + "title": "Workarounds", + "description": "A bypass, usually temporary, of the vulnerability that reduces its likelihood and/or impact. Workarounds often involve changes to configuration or deployments." + }, + "proofOfConcept": { + "type": "object", + "title": "Proof of Concept", + "description": "Evidence used to reproduce the vulnerability.", + "properties": { + "reproductionSteps": { + "type": "string", + "title": "Steps to Reproduce", + "description": "Precise steps to reproduce the vulnerability." + }, + "environment": { + "type": "string", + "title": "Environment", + "description": "A description of the environment in which reproduction was possible." + }, + "supportingMaterial": { + "type": "array", + "title": "Supporting Material", + "description": "Supporting material that helps in reproducing or understanding how reproduction is possible. This may include screenshots, payloads, and PoC exploit code.", + "items": { "$ref": "#/definitions/attachment" } + } + } + }, "advisories": { "type": "array", "title": "Advisories", @@ -1735,11 +2038,39 @@ } }, "tools": { - "type": "array", - "title": "Creation Tools", - "description": "The tool(s) used to identify, confirm, or score the vulnerability.", - "additionalItems": false, - "items": {"$ref": "#/definitions/tool"} + "oneOf": [ + { + "type": "object", + "title": "Tools", + "description": "The tool(s) used to identify, confirm, or score the vulnerability.", + "additionalProperties": false, + "properties": { + "components": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/component"}, + "uniqueItems": true, + "title": "Components", + "description": "A list of software and hardware components used as tools" + }, + "services": { + "type": "array", + "additionalItems": false, + "items": {"$ref": "#/definitions/service"}, + "uniqueItems": true, + "title": "Services", + "description": "A list of services used as tools. This may include microservices, function-as-a-service, and other types of network or intra-process services." + } + } + }, + { + "type": "array", + "title": "Tools (legacy)", + "description": "[Deprecated] The tool(s) used to identify, confirm, or score the vulnerability.", + "additionalItems": false, + "items": {"$ref": "#/definitions/tool"} + } + ] }, "analysis": { "type": "object", @@ -1825,7 +2156,7 @@ }, "range": { "description": "A version range specified in Package URL Version Range syntax (vers) which is defined at https://github.com/package-url/purl-spec/VERSION-RANGE-SPEC.rst", - "$ref": "#/definitions/version" + "$ref": "#/definitions/range" }, "status": { "description": "The vulnerability status for the version or range of versions.", @@ -1963,6 +2294,426 @@ } } }, + "modelCard": { + "$comment": "Model card support in CycloneDX is derived from TensorFlow Model Card Toolkit released under the Apache 2.0 license and available from https://github.com/tensorflow/model-card-toolkit/blob/main/model_card_toolkit/schema/v0.0.2/model_card.schema.json. In addition, CycloneDX model card support includes portions of VerifyML, also released under the Apache 2.0 license and available from https://github.com/cylynx/verifyml/blob/main/verifyml/model_card_toolkit/schema/v0.0.4/model_card.schema.json.", + "type": "object", + "title": "Model Card", + "description": "A model card describes the intended uses of a machine learning model and potential limitations, including biases and ethical considerations. Model cards typically contain the training parameters, which datasets were used to train the model, performance metrics, and other relevant data useful for ML transparency. This object SHOULD be specified for any component of type `machine-learning-model` and MUST NOT be specified for other component types.", + "additionalProperties": false, + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the model card elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "modelParameters": { + "type": "object", + "title": "Model Parameters", + "description": "Hyper-parameters for construction of the model.", + "additionalProperties": false, + "properties": { + "approach": { + "type": "object", + "title": "Approach", + "description": "The overall approach to learning used by the model for problem solving.", + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "title": "Learning Type", + "description": "Learning types describing the learning problem or hybrid learning problem.", + "enum": [ + "supervised", + "unsupervised", + "reinforcement-learning", + "semi-supervised", + "self-supervised" + ] + } + } + }, + "task": { + "type": "string", + "title": "Task", + "description": "Directly influences the input and/or output. Examples include classification, regression, clustering, etc." + }, + "architectureFamily": { + "type": "string", + "title": "Architecture Family", + "description": "The model architecture family such as transformer network, convolutional neural network, residual neural network, LSTM neural network, etc." + }, + "modelArchitecture": { + "type": "string", + "title": "Model Architecture", + "description": "The specific architecture of the model such as GPT-1, ResNet-50, YOLOv3, etc." + }, + "datasets": { + "type": "array", + "title": "Datasets", + "description": "The datasets used to train and evaluate the model.", + "additionalItems": false, + "items" : { + "oneOf" : [ + { + "title": "Inline Component Data", + "$ref": "#/definitions/componentData" + }, + { + "title": "Data Component Reference", + "additionalProperties": false, + "properties": { + "ref": { + "type": "string", + "title": "Reference", + "description": "References a data component by the components bom-ref attribute" + } + } + } + ] + } + }, + "inputs": { + "type": "array", + "title": "Inputs", + "description": "The input format(s) of the model", + "additionalItems": false, + "items": { "$ref": "#/definitions/inputOutputMLParameters" } + }, + "outputs": { + "type": "array", + "title": "Outputs", + "description": "The output format(s) from the model", + "additionalItems": false, + "items": { "$ref": "#/definitions/inputOutputMLParameters" } + } + } + }, + "quantitativeAnalysis": { + "type": "object", + "title": "Quantitative Analysis", + "description": "A quantitative analysis of the model", + "additionalProperties": false, + "properties": { + "performanceMetrics": { + "type": "array", + "title": "Performance Metrics", + "description": "The model performance metrics being reported. Examples may include accuracy, F1 score, precision, top-3 error rates, MSC, etc.", + "additionalItems": false, + "items": { "$ref": "#/definitions/performanceMetric" } + }, + "graphics": { "$ref": "#/definitions/graphicsCollection" } + } + }, + "considerations": { + "type": "object", + "title": "Considerations", + "description": "What considerations should be taken into account regarding the model's construction, training, and application?", + "additionalProperties": false, + "properties": { + "users": { + "type": "array", + "title": "Users", + "description": "Who are the intended users of the model?", + "additionalItems": false, + "items": { + "type": "string" + } + }, + "useCases": { + "type": "array", + "title": "Use Cases", + "description": "What are the intended use cases of the model?", + "additionalItems": false, + "items": { + "type": "string" + } + }, + "technicalLimitations": { + "type": "array", + "title": "Technical Limitations", + "description": "What are the known technical limitations of the model? E.g. What kind(s) of data should the model be expected not to perform well on? What are the factors that might degrade model performance?", + "additionalItems": false, + "items": { + "type": "string" + } + }, + "performanceTradeoffs": { + "type": "array", + "title": "Performance Tradeoffs", + "description": "What are the known tradeoffs in accuracy/performance of the model?", + "additionalItems": false, + "items": { + "type": "string" + } + }, + "ethicalConsiderations": { + "type": "array", + "title": "Ethical Considerations", + "description": "What are the ethical (or environmental) risks involved in the application of this model?", + "additionalItems": false, + "items": { "$ref": "#/definitions/risk" } + }, + "fairnessAssessments": { + "type": "array", + "title": "Fairness Assessments", + "description": "How does the model affect groups at risk of being systematically disadvantaged? What are the harms and benefits to the various affected groups?", + "additionalItems": false, + "items": { + "$ref": "#/definitions/fairnessAssessment" + } + } + } + }, + "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.", + "additionalItems": false, + "items": {"$ref": "#/definitions/property"} + } + } + }, + "inputOutputMLParameters": { + "type": "object", + "title": "Input and Output Parameters", + "additionalProperties": false, + "properties": { + "format": { + "description": "The data format for input/output to the model. Example formats include string, image, time-series", + "type": "string" + } + } + }, + "componentData": { + "type": "object", + "additionalProperties": false, + "required": [ + "type" + ], + "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the dataset elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, + "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* __other__ = Any other type of data that does not fit into existing definitions.", + "enum": [ + "source-code", + "configuration", + "dataset", + "other" + ] + }, + "name": { + "description": "The name of the dataset.", + "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" + }, + "properties": { + "type": "array", + "title": "Configuration Properties", + "description": "Provides the ability to document name-value parameters used for configuration.", + "additionalItems": false, + "items": { + "$ref": "#/definitions/property" + } + } + } + }, + "classification": { + "$ref": "#/definitions/dataClassification" + }, + "sensitiveData": { + "type": "array", + "description": "A description of any sensitive data in a dataset.", + "additionalItems": false, + "items": { + "type": "string" + } + }, + "graphics": { "$ref": "#/definitions/graphicsCollection" }, + "description": { + "description": "A description of the dataset. Can describe size of dataset, whether it's used for source code, training, testing, or validation, etc.", + "type": "string" + }, + "governance": { + "type": "object", + "title": "Data Governance", + "description": "", + "additionalProperties": false, + "properties": { + "custodians": { + "type": "array", + "title": "Data Custodians", + "description": "Data custodians are responsible for the safe custody, transport, and storage of data.", + "additionalItems": false, + "items": { "$ref": "#/definitions/dataGovernanceResponsibleParty" } + }, + "stewards": { + "type": "array", + "title": "Data Stewards", + "description": "Data stewards are responsible for data content, context, and associated business rules.", + "items": { "$ref": "#/definitions/dataGovernanceResponsibleParty" } + }, + "owners": { + "type": "array", + "title": "Data Owners", + "description": "Data owners are concerned with risk and appropriate access to data.", + "items": { "$ref": "#/definitions/dataGovernanceResponsibleParty" } + } + } + } + } + }, + "dataGovernanceResponsibleParty": { + "additionalProperties": false, + "properties": { + "organization": { + "title": "Organization", + "$ref": "#/definitions/organizationalEntity" + }, + "contact": { + "title": "Individual", + "$ref": "#/definitions/organizationalContact" + } + }, + "oneOf":[ + { + "required": ["organization"] + }, + { + "required": ["contact"] + } + ] + }, + "graphicsCollection": { + "type": "object", + "title": "Graphics Collection", + "description": "A collection of graphics that represent various measurements.", + "additionalProperties": false, + "properties": { + "description": { + "description": "A description of this collection of graphics.", + "type": "string" + }, + "collection": { + "description": "A collection of graphics.", + "type": "array", + "additionalItems": false, + "items": { "$ref": "#/definitions/graphic" } + } + } + }, + "graphic": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "description": "The name of the graphic.", + "type": "string" + }, + "image": { + "title": "Graphic Image", + "description": "The graphic (vector or raster). Base64 encoding MUST be specified for binary images.", + "$ref": "#/definitions/attachment" + } + } + }, + "performanceMetric": { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { + "description": "The type of performance metric.", + "type": "string" + }, + "value": { + "description": "The value of the performance metric.", + "type": "string" + }, + "slice": { + "description": "The name of the slice this metric was computed on. By default, assume this metric is not sliced.", + "type": "string" + }, + "confidenceInterval": { + "description": "The confidence interval of the metric.", + "type": "object", + "additionalProperties": false, + "properties": { + "lowerBound": { + "description": "The lower bound of the confidence interval.", + "type": "string" + }, + "upperBound": { + "description": "The upper bound of the confidence interval.", + "type": "string" + } + } + } + } + }, + "risk": { + "type": "object", + "additionalProperties": false, + "properties": { + "name": { + "description": "The name of the risk.", + "type": "string" + }, + "mitigationStrategy": { + "description": "Strategy used to address this risk.", + "type": "string" + } + } + }, + "fairnessAssessment": { + "type": "object", + "title": "Fairness Assessment", + "description": "Information about the benefits and harms of the model to an identified at risk group.", + "additionalProperties": false, + "properties": { + "groupAtRisk": { + "type": "string", + "description": "The groups or individuals at risk of being systematically disadvantaged by the model." + }, + "benefits": { + "type": "string", + "description": "Expected benefits to the identified groups." + }, + "harms": { + "type": "string", + "description": "Expected harms to the identified groups." + }, + "mitigationStrategy": { + "type": "string", + "description": "With respect to the benefits and harms outlined, please describe any mitigation strategy implemented." + } + } + }, + "dataClassification": { + "type": "string", + "title": "Data Classification", + "description": "Data classification tags data according to its type, sensitivity, and value if altered, stolen, or destroyed." + }, "signature": { "$ref": "jsf-0.82.schema.json#/definitions/signature", "title": "Signature", diff --git a/resources/schema/spdx/2.3.1/spdx-schema.json b/resources/schema/spdx/2.3.1/spdx-schema.json index ee66afa1..403d2024 100644 --- a/resources/schema/spdx/2.3.1/spdx-schema.json +++ b/resources/schema/spdx/2.3.1/spdx-schema.json @@ -1,5 +1,5 @@ { - "$schema" : "http://json-schema.org/draft-07/schema#", + "$schema" : "https://json-schema.org/draft/2019-09/schema#", "$id" : "http://spdx.org/rdf/terms/2.3", "title" : "SPDX 2.3", "type" : "object", @@ -187,6 +187,7 @@ }, "revieweds" : { "description" : "Reviewed", + "deprecated": true, "type" : "array", "items" : { "type" : "object", @@ -217,7 +218,9 @@ "description" : "The URI provides an unambiguous mechanism for other SPDX documents to reference SPDX elements within this SPDX document." }, "documentDescribes" : { - "description" : "Packages, files and/or Snippets described by this SPDX document", + "description" : "DEPRECATED: use relationships instead of this field. Packages, files and/or Snippets described by this SPDX document", + "deprecated": true, + "$comment": "This field has been deprecated as it is a duplicate of using the SPDXRef-DOCUMENT DESCRIBES relationship", "type" : "array", "items" : { "type" : "string", @@ -343,7 +346,9 @@ "type" : "boolean" }, "hasFiles" : { - "description" : "Indicates that a particular file belongs to a package.", + "description" : "DEPRECATED: use relationships instead of this field. Indicates that a particular file belongs to a package.", + "deprecated": true, + "$comment": "This field has been deprecated as it is a duplicate of using CONTAINS relationships from a package to files", "type" : "array", "items" : { "description" : "SPDX ID for File. Indicates that a particular file belongs to a package.", @@ -531,6 +536,7 @@ }, "fileDependencies" : { "description" : "This field is deprecated since SPDX 2.0 in favor of using Section 7 which provides more granularity about relationships.", + "deprecated": true, "type" : "array", "items" : { "description" : "SPDX ID for File. This field is deprecated since SPDX 2.0 in favor of using Section 7 which provides more granularity about relationships.",