Add detailed VEX example Annex

This commit adds an annex explaining how to implement VEX in SPDX.

Signed-off-by: Rose Judge <[email protected]>

docs/annexes/how-to-implement-VEX-in-SPDX.md

@@ -0,0 +1,64 @@
+# Annex J: How to Implement VEX in SPDX
+
+Vulnerability Exploitability eXchange (VEX) was designed to allow a software supplier or other parties to assert the status of specific vulnerabilities in a particular product. The SPDX security profile supports the communication of VEX metadata using subclassed [VEX Vulnerability Assessment Relationships](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexVulnAssessmentRelationship/). You can use the following relationships in SPDX to convey the [minimum elements](https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf) of a vulnerability assessment (severity, impact, exploitability).
+
+* [VexAffectedVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexAffectedVulnAssessmentRelationship/)
+* [VexFixedVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexFixedVulnAssessmentRelationship/)
+* [VexNotAffectedVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexNotAffectedVulnAssessmentRelationship/)
+* [VexUnderInvestigationVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexUnderInvestigationVulnAssessmentRelationship/)
+
+
+For all VEX Relationships, the `from` element  must be a [Vulnerability](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/Vulnerability/) and the `to` end of the relationship must point to one or more elements representing the VEX products. To specify a different element where the vulnerability was detected, the VEX relationship can optionally specify subcomponents using the [assessedElement](https://spdx.github.io/spdx-spec/v3.0/model/Security/Properties/assessedElement/) property.
+
+VEX inherits information from the document level down to its statements. When a statement is missing information it can be completed by reading the equivalent field from the containing document. For example, if a VEX relationship is missing data in its createdBy property, tools must consider the entity listed in the CreationInfo section of the document as the VEX author. In the same way, when a VEX relationship does not have a created property, the document's date must be considered as authoritative.
+
+
+## J.1 Assembling a VEX Statement
+
+A VEX statement is assembled by a triad of (at least):
+
+a software package + a vex assessment relationship + a vulnerability
+
+The following example shows how you would communicate that a vulnerability is under investigation to determine whether or not it affects a software product.
+
+```json
+  "@type": "VexUnderInvestigationVulnAssessmentRelationship",
+  "@id": "urn:spdx.dev:vex-underInvestigation-1",
+  "relationshipType": "underInvestigationFor",
+  "from": "urn:spdx.dev:vuln-cve-2020-28498",
+  "to": ["urn:product-acme-application-1.3"],
+  "assessedElement": "urn:npm-elliptic-6.5.2",
+  "suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
+  "publishedTime": "2021-03-09T11:04:53Z"
+```
+
+
+## J.2 Changing the Status of a Vulnerability
+
+Because [Elements](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) in SPDX are immutable, a new VEX Assessment Relationship of type `amends` must be issued each time the VEX status of a vulnerability changes (i.e. `underInvestigationFor` --> `affects`) in addition to creating a new type of VEX status relationship. The following example shows how you would communicate that a vulnerbaility was under investigation before determining that the vulnerability indeed affects a product.
+
+```json
+  "@type": "VexUnderInvestigationVulnAssessmentRelationship",
+  "@id": "urn:spdx.dev:vex-underInvestigation-1",
+  "relationshipType": "underInvestigationFor",
+  "from": "urn:spdx.dev:vuln-cve-2020-28498",
+  "to": ["urn:product-acme-application-1.3"],
+  "assessedElement": "urn:npm-elliptic-6.5.2",
+  "suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
+  "publishedTime": "2021-03-09T11:04:53Z"
+
+  "@type": "VexAssessmentRelationship",
+  "@id": "urn:spdx.dev:vex-update",
+  "relationshipType": "amends",
+  "from": "urn:spdx.dev:vex-underInvestigation-1",
+  "to": ["urn:spdx.dev:vex-affected-1"],
+
+  "@type": "VexAffectedVulnAssessmentRelationship",
+  "@id": "urn:spdx.dev:vex-affected-1",
+  "relationshipType": "affects",
+  "from": "urn:spdx.dev:vuln-cve-2020-28498",
+  "to": ["urn:product-acme-application-1.3"],
+  "assessedElement": "urn:npm-elliptic-6.5.2",
+  "suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
+  "publishedTime": "2021-03-15T08:10:43Z"
+``` 

mkdocs.yml

@@ -338,6 +338,7 @@ nav:
   - 'Using SPDX to comply with norms, standards and regulation': annexes/using-SPDX-to-comply-with-industry-guidance.md
   - 'Including Security Information in SPDX': annexes/including-security-information-in-SPDX.md
   - 'SPDX Lite': annexes/SPDX-Lite.md
+  - 'Implementing VEX in SPDX': annexes/how-to-implement-VEX-in-SPDX.md
 - licenses:
   - 'Creative Commons Attribution License 3.0 Unported': licenses/CC-BY-3.0.md
   - 'Community Specification License 1.0': licenses/Community-Spec-1.0.md