feat: bom.vulnerabilities data models and enums (#419)

* Added
  * New vulnerability-related enums were added in a new namespace `Enums.Vulnerability` ([#164] via [#419])  
    _Release stage is “beta”._ These namespace and enums have been released to third-party developers experimentally for the purpose of collecting feedback. These enums should not be used in production, because their contracts may change without notice.
    * `AffectStatus`
    * `AnalysisJustification`
    * `AnalysisResponse`
    * `AnalysisState`
    * `RatingMethod`
    * `Severity`
  * New vulnerability-related models were added in a new namespace `Models.Vulnerability` ([#164] via [#419])  
    _Release stage is “beta”._ These namespace and models have been released to third-party developers experimentally for the purpose of collecting feedback. These models should not be used in production, because their contracts may change without notice.  
    _Attention_: The models are not yet supported by shipped serializers nor shipped normalizers.
    * `Advisory`, `AdvisoryRepository`
    * `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository`
    * `Analysis`
    * `Credits`
    * `Rating`, `RatingRepository`
    * `Reference`, `ReferenceRepository`
    * `Source`
    * `Vulnerability`, `VulnerabilityRepository`
  * New class `Models.OrganizationalEntityRepository` to represent a collection of `Models.OrganizationalEntity` (via [#419])  
    Additionally, `Models.OrganizationalEntity.compare()` was implemented.
  * New types and related functionality Common Weaknesses Enumerations (CWE) were added (via [#419])  
    _Release stage is “beta”._ These types, functions and classes have been released to third-party developers experimentally for the purpose of collecting feedback. These types, functions and classes should not be used in production, because their contracts may change without notice.
    * type `Types.CWE`
    * runtime validation `Types.isCWE()`
    * class `Types.CweRepository`

---------

Signed-off-by: Peter Wagner <[email protected]>
Signed-off-by: Jan Kowalleck <[email protected]>
Co-authored-by: Peter Wagner <[email protected]>

Author: jkowalleck

HISTORY.md

@@ -4,12 +4,41 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* Added
+  * New vulnerability-related enums were added in a new namespace `Enums.Vulnerability` ([#164] via [#419])  
+    _Release stage is “beta”._ These namespace and enums have been released to third-party developers experimentally for the purpose of collecting feedback. These enums should not be used in production, because their contracts may change without notice.
+    * `AffectStatus`
+    * `AnalysisJustification`
+    * `AnalysisResponse`
+    * `AnalysisState`
+    * `RatingMethod`
+    * `Severity`
+  * New vulnerability-related models were added in a new namespace `Models.Vulnerability` ([#164] via [#419])  
+    _Release stage is “beta”._ These namespace and models have been released to third-party developers experimentally for the purpose of collecting feedback. These models should not be used in production, because their contracts may change without notice.  
+    _Attention_: The models are not yet supported by shipped serializers nor shipped normalizers.
+    * `Advisory`, `AdvisoryRepository`
+    * `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository`
+    * `Analysis`
+    * `Credits`
+    * `Rating`, `RatingRepository`
+    * `Reference`, `ReferenceRepository`
+    * `Source`
+    * `Vulnerability`, `VulnerabilityRepository`
+  * New class `Models.OrganizationalEntityRepository` to represent a collection of `Models.OrganizationalEntity` (via [#419])  
+    Additionally, `Models.OrganizationalEntity.compare()` was implemented.
+  * New types and related functionality Common Weaknesses Enumerations (CWE) were added (via [#419])  
+    _Release stage is “beta”._ These types, functions and classes have been released to third-party developers experimentally for the purpose of collecting feedback. These types, functions and classes should not be used in production, because their contracts may change without notice.
+    * type `Types.CWE`
+    * runtime validation `Types.isCWE()`
+    * class `Types.CweRepository`
 * Docs
   * Use [TSDoc](https://tsdoc.org/) syntax in TypeScript files, instead of [JSDoc](https://jsdoc.app/) (via [#318], [#453])
 * Misc
   * Added tests for internal helpers (via [#454])
 
+[#164]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/164
 [#318]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/318
+[#419]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/419
 [#453]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/453
 [#454]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/454
 

README.md

@@ -38,6 +38,14 @@ written in _TypeScript_ and compiled for the target.
   * `ComponentType`
   * `ExternalReferenceType`
   * `HashAlgorithm`
+  * Vulnerability related:  
+    _Release stage is “beta”._ These namespace and enums have been released to third-party developers experimentally for the purpose of collecting feedback. These enums should not be used in production, because their contracts may change without notice.
+    * `AffectStatus`
+    * `AnalysisJustification`
+    * `AnalysisResponse`
+    * `AnalysisState`
+    * `RatingMethod`
+    * `Severity`
 * Data models for the following use cases:
   * `Attachment`
   * `Bom`
@@ -48,10 +56,21 @@ written in _TypeScript_ and compiled for the target.
   * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository`
   * `Metadata`
   * `OrganizationalContact`, `OrganizationalContactRepository`
-  * `OrganizationalEntity`
+  * `OrganizationalEntity`, `OrganizationalEntityRepository`
   * `Property`, `PropertyRepository`
   * `SWID`
   * `Tool`, `ToolRepository`
+  * Vulnerability related:   
+    _Release stage is “beta”._ These namespace and models have been released to third-party developers experimentally for the purpose of collecting feedback. These models should not be used in production, because their contracts may change without notice.  
+    _Attention_: These models are not yet supported by serializers nor normalizers.
+    * `Advisory`, `AdvisoryRepository`
+    * `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository`
+    * `Analysis`
+    * `Credits`
+    * `Rating`, `RatingRepository`
+    * `Reference`, `ReferenceRepository`
+    * `Source`
+    * `Vulnerability`, `VulnerabilityRepository`
 * Factories for the following use cases:
   * Create data models from any license descriptor string
   * Create `PackageURL` from `Component` data models

src/_helpers/sortable.ts

@@ -73,19 +73,19 @@ abstract class SortableSet<TItem> extends Set<TItem> implements SortableIterable
   }
 }
 
-export abstract class SortableComparables<TItem extends Comparable<TItem>> extends SortableSet<TItem> {
+export class SortableComparables<TItem extends Comparable<TItem>> extends SortableSet<TItem> {
   protected [compareObjectsSymbol] (a: TItem, b: TItem): number {
     return a.compare(b)
   }
 }
 
-export abstract class SortableStringables<TItem extends Stringable = Stringable> extends SortableSet<TItem> {
+export class SortableStringables<TItem extends Stringable = Stringable> extends SortableSet<TItem> {
   protected [compareObjectsSymbol] (a: TItem, b: TItem): number {
     return a.toString().localeCompare(b.toString())
   }
 }
 
-export abstract class SortableNumbers<TItem extends number = number> extends SortableSet<TItem> {
+export class SortableNumbers<TItem extends number = number> extends SortableSet<TItem> {
   protected [compareObjectsSymbol] (a: TItem, b: TItem): number {
     return a - b
   }

src/enums/index.ts

@@ -22,3 +22,6 @@ export * from './componentScope'
 export * from './componentType'
 export * from './externalReferenceType'
 export * from './hashAlogorithm'
+
+/** @beta */
+export * as Vulnerability from './vulnerability'

src/enums/vulnerability/affectStatus.ts

@@ -0,0 +1,25 @@
+/*!
+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.
+*/
+
+/** @beta */
+export enum AffectStatus {
+  Affected = 'affected',
+  Unaffected = 'unaffected',
+  Unknown = 'unknown',
+}

src/enums/vulnerability/analysisJustification.ts

@@ -0,0 +1,31 @@
+/*!
+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.
+*/
+
+/** @beta */
+export enum AnalysisJustification {
+  CodeNotPresent = 'code_not_present',
+  CodeNotReachable = 'code_not_reachable',
+  RequiresConfiguration = 'requires_configuration',
+  RequiresDependency = 'requires_dependency',
+  RequiresEnvironment = 'requires_environment',
+  ProtectedByCompiler = 'protected_by_compiler',
+  ProtectedAtRuntime = 'protected_at_runtime',
+  ProtectedAtPerimeter = 'protected_at_perimeter',
+  ProtectedByMitigatingControl = 'protected_by_mitigating_control',
+}

src/enums/vulnerability/analysisResponse.ts

@@ -0,0 +1,33 @@
+/*!
+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 { SortableStringables } from '../../_helpers/sortable'
+
+/** @beta */
+export enum AnalysisResponse {
+  CanNotFix = 'can_not_fix',
+  WillNotFix = 'will_not_fix',
+  Update = 'update',
+  Rollback = 'rollback',
+  WorkaroundAvailable = 'workaround_available',
+}
+
+/** @beta */
+export class AnalysisResponseRepository extends SortableStringables<AnalysisResponse> {
+}

src/enums/vulnerability/analysisState.ts

@@ -0,0 +1,28 @@
+/*!
+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.
+*/
+
+/** @beta */
+export enum AnalysisState {
+  Resolved = 'resolved',
+  ResolvedWithPedigree = 'resolved_with_pedigree',
+  Exploitable = 'exploitable',
+  InTriage = 'in_triage',
+  FalsePositive = 'false_positive',
+  NotAffected = 'not_affected',
+}

src/enums/vulnerability/index.ts

@@ -0,0 +1,25 @@
+/*!
+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.
+*/
+
+export * from './affectStatus'
+export * from './analysisJustification'
+export * from './analysisResponse'
+export * from './analysisState'
+export * from './ratingMethod'
+export * from './severity'

src/enums/vulnerability/ratingMethod.ts

@@ -0,0 +1,35 @@
+/*!
+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.
+*/
+
+/**
+ * Specifies the severity or risk scoring methodology or standard used.
+ *
+ * @beta
+ */
+export enum RatingMethod {
+  /** [CVSS v2 standard](https://www.first.org/cvss/v2/) */
+  CVSSv2 = 'CVSSv2',
+  /** [CVSS v3.0 standard](https://www.first.org/cvss/v3-0/) */
+  CVSSv3 = 'CVSSv3',
+  /** [CVSS v3.1 standard](https://www.first.org/cvss/v3-1/) */
+  CVSSv31 = 'CVSSv31',
+  /** [OWASP Risk Rating](https://owasp.org/www-community/OWASP_Risk_Rating_Methodology) */
+  OWASP = 'OWASP',
+  Other = 'other',
+}

src/enums/vulnerability/severity.ts

@@ -0,0 +1,34 @@
+/*!
+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.
+*/
+
+/**
+ * Textual representation of the severity of the vulnerability adopted by the analysis method.
+ * If the analysis method uses values other than what is provided, the user is expected to translate appropriately.
+ *
+ * @beta
+ */
+export enum Severity {
+  Critical = 'critical',
+  High = 'high',
+  Medium = 'medium',
+  Low = 'low',
+  Info = 'info',
+  None = 'none',
+  Unknown = 'unknown',
+}

src/models/bom.ts

@@ -21,17 +21,20 @@ import type { PositiveInteger, UrnUuid } from '../types'
 import { isPositiveInteger, isUrnUuid } from '../types'
 import { ComponentRepository } from './component'
 import { Metadata } from './metadata'
+import { VulnerabilityRepository } from './vulnerability'
 
 export interface OptionalBomProperties {
   metadata?: Bom['metadata']
   components?: Bom['components']
   version?: Bom['version']
+  vulnerabilities?: Bom['vulnerabilities']
   serialNumber?: Bom['serialNumber']
 }
 
 export class Bom {
   metadata: Metadata
   components: ComponentRepository
+  vulnerabilities: VulnerabilityRepository
 
   /** @see {@link version} */
   #version: PositiveInteger = 1
@@ -53,6 +56,7 @@ export class Bom {
     this.metadata = op.metadata ?? new Metadata()
     this.components = op.components ?? new ComponentRepository()
     this.version = op.version ?? this.version
+    this.vulnerabilities = op.vulnerabilities ?? new VulnerabilityRepository()
     this.serialNumber = op.serialNumber
   }
 

src/models/index.ts

@@ -30,3 +30,6 @@ export * from './organizationalEntity'
 export * from './property'
 export * from './swid'
 export * from './tool'
+
+/** @beta */
+export * as Vulnerability from './vulnerability'

src/models/organizationalContact.ts

@@ -46,5 +46,4 @@ export class OrganizationalContact implements Comparable<OrganizationalContact>
   }
 }
 
-export class OrganizationalContactRepository extends SortableComparables<OrganizationalContact> {
-}
+export class OrganizationalContactRepository extends SortableComparables<OrganizationalContact> {}