Skip to content

Commit e59d59a

Browse files
bactbact
committed
how-to-vex: Fix namespace in JSON examples
- A follow-up of spdx#6 - Rename `how-to-vex.mc` -> `how-to-vex.md`, so it can be rendered - Fix property names in the JSON example. Namespaces for non-core profile properties are required. - Fix Markdown warnings: add one blank lines around headings and lists - Remove "J" numbering from the heading, as it is no longer an appendix of the spec - Fix few typos: "metdata" -> "metadata", "logj4" -> "log4j", etc. Original PR: spdx#21 Signed-off-by: Arthit Suriyawongkul <[email protected]>
1 parent 10e4b14 commit e59d59a

File tree

2 files changed

+72
-45
lines changed

2 files changed

+72
-45
lines changed

‎docs/how-to-vex.mc‎ renamed to ‎docs/how-to-vex.md‎

Lines changed: 71 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,178 @@
1-
# How to Implement VEX in SPDX
1+
---
2+
SPDX-License-Identifier: Community-Spec-1.0
3+
tags:
4+
- security
5+
- guide
6+
- v3.0
7+
---
8+
9+
# How to implement VEX in SPDX
210

311
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/). SPDX uses relationships 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).
412

513
VEX centers on the notion of a statement. A statement can be defined as an assertion intersecting product, a vulnerability, and an impact status:
14+
615
```text
716
statement = product(s) + vulnerability + status
817
│ │ │
918
└ The software product └ Typically a CVE related └ One of the impact
1019
we are talking about to one of the product's statuses as identified
1120
components by the VEX working group.
1221
```
13-
The `product` is a piece of software that can be correlated to an entry in an SBOM. `vulnerability` is the ID of a security vulnerability as understood by scanners, which can be looked up in a vulnerability tracking system. `status` is one of the impact status labels defined by VEX (See https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf).
1422

15-
## J.1 Linking vs Embedding VEX information in SPDX
23+
The `product` is a piece of software that can be correlated to an entry in an SBOM. `vulnerability` is the ID of a security vulnerability as understood by scanners, which can be looked up in a vulnerability tracking system. `status` is one of the impact status labels defined by VEX (See <https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf>).
24+
25+
## 1. Linking vs embedding VEX information in SPDX
1626

1727
SPDX 3.0 provides support to include VEX information in two ways:
28+
1829
1) Linking to external VEX information
19-
2) Embed VEX metdata directly in an SPDX security document
30+
2) Embed VEX metadata directly in an SPDX security document
2031

21-
### J.1.1 Linking to VEX
32+
### 1.1 Linking to VEX
2233

2334
To link to an external VEX document, include an external reference of type `vulnerabilityExploitabilityAssessment` on the Vulnerability Element that encapsulates the CVE described in the VEX document.
35+
2436
```json
2537
{
26-
"@type": "Vulnerability",
27-
"@id": "urn:spdx.dev:vuln-2",
38+
"type": "security_Vulnerability",
39+
"spdxId": "urn:spdx.dev:vuln-2",
2840
"name": "cve-1234-5678",
2941
"publishedTime": "2024-01-01T16:28:45Z",
3042
"externalRef": [
3143
{
32-
"@type": "ExternalRef",
44+
"type": "ExternalRef",
3345
"externalRefType": "vulnerabilityExploitabilityAssessment",
34-
"locator": "https://github.com/openvex/vexctl/blob/main/examples/openvex/document1.vex.json"
46+
"locator": [
47+
"https://github.com/openvex/vexctl/blob/main/examples/openvex/document1.vex.json"
48+
]
3549
}
3650
]
3751
}
3852
```
3953

40-
### J.1.2 Embedding VEX information in SPDX
54+
### 1.2 Embedding VEX information in SPDX
4155

4256
In order to embed VEX metadata in an SPDX document, you can utilize the SPDX 3.0 Security Profile. See the following sections for examples.
4357

44-
45-
## J.2 Assembling a VEX Statement
58+
## 2. Assembling a VEX statement
4659

4760
A VEX statement is assembled by a triad of (at least):
4861

4962
```a software product + a vex status + a vulnerability```
5063

5164
In SPDX the VEX product can be any software package. There are four VEX status labels, each of which is represented in SPDX with a subclassed VEX Relationship:
52-
| VEX Status | SPDX VEX Relationship |
65+
66+
| VEX status | SPDX VEX Relationship |
5367
| --- | --- |
5468
| not_affected | [VexNotAffectedVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexNotAffectedVulnAssessmentRelationship/) |
5569
| affected | [VexAffectedVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexAffectedVulnAssessmentRelationship/) |
5670
| fixed | [VexFixedVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexFixedVulnAssessmentRelationship/) |
57-
| under_investigation | [VexUnderInvestigationVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexUnderInvestigationVulnAssessmentRelationship/) |
71+
| under_investigation | [VexUnderInvestigationVulnAssessmentRelationship](https://spdx.github.io/spdx-spec/v3.0/model/Security/Classes/VexUnderInvestigationVulnAssessmentRelationship/) |
5872

59-
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 that represent the VEX product(s).
73+
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 that represent the VEX product(s).
6074

6175
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.
6276

6377
The following example shows how you would communicate that a vulnerability is under investigation to determine whether or not it affects a software product.
6478

6579
```json
66-
"@type": "VexUnderInvestigationVulnAssessmentRelationship",
67-
"@id": "urn:spdx.dev:vex-underInvestigation-1",
80+
{
81+
"type": "VexUnderInvestigationVulnAssessmentRelationship",
82+
"spdxId": "urn:spdx.dev:vex-underInvestigation-1",
6883
"relationshipType": "underInvestigationFor",
6984
"from": "urn:spdx.dev:vuln-cve-2020-28498",
7085
"to": ["urn:product-acme-application-1.3"],
71-
"assessedElement": "urn:npm-elliptic-6.5.2",
86+
"security_assessedElement": "urn:npm-elliptic-6.5.2",
7287
"suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
7388
"publishedTime": "2021-03-09T11:04:53Z"
89+
}
7490
```
7591

7692
To communicate that a product is affected by a vulnerability, you would instead use the `VexAffectedVulnAssessmentRelationship`:
7793

7894
```json
79-
"@type": "VexAffectedVulnAssessmentRelationship",
80-
"@id": "urn:spdx.dev:vex-affected-1",
95+
{
96+
"type": "VexAffectedVulnAssessmentRelationship",
97+
"spdxId": "urn:spdx.dev:vex-affected-1",
8198
"relationshipType": "affects",
8299
"from": "urn:spdx.dev:vuln-cve-2020-28498",
83100
"to": ["urn:product-acme-application-1.3"],
84-
"assessedElement": "urn:npm-elliptic-6.5.2",
101+
"security_assessedElement": "urn:npm-elliptic-6.5.2",
85102
"suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
86103
"publishedTime": "2021-03-09T11:04:53Z"
104+
}
87105
```
88106

89-
VEX relationships in SPDX will always point `to` element(s) representing the VEX *products*. A product is a logical unit representing a piece of software, typically composed of one or more software packages/libraries/components. To specify an element (typially a software package) contained *in* a product where the vulnerability was detected, the VEX relationship can optionally specify this subcomponent using the [assessedElement](https://spdx.github.io/spdx-spec/v3.0/model/Security/Properties/assessedElement/) property. Using the `assessedElement` can be helful in situations where a particular CVE may affect software products differently. For example, perhaps you have two software products which both contain the log4j vulnerability (CVE-2021-44228) but only one of the products is exploitable by the vulnerability. The `to` product in your SPDX VEX statements and the VEX status relationships would be different but the `assessedElement` would be the same log4j package.
107+
VEX relationships in SPDX will always point `to` element(s) representing the VEX *products*. A product is a logical unit representing a piece of software, typically composed of one or more software packages/libraries/components. To specify an element (typically a software package) contained *in* a product where the vulnerability was detected, the VEX relationship can optionally specify this subcomponent using the [assessedElement](https://spdx.github.io/spdx-spec/v3.0/model/Security/Properties/assessedElement/) property. Using the `assessedElement` can be helpful in situations where a particular CVE may affect software products differently. For example, perhaps you have two software products which both contain the log4j vulnerability (CVE-2021-44228) but only one of the products is exploitable by the vulnerability. The `to` product in your SPDX VEX statements and the VEX status relationships would be different but the `assessedElement` would be the same log4j package.
90108

91109
Product A, affected by CVE-2021-44228:
110+
92111
```json
93-
"@type": "VexAffectedVulnAssessmentRelationship",
94-
"@id": "urn:spdx.dev:vex-affected-1",
112+
{
113+
"type": "VexAffectedVulnAssessmentRelationship",
114+
"spdxId": "urn:spdx.dev:vex-affected-1",
95115
"relationshipType": "affects",
96116
"from": "urn:spdx.dev:vuln-cve-2021-44228",
97117
"to": ["urn:product-acme-application-1.3"],
98-
"assessedElement": "urn:apache-log4j-2.12",
118+
"security_assessedElement": "urn:apache-log4j-2.12",
99119
"suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
100120
"publishedTime": "2021-12-10T11:04:53Z",
101-
"actionStatement": "Recommend to update logj4 version to 2.16.0 or later"
102-
"actionStatementTime": "2021-12-12T12:09:23Z"
121+
"security_actionStatement": "Recommend to update log4j version to 2.16.0 or later",
122+
"security_actionStatementTime": "2021-12-12T12:09:23Z"
123+
}
103124
```
104125

105126
Product B, not affected by CVE-2021-44228:
127+
106128
```json
107-
"@type": "VexNotAffectedVulnAssessmentRelationship",
108-
"@id": "urn:spdx.dev:vex-not-affected-1",
129+
{
130+
"type": "VexNotAffectedVulnAssessmentRelationship",
131+
"spdxId": "urn:spdx.dev:vex-not-affected-1",
109132
"relationshipType": "doesNotAffect",
110133
"from": "urn:spdx.dev:vuln-cve-2021-44228",
111134
"to": ["urn:product-acme-application-1.4"],
112-
"assessedElement": "urn:apache-log4j-2.12",
135+
"security_assessedElement": "urn:apache-log4j-2.12",
113136
"suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
114137
"publishedTime": "2021-12-10T11:04:53Z",
115-
"justificationType": "vulnerableCodeNotInExecutePath"
138+
"security_justificationType": "vulnerableCodeNotInExecutePath"
139+
}
116140
```
117141

118-
119-
120-
## J.3 Changing the Status of a Vulnerability
142+
## 3. Changing the status of a vulnerability
121143

122144
VEX is designed to communicate status of a vulnerability in a software product which is inherently dynamic and prone to change over time.
123145

124-
Because [Elements](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) in SPDX are immutable, it is best best practice to issue a new VulnAssessmentRelationship of type `amendedBy` each time the VEX status of a vulnerability changes (i.e. `underInvestigationFor` --> `affects`) in addition to creating the new type of VEX status relationship. Linking the two VEX relationships this way creates a more complete graph while making it easier for tools to track the changing status of a vulnerability in a software product. The following example shows how you would communicate that a vulnerability was under investigation before determining that the vulnerability indeed affects a product.
146+
Because [Elements](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) in SPDX are immutable, it is best practice to issue a new VulnAssessmentRelationship of type `amendedBy` each time the VEX status of a vulnerability changes (i.e. `underInvestigationFor` --> `affects`) in addition to creating the new type of VEX status relationship. Linking the two VEX relationships this way creates a more complete graph while making it easier for tools to track the changing status of a vulnerability in a software product. The following example shows how you would communicate that a vulnerability was under investigation before determining that the vulnerability indeed affects a product.
125147

126148
```json
127-
"@type": "VexUnderInvestigationVulnAssessmentRelationship",
128-
"@id": "urn:spdx.dev:vex-underInvestigation-1",
149+
{
150+
"type": "VexUnderInvestigationVulnAssessmentRelationship",
151+
"spdxId": "urn:spdx.dev:vex-underInvestigation-1",
129152
"relationshipType": "underInvestigationFor",
130153
"from": "urn:spdx.dev:vuln-cve-2020-28498",
131154
"to": ["urn:product-acme-application-1.3"],
132-
"assessedElement": "urn:npm-elliptic-6.5.2",
155+
"security_assessedElement": "urn:npm-elliptic-6.5.2",
133156
"suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
134157
"publishedTime": "2021-03-09T11:04:53Z"
135-
136-
"@type": "VulnAssessmentRelationship",
137-
"@id": "urn:spdx.dev:vex-update-acme-1.3",
158+
},
159+
{
160+
"type": "VulnAssessmentRelationship",
161+
"spdxId": "urn:spdx.dev:vex-update-acme-1.3",
138162
"relationshipType": "amendedBy",
139163
"from": "urn:spdx.dev:vex-underInvestigation-1",
140164
"to": ["urn:spdx.dev:vex-affected-1"],
141-
142-
"@type": "VexAffectedVulnAssessmentRelationship",
143-
"@id": "urn:spdx.dev:vex-affected-1",
165+
},
166+
{
167+
"type": "VexAffectedVulnAssessmentRelationship",
168+
"spdxId": "urn:spdx.dev:vex-affected-1",
144169
"relationshipType": "affects",
145170
"from": "urn:spdx.dev:vuln-cve-2020-28498",
146171
"to": ["urn:product-acme-application-1.3"],
147-
"assessedElement": "urn:npm-elliptic-6.5.2",
172+
"security_assessedElement": "urn:npm-elliptic-6.5.2",
148173
"suppliedBy": ["urn:spdx.dev:agent-jane-doe"],
149174
"publishedTime": "2021-03-15T08:10:43Z"
175+
}
150176
```
151177

152178
Note that it is not required to include an `amendedBy` relationship for evolving impact statements but it is considered best practice. One could also simply create a new VEX status relationship for tools/consumers to piece together using context clues like product names, ids and time stamps.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ nav:
4848
- Getting started: getting-started.md
4949
- Cross referencing: cross-reference.md
5050
- Including security information in a SPDX document: security-info-in-spdx.md
51+
- How to implement VEX in SPDX: how-to-vex.md
5152
- Using SPDX License List short identifiers in source files: license-id-in-source.md
5253
- Using SPDX to comply with norms, standards and regulation: comply-with-norms.md
5354
- Differences from previous editions: diffs-from-previous-editions.md

0 commit comments

Comments
 (0)