diff --git a/docs/vex-alpha-details.md b/docs/vex-beta-details.md similarity index 69% rename from docs/vex-alpha-details.md rename to docs/vex-beta-details.md index d3c604e..bd6c6fc 100644 --- a/docs/vex-alpha-details.md +++ b/docs/vex-beta-details.md @@ -1,16 +1,18 @@ -# CSAF-VEX Alpha Details +# CSAF-VEX Beta Details -This document is intended to cover the changes made in the new release of alpha 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. +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. -Please Note: The alpha VEX files are still in a state of flux as we address 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-alpha-details/#how-to-provide-feedback). +++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). -## Document Section -The new alpha VEX files include a few minor changes to the `document` section, outlined in the sections below. +## Document Section -### Document Changes +The new beta VEX files include a few minor changes to the `document` section, outlined in the sections below. -#### Title -Previously, the `document.title` followed the format component:CVE title. The title in the alpha VEX files removed the component prefix. This decision was made to simplify the title and remove confusion when a CVE affects multiple components. +### Document Changes + +#### Title + +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. ```json # Example of legacy VEX title @@ -18,14 +20,15 @@ Previously, the `document.title` followed the format component:CVE title. The ti ``` ```json -# Example of alpha VEX title +# Example of beta VEX title "title": "Integer overflow in memalign leads to heap corruption", ``` -#### Tracking -The `document.tracking` object has two changes in the new alpha VEX files: the generator name has changed and the revision history has been simplified. +#### Tracking + +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. -In the new alpha VEX files, the `document.tracking.generator.engine.name` now references the new service responsible for creating VEX files, "CSAF Generator". +In the new beta VEX files, the `document.tracking.generator.engine.name` now references the new service responsible for creating VEX files, "CSAF Generator". ```json # Example of legacy VEX generator @@ -40,7 +43,7 @@ In the new alpha VEX files, the `document.tracking.generator.engine.name` now re ``` ```json -# Example of alpha VEX generator +# Example of beta VEX generator "generator": { "date": "2026-02-27T12:07:46+00:00", "engine": { @@ -50,7 +53,7 @@ In the new alpha VEX files, the `document.tracking.generator.engine.name` now re }, ``` -The `document.tracking.revision_history` has also been updated in the new alpha 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 alpha VEX files, there will only be one revision that represents the last generated version. +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. ```json # Example of legacy VEX revision history @@ -74,7 +77,7 @@ The `document.tracking.revision_history` has also been updated in the new alpha ``` ```json -# Example of alpha VEX revision history +# Example of beta VEX revision history "revision_history": [ { "date": "2026-02-27T12:07:46+00:00", @@ -85,20 +88,22 @@ The `document.tracking.revision_history` has also been updated in the new alpha ``` -### Removed Document Objects -The following optional objects were removed from the `document` section and will not be present in the new alpha VEX files: +### Removed Document Objects + +The following optional objects were removed from the `document` section and will not be present in the new beta VEX files: + +- `document.distribution` +- `document.lang` +- `document.notes` +- `document.references` -* `document.distribution` -* `document.lang` -* `document.notes` -* `document.references` +## Product Tree Section +The `product_tree` section of VEX files includes the most significant changes between legacy VEX files and the new beta VEX files. -## Product Tree Section -The `product_tree` section of VEX files includes the most significant changes between legacy VEX files and the new alpha VEX files. +### Branch Removal -### Branch Removal -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 alpha VEX files remove any branch nesting. All `product_name` and `product_version` objects will only be nested under the parent `vendor` branch. +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. ```json # Example of legacy VEX branch nesting @@ -130,7 +135,7 @@ In the `product_tree` section of a VEX file, legacy VEX files used to nest `prod ``` ```json -# Example of alpha VEX branch nesting +# Example of beta VEX branch nesting "branches": [ { "category": "vendor", @@ -153,10 +158,12 @@ In the `product_tree` section of a VEX file, legacy VEX files used to nest `prod ``` ### Product Changes -The new alpha 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. + +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. #### Product Granularity -Previously, legacy VEX files only represented a product with a minor version when a fix was available. New alpha 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. + +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. 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. @@ -175,10 +182,10 @@ In the example for CVE-2026-0861, the [legacy VEX file](https://security.access. } ``` -The [alpha VEX file](https://security.access.redhat.com/data/csaf/v2/vex-alpha/2026/cve-2026-0861.json) includes 5 `product_name` entries to represent the status of each supported version of Red Hat Enterprise Linux 8. +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. ```json -# Example of alpha VEX RHEL 8 product representation +# Example of beta VEX RHEL 8 product representation { "category": "product_name", "name": "Red Hat Enterprise Linux 8.10.z", @@ -237,7 +244,8 @@ The [alpha VEX file](https://security.access.redhat.com/data/csaf/v2/vex-alpha/2 ``` #### Product Naming -Previously, legacy VEX files used different naming schemas based on the fix status of the product. The new alpha VEX files has standardized on a naming schema to improve consistency of a product's representation throughout the entire lifecycle of a VEX file. + +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. 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. @@ -269,10 +277,10 @@ By comparing the Openshift 4.18 in legacy VEX files for [CVE-2025-12801](https:/ } ``` -In new alpha VEX files for [CVE-2025-12801](https://security.access.redhat.com/data/csaf/v2/vex-alpha/2025/cve-2025-12801.json) and [CVE-2025-6176](https://security.access.redhat.com/data/csaf/v2/vex-alpha/2025/cve-2025-6176.json), the `product_id` value remains the same between fixed and unfixed states. +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. ```json -# Example of alpha VEX unfixed product name for CVE-2025-12801 +# Example of beta VEX unfixed product name for CVE-2025-12801 { "category": "product_name", "name": "OpenShift Container Platform 4.18", @@ -285,7 +293,7 @@ In new alpha VEX files for [CVE-2025-12801](https://security.access.redhat.com/d } } -# Example of alpha VEX fixed product name for CVE-2025-6176 +# Example of beta VEX fixed product name for CVE-2025-6176 { "category": "product_name", "name": "OpenShift Container Platform 4.18", @@ -301,9 +309,10 @@ In new alpha VEX files for [CVE-2025-12801](https://security.access.redhat.com/d ``` #### Product Variants -The new alpha 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'. -```json +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'. + +```json # Example of legacy VEX product variants { "category": "product_name", @@ -342,7 +351,7 @@ The new alpha VEX files change how multiple product variants are represented. Fo ``` ```json -# Example of alpha VEX product variants +# Example of beta VEX product variants { "category": "product_name", "name": "Red Hat Enterprise Linux 9.7.z", @@ -358,10 +367,12 @@ The new alpha VEX files change how multiple product variants are represented. Fo ``` ### Component Changes + In additon to the product representation changes, there are a few changes to component representation. -#### Component Naming -A minor change was made to the component naming in the new alpha VEX files. The `product_version.name` and `product.name` fields for components will not include any version information, even when fixed in the new alpha VEX files. +#### Component Naming + +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. ```json # Example of legacy VEX component naming for unfixed component @@ -392,7 +403,7 @@ A minor change was made to the component naming in the new alpha VEX files. The ``` ```json -# Example of alpha VEX component naming for unfixed component +# Example of beta VEX component naming for unfixed component { "category": "product_version", "name": "libxml2", @@ -405,7 +416,7 @@ A minor change was made to the component naming in the new alpha VEX files. The } } -# Example of alpha VEX component naming for fixed component +# Example of beta VEX component naming for fixed component { "category": "product_version", "name": "libxml2", @@ -420,6 +431,7 @@ A minor change was made to the component naming in the new alpha VEX files. The ``` #### Architecture Removal + In legacy VEX files, fixed components were represented multiple times for their different architectures. To reduce the total number of component and relationship entries, we have decided to remove architecture representation for components in both their `name`, `product_id` and `purl`. The only exception to this is for SRPM components, which will include a ".src" in the `name` and `product_id` and "arch=src" in the `purl`. ```json @@ -472,14 +484,13 @@ In legacy VEX files, fixed components were represented multiple times for their ``` ```json -# Example of alpha VEX component architecture -# Note: Subject to change pending resolution of component version jiras +# Example of beta VEX component architecture { "category": "product_version", "name": "glibc", "product": { "name": "glibc", - "product_id": "glibc-2.34-231.el9_7.10", + "product_id": "glibc-0:2.34-231.el9_7.10", "product_identification_helper": { "purl": "pkg:rpm/redhat/glibc@2.34-231.el9_7.10?arch=src" } @@ -487,18 +498,22 @@ In legacy VEX files, fixed components were represented multiple times for their }, ``` -#### Binary RPMs -More information available soon + +#### Binary RPMs + +More information on binary RPMS will be available soon. Product Security is working to address this gap as soon as possible. ## Vulnerabilities Section -Finally, there were a few changes made the the `vulnerabilties` section of the new alpha VEX files. -### Remediations -A minor change to the `vulnerabilites.remediations` object was included in the new alpha 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. +Finally, there were a few changes made the the `vulnerabilties` section of the new beta VEX files. + +### Remediations +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. ### CVSS Score -The new alpha VEX files simplify the representation of CVSS scores by eliminating the individual metrics, which are still represented in the `vectorString`. + +The new beta VEX files simplify the representation of CVSS scores by eliminating the individual metrics, which are still represented in the `vectorString`. ```json # Example of legacy VEX CVSS scores @@ -519,7 +534,7 @@ The new alpha VEX files simplify the representation of CVSS scores by eliminatin ``` ```json -# Example of alpha VEX CVSS scores +# Example of beta VEX CVSS scores "cvss_v3": { "version": "3.1", "vectorString": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:H", @@ -530,10 +545,10 @@ The new alpha VEX files simplify the representation of CVSS scores by eliminatin ### Removed Vulnerabilties Objects -* `vulnerabilities.ids`: Entire object has been removed -* `vulnerabilities.notes`: Note objects of the summary category and the general category have been removed -* `vulnerabilities.references`: References to legacy Bugzilla flaws have been removed from this section -* `vulenrabilities.release_date`: Removed as this date is a duplicate value to `vulnerabilities.discovery_date` +- `vulnerabilities.ids`: Entire object has been removed +- `vulnerabilities.notes`: Note objects of the summary category and the general category have been removed +- `vulnerabilities.references`: References to legacy Bugzilla flaws have been removed from this section +- `vulenrabilities.release_date`: Removed as this date is a duplicate value to `vulnerabilities.discovery_date` ## How to Provide Feedback @@ -542,4 +557,5 @@ For any issues or questions you have, please file a jira issue with the followi - **Project**: [SECDATA](https://issues.redhat.com/projects/SECDATA/summary) - **Issue Type**: Ticket - **Component**: ‘feedback-new-vex’ -- **Description**: The question or issue you wish to raise. Please provide a detailed explanation, the VEX file you are referencing and a specific example of the data. \ No newline at end of file +- **Description**: The question or issue you wish to raise. Please provide a detailed explanation, the VEX file you are referencing and a specific example of the data. + diff --git a/docs/vex-alpha.md b/docs/vex-beta.md similarity index 74% rename from docs/vex-alpha.md rename to docs/vex-beta.md index cc83713..2fb2d8b 100644 --- a/docs/vex-alpha.md +++ b/docs/vex-beta.md @@ -1,8 +1,8 @@ -# CSAF VEX-Alpha Release +# CSAF VEX-Beta Release -## VEX-Alpha Announcement +## VEX-Beta Announcement -Red Hat Product Security is pleased to share that the Alpha version of our new VEX (Vulnerability Exploit eXchange) files is now available [here](https://security.access.redhat.com/data/csaf/v2/vex-alpha/). +Red Hat Product Security is pleased to share that the Beta version of our new VEX (Vulnerability Exploit eXchange) files is now available [here](https://security.access.redhat.com/data/csaf/v2/vex-feed/). ### Current Update Overview @@ -15,22 +15,19 @@ This update focuses on data precision and standardizing our CSAF VEX format. Key - **Streamlined Content**: We’ve removed unrequired fields (duplicate titles, redundant CVSS scores, unnecessary note objects) and ensured `fixed` product and components no longer appear in `workaround` remediation objects. - **Modernized Infrastructure**: We have migrated VEX publication to a completely new service that improves performance and supportability. -More detailed information on the differences between legacy VEX files and Alpha VEX files will be found [here](https://redhatproductsecurity.github.io/security-data-guidelines/vex-alpha-details/). +More detailed information on the differences between legacy VEX files and Beta VEX files will be found [here](https://redhatproductsecurity.github.io/security-data-guidelines/vex-beta-details/). -### Alpha Limitations & Known Issues +### Beta Limitations & Known Issues As we perform final data cleanup and address some remaining functionality, you may notice daily fluctuations in file content. Please be aware of the following known issues: - **Binary RPMs**: Currently unavailable for unfixed items. Product Security is working to address this as soon as possible. -- **Data Accuracy**: Some products and components may be missing or product statuses may be temporarily incorrect during this transition. - **Legacy Data**: Some older CVEs may display inaccurate CPEs (e.g., RHEL 7 transitioning from mainstream to EUS CPEs). -- **Data Deletion**: Removing files and handling rejected flaws is currently unsupported. -- **Scope**: Middleware remains out of scope for this project phase. +- **Scope**: Middleware remains out of scope for this project phase. Some middleware products will be included in the GA phase as data becomes available. ### Short Term Adoption Timeline -- **Beta VEX (End of March)**: Will address any outstanding known issues and initial vendor feedback. We will recommend that vendors begin the adoption process at this time. At this time, the VEX files will be moved into the final hosted location at https://security.access.redhat.com/data/csaf/v2/vex-feed/. The legacy VEX file location will remain unchanged. -- **GA VEX (Red Hat Summit)**: Upon GA, legacy VEX files will be deprecated. No further enhancements will be made to legacy files, though they will remain published for a transition period based on vendor adoption. +- **GA VEX (Red Hat Summit)**: Upon GA, legacy VEX files will be deprecated. No further enhancements will be made to legacy files, though they will remain published in the existing location for a transition period based on vendor adoption. ### Future Enhancements diff --git a/mkdocs.yml b/mkdocs.yml index 3f7e478..c24d1cd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,8 +39,8 @@ nav: - CPE: "cpe.md" - CSAF/VEX: - "CSAF/VEX Overview": "csaf-vex.md" - - "VEX-Alpha Release": "vex-alpha.md" - - "VEX-Alpha Details": "vex-alpha-details.md" + - "VEX-Beta Release": "vex-beta.md" + - "VEX-Beta Details": "vex-beta-details.md" - "Scanning Vendor Guidance": "scanning-vendors.md" - purl: "purl.md" - SBOM: "sbom.md"