@cyclonedx/cyclonedx-library 2.0.0 → 3.0.0

package/src/enums/componentType.ts

@@ -22,8 +22,12 @@ export enum ComponentType {
   Framework = 'framework',
   Library = 'library',
   Container = 'container',
+  Platform = 'platform',
   OperatingSystem = 'operating-system',
   Device = 'device',
+  DeviceDriver = 'device-driver',
   Firmware = 'firmware',
   File = 'file',
+  MachineLearningModel = 'machine-learning-model',
+  Data = 'data',
 }

package/src/enums/externalReferenceType.ts

@@ -29,9 +29,32 @@ export enum ExternalReferenceType {
   Documentation = 'documentation',
   Support = 'support',
   Distribution = 'distribution',
+  DistributionIntake = 'distribution-intake',
   License = 'license',
   BuildMeta = 'build-meta',
   BuildSystem = 'build-system',
   ReleaseNotes = 'release-notes',
+  SecurityContact = 'security-contact',
+  ModelCard = 'model-card',
+  Log = 'log',
+  Configuration = 'configuration',
+  Evidence = 'evidence',
+  Formulation = 'formulation',
+  Attestation = 'attestation',
+  ThreatModel = 'threat-model',
+  AdversaryModel = 'adversary-model',
+  RiskAssessment = 'risk-assessment',
+  VulnerabilityAssertion = 'vulnerability-assertion',
+  ExploitabilityStatement = 'exploitability-statement',
+  PentestReport = 'pentest-report',
+  StaticAnalysisReport = 'static-analysis-report',
+  DynamicAnalysisReport = 'dynamic-analysis-report',
+  RuntimeAnalysisReport = 'runtime-analysis-report',
+  ComponentAnalysisReport = 'component-analysis-report',
+  MaturityReport = 'maturity-report',
+  CertificationReport = 'certification-report',
+  CodifiedInfrastructure = 'codified-infrastructure',
+  QualityMetrics = 'quality-metrics',
+  POAM = 'poam',
   Other = 'other',
 }

package/src/enums/vulnerability/ratingMethod.ts

@@ -21,13 +21,18 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
  * Specifies the severity or risk scoring methodology or standard used.
  */
 export enum RatingMethod {
-  /** [CVSS v2 standard](https://www.first.org/cvss/v2/) */
+  /** CVSSv2 - [Common Vulnerability Scoring System v2](https://www.first.org/cvss/v2/) */
   CVSSv2 = 'CVSSv2',
-  /** [CVSS v3.0 standard](https://www.first.org/cvss/v3-0/) */
+  /** CVSSv3 - [Common Vulnerability Scoring System v3](https://www.first.org/cvss/v3-0/) */
   CVSSv3 = 'CVSSv3',
-  /** [CVSS v3.1 standard](https://www.first.org/cvss/v3-1/) */
+  /** CVSSv31 - [Common Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3-1/) */
   CVSSv31 = 'CVSSv31',
-  /** [OWASP Risk Rating](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology) */
+  /** CVSSv4 - [Common Vulnerability Scoring System v4](https://www.first.org/cvss/v4-0/) */
+  CVSSv4 = 'CVSSv4',
+  /** OWASP - [OWASP Risk Rating Methodology](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology) */
   OWASP = 'OWASP',
+  /** SSVC - [Stakeholder Specific Vulnerability Categorization](https://github.com/CERTCC/SSVC) (all versions) */
+  SSVC = 'SSVC',
+  /** any other */
   Other = 'other',
 }

package/src/models/bomLink.ts

@@ -0,0 +1,111 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+import type { Comparable } from '../_helpers/sortable'
+import type { Stringable } from '../_helpers/stringable'
+
+abstract class BomLinkBase implements Stringable, Comparable<Stringable> {
+  /* @ts-expect-error TS2564 */
+  #value: string
+
+  /** @internal */
+  protected abstract _isValid (value: any): boolean
+
+  /**
+   * @throws {@link RangeError} if value is invalid
+   */
+  constructor (value: string) {
+    this.value = value
+  }
+
+  /**
+   * @throws {@link RangeError} if value is invalid
+   */
+  set value (value: string) {
+    if (!this._isValid(value)) {
+      throw new RangeError('invalid value')
+    }
+    this.#value = value
+  }
+
+  get value (): string {
+    return this.#value
+  }
+
+  compare (other: Stringable): number {
+    return this.toString().localeCompare(other.toString())
+  }
+
+  toString (): string {
+    return this.value
+  }
+}
+
+/**
+ * Descriptor for another BOM document.
+ *
+ * See [the docs](https://cyclonedx.org/capabilities/bomlink/)
+ */
+export class BomLinkDocument extends BomLinkBase {
+  /* regular expressions were taken from the CycloneDX schema definitions. */
+  static #pattern = /^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[1-9][0-9]*$/
+
+  /**
+   * Whether the `value` is a valid descriptor for another BOM document.
+   */
+  static isValid (value: any): boolean {
+    return typeof value === 'string' &&
+      this.#pattern.test(value)
+  }
+
+  /** @internal */
+  protected _isValid (value: any): boolean {
+    return BomLinkDocument.isValid(value)
+  }
+}
+
+/**
+ * Descriptor for an element in a BOM document.
+ *
+ * See [the docs](https://cyclonedx.org/capabilities/bomlink/)
+ */
+export class BomLinkElement extends BomLinkBase {
+  /* regular expressions were taken from the CycloneDX schema definitions. */
+  static #pattern = /^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[1-9][0-9]*#.+$/
+
+  /**
+   * Whether the `value` is a valid descriptor for an element in a BOM document.
+   */
+  static isValid (value: any): boolean {
+    return typeof value === 'string' &&
+      this.#pattern.test(value)
+  }
+
+  /** @internal */
+  protected _isValid (value: any): boolean {
+    return BomLinkElement.isValid(value)
+  }
+}
+
+/**
+ * Either {@link BomLinkDocument} or {@link BomLinkElement}.
+ *
+ * See [the docs](https://cyclonedx.org/capabilities/bomlink/)
+ */
+export type BomLink = BomLinkDocument | BomLinkElement

package/src/models/bomRef.ts

@@ -17,18 +17,21 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
+import type { Comparable } from '../_helpers/sortable'
+import type { Stringable } from '../_helpers/stringable'
+
 /**
  * Proxy for the BomRef.
  * This way a `BomRef` gets unique by the in-memory-address of the object.
  */
-export class BomRef {
+export class BomRef implements Stringable, Comparable<Stringable> {
   value?: string
 
   constructor (value?: BomRef['value']) {
     this.value = value
   }
 
-  compare (other: BomRef): number {
+  compare (other: Stringable): number {
     return this.toString().localeCompare(other.toString())
   }
 

package/src/models/externalReference.ts

@@ -20,13 +20,14 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 import type { Comparable } from '../_helpers/sortable'
 import { SortableComparables } from '../_helpers/sortable'
 import type { ExternalReferenceType } from '../enums'
+import type { BomLink } from './bomLink'
 
 export interface OptionalExternalReferenceProperties {
   comment?: ExternalReference['comment']
 }
 
 export class ExternalReference implements Comparable<ExternalReference> {
-  url: URL | string
+  url: URL | BomLink | string
   type: ExternalReferenceType
   comment?: string
 

package/src/models/index.ts

@@ -19,6 +19,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 
 export * from './attachment'
 export * from './bom'
+export * from './bomLink'
 export * from './bomRef'
 export * from './component'
 export * from './externalReference'

package/src/models/vulnerability/affect.ts

@@ -20,6 +20,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 import type { Comparable } from '../../_helpers/sortable'
 import { SortableComparables } from '../../_helpers/sortable'
 import type { AffectStatus } from '../../enums/vulnerability'
+import type { BomLinkElement } from '../bomLink'
 import type { BomRef } from '../bomRef'
 
 export interface OptionalAffectProperties {
@@ -27,10 +28,10 @@ export interface OptionalAffectProperties {
 }
 
 export class Affect implements Comparable<Affect> {
-  ref: BomRef
+  ref: BomRef | BomLinkElement
   versions: AffectedVersionRepository
 
-  constructor (ref: BomRef, op: OptionalAffectProperties = {}) {
+  constructor (ref: Affect['ref'], op: OptionalAffectProperties = {}) {
     this.ref = ref
     this.versions = op.versions ?? new AffectedVersionRepository()
   }

package/src/resources.node.ts

@@ -31,30 +31,33 @@ export const SCHEMA_ROOT = path.resolve(ROOT, 'schema')
 export const FILES = Object.freeze({
   CDX: Object.freeze({
     XML_SCHEMA: Object.freeze({
-      [Version.v1dot0]: path.resolve(SCHEMA_ROOT, 'bom-1.0.SNAPSHOT.xsd'),
-      [Version.v1dot1]: path.resolve(SCHEMA_ROOT, 'bom-1.1.SNAPSHOT.xsd'),
-      [Version.v1dot2]: path.resolve(SCHEMA_ROOT, 'bom-1.2.SNAPSHOT.xsd'),
+      [Version.v1dot5]: path.resolve(SCHEMA_ROOT, 'bom-1.5.SNAPSHOT.xsd'),
+      [Version.v1dot4]: path.resolve(SCHEMA_ROOT, 'bom-1.4.SNAPSHOT.xsd'),
       [Version.v1dot3]: path.resolve(SCHEMA_ROOT, 'bom-1.3.SNAPSHOT.xsd'),
-      [Version.v1dot4]: path.resolve(SCHEMA_ROOT, 'bom-1.4.SNAPSHOT.xsd')
+      [Version.v1dot2]: path.resolve(SCHEMA_ROOT, 'bom-1.2.SNAPSHOT.xsd'),
+      [Version.v1dot1]: path.resolve(SCHEMA_ROOT, 'bom-1.1.SNAPSHOT.xsd'),
+      [Version.v1dot0]: path.resolve(SCHEMA_ROOT, 'bom-1.0.SNAPSHOT.xsd')
+
     }),
     JSON_SCHEMA: Object.freeze({
-      // v1.0 is not defined in JSON
-      [Version.v1dot0]: undefined,
-      // v1.1 is not defined in JSON
-      [Version.v1dot1]: undefined,
-      [Version.v1dot2]: path.resolve(SCHEMA_ROOT, 'bom-1.2.SNAPSHOT.schema.json'),
+      [Version.v1dot5]: path.resolve(SCHEMA_ROOT, 'bom-1.5.SNAPSHOT.schema.json'),
+      [Version.v1dot4]: path.resolve(SCHEMA_ROOT, 'bom-1.4.SNAPSHOT.schema.json'),
       [Version.v1dot3]: path.resolve(SCHEMA_ROOT, 'bom-1.3.SNAPSHOT.schema.json'),
-      [Version.v1dot4]: path.resolve(SCHEMA_ROOT, 'bom-1.4.SNAPSHOT.schema.json')
+      [Version.v1dot2]: path.resolve(SCHEMA_ROOT, 'bom-1.2.SNAPSHOT.schema.json'),
+      // <= v1.1 is not defined in JSON
+      [Version.v1dot1]: undefined,
+      [Version.v1dot0]: undefined
     }),
     JSON_STRICT_SCHEMA: Object.freeze({
-      // v1.0 is not defined in JSON
-      [Version.v1dot0]: undefined,
-      // v1.1 is not defined in JSON
-      [Version.v1dot1]: undefined,
-      [Version.v1dot2]: path.resolve(SCHEMA_ROOT, 'bom-1.2-strict.SNAPSHOT.schema.json'),
+      // >= v1.4 is already strict - no special file here
+      [Version.v1dot5]: path.resolve(SCHEMA_ROOT, 'bom-1.5.SNAPSHOT.schema.json'),
+      [Version.v1dot4]: path.resolve(SCHEMA_ROOT, 'bom-1.4.SNAPSHOT.schema.json'),
+      // <= 1.3 need special files
       [Version.v1dot3]: path.resolve(SCHEMA_ROOT, 'bom-1.3-strict.SNAPSHOT.schema.json'),
-      // v1.4 is already strict - no special file here
-      [Version.v1dot4]: path.resolve(SCHEMA_ROOT, 'bom-1.4.SNAPSHOT.schema.json')
+      [Version.v1dot2]: path.resolve(SCHEMA_ROOT, 'bom-1.2-strict.SNAPSHOT.schema.json'),
+      // <= v1.1 is not defined in JSON
+      [Version.v1dot1]: undefined,
+      [Version.v1dot0]: undefined
     })
   }),
   SPDX: Object.freeze({

package/src/serialize/json/normalize.ts

@@ -134,9 +134,10 @@ export class Factory {
 }
 
 const schemaUrl: ReadonlyMap<SpecVersion, string> = new Map([
-  [SpecVersion.v1dot2, 'http://cyclonedx.org/schema/bom-1.2b.schema.json'],
+  [SpecVersion.v1dot5, 'http://cyclonedx.org/schema/bom-1.5.schema.json'],
+  [SpecVersion.v1dot4, 'http://cyclonedx.org/schema/bom-1.4.schema.json'],
   [SpecVersion.v1dot3, 'http://cyclonedx.org/schema/bom-1.3a.schema.json'],
-  [SpecVersion.v1dot4, 'http://cyclonedx.org/schema/bom-1.4.schema.json']
+  [SpecVersion.v1dot2, 'http://cyclonedx.org/schema/bom-1.2b.schema.json']
 ])
 
 interface JsonNormalizer<TModel, TNormalized> {
@@ -680,7 +681,9 @@ export class VulnerabilityRatingNormalizer extends BaseJsonNormalizer<Models.Vul
         : this._factory.makeForVulnerabilitySource().normalize(data.source, options),
       score: data.score,
       severity: data.severity,
-      method: data.method,
+      method: this._factory.spec.supportsVulnerabilityRatingMethod(data.method)
+        ? data.method
+        : undefined,
       vector: data.vector,
       justification: data.justification
     }

package/src/serialize/json/types.ts

@@ -66,6 +66,11 @@ export namespace JsonSchema {
 export namespace Normalized {
 
   export type RefType = string
+  export type RefLinkType = RefType
+
+  export type BomLinkDocumentType = string
+  export type BomLinkElementType = string
+  export type BomLink = BomLinkDocumentType | BomLinkElementType
 
   export interface Bom {
     $schema?: string
@@ -183,7 +188,7 @@ export namespace Normalized {
   }
 
   export interface ExternalReference {
-    url: string
+    url: JsonSchema.IriReference | BomLink
     type: Enums.ExternalReferenceType
     comment?: string
   }
@@ -200,8 +205,8 @@ export namespace Normalized {
   }
 
   export interface Dependency {
-    ref: RefType
-    dependsOn?: RefType[]
+    ref: RefLinkType
+    dependsOn?: RefLinkType[]
   }
 
   export interface Vulnerability {
@@ -248,7 +253,7 @@ export namespace Normalized {
 
     export interface Advisory {
       title?: string
-      url: string
+      url: JsonSchema.IriReference
     }
 
     export interface Credits {
@@ -264,7 +269,7 @@ export namespace Normalized {
     }
 
     export interface Affect {
-      ref: RefType
+      ref: RefLinkType | BomLinkElementType
       versions?: AffectedVersion[]
     }
 

package/src/serialize/xml/normalize.ts

@@ -134,9 +134,12 @@ export class Factory {
 }
 
 const xmlNamespace: ReadonlyMap<SpecVersion, string> = new Map([
-  [SpecVersion.v1dot2, 'http://cyclonedx.org/schema/bom/1.2'],
+  [SpecVersion.v1dot5, 'http://cyclonedx.org/schema/bom/1.5'],
+  [SpecVersion.v1dot4, 'http://cyclonedx.org/schema/bom/1.4'],
   [SpecVersion.v1dot3, 'http://cyclonedx.org/schema/bom/1.3'],
-  [SpecVersion.v1dot4, 'http://cyclonedx.org/schema/bom/1.4']
+  [SpecVersion.v1dot2, 'http://cyclonedx.org/schema/bom/1.2'],
+  [SpecVersion.v1dot1, 'http://cyclonedx.org/schema/bom/1.1'],
+  [SpecVersion.v1dot0, 'http://cyclonedx.org/schema/bom/1.0']
 ])
 
 interface XmlNormalizer<TModel, TNormalized> {
@@ -724,7 +727,7 @@ export class DependencyGraphNormalizer extends BaseXmlNormalizer<Models.Bom> {
   }
 }
 
-class VulnerabilityNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Vulnerability> {
+export class VulnerabilityNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Vulnerability> {
   normalize (data: Models.Vulnerability.Vulnerability, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     const references: SimpleXml.Element | undefined = data.references.size > 0
       ? {
@@ -820,7 +823,7 @@ class VulnerabilityNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Vul
   }
 }
 
-class VulnerabilitySourceNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Source> {
+export class VulnerabilitySourceNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Source> {
   normalize (data: Models.Vulnerability.Source, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     const url = data.url?.toString()
     return {
@@ -836,7 +839,7 @@ class VulnerabilitySourceNormalizer extends BaseXmlNormalizer<Models.Vulnerabili
   }
 }
 
-class VulnerabilityReferenceNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Reference> {
+export class VulnerabilityReferenceNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Reference> {
   normalize (data: Models.Vulnerability.Reference, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     return {
       type: 'element',
@@ -857,7 +860,7 @@ class VulnerabilityReferenceNormalizer extends BaseXmlNormalizer<Models.Vulnerab
   }
 }
 
-class VulnerabilityRatingNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Rating> {
+export class VulnerabilityRatingNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Rating> {
   normalize (data: Models.Vulnerability.Rating, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     return {
       type: 'element',
@@ -868,7 +871,9 @@ class VulnerabilityRatingNormalizer extends BaseXmlNormalizer<Models.Vulnerabili
           : this._factory.makeForVulnerabilitySource().normalize(data.source, options, 'source'),
         makeOptionalTextElement(data.score, 'score'),
         makeOptionalTextElement(data.severity, 'severity'),
-        makeOptionalTextElement(data.method, 'method'),
+        this._factory.spec.supportsVulnerabilityRatingMethod(data.method)
+          ? makeOptionalTextElement(data.method, 'method')
+          : undefined,
         makeOptionalTextElement(data.vector, 'vector'),
         makeOptionalTextElement(data.justification, 'justification')
       ].filter(isNotUndefined)
@@ -884,7 +889,7 @@ class VulnerabilityRatingNormalizer extends BaseXmlNormalizer<Models.Vulnerabili
   }
 }
 
-class VulnerabilityAdvisoryNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Advisory> {
+export class VulnerabilityAdvisoryNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Advisory> {
   normalize (data: Models.Vulnerability.Advisory, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
     const url = data.url.toString()
     if (!XmlSchema.isAnyURI(url)) {
@@ -912,7 +917,7 @@ class VulnerabilityAdvisoryNormalizer extends BaseXmlNormalizer<Models.Vulnerabi
   }
 }
 
-class VulnerabilityCreditsNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Credits> {
+export class VulnerabilityCreditsNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Credits> {
   normalize (data: Models.Vulnerability.Credits, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     const organizations: SimpleXml.Element | undefined = data.organizations.size > 0
       ? {
@@ -939,7 +944,7 @@ class VulnerabilityCreditsNormalizer extends BaseXmlNormalizer<Models.Vulnerabil
   }
 }
 
-class VulnerabilityAnalysisNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Analysis> {
+export class VulnerabilityAnalysisNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Analysis> {
   normalize (data: Models.Vulnerability.Analysis, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     const responses: SimpleXml.Element | undefined = data.response.size > 0
       ? {
@@ -965,7 +970,7 @@ class VulnerabilityAnalysisNormalizer extends BaseXmlNormalizer<Models.Vulnerabi
   }
 }
 
-class VulnerabilityAffectNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Affect> {
+export class VulnerabilityAffectNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Affect> {
   normalize (data: Models.Vulnerability.Affect, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     const versions: SimpleXml.Element | undefined = data.versions.size > 0
       ? {
@@ -993,7 +998,7 @@ class VulnerabilityAffectNormalizer extends BaseXmlNormalizer<Models.Vulnerabili
   }
 }
 
-class VulnerabilityAffectedVersionNormalizer extends BaseXmlNormalizer<Models.Vulnerability.AffectedVersion> {
+export class VulnerabilityAffectedVersionNormalizer extends BaseXmlNormalizer<Models.Vulnerability.AffectedVersion> {
   normalize (data: Models.Vulnerability.AffectedVersion, options: NormalizerOptions, elementName: string): SimpleXml.Element {
     switch (true) {
       case data instanceof Models.Vulnerability.AffectedSingleVersion: