Merge pull request #91 from CycloneDX/v1.4-vulns

Added vulnerabilities as part of core spec

schema/bom-1.4-SNAPSHOT.proto

@@ -31,6 +31,8 @@ message Bom {
   repeated Dependency dependencies = 8;
   // Provides the ability to document aggregate completeness
   repeated Composition compositions = 9;
+  // Vulnerabilities identified in components or services.
+  repeated Vulnerability vulnerabilities = 10;
 }
 
 enum Classification {
@@ -452,3 +454,186 @@ message Evidence {
   repeated LicenseChoice licenses = 1;
   repeated EvidenceCopyright copyright = 2;
 }
+
+message Vulnerability {
+  // An optional identifier which can be used to reference the vulnerability 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 that uniquely identifies the vulnerability.
+  optional string id = 2;
+  // The source that published the vulnerability.
+  optional Source source = 3;
+  // Zero or more pointers to vulnerabilities that are the equivalent of the vulnerability specified. Often times, the same vulnerability may exist in multiple sources of vulnerability intelligence, but have different identifiers. References provide a way to correlate vulnerabilities across multiple sources of vulnerability intelligence.
+  repeated VulnerabilityReference references = 4;
+  // List of vulnerability ratings
+  repeated VulnerabilityRating ratings = 5;
+  // List of Common Weaknesses Enumerations (CWEs) codes that describes this vulnerability. For example 399 (of https://cwe.mitre.org/data/definitions/399.html)
+  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.
+  optional string detail = 8;
+  // Recommendations of how the vulnerability can be remediated or mitigated.
+  optional string recommendation = 9;
+  // Published advisories of the vulnerability if provided.
+  repeated Advisory advisories = 10;
+  // The date and time (timestamp) when the vulnerability record was created in the vulnerability database.
+  optional google.protobuf.Timestamp created = 11;
+  // The date and time (timestamp) when the vulnerability record was first published.
+  optional google.protobuf.Timestamp published = 12;
+  // The date and time (timestamp) when the vulnerability record was last updated.
+  optional google.protobuf.Timestamp updated = 13;
+  // 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;
+  // An assessment of the impact and exploitability of the vulnerability.
+  optional VulnerabilityAnalysis analysis = 16;
+  // affects
+  repeated VulnerabilityAffects affects = 17;
+}
+
+message VulnerabilityReference {
+  // An identifier that uniquely identifies the vulnerability.
+  optional string id = 1;
+  // The source that published the vulnerability.
+  optional Source source = 2;
+}
+
+message VulnerabilityRating {
+  // The source that calculated the severity or risk rating of the vulnerability.
+  optional Source source = 1;
+  // The numerical score of the rating.
+  optional double score = 2;
+  // Textual representation of the severity that corresponds to the numerical score of the rating.
+  optional Severity severity = 3;
+  // Specifies the severity or risk scoring methodology or standard used.
+  optional ScoreMethod method = 4;
+  // Textual representation of the metric values used to score the vulnerability.
+  optional string vector = 5;
+  // An optional reason for rating the vulnerability as it was.
+  optional string justification = 6;
+}
+
+enum Severity {
+  SEVERITY_UNKNOWN = 0;
+  SEVERITY_CRITICAL = 1;
+  SEVERITY_HIGH = 2;
+  SEVERITY_MEDIUM = 3;
+  SEVERITY_LOW = 4;
+  SEVERITY_INFO = 5;
+  SEVERITY_NONE = 6;
+}
+
+enum ScoreMethod {
+  // An undefined score method
+  SCORE_METHOD_NULL = 0;
+  // Common Vulnerability Scoring System v2 - https://www.first.org/cvss/v2/
+  SCORE_METHOD_CVSSV2 = 1;
+  // Common Vulnerability Scoring System v3 - https://www.first.org/cvss/v3-0/
+  SCORE_METHOD_CVSSV3 = 2;
+  // Common Vulnerability Scoring System v3.1 - https://www.first.org/cvss/v3-1/
+  SCORE_METHOD_CVSSV31 = 3;
+  // OWASP Risk Rating Methodology - https://owasp.org/www-community/OWASP_Risk_Rating_Methodology
+  SCORE_METHOD_OWASP = 4;
+  // Other scoring method
+  SCORE_METHOD_OTHER = 5;
+}
+
+message Advisory {
+  // An optional name of the advisory.
+  optional string title = 1;
+  // Location where the advisory can be obtained.
+  string url = 2;
+}
+
+message VulnerabilityCredits {
+  // The organizations credited with vulnerability discovery.
+  repeated OrganizationalEntity organizations = 1;
+  // The individuals, not associated with organizations, that are credited with vulnerability discovery.
+  repeated OrganizationalContact individuals = 2;
+}
+
+message VulnerabilityAnalysis {
+  // Declares the current state of an occurrence of a vulnerability, after automated or manual analysis.
+  optional ImpactAnalysisState state = 1;
+  // The rationale of why the impact analysis state was asserted.
+  optional ImpactAnalysisJustification justification = 2;
+  // A response to the vulnerability by the manufacturer, supplier, or project responsible for the affected component or service. More than one response is allowed. Responses are strongly encouraged for vulnerabilities where the analysis state is exploitable.
+  repeated VulnerabilityResponse response = 3;
+  // Detailed description of the impact including methods used during assessment. If a vulnerability is not exploitable, this field should include specific details on why the component or service is not impacted by this vulnerability.
+  optional string detail = 4;
+}
+
+enum ImpactAnalysisState {
+  // An undefined impact analysis state
+  IMPACT_ANALYSIS_STATE_NULL = 0;
+  // The vulnerability has been remediated.
+  IMPACT_ANALYSIS_STATE_RESOLVED = 1;
+  // 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).
+  IMPACT_ANALYSIS_STATE_RESOLVED_WITH_PEDIGREE = 2;
+  // The vulnerability may be directly or indirectly exploitable.
+  IMPACT_ANALYSIS_STATE_EXPLOITABLE = 3;
+  // The vulnerability is being investigated.
+  IMPACT_ANALYSIS_STATE_IN_TRIAGE = 4;
+  // The vulnerability is not specific to the component or service and was falsely identified or associated.
+  IMPACT_ANALYSIS_STATE_FALSE_POSITIVE = 5;
+  // The component or service is not affected by the vulnerability. Justification should be specified for all not_affected cases.
+  IMPACT_ANALYSIS_STATE_NOT_AFFECTED = 6;
+}
+
+enum ImpactAnalysisJustification {
+  // An undefined impact analysis justification
+  IMPACT_ANALYSIS_JUSTIFICATION_NULL = 0;
+  // The code has been removed or tree-shaked.
+  IMPACT_ANALYSIS_JUSTIFICATION_CODE_NOT_PRESENT = 1;
+  // The vulnerable code is not invoked at runtime.
+  IMPACT_ANALYSIS_JUSTIFICATION_CODE_NOT_REACHABLE = 2;
+  // Exploitability requires a configurable option to be set/unset.
+  IMPACT_ANALYSIS_JUSTIFICATION_REQUIRES_CONFIGURATION = 3;
+  // Exploitability requires a dependency that is not present.
+  IMPACT_ANALYSIS_JUSTIFICATION_REQUIRES_DEPENDENCY = 4;
+  // Exploitability requires a certain environment which is not present.
+  IMPACT_ANALYSIS_JUSTIFICATION_REQUIRES_ENVIRONMENT = 5;
+  // Exploitability requires a compiler flag to be set/unset.
+  IMPACT_ANALYSIS_JUSTIFICATION_PROTECTED_BY_COMPILER = 6;
+  // Exploits are prevented at runtime.
+  IMPACT_ANALYSIS_JUSTIFICATION_PROTECTED_AT_RUNTIME = 7;
+  // Attacks are blocked at physical, logical, or network perimeter.
+  IMPACT_ANALYSIS_JUSTIFICATION_PROTECTED_AT_PERIMETER = 8;
+  // Preventative measures have been implemented that reduce the likelihood and/or impact of the vulnerability.
+  IMPACT_ANALYSIS_JUSTIFICATION_PROTECTED_BY_MITIGATING_CONTROL = 9;
+}
+
+enum VulnerabilityResponse {
+  VULNERABILITY_RESPONSE_NULL = 0;
+  VULNERABILITY_RESPONSE_CAN_NOT_FIX = 1;
+  VULNERABILITY_RESPONSE_WILL_NOT_FIX = 2;
+  VULNERABILITY_RESPONSE_UPDATE = 3;
+  VULNERABILITY_RESPONSE_ROLLBACK = 4;
+  VULNERABILITY_RESPONSE_WORKAROUND_AVAILABLE = 5;
+}
+
+message VulnerabilityAffects {
+  // References a component or service by the objects bom-ref
+  string ref = 1;
+  // Zero or more individual versions or range of versions.
+  repeated VulnerabilityAffectedVersions versions = 2;
+}
+
+message VulnerabilityAffectedVersions {
+  oneof choice {
+    // A single version of a component or service.
+    string version = 1;
+    // 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
+    string range = 2;
+  }
+  // The vulnerability status for the version or range of versions.
+  optional VulnerabilityAffectedStatus status = 3;
+}
+
+enum VulnerabilityAffectedStatus {
+  // The vulnerability status of a given version or range of versions of a product. The statuses 'affected' and 'unaffected' indicate that the version is affected or unaffected by the vulnerability. The status 'unknown' indicates that it is unknown or unspecified whether the given version is affected. There can be many reasons for an 'unknown' status, including that an investigation has not been undertaken or that a vendor has not disclosed the status.
+  VULNERABILITY_AFFECTED_STATUS_UNKNOWN = 0;
+  VULNERABILITY_AFFECTED_STATUS_AFFECTED = 1;
+  VULNERABILITY_AFFECTED_STATUS_NOT_AFFECTED = 2;
+}