feat: bom.vulnerabilities JSON normalization/serialization (CycloneDX#164)

xmasoracle · xmasoracle · commit 5fd9b4487eac · 2023-03-20T10:13:20.000+01:00
Signed-off-by: Xavier Maso &lt;xavier.maso@oracle.com&gt;
diff --git a/src/models/vulnerability/reference.ts b/src/models/vulnerability/reference.ts
@@ -17,6 +17,8 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
+import type { Comparable } from '../../_helpers/sortable'
+import { SortableComparables } from '../../_helpers/sortable'
 import type { Source } from './source'
 
 /**
@@ -27,7 +29,7 @@ import type { Source } from './source'
  *
  * @beta
  */
-export class Reference {
+export class Reference implements Comparable<Reference> {
   /**
    * @example values
    * - `CVE-2021-39182`
@@ -41,7 +43,14 @@ export class Reference {
     this.id = id
     this.source = source
   }
+
+  compare (other: Reference): number {
+    /* eslint-disable @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return (this.id ?? '').localeCompare(other.id ?? '') ||
+      this.source.compare(other.source)
+    /* eslint-enable  @typescript-eslint/strict-boolean-expressions */
+  }
 }
 
-/** @beta */
-export class ReferenceRepository extends Set<Reference> {}
+export class ReferenceRepository extends SortableComparables<Reference> {
+}
diff --git a/src/models/vulnerability/source.ts b/src/models/vulnerability/source.ts
@@ -17,19 +17,31 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
+import type { Comparable } from '../../_helpers/sortable'
+
 /** @beta */
 export interface OptionalSourceProperties {
   name?: Source['name']
   url?: Source['url']
 }
 
 /** @beta */
-export class Source {
+export class Source implements Comparable<Source> {
   name?: string
   url?: URL | string
 
   constructor (op: OptionalSourceProperties = {}) {
     this.name = op.name
     this.url = op.url
   }
+
+  compare (other: Source): number {
+    function normalizeUrl (u: URL | string): string {
+      return (typeof u === 'string') ? u : u.toString()
+    }
+    const urlCompare = normalizeUrl(this.url ?? '').localeCompare(normalizeUrl(other.url ?? ''))
+
+    /* eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return (this.name ?? '').localeCompare(other.name ?? '') || urlCompare
+  }
 }
diff --git a/src/models/vulnerability/vulnerability.ts b/src/models/vulnerability/vulnerability.ts
@@ -17,6 +17,8 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
+import type { Comparable } from '../../_helpers/sortable'
+import { SortableComparables } from '../../_helpers/sortable'
 import { CweRepository } from '../../types'
 import { BomRef } from '../bomRef'
 import { PropertyRepository } from '../property'
@@ -27,7 +29,7 @@ import type { Analysis } from './analysis'
 import type { Credits } from './credits'
 import { RatingRepository } from './rating'
 import { ReferenceRepository } from './reference'
-import type { Source } from './source'
+import { Source } from './source'
 
 /** @beta */
 export interface OptionalVulnerabilityProperties {
@@ -52,11 +54,11 @@ export interface OptionalVulnerabilityProperties {
 }
 
 /** @beta */
-export class Vulnerability {
+export class Vulnerability implements Comparable<Vulnerability> {
   /** @see bomRef */
   readonly #bomRef: BomRef
   id?: string
-  source?: Source
+  source: Source
   references: ReferenceRepository
   ratings: RatingRepository
   cwes: CweRepository
@@ -76,7 +78,7 @@ export class Vulnerability {
   constructor (op: OptionalVulnerabilityProperties = {}) {
     this.#bomRef = new BomRef(op.bomRef)
     this.id = op.id
-    this.source = op.source
+    this.source = op.source ?? new Source()
     this.references = op.references ?? new ReferenceRepository()
     this.ratings = op.ratings ?? new RatingRepository()
     this.cwes = op.cwes ?? new CweRepository()
@@ -97,7 +99,20 @@ export class Vulnerability {
   get bomRef (): BomRef {
     return this.#bomRef
   }
+
+  compare (other: Vulnerability): number {
+    const bomRefCompare = this.bomRef.compare(other.bomRef)
+    if (bomRefCompare !== 0) {
+      return bomRefCompare
+    }
+    /* eslint-disable @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return (this.id ?? '').localeCompare(other.id ?? '') ||
+      this.source.compare(other.source) ||
+      (this.description ?? '').localeCompare(other.description ?? '') ||
+      (this.detail ?? '').localeCompare(other.detail ?? '')
+    /* eslint-enable  @typescript-eslint/strict-boolean-expressions */
+  }
 }
 
 /** @beta */
-export class VulnerabilityRepository extends Set<Vulnerability> {}
+export class VulnerabilityRepository extends SortableComparables<Vulnerability> {}
diff --git a/src/serialize/json/normalize.ts b/src/serialize/json/normalize.ts
@@ -90,6 +90,18 @@ export class Factory {
   makeForDependencyGraph (): DependencyGraphNormalizer {
     return new DependencyGraphNormalizer(this)
   }
+
+  makeForVulnerability (): VulnerabilityNormalizer {
+    return new VulnerabilityNormalizer(this)
+  }
+
+  makeForVulnerabilitySource (): VulnerabilitySourceNormalizer {
+    return new VulnerabilitySourceNormalizer(this)
+  }
+
+  makeForVulnerabilityReference (): VulnerabilityReferenceNormalizer {
+    return new VulnerabilityReferenceNormalizer(this)
+  }
 }
 
 const schemaUrl: ReadonlyMap<SpecVersion, string> = new Map([
@@ -140,6 +152,9 @@ export class BomNormalizer extends BaseJsonNormalizer<Models.Bom> {
         : [],
       dependencies: this._factory.spec.supportsDependencyGraph
         ? this._factory.makeForDependencyGraph().normalize(data, options)
+        : undefined,
+      vulnerabilities: this._factory.spec.supportsVulnerabilities && data.vulnerabilities.size > 0
+        ? this._factory.makeForVulnerability().normalizeIterable(data.vulnerabilities, options)
         : undefined
     }
   }
@@ -511,6 +526,72 @@ export class DependencyGraphNormalizer extends BaseJsonNormalizer<Models.Bom> {
   }
 }
 
+export class VulnerabilityNormalizer extends BaseJsonNormalizer<Models.Vulnerability.Vulnerability> {
+  normalize (data: Models.Vulnerability.Vulnerability, options: NormalizerOptions): Normalized.Vulnerability | undefined {
+    const source = data.source !== undefined
+      ? this._factory.makeForVulnerabilitySource().normalize(data.source, options)
+      : undefined
+    const references = data.references.size > 0
+      ? this._factory.makeForVulnerabilityReference().normalizeIterable(data.references, options)
+      : undefined
+
+    return {
+      id: data.id,
+      source,
+      references,
+      description: data.description,
+      detail: data.detail,
+      recommendation: data.recommendation,
+      created: data.created,
+      published: data.published,
+      updated: data.updated
+    }
+  }
+
+  normalizeIterable (data: SortableIterable<Models.Vulnerability.Vulnerability>, options: NormalizerOptions): Normalized.Vulnerability[] {
+    return (
+      options.sortLists ?? false
+        ? data.sorted()
+        : Array.from(data)
+    ).map(
+      c => this.normalize(c, options)
+    ).filter(isNotUndefined)
+  }
+}
+
+export class VulnerabilitySourceNormalizer extends BaseJsonNormalizer<Models.Vulnerability.Source> {
+  normalize (data: Models.Vulnerability.Source, options: NormalizerOptions): Normalized.VulnerabilitySource {
+    const url = data.url !== undefined && typeof data.url !== 'string'
+      ? data.url.toString()
+      : data.url
+    return {
+      name: data.name,
+      url
+    }
+  }
+}
+
+export class VulnerabilityReferenceNormalizer extends BaseJsonNormalizer<Models.Vulnerability.Reference> {
+  normalize (data: Models.Vulnerability.Reference, options: NormalizerOptions): Normalized.VulnerabilityReference {
+    return {
+      id: data.id,
+      source: data.source !== undefined
+        ? this._factory.makeForVulnerabilitySource().normalize(data.source, options)
+        : undefined
+    }
+  }
+
+  normalizeIterable (data: SortableIterable<Models.Vulnerability.Reference>, options: NormalizerOptions): Normalized.VulnerabilityReference[] {
+    return (
+      options.sortLists ?? false
+        ? data.sorted()
+        : Array.from(data)
+    ).map(
+      c => this.normalize(c, options)
+    ).filter(isNotUndefined)
+  }
+}
+
 /* eslint-enable @typescript-eslint/prefer-nullish-coalescing, @typescript-eslint/strict-boolean-expressions */
 
 function normalizeStringableIter (data: Iterable<Stringable>, options: NormalizerOptions): string[] {
diff --git a/src/serialize/json/types.ts b/src/serialize/json/types.ts
@@ -74,6 +74,7 @@ export namespace Normalized {
     components?: Component[]
     externalReferences?: ExternalReference[]
     dependencies?: Dependency[]
+    vulnerabilities?: Vulnerability[]
   }
 
   export interface Metadata {
@@ -190,4 +191,26 @@ export namespace Normalized {
     dependsOn?: RefType[]
   }
 
+  export interface Vulnerability {
+    id?: string
+    source?: VulnerabilitySource
+    references?: VulnerabilityReference[]
+    description?: string
+    detail?: string
+    recommendation?: string
+    created?: Date
+    published?: Date
+    updated?: Date
+
+  }
+
+  export interface VulnerabilitySource {
+    name?: string
+    url?: string
+  }
+
+  export interface VulnerabilityReference {
+    id?: string
+    source?: VulnerabilitySource
+  }
 }
diff --git a/src/spec.ts b/src/spec.ts
@@ -47,6 +47,7 @@ export interface Protocol {
   supportsToolReferences: boolean
   requiresComponentVersion: boolean
   supportsProperties: (model: any) => boolean
+  supportsVulnerabilities: boolean
 }
 
 /**
@@ -64,6 +65,7 @@ class Spec implements Protocol {
   readonly #supportsToolReferences: boolean
   readonly #requiresComponentVersion: boolean
   readonly #supportsProperties: boolean
+  readonly #supportsVulnerabilities: boolean
 
   constructor (
     version: Version,
@@ -75,7 +77,8 @@ class Spec implements Protocol {
     supportsDependencyGraph: boolean,
     supportsToolReferences: boolean,
     requiresComponentVersion: boolean,
-    supportsProperties: boolean
+    supportsProperties: boolean,
+    supportsVulnerabilities: boolean
   ) {
     this.#version = version
     this.#formats = new Set(formats)
@@ -87,6 +90,7 @@ class Spec implements Protocol {
     this.#supportsToolReferences = supportsToolReferences
     this.#requiresComponentVersion = requiresComponentVersion
     this.#supportsProperties = supportsProperties
+    this.#supportsVulnerabilities = supportsVulnerabilities
   }
 
   get version (): Version {
@@ -130,6 +134,10 @@ class Spec implements Protocol {
     // currently a global allow/deny -- might work based on input, in the future
     return this.#supportsProperties
   }
+
+  get supportsVulnerabilities (): boolean {
+    return this.#supportsVulnerabilities
+  }
 }
 
 /** Specification v1.2 */
@@ -184,6 +192,7 @@ export const Spec1dot2: Readonly<Protocol> = Object.freeze(new Spec(
   true,
   false,
   true,
+  false,
   false
 ))
 
@@ -239,7 +248,8 @@ export const Spec1dot3: Readonly<Protocol> = Object.freeze(new Spec(
   true,
   false,
   true,
-  true
+  true,
+  false
 ))
 
 /** Specification v1.4 */
@@ -295,6 +305,7 @@ export const Spec1dot4: Readonly<Protocol> = Object.freeze(new Spec(
   true,
   true,
   false,
+  true,
   true
 ))
 
diff --git a/tests/_data/models.js b/tests/_data/models.js
@@ -197,5 +197,34 @@ module.exports.createComplexStructure = function () {
       ])
     }))
 
+  bom.vulnerabilities.add(new Models.Vulnerability.Vulnerability({
+    id: '1',
+    source: new Models.Vulnerability.Source({ name: 'manual' }),
+    references: new Models.Vulnerability.ReferenceRepository([
+      new Models.Vulnerability.Reference('CVE-2042-42420'),
+      new Models.Vulnerability.Reference('CVE-2042-42421')
+    ]),
+    description: 'description of 1',
+    detail: 'detail of 1',
+    recommendation: 'recommendation of 1',
+    created: '2023-03-03T00:00:00.040Z',
+    published: '2023-03-03T00:00:00.041Z',
+    updated: '2023-03-03T00:00:00.042Z'
+  }))
+
+  bom.vulnerabilities.add(new Models.Vulnerability.Vulnerability({
+    id: '2',
+    source: new Models.Vulnerability.Source({ name: 'manual' }),
+    references: new Models.Vulnerability.ReferenceRepository([
+      new Models.Vulnerability.Reference('CVE-2042-42422')
+    ]),
+    description: 'description of 2',
+    detail: 'detail of 2',
+    recommendation: 'recommendation of 2',
+    created: '2023-03-03T00:00:00.040Z',
+    published: '2023-03-03T00:00:00.041Z',
+    updated: '2023-03-03T00:00:00.042Z'
+  }))
+
   return bom
 }
diff --git a/tests/_data/normalizeResults/json_sortedLists_spec1.4.json b/tests/_data/normalizeResults/json_sortedLists_spec1.4.json
diff --git a/tests/_data/serializeResults/json_complex_spec1.4.json.bin b/tests/_data/serializeResults/json_complex_spec1.4.json.bin
diff --git a/tests/unit/Models.Vulnerability.Vulnerability.spec.js b/tests/unit/Models.Vulnerability.Vulnerability.spec.js
