OpenVEX Specification v0.2.0 #35
Merged
Conversation
This file contains 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 commit modifies the openvex spec to reflect the changes in the OpenVEX Enhancement Proposal 0014: Expansion of the VEX Product Field. Signed-off-by: Adolfo García Veytia (Puerco) <puerco@chainguard.dev>
This commit updates the SPEC to incorporate the changes approved in the OpenVEX Enhancement Proposal 0015: Expansion of the Vulnerability Field. Signed-off-by: Adolfo García Veytia (Puerco) <puerco@chainguard.dev>
This commit adds reference tables for the hash names and identifier labels to be used in the product data structure. Signed-off-by: Adolfo García Veytia (Puerco) <puerco@chainguard.dev>
This commit bumps the spec to v0.2.0. Signed-off-by: Adolfo García Veytia (Puerco) <puerco@chainguard.dev>
|
PR is open implementing these changes in the go-vex libraries: openvex/go-vex#45 |
lumjjb
reviewed
Aug 17, 2023
SecurityCRob
approved these changes
Aug 21, 2023
|
Thanks everyone! |
sudo-bmitch
reviewed
Aug 22, 2023
| @@ -190,12 +195,10 @@ The following table lists the fields of the OpenVEX statement struct. | |||
| | --- | --- | --- | | |||
| | @id | ✕ | Optional IRI identifying the statement to make it externally referenceable. | | |||
| | version | ✕ | Optional integer representing the statement's version number. Defaults to zero, required when incremented. | | |||
| | vulnerability | ✓ | Vulnerability SHOULD use existing and well known identifiers. For example: [CVE](https://cve.mitre.org/), [OSV](https://osv.dev/), [GHSA](https://github.com/advisories), a supplier's vulnerability tracking system such as [RHSA](https://access.redhat.com/security/security-updates/#/) or a propietary system. It is expected that vulnerability identification systems are external to and maintained separately from VEX.<br>`vulnerability` MAY be an IRI and MAY be arbitrary, created by the VEX document `author`. | | |||
| | vuln_description | ✕ | Optional free-form text describing the vulnerability | | |||
| | vulnerability | ✓ | A struct identifying the vulnerability. See the [Vulnerability Data Structure] section below for the complete data structure reference. | | |||
There was a problem hiding this comment.
Suggested change
| | vulnerability | ✓ | A struct identifying the vulnerability. See the [Vulnerability Data Structure] section below for the complete data structure reference. | | |
| | vulnerability | ✓ | A struct identifying the vulnerability. See the [Vulnerability Data Structure](#Vulnerability Data Structure) section below for the complete data structure reference. | |
|
|
||
| The product field should list as many software identifiers as possible to | ||
| help VEX processors when matching the product. The use of | ||
| [Package URLs](https://github.com/package-url/purl-spec) (purls) is recommended. |
There was a problem hiding this comment.
Recommend moving the URL to the bottom and making it a named link.
| | timestamp | ✕ | Timestamp is the time at which the information expressed in the Statement was known to be true. Cascades down from the document, see [Inheritance](#Inheritance). | | ||
| | last_updated | ✕ | Timestamp when the statement was last updated. | | ||
| | products | ✕ | Product identifiers that the statement applies to. Any software identifier can be used and SHOULD be traceable to a described item in an SBOM. The use of [Package URLs](https://github.com/package-url/purl-spec) (purls) is recommended. While a product identifier is required to have a complete statement, this field is optional as it can cascade down from the encapsulating document, see [Inheritance](#Inheritance). | | ||
| | subcomponents | ✕ | Identifiers of components where the vulnerability originates. While the statement asserts about the impact on the software product, listing `subcomponents` let scanners find identifiers to match their findings. | | ||
| | products | ✕ | List of product structs that the statement applies to. See the [Product Data Structure] section below for the full description. While a product is required to have a complete statement, this field is optional as it can cascade down from the encapsulating document, see [Inheritance](#Inheritance). | |
There was a problem hiding this comment.
Suggested change
| | products | ✕ | List of product structs that the statement applies to. See the [Product Data Structure] section below for the full description. While a product is required to have a complete statement, this field is optional as it can cascade down from the encapsulating document, see [Inheritance](#Inheritance). | | |
| | products | ✕ | List of product structs that the statement applies to. See the [Product Data Structure](#Product Data Structure) section below for the full description. While a product is required to have a complete statement, this field is optional as it can cascade down from the encapsulating document, see [Inheritance](#Inheritance). | |
| Agency](https://www.cisa.gov/) (CISA). | ||
| a valid VEX implementation as defined in the [Minimum Requirements for VEX] | ||
| document published on April 2023 as defined by the VEX Working Group coordinated | ||
| by the [Cybersecurity & Infrastructure Security Agency](https://www.cisa.gov/) (CISA). |
There was a problem hiding this comment.
Recommend moving the URL to the bottom and making this a named link.
| | --- | --- | --- | | ||
| | @id | ✕ | Optional [IRI](#IRI) identifying the component to make it externally referenceable. | | ||
| | identifiers | ✕ | A map of software identifiers where the key is the type and the value the identifier. OpenVEX favors the use of purl but others are recognized (see the Identifiers Labels table below) | | ||
| | hashes | ✕ | Map of cryptographic hashes of the component. The key is the algorithm name based on the [Hash Function Textual Names](https://www.iana.org/assignments/named-information/named-information.xhtml) from IANA. See [Hash Names Table] for the full supported list. | |
There was a problem hiding this comment.
Also recommend moving the URL to the bottom and making it a named link.
Suggested change
| | hashes | ✕ | Map of cryptographic hashes of the component. The key is the algorithm name based on the [Hash Function Textual Names](https://www.iana.org/assignments/named-information/named-information.xhtml) from IANA. See [Hash Names Table] for the full supported list. | | |
| | hashes | ✕ | Map of cryptographic hashes of the component. The key is the algorithm name based on the [Hash Function Textual Names](https://www.iana.org/assignments/named-information/named-information.xhtml) from IANA. See [Hash Names Table](#Hash Names Table) for the full supported list. | |
|
|
||
| The following list of hash names can be used as keys in the `hashes` field of the | ||
| product field. These labels follow and extend the | ||
| [Hash Function Textual Names](https://www.iana.org/assignments/named-information/named-information.xhtml) |
There was a problem hiding this comment.
Recommend moving the URL to the bottom and making this a named link.
Comment on lines
+626
to
+628
| | purl | [Package URL](https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst) | | ||
| | cpe22 | [Common Platform Enumeration v2.2](https://cpe.mitre.org/files/cpe-specification_2.2.pdf) | | ||
| | cpe23 | [Common Platform Enumeration v2.3](https://csrc.nist.gov/pubs/ir/7695/final) | |
There was a problem hiding this comment.
Recommend moving all links to the bottom.
Comment on lines
+635
to
+636
| | 2023-07-18 | Updated spec to reflect changes in [OPEV-0015: Expansion of the Vulnerability Field](https://github.com/openvex/community/blob/main/enhancements/opev-0015.md) | | ||
| | 2023-07-18 | Updated spec to reflect changes in [OPEV-0014: Expansion of the VEX Product Field](https://github.com/openvex/community/blob/main/enhancements/opev-0014.md) | |
There was a problem hiding this comment.
More links to consider moving.
|
Thanks for the thorough review @sudo-bmitch we're more than happy to add those comments to the review, do you want to open a PR? I can review it right away 🙏 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This PR updates the OpenVEX specification to v0.2.0, a breaking change that expands the product and vulnerability fields to make them more expressive and better suited for future expansion.
This PR incorporates the changes discussed and approved by the SIG as part of the following OpenVEX Enhancement Proposals:
/cc OpenVEX Maintainers: @lumjjb @wagoodman @luhring @rnjudge
/cc OpenVEX SIG OPEV Contributors: @sudo-bmitch @SecurityCRob
Signed-off-by: Adolfo García Veytia (Puerco) puerco@chainguard.dev