Merge branch 'v1.5-dev' into v1.5-dev-machine-learning

Author: stevespringett

docgen/json/gen.sh

@@ -4,7 +4,7 @@ mkdir -p docs/{1.2,1.3,1.4,1.5}
 
 # 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.39.5
+  pip3 install json-schema-for-humans==0.44.3
 fi
 
 generate () {
@@ -18,7 +18,7 @@ generate () {
       SCHEMA_FILE='../../schema/bom-'$version'.schema.json'
   fi
   echo $SCHEMA_FILE
-  generate-schema-doc --config no_link_to_reused_ref --config no_show_breadcrumbs --config no_collapse_long_descriptions --config deprecated_from_description --config title="$title" --config custom_template_path=$(pwd)'/templates/cyclonedx/base.html' --minify $SCHEMA_FILE 'docs/'$version'/index.html'
+  generate-schema-doc --config no_link_to_reused_ref --config no_show_breadcrumbs --config no_collapse_long_descriptions --deprecated-from-description --config title="$title" --config custom_template_path=$(pwd)'/templates/cyclonedx/base.html' --minify $SCHEMA_FILE 'docs/'$version'/index.html'
   sed -i -e "s/\${quotedTitle}/\"$title\"/g" 'docs/'$version'/index.html'
   sed -i -e "s/\${title}/$title/g" 'docs/'$version'/index.html'
   sed -i -e "s/\${version}/$version/g" 'docs/'$version'/index.html'

schema/bom-1.5.proto

@@ -57,12 +57,14 @@ enum Classification {
   CLASSIFICATION_CONTAINER = 7;
   // A special type of software that provides low-level control over a devices hardware. Refer to https://en.wikipedia.org/wiki/Firmware
   CLASSIFICATION_FIRMWARE = 8;
+  // A special type of software that operates or controls a particular type of device. Refer to https://en.wikipedia.org/wiki/Device_driver
+  CLASSIFICATION_DEVICE_DRIVER = 9;
   // 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.
-  CLASSIFICATION_PLATFORM = 9;
+  CLASSIFICATION_PLATFORM = 10;
   // A model based on training data that can make predictions or decisions without being explicitly programmed to do so.
-  CLASSIFICATION_MACHINE_LEARNING_MODEL = 10;
+  CLASSIFICATION_MACHINE_LEARNING_MODEL = 11;
   // A collection of discrete values that convey information.
-  CLASSIFICATION_DATA = 11;
+  CLASSIFICATION_DATA = 12;
 }
 
 message Commit {
@@ -131,16 +133,24 @@ message Component {
   optional ComponentData data = 26;
 }
 
-// Specifies the data classification.
-message DataClassification {
+// Specifies the data flow.
+message DataFlow {
   // Specifies the flow direction of the data.
-  DataFlow flow = 1;
-  // SimpleContent value of element
+  DataFlowDirection flow = 1;
+  // Data classification tags data according to its type, sensitivity, and value if altered, stolen, or destroyed.
   string value = 2;
+  // Name for the defined data
+  optional string name = 3;
+  // Short description of the data content and usage
+  optional string description = 4;
+  // The URI, URL, or BOM-Link of the components or services the data came in from
+  repeated string source = 5;
+  // The URI, URL, or BOM-Link of the components or services the data is sent to
+  repeated string destination = 6;
 }
 
 // Specifies the flow direction of the data. Valid values are: inbound, outbound, bi-directional, and unknown. 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.
-enum DataFlow {
+enum DataFlowDirection {
   DATA_FLOW_NULL = 0;
   DATA_FLOW_INBOUND = 1;
   DATA_FLOW_OUTBOUND = 2;
@@ -205,8 +215,36 @@ enum ExternalReferenceType {
   EXTERNAL_REFERENCE_TYPE_BUILD_SYSTEM = 14;
   // 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.
   EXTERNAL_REFERENCE_TYPE_SECURITY_CONTACT = 15;
+  // Human or machine-readable statements containing facts, evidence, or testimony
+  EXTERNAL_REFERENCE_TYPE_ATTESTATION = 16;
+  // An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format
+  EXTERNAL_REFERENCE_TYPE_THREAT_MODEL = 17;
+  // 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
+  EXTERNAL_REFERENCE_TYPE_DISTRIBUTION_INTAKE = 18;
+  // 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
+  EXTERNAL_REFERENCE_TYPE_VULNERABILITY_ASSERTION = 19;
+  // 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
+  EXTERNAL_REFERENCE_TYPE_EXPLOITABILITY_STATEMENT = 20;
+  // Results from an authorized simulated cyberattack on a component or service, otherwise known as a penetration test
+  EXTERNAL_REFERENCE_TYPE_PENTEST_REPORT = 21;
+  // 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
+  EXTERNAL_REFERENCE_TYPE_STATIC_ANALYSIS_REPORT = 22;
+  // Dynamic analysis report that has identified issues such as vulnerabilities and misconfigurations
+  EXTERNAL_REFERENCE_TYPE_DYNAMIC_ANALYSIS_REPORT = 23;
+  // Report generated by analyzing the call stack of a running application
+  EXTERNAL_REFERENCE_TYPE_RUNTIME_ANALYSIS_REPORT = 24;
+  // Report generated by Software Composition Analysis (SCA), container analysis, or other forms of component analysis
+  EXTERNAL_REFERENCE_TYPE_COMPONENT_ANALYSIS_REPORT = 25;
+  // Report containing a formal assessment of an organization, business unit, or team against a maturity model
+  EXTERNAL_REFERENCE_TYPE_MATURITY_REPORT = 26;
+  // Industry, regulatory, or other certification from an accredited (if applicable) certification body
+  EXTERNAL_REFERENCE_TYPE_CERTIFICATION_REPORT = 27;
+  // Report or system in which quality metrics can be obtained
+  EXTERNAL_REFERENCE_TYPE_QUALITY_METRICS = 28;
+  // Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC)
+  EXTERNAL_REFERENCE_TYPE_CODIFIED_INFRASTRUCTURE = 29;
   // 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.
-  EXTERNAL_REFERENCE_TYPE_MODEL_CARD = 16;
+  EXTERNAL_REFERENCE_TYPE_MODEL_CARD = 30;
 }
 
 enum HashAlg {
@@ -365,7 +403,7 @@ message Metadata {
   // The date and time (timestamp) when the document was created.
   optional google.protobuf.Timestamp timestamp = 1;
   // The tool(s) used in the creation of the BOM.
-  repeated Tool tools = 2;
+  optional Tool tools = 2;
   // The person(s) who created the BOM. Authors are common in BOMs created through manual processes. BOMs created through automated means may not have authors.
   repeated OrganizationalContact authors = 3;
   // The component that the BOM describes.
@@ -463,7 +501,7 @@ message Service {
   optional bool authenticated = 8;
   // 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.
   optional bool x_trust_boundary = 9;
-  repeated DataClassification data = 10;
+  repeated DataFlow data = 10;
   repeated LicenseChoice licenses = 11;
   // Provides the ability to document external references related to the service.
   repeated ExternalReference external_references = 12;
@@ -473,6 +511,8 @@ message Service {
   repeated Property properties = 14;
   // Specifies optional release notes.
   optional ReleaseNotes releaseNotes = 15;
+  // The name of the trust zone the service resides in.
+  optional string trustZone = 16;
 }
 
 message Swid {
@@ -494,15 +534,20 @@ message Swid {
 
 // Specifies a tool (manual or automated).
 message Tool {
-  // The vendor of the tool used to create the BOM.
-  optional string vendor = 1;
-  // The name of the tool used to create the BOM.
-  optional string name = 2;
-  // The version of the tool used to create the BOM.
-  optional string version = 3;
-  repeated Hash hashes = 4;
-  // Provides the ability to document external references related to the tool.
-  repeated ExternalReference external_references = 5;
+  // DEPRECATED - DO NOT USE - The vendor of the tool used to create the BOM.
+  optional string vendor = 1 [deprecated = true];
+  // DEPRECATED - DO NOT USE - The name of the tool used to create the BOM.
+  optional string name = 2 [deprecated = true];
+  // DEPRECATED - DO NOT USE - The version of the tool used to create the BOM.
+  optional string version = 3 [deprecated = true];
+  // DEPRECATED - DO NOT USE
+  repeated Hash hashes = 4 [deprecated = true];
+  // DEPRECATED - DO NOT USE - Provides the ability to document external references related to the tool.
+  repeated ExternalReference external_references = 5 [deprecated = true];
+  // A list of software and hardware components used as tools
+  repeated Component components = 6;
+  // A list of services used as tools. This may include microservices, function-as-a-service, and other types of network or intra-process services.
+  repeated Service services = 7;
 }
 
 // Specifies a property
@@ -543,6 +588,82 @@ message EvidenceCopyright {
 message Evidence {
   repeated LicenseChoice licenses = 1;
   repeated EvidenceCopyright copyright = 2;
+  repeated EvidenceIdentity identity = 3;
+  repeated EvidenceOccurrences occurrences = 4;
+  optional Callstack callstack = 5;
+}
+
+// Evidence of the components use through the callstack.
+message Callstack {
+  repeated Frames frames = 1;
+
+  message Frames {
+    // A package organizes modules into namespaces, providing a unique namespace for each type it contains.
+    optional string package = 1;
+    // A module or class that encloses functions/methods and other code.
+    string module = 2;
+    // A block of code designed to perform a particular task.
+    optional string function = 3;
+    // Optional arguments that are passed to the module or function.
+    repeated string parameters = 4;
+    // The line number the code that is called resides on.
+    optional int32 line = 5;
+    // The column the code that is called resides.
+    optional int32 column = 6;
+    // The full path and filename of the module.
+    optional string fullFilename = 7;
+  }
+}
+
+message EvidenceIdentity {
+  // The identity field of the component which the evidence describes.
+  EvidenceFieldType field = 1;
+  // The overall confidence of the evidence from 0 - 1, where 1 is 100% confidence.
+  optional float confidence = 2;
+  // The methods used to extract and/or analyze the evidence.
+  repeated EvidenceMethods methods = 3;
+  // 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.
+  repeated string tools = 4;
+}
+
+message EvidenceMethods {
+  // The technique used in this method of analysis.
+  EvidenceTechnique technique = 1;
+  // 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.
+  float confidence = 2;
+  // The value or contents of the evidence.
+  optional string value = 3;
+}
+
+message EvidenceOccurrences {
+  // An optional identifier which can be used to reference the occurrence elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.
+  optional string bom_ref = 1;
+  // The location or path to where the component was found.
+  string location = 2;
+}
+
+enum EvidenceFieldType {
+  EVIDENCE_FIELD_NULL = 0;
+  EVIDENCE_FIELD_GROUP = 1;
+  EVIDENCE_FIELD_NAME = 2;
+  EVIDENCE_FIELD_VERSION = 3;
+  EVIDENCE_FIELD_PURL = 4;
+  EVIDENCE_FIELD_CPE = 5;
+  EVIDENCE_FIELD_SWID = 6;
+  EVIDENCE_FIELD_HASH = 7;
+}
+
+enum EvidenceTechnique {
+  EVIDENCE_TECHNIQUE_SOURCE_CODE_ANALYSIS = 0;
+  EVIDENCE_TECHNIQUE_BINARY_ANALYSIS = 1;
+  EVIDENCE_TECHNIQUE_MANIFEST_ANALYSIS = 2;
+  EVIDENCE_TECHNIQUE_AST_FINGERPRINT = 3;
+  EVIDENCE_TECHNIQUE_HASH_COMPARISON = 4;
+  EVIDENCE_TECHNIQUE_INSTRUMENTATION = 5;
+  EVIDENCE_TECHNIQUE_DYNAMIC_ANALYSIS = 6;
+  EVIDENCE_TECHNIQUE_FILENAME = 7;
+  EVIDENCE_TECHNIQUE_ATTESTATION = 8;
+  EVIDENCE_TECHNIQUE_OTHER = 9;
 }
 
 message Note {
@@ -592,7 +713,7 @@ message Vulnerability {
   repeated int32 cwes = 6;
   // A description of the vulnerability as provided by the source.
   optional string description = 7;
-  // 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.
+  // If available, an in-depth description of the vulnerability as provided by the source organization. Details often include information useful in understanding root cause.
   optional string detail = 8;
   // Recommendations of how the vulnerability can be remediated or mitigated.
   optional string recommendation = 9;
@@ -607,7 +728,7 @@ message Vulnerability {
   // Individuals or organizations credited with the discovery of the vulnerability.
   optional VulnerabilityCredits credits = 14;
   // The tool(s) used to identify, confirm, or score the vulnerability.
-  repeated Tool tools = 15;
+  optional Tool tools = 15;
   // An assessment of the impact and exploitability of the vulnerability.
   optional VulnerabilityAnalysis analysis = 16;
   // affects
@@ -616,6 +737,19 @@ message Vulnerability {
   repeated Property properties = 18;
   // The date and time (timestamp) when the vulnerability record was rejected (if applicable).
   optional google.protobuf.Timestamp rejected = 19;
+  // Evidence used to reproduce the vulnerability.
+  optional ProofOfConcept proofOfConcept = 20;
+  // A bypass, usually temporary, of the vulnerability that reduces its likelihood and/or impact. Workarounds often involve changes to configuration or deployments.
+  optional string workaround = 21;
+}
+
+message ProofOfConcept {
+  // Precise steps to reproduce the vulnerability.
+  optional string reproductionSteps = 1;
+  // A description of the environment in which reproduction was possible.
+  optional string environment = 2;
+  // Supporting material that helps in reproducing or understanding how reproduction is possible. This may include screenshots, payloads, and PoC exploit code.
+  repeated AttachedText supportingMaterial = 3;
 }
 
 message VulnerabilityReference {
@@ -663,6 +797,8 @@ enum ScoreMethod {
   SCORE_METHOD_OWASP = 4;
   // Other scoring method
   SCORE_METHOD_OTHER = 5;
+  // Common Vulnerability Scoring System v3.1 - https://www.first.org/cvss/v4-0/
+  SCORE_METHOD_CVSSV4 = 6;
 }
 
 message Advisory {