Skip to content

Commit 8205f4b

Browse files
oaubreyoaubrey
committed
Updates to documentation for GA release
1 parent 6cf34ba commit 8205f4b

3 files changed

Lines changed: 52 additions & 120 deletions

File tree

docs/vex-beta-details.md renamed to docs/vex-ga-details.md

Lines changed: 40 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,34 @@
1-
# CSAF-VEX Beta Details
1+
# CSAF-VEX GA Details
22

3-
This document is intended to cover the changes made in the new release of beta VEX files compared to the legacy VEX files. These changes are broken out by the three main CSAF VEX document sections: Document, Product Tree and Vulnerabilities.
3+
This document is intended to cover the changes made in the new release of GA VEX files compared to the legacy VEX files. These changes are broken out by the three main CSAF VEX document sections: Document, Product Tree and Vulnerabilities.
44

5-
++Please Note:++ The beta VEX files may experience minor changes as we address any final known issues. We aim to keep this documentation in sync with the changes, but there may be times when the documentation and implementation are not aligned. If you have questions on any of these changes, please see [How to Provide Feedback](https://redhatproductsecurity.github.io/security-data-guidelines/vex-beta-details/#how-to-provide-feedback).
5+
++ Please Note: ++ The GA VEX files may experience minor changes as we address any final known issues. We aim to keep this documentation in sync with the changes, but there may be times when the documentation and implementation are not aligned. If you have questions on any of these changes, please see [How to Provide Feedback](https://redhatproductsecurity.github.io/security-data-guidelines/vex-GA-details/#how-to-provide-feedback).
66

77
## Document Section
88

9-
The new beta VEX files include a few minor changes to the `document` section, outlined in the sections below.
9+
The new GA VEX files include a few minor changes to the `document` section, outlined in the sections below.
1010

1111
### Document Changes
1212

1313
#### Title
1414

15-
Previously, the `document.title` followed the format component:CVE title. The title in the beta VEX files removed the component prefix. This decision was made to simplify the title and remove confusion when a CVE affects multiple components.
15+
Previously, the `document.title` followed the format component:CVE title. The title in the GA VEX files removed the component prefix. This decision was made to simplify the title and remove confusion when a CVE affects multiple components.
1616

1717
```json
1818
# Example of legacy VEX title
1919
"title": "glibc: Integer overflow in memalign leads to heap corruption",
2020
```
2121

2222
```json
23-
# Example of beta VEX title
23+
# Example of GA VEX title
2424
"title": "Integer overflow in memalign leads to heap corruption",
2525
```
2626

2727
#### Tracking
2828

29-
The `document.tracking` object has two changes in the new beta VEX files: the generator name has changed and the revision history has been simplified.
29+
The `document.tracking` object has two changes in the new GA VEX files: the generator name has changed and the revision history has been simplified.
3030

31-
In the new beta VEX files, the `document.tracking.generator.engine.name` now references the new service responsible for creating VEX files, "CSAF Generator".
31+
In the new GA VEX files, the `document.tracking.generator.engine.name` now references the new service responsible for creating VEX files, "CSAF Generator".
3232

3333
```json
3434
# Example of legacy VEX generator
@@ -43,7 +43,7 @@ In the new beta VEX files, the `document.tracking.generator.engine.name` now ref
4343
```
4444

4545
```json
46-
# Example of beta VEX generator
46+
# Example of GA VEX generator
4747
"generator": {
4848
"date": "2026-02-27T12:07:46+00:00",
4949
"engine": {
@@ -53,7 +53,7 @@ In the new beta VEX files, the `document.tracking.generator.engine.name` now ref
5353
},
5454
```
5555

56-
The `document.tracking.revision_history` has also been updated in the new beta VEX files. Previously, the revision history object implemented some logic to create a history of changes, which was neither accurate nor comprehensive of the historical changes to an individual VEX file. In the new beta VEX files, there will only be one revision that represents the last generated version.
56+
The `document.tracking.revision_history` has also been updated in the new GA VEX files. Previously, the revision history object implemented some logic to create a history of changes, which was neither accurate nor comprehensive of the historical changes to an individual VEX file. In the new GA VEX files, there will only be one revision that represents the last generated version.
5757

5858
```json
5959
# Example of legacy VEX revision history
@@ -77,7 +77,7 @@ The `document.tracking.revision_history` has also been updated in the new beta V
7777
```
7878

7979
```json
80-
# Example of beta VEX revision history
80+
# Example of GA VEX revision history
8181
"revision_history": [
8282
{
8383
"date": "2026-02-27T12:07:46+00:00",
@@ -90,7 +90,7 @@ The `document.tracking.revision_history` has also been updated in the new beta V
9090

9191
### Removed Document Objects
9292

93-
The following optional objects were removed from the `document` section and will not be present in the new beta VEX files:
93+
The following optional objects were removed from the `document` section and will not be present in the new GA VEX files:
9494

9595
- `document.distribution`
9696
- `document.lang`
@@ -99,11 +99,11 @@ The following optional objects were removed from the `document` section and will
9999

100100
## Product Tree Section
101101

102-
The `product_tree` section of VEX files includes the most significant changes between legacy VEX files and the new beta VEX files.
102+
The `product_tree` section of VEX files includes the most significant changes between legacy VEX files and the new GA VEX files.
103103

104104
### Branch Removal
105105

106-
In the `product_tree` section of a VEX file, legacy VEX files used to nest `product_name` objects under `product_family` branches and `product_version` objects under `architecture` branches, depending on the fix status of each. The new beta VEX files remove any branch nesting. All `product_name` and `product_version` objects will only be nested under the parent `vendor` branch.
106+
In the `product_tree` section of a VEX file, legacy VEX files used to nest `product_name` objects under `product_family` branches and `product_version` objects under `architecture` branches, depending on the fix status of each. The new GA VEX files remove any branch nesting. All `product_name` and `product_version` objects will only be nested under the parent `vendor` branch.
107107

108108
```json
109109
# Example of legacy VEX branch nesting
@@ -135,7 +135,7 @@ In the `product_tree` section of a VEX file, legacy VEX files used to nest `prod
135135
```
136136

137137
```json
138-
# Example of beta VEX branch nesting
138+
# Example of GA VEX branch nesting
139139
"branches": [
140140
{
141141
"category": "vendor",
@@ -159,11 +159,11 @@ In the `product_tree` section of a VEX file, legacy VEX files used to nest `prod
159159

160160
### Product Changes
161161

162-
The new beta VEX files include three notable changes to product representation: products are now always represented with a minor version, the product naming convention has been modified for improved consistency and product variants have been eliminated for simplicity.
162+
The new GA VEX files include three notable changes to product representation: products are now always represented with a minor version, the product naming convention has been modified for improved consistency and product variants have been eliminated for simplicity.
163163

164164
#### Product Granularity
165165

166-
Previously, legacy VEX files only represented a product with a minor version when a fix was available. New beta VEX files include representation for any supported minor version, regardless of fix status. This change is intended to provide better affectedness information for each support version of a product that may be impacted by a vulnerability.
166+
Previously, legacy VEX files only represented a product with a minor version when a fix was available. New GA VEX files include representation for any supported minor version, regardless of fix status. This change is intended to provide better affectedness information for each support version of a product that may be impacted by a vulnerability.
167167

168168
In the example for CVE-2026-0861, the [legacy VEX file](https://security.access.redhat.com/data/csaf/v2/vex/2026/cve-2026-0861.json) only includes a single `product_name` entry to represent the status of Red Hat Enterprise Linux 8.
169169

@@ -182,10 +182,10 @@ In the example for CVE-2026-0861, the [legacy VEX file](https://security.access.
182182
}
183183
```
184184

185-
The [beta VEX file](https://security.access.redhat.com/data/csaf/v2/vex-feed/2026/cve-2026-0861.json) includes 5 `product_name` entries to represent the status of each supported version of Red Hat Enterprise Linux 8.
185+
The [GA VEX file](https://security.access.redhat.com/data/csaf/v2/vex-feed/2026/cve-2026-0861.json) includes 5 `product_name` entries to represent the status of each supported version of Red Hat Enterprise Linux 8.
186186

187187
```json
188-
# Example of beta VEX RHEL 8 product representation
188+
# Example of GA VEX RHEL 8 product representation
189189
{
190190
"category": "product_name",
191191
"name": "Red Hat Enterprise Linux 8.10.z",
@@ -245,12 +245,12 @@ The [beta VEX file](https://security.access.redhat.com/data/csaf/v2/vex-feed/202
245245

246246
#### Product Naming
247247

248-
Previously, legacy VEX files used different naming schemas based on the fix status of the product. The new beta VEX files has standardized on a naming schema to improve consistency of a product's representation throughout the entire lifecycle of a VEX file.
248+
Previously, legacy VEX files used different naming schemas based on the fix status of the product. The new GA VEX files has standardized on a naming schema to improve consistency of a product's representation throughout the entire lifecycle of a VEX file.
249249

250-
By comparing the Openshift 4.18 in legacy VEX files for [CVE-2025-12801](https://security.access.redhat.com/data/csaf/v2/vex/2025/cve-2025-12801.json) and [CVE-2025-6176](https://security.access.redhat.com/data/csaf/v2/vex/2025/cve-2025-6176.json), you can see that the `product_id` changes format from "red_hat_openshift_container_platform_4" in an unfixed state to "9Base-RHOSE-4.18" in a fixed state.
250+
By comparing the Openshift 4.18 in legacy VEX files for [CVE-2023-26819](https://security.access.redhat.com/data/csaf/v2/vex/2025/cve-2023-126819.json) and [CVE-2025-6176](https://security.access.redhat.com/data/csaf/v2/vex/2025/cve-2025-6176.json), you can see that the `product_id` changes format from "red_hat_openshift_container_platform_4" in an unfixed state to "9Base-RHOSE-4.18" in a fixed state.
251251

252252
```json
253-
# Example of legacy VEX unfixed product name for CVE-2025-12801
253+
# Example of legacy VEX unfixed product name for CVE-2023-26819
254254
{
255255
"category": "product_name",
256256
"name": "Red Hat OpenShift Container Platform 4",
@@ -277,10 +277,10 @@ By comparing the Openshift 4.18 in legacy VEX files for [CVE-2025-12801](https:/
277277
}
278278
```
279279

280-
In new beta VEX files for [CVE-2025-12801](https://security.access.redhat.com/data/csaf/v2/vex-feed/2025/cve-2025-12801.json) and [CVE-2025-6176](https://security.access.redhat.com/data/csaf/v2/vex-feed/2025/cve-2025-6176.json), the `product_id` value remains the same between fixed and unfixed states.
280+
In new GA VEX files for [CVE-2023-26819](https://security.access.redhat.com/data/csaf/v2/vex-feed/2023/cve-2023-26819.json) and [CVE-2025-6176](https://security.access.redhat.com/data/csaf/v2/vex-feed/2025/cve-2025-6176.json), the `product_id` value follows the same naming convention between fixed and unfixed states, only varying in the channel specifier.
281281

282282
```json
283-
# Example of beta VEX unfixed product name for CVE-2025-12801
283+
# Example of GA VEX unfixed product name for CVE-2023-26819
284284
{
285285
"category": "product_name",
286286
"name": "OpenShift Container Platform 4.18",
@@ -293,86 +293,29 @@ In new beta VEX files for [CVE-2025-12801](https://security.access.redhat.com/da
293293
}
294294
}
295295

296-
# Example of beta VEX fixed product name for CVE-2025-6176
296+
# Example of GA VEX fixed product name for CVE-2025-6176
297297
{
298298
"category": "product_name",
299299
"name": "OpenShift Container Platform 4.18",
300300
"product": {
301301
"name": "OpenShift Container Platform 4.18",
302-
"product_id": "openshift-4.18",
302+
"product_id": "openshift-4.18::el9",
303303
"product_identification_helper": {
304-
"cpe": "cpe:/a:redhat:openshift:4.18"
305-
}
306-
}
307-
},
308-
309-
```
310-
311-
#### Product Variants
312-
313-
The new beta VEX files change how multiple product variants are represented. For RHEL products, only the 'appstream' variant will be represented. For other products that are based on RHEL, the RHEL base version will be represented like '::el8'.
314-
315-
```json
316-
# Example of legacy VEX product variants
317-
{
318-
"category": "product_name",
319-
"name": "Red Hat Enterprise Linux CodeReady Linux Builder (v. 9)",
320-
"product": {
321-
"name": "Red Hat Enterprise Linux CodeReady Linux Builder (v. 9)",
322-
"product_id": "CRB-9.7.0.Z.MAIN",
323-
"product_identification_helper": {
324-
"cpe": "cpe:/a:redhat:enterprise_linux:9::crb"
325-
}
326-
}
327-
},
328-
{
329-
"category": "product_name",
330-
"name": "Red Hat Enterprise Linux AppStream (v. 9)",
331-
"product": {
332-
"name": "Red Hat Enterprise Linux AppStream (v. 9)",
333-
"product_id": "AppStream-9.7.0.Z.MAIN",
334-
"product_identification_helper": {
335-
"cpe": "cpe:/a:redhat:enterprise_linux:9::appstream"
304+
"cpe": "cpe:/a:redhat:openshift:4.18::el9"
336305
}
337306
}
338307
},
339-
{
340-
"category": "product_name",
341-
"name": "Red Hat Enterprise Linux BaseOS (v. 9)",
342-
"product": {
343-
"name": "Red Hat Enterprise Linux BaseOS (v. 9)",
344-
"product_id": "BaseOS-9.7.0.Z.MAIN",
345-
"product_identification_helper": {
346-
"cpe": "cpe:/o:redhat:enterprise_linux:9::baseos"
347-
}
348-
}
349-
},
350308

351309
```
352310

353-
```json
354-
# Example of beta VEX product variants
355-
{
356-
"category": "product_name",
357-
"name": "Red Hat Enterprise Linux 9.7.z",
358-
"product": {
359-
"name": "Red Hat Enterprise Linux 9.7.z",
360-
"product_id": "rhel-9.7.z::appstream",
361-
"product_identification_helper": {
362-
"cpe": "cpe:/a:redhat:enterprise_linux:9::appstream"
363-
}
364-
}
365-
},
366-
367-
```
368311

369312
### Component Changes
370313

371314
In additon to the product representation changes, there are a few changes to component representation.
372315

373316
#### Component Naming
374317

375-
A minor change was made to the component naming in the new beta VEX files. The `product_version.name` and `product.name` fields for components will not include any version information, even when fixed in the new beta VEX files.
318+
A minor change was made to the component naming in the new GA VEX files. The `product_version.name` and `product.name` fields for components will not include any version information, even when fixed in the new GA VEX files. Additionally, epoch values will always be present in both the `product_id` and the `purl`.
376319

377320
```json
378321
# Example of legacy VEX component naming for unfixed component
@@ -403,7 +346,7 @@ A minor change was made to the component naming in the new beta VEX files. The `
403346
```
404347

405348
```json
406-
# Example of beta VEX component naming for unfixed component
349+
# Example of GA VEX component naming for unfixed component
407350
{
408351
"category": "product_version",
409352
"name": "libxml2",
@@ -416,15 +359,15 @@ A minor change was made to the component naming in the new beta VEX files. The `
416359
}
417360
}
418361

419-
# Example of beta VEX component naming for fixed component
362+
# Example of GA VEX component naming for fixed component
420363
{
421364
"category": "product_version",
422365
"name": "libxml2",
423366
"product": {
424367
"name": "libxml2",
425-
"product_id": "libxml2-2.9.13-10.el9_6",
368+
"product_id": "libxml2-0:2.9.13-10.el9_6.src",
426369
"product_identification_helper": {
427-
"purl": "pkg:rpm/redhat/libxml2@2.9.13-10.el9_6?arch=src"
370+
"purl": "pkg:rpm/redhat/libxml2@2.9.13-10.el9_6?arch=src&epoch=0"
428371
}
429372
}
430373
}
@@ -484,15 +427,15 @@ In legacy VEX files, fixed components were represented multiple times for their
484427
```
485428

486429
```json
487-
# Example of beta VEX component architecture
430+
# Example of GA VEX component architecture
488431
{
489432
"category": "product_version",
490433
"name": "glibc",
491434
"product": {
492435
"name": "glibc",
493-
"product_id": "glibc-0:2.34-231.el9_7.10",
436+
"product_id": "glibc-0:2.34-231.el9_7.10.src",
494437
"product_identification_helper": {
495-
"purl": "pkg:rpm/redhat/glibc@2.34-231.el9_7.10?arch=src"
438+
"purl": "pkg:rpm/redhat/glibc@2.34-231.el9_7.10?arch=src&epoch=0"
496439
}
497440
}
498441
},
@@ -501,19 +444,19 @@ In legacy VEX files, fixed components were represented multiple times for their
501444

502445
#### Binary RPMs
503446

504-
More information on binary RPMS will be available soon. Product Security is working to address this gap as soon as possible.
447+
Binary RPM information is primarily available for Red Hat Hardened Images. Binary RPM information will start being available for newer CVEs soon. Product Security is actively working to address this gap as quickly as possible.
505448

506449
## Vulnerabilities Section
507450

508-
Finally, there were a few changes made the the `vulnerabilties` section of the new beta VEX files.
451+
Finally, there were a few changes made the the `vulnerabilties` section of the new GA VEX files.
509452

510453
### Remediations
511454

512-
A minor change to the `vulnerabilites.remediations` object was included in the new beta VEX files. Product and component pairs that have a 'fixed' product status will no longer be listed under a `category: workaround` remediation object. Fixed product and componets will only be listed under a `category: vendor_fix` remediation object.
455+
A minor change to the `vulnerabilites.remediations` object was included in the new GA VEX files. Product and component pairs that have a 'fixed' product status will no longer be listed under a `category: workaround` remediation object. Fixed product and componets will only be listed under a `category: vendor_fix` remediation object.
513456

514457
### CVSS Score
515458

516-
The new beta VEX files simplify the representation of CVSS scores by eliminating the individual metrics, which are still represented in the `vectorString`.
459+
The new GA VEX files simplify the representation of CVSS scores by eliminating the individual metrics, which are still represented in the `vectorString`.
517460

518461
```json
519462
# Example of legacy VEX CVSS scores
@@ -534,7 +477,7 @@ The new beta VEX files simplify the representation of CVSS scores by eliminating
534477
```
535478

536479
```json
537-
# Example of beta VEX CVSS scores
480+
# Example of GA VEX CVSS scores
538481
"cvss_v3": {
539482
"version": "3.1",
540483
"vectorString": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:H",

0 commit comments

Comments
 (0)