Add a formal semver 2.0.0 version type #371
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| # Add a formal semver 2.0.0 version type | ||
|
|
||
| | Field | Value | | ||
| |:-----------------|:-------| | ||
| | RFD Submitter | Jon Moroney | | ||
| | RFD Pull Request | [RFD #0000](https://github.com/CVEProject/cve-schema/pull/371) | | ||
|
|
||
| ## Summary | ||
| [summary]: #summary | ||
|
|
||
| Introduce a new semantic versioning version type for the machine readable `versions` array. The goal of this addition is to provide consumers of CVE records with version information which is interoperable with off the shelf semantic versioning compatible tools. The proposed change includes schema based validation to ensure submitted records conform to the semver specification as well as tests to ensure conformity. | ||
|
|
||
| ## Problem Statement | ||
| [problem-statement]: #problem-statement | ||
|
|
||
| Today the `versions` array allows for a number of typed version fields which should inform the reader how to interpret the data. Alas, there is no validation that a record producer must conform to and as a result the version types have been used inconsistently. A consumer reading the semantic versioning type in particular has about a [44% chance of the data conforming to the semantic versioning specification](https://darakian.github.io/2025/06/04/parsing-semver-from-cve.html). | ||
|
|
||
| As a result consumers of CVE records cannot build reliable automation from the data in the record itself. Multiple sub-patterns do exist, but there is canonical list of them nor is there any guarantee of their stability. This leads to increased operational complexity in vulnerability management and potentially to vulnerabilities going unresolved. | ||
|
|
||
| Failing to adopt stricter datatypes will keep maintain the status quo which is generally accepted to be lacking. | ||
|
|
||
| ## Proposed Solution | ||
| [proposed-solution]: #proposed-solution | ||
|
|
||
| The proposed change adds a new "semver-2.0.0-version" pattern and two new properties for expressing version ranges. The two new properties `greaterThan`, and `greaterThanOrEqual` allow for the expression of an either exclusive, or inclusive upper bound on a version range. The new pattern "semver-2.0.0-version" is used to validate payloads which may be provided in the `version`, `lessThan`, `lessThanOrEqual`, `greaterThan`, and `greaterThanOrEqual`. | ||
|
|
||
| ## Examples | ||
| [examples]: #examples | ||
|
|
||
| Examples are provided as tests and may be viewed in the valid and invalid semver-2-0-0 subdirectories here: | ||
| https://github.com/CVEProject/cve-schema/tree/0dc04e2a9adb9e3d50409051ce1d006d79b57a90/schema/support/tests | ||
|
|
||
| ## Impact Assessment | ||
| [impact-assessment]: #impact-assessment | ||
|
|
||
| This proposal has been designed to be very low impact. In the base case both record producers and record consumers can simply ignore the new data type. Adoption of the new data type into systems that process CVE records should be quite straight forward as semantic versioning is well supported across many languages. Once records begin to be produced with `semver-2.0.0` values a record consumer will be able to build reliable vulnerability managment automation based on the data. | ||
|
|
||
| ## Compatibility and Migration | ||
| [compatibility-and-migration]: #compatibility-and-migration | ||
|
|
||
| This change adds one new, optional, value to the `versions` array and should be completely backwards compatible as no prior data formats are altered. The version type is currently arbitrary and so record providers are free to populate anything in that field, however no currently published records have used `semver-2.0.0`. | ||
|
|
||
| Both consumers are producers will need to update their code/process in order to make use of the new field. Should there be a desire to coordinate a migration an addition could be made to this RFD with guidance both for record producer and consumers, but off the shelf, semver compatible tools are expected to work. | ||
|
|
||
| Existence of the new version type should be communicated to stakeholders upon the RFDs acceptance. | ||
|
|
||
| ## Success Metrics | ||
| [success-metrics]: #success-metrics | ||
|
|
||
| 6+ months after the acceptance and adoption of this RFD process, the QWG should conduct a review of published CVE records to assess usage of the new version type. Additionally the QWG should solicit a survey to QWG members and outside CVE stakeholders about the perceived value of the new type. If there is low/no usage as well as a poor qualitative perception then the effort should be considered a failure and discussion of a rollback should be considered. | ||
|
|
||
| If there is consistent measured usage as well as positive qualitative perception then the effort should be considered a success. Anything between these two polls will require more qualitative analysis, but it is the RFD author's opinion that if there is a lack of consensus then the effort should by default be considered a failure. | ||
|
|
||
| A roll back of this RFD would consist of a removal of the `semver-2.0.0` version type and associated tests. | ||
|
|
||
| ## Supporting Data or Research | ||
| [supporting-data-or-research]: #supporting-data-or-research | ||
|
|
||
|
|
||
| ## Related Issues or Proposals | ||
| [related-issues-or-proposals]: #related-issues-or-proposals | ||
|
|
||
| This change originated out of a conversation detailing the shortcomings of the current versioning system here: | ||
| https://github.com/CVEProject/cve-schema/issues/362 | ||
|
|
||
| An alternative to adopting this RFD would be to not adopt it. | ||
|
|
||
| ## Recommended Priority | ||
| [recommended-priority]: #recommended-priority | ||
|
|
||
| Medium | ||
|
|
||
| ## Unresolved Questions | ||
| [unresolved-questions]: #unresolved-questions | ||
|
|
||
| None currently. | ||
|
|
||
| ## Future Possibilities | ||
| [future-possibilities]: #future-possibilities | ||
|
|
||
| Other common versioning types could have new, validated versions provided via subsequent RFDs. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -98,6 +98,11 @@ | |||||
| "minLength": 1, | ||||||
| "maxLength": 1024 | ||||||
| }, | ||||||
| "semver-2.0.0-version": { | ||||||
| "description": "A semver 2.0.0 compatible version", | ||||||
| "type": "string", | ||||||
| "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" | ||||||
| }, | ||||||
| "status": { | ||||||
| "description": "The vulnerability status of a given version or range of versions of a product. The statuses 'affected' and 'unaffected' indicate that the version is affected or unaffected by the vulnerability. The status 'unknown' indicates that it is unknown or unspecified whether the given version is affected. There can be many reasons for an 'unknown' status, including that an investigation has not been undertaken or that a vendor has not disclosed the status.", | ||||||
| "type": "string", | ||||||
|
|
@@ -299,12 +304,32 @@ | |||||
| "maxProperties": 3 | ||||||
| }, | ||||||
| { | ||||||
| "required": ["status", "versionType", "lessThan"] | ||||||
| }, | ||||||
| { | ||||||
| "required": ["status", "versionType", "lessThanOrEqual"] | ||||||
| }, | ||||||
| { | ||||||
| "required": ["status", "versionType", "greaterThan"] | ||||||
| }, | ||||||
| { | ||||||
| "required": ["status", "versionType", "greaterThanOrEqual"] | ||||||
| } | ||||||
| ], | ||||||
| "if": { | ||||||
| "properties": { | ||||||
| "versionType": {"const": "semver-2.0.0"} | ||||||
|
There was a problem hiding this comment. Since a PATCH must be backwards compatible.
Suggested change
There was a problem hiding this comment. As I said here (https://github.com/CVEProject/cve-schema/pull/371/files#r2210891519) I believe we've resolved this in QWG discussions, determining that "2.0.0" is correct. |
||||||
| } | ||||||
| }, | ||||||
| "then": { | ||||||
| "properties": { | ||||||
| "version": { "$ref": "#/definitions/semver-2.0.0-version" }, | ||||||
| "lessThan": { "$ref": "#/definitions/semver-2.0.0-version" }, | ||||||
| "lessThanOrEqual": { "$ref": "#/definitions/semver-2.0.0-version" }, | ||||||
| "greaterThan": { "$ref": "#/definitions/semver-2.0.0-version" }, | ||||||
| "greaterThanOrEqual": { "$ref": "#/definitions/semver-2.0.0-version" } | ||||||
| } | ||||||
| }, | ||||||
| "properties": { | ||||||
| "version": { | ||||||
| "description": "The single version being described, or the version at the start of the range. By convention, typically 0 denotes the earliest possible version.", | ||||||
|
|
@@ -336,6 +361,14 @@ | |||||
| "description": "The inclusive upper limit of the range. This is the greatest version contained in the range. Only one of lessThan and lessThanOrEqual should be specified. For example, `{version: 1.0, lessThanOrEqual: 1.3}` covers all versions from 1.0 up to and including 1.3.", | ||||||
| "$ref": "#/definitions/version" | ||||||
| }, | ||||||
| "greaterThan": { | ||||||
| "description": "The exclusive lower limit of the range. This is the lowest version NOT in the range. Used only for ranges which extend to positive infinity.", | ||||||
| "$ref": "#/definitions/version" | ||||||
| }, | ||||||
| "greaterThanOrEqual": { | ||||||
| "description": "The inclusive lower limit of the range. This is the lowest version in the range. Used only for ranges which extend to positive infinity.", | ||||||
| "$ref": "#/definitions/version" | ||||||
| }, | ||||||
| "changes": { | ||||||
| "type": "array", | ||||||
| "description": "A list of status changes that take place during the range. The array should be sorted in increasing order by the 'at' field, according to the versionType, but clients must re-sort the list themselves rather than assume it is sorted.", | ||||||
|
|
@@ -349,7 +382,9 @@ | |||||
| "properties": { | ||||||
| "at": { | ||||||
| "description": "The version at which a status change occurs.", | ||||||
| "oneOf": [ | ||||||
| {"$ref": "#/definitions/version"} | ||||||
| ] | ||||||
| }, | ||||||
| "status": { | ||||||
| "description": "The new status in the range starting at the given version.", | ||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| { | ||
| "dataType": "CVE_RECORD", | ||
| "dataVersion": "5.1", | ||
| "cveMetadata": { | ||
| "cveId": "CVE-1900-1234", | ||
| "assignerOrgId": "b3476cb9-2e3d-41a6-98d0-0f47421a65b6", | ||
| "state": "PUBLISHED" | ||
| }, | ||
| "containers": { | ||
| "cna": { | ||
| "providerMetadata": { | ||
| "orgId": "b3476cb9-2e3d-41a6-98d0-0f47421a65b6" | ||
| }, | ||
| "problemTypes": [ | ||
| { | ||
| "descriptions": [ | ||
| { | ||
| "lang": "en", | ||
| "description": "CWE-78 OS Command Injection" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "affected": [ | ||
| { | ||
| "vendor": "Example.org", | ||
| "product": "Example Enterprise", | ||
| "versions": [ | ||
| { | ||
| "versionType": "semver-2.0.0", | ||
| "status": "affected", | ||
| "version": "1.2.*" | ||
| } | ||
| ], | ||
| "defaultStatus": "unaffected" | ||
| } | ||
| ], | ||
| "descriptions": [ | ||
| { | ||
| "lang": "en", | ||
| "value": "OS Command Injection vulnerability parseFilename function of example.php in the Web Management Interface of Example.org Example Enterprise on Windows, MacOS and XT-4500 allows remote unauthenticated attackers to escalate privileges.\n\nThis issue affects:\n * 1.0 versions before 1.0.6\n * 2.1 versions from 2.16 until 2.1.9." | ||
| } | ||
| ], | ||
| "references": [ | ||
| { | ||
| "url": "https://example.org/ESA-22-11-CVE-1900-1234" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| { | ||
| "dataType": "CVE_RECORD", | ||
| "dataVersion": "5.1", | ||
| "cveMetadata": { | ||
| "cveId": "CVE-1900-1234", | ||
| "assignerOrgId": "b3476cb9-2e3d-41a6-98d0-0f47421a65b6", | ||
| "state": "PUBLISHED" | ||
| }, | ||
| "containers": { | ||
| "cna": { | ||
| "providerMetadata": { | ||
| "orgId": "b3476cb9-2e3d-41a6-98d0-0f47421a65b6" | ||
| }, | ||
| "problemTypes": [ | ||
| { | ||
| "descriptions": [ | ||
| { | ||
| "lang": "en", | ||
| "description": "CWE-78 OS Command Injection" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "affected": [ | ||
| { | ||
| "vendor": "Example.org", | ||
| "product": "Example Enterprise", | ||
| "versions": [ | ||
| { | ||
| "versionType": "semver-2.0.0", | ||
| "status": "affected", | ||
| "version": "1.2.3", | ||
| "greaterThan": "1.2.4", | ||
| "greaterThanEqualTo": "1.2.4" | ||
| } | ||
| ], | ||
| "defaultStatus": "unaffected" | ||
| } | ||
| ], | ||
| "descriptions": [ | ||
| { | ||
| "lang": "en", | ||
| "value": "OS Command Injection vulnerability parseFilename function of example.php in the Web Management Interface of Example.org Example Enterprise on Windows, MacOS and XT-4500 allows remote unauthenticated attackers to escalate privileges.\n\nThis issue affects:\n * 1.0 versions before 1.0.6\n * 2.1 versions from 2.16 until 2.1.9." | ||
| } | ||
| ], | ||
| "references": [ | ||
| { | ||
| "url": "https://example.org/ESA-22-11-CVE-1900-1234" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since a PATCH is backwards compatible.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I may be incorrect, but I don't see this definition referenced anywhere. Is this intentional?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I believe we've resolved this point in QWG discussions since this comment was posted. "2.0" is not a valid SemVer version, and it would be awkward to version our SemVer version type with a version which is not itself a valid SemVer version.