-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #25 from puerco/minimum-reqs-update
Update spec to final VEX-WG document
- Loading branch information
Showing
1 changed file
with
34 additions
and
24 deletions.
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,11 @@ | ||
| # OpenVEX Specification v0.0.0 | ||
| # OpenVEX Specification v0.0.2 | ||
|
|
||
| ## Overview | ||
|
|
||
| OpenVEX is an implementation of Vulnerability Exploitability eXchange (VEX) | ||
| designed to be lightweight, and embeddable while meeting all requirements of | ||
| a valid VEX implementation as defined in the [Minimum Requirements for Vulnerability | ||
| Exploitability eXchange (VEX)](http://example.com) document published on XXX | ||
| by the VEX working group coordinated by the [Cybersecurity & Infrastructure | ||
| Security 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). | ||
|
|
||
|
|
||
| ## The VEX Statement | ||
|
|
@@ -132,7 +130,7 @@ Here is a sample of a minimal OpenVEX document: | |
| "author": "Wolfi J Inkinson", | ||
| "role": "Document Creator", | ||
| "timestamp": "2023-01-08T18:02:03.647787998-06:00", | ||
| "version": "1", | ||
| "version": 1, | ||
| "statements": [ | ||
| { | ||
| "vulnerability": "CVE-2023-12345", | ||
|
|
@@ -153,14 +151,14 @@ The following table lists the fields in the document struct | |
|
|
||
| | Field | Required | Description | | ||
| | --- | --- | --- | | ||
| | @context | ✓ | The URL linking to the OpenVEX context definition. Fixed to `https://openvex.dev/ns`. | | ||
| | @id | ✓ | The IRI identifying the VEX document. | | ||
| | author | ✓ | Author is the identifier for the author of the VEX statement. Ideally, a common name, may be a URI. `author` can be an individual or organization. The author identity SHOULD be cryptographically associated with the signature of the VEX statement or document or transport. | | ||
| | role | ✓ | role describes the role of the document author. | | ||
| | @context | ✓ | The URL linking to the OpenVEX context definition. Fixed to `https://openvex.dev/ns` before 1.0 is released. | | ||
| | @id | ✓ | The IRI identifying the VEX document. | | ||
| | author | ✓ | Author is the identifier for the author of the VEX statement. This field should ideally be a machine readable identifier such as an IRI, email address, etc. `author` MUST be an individual or organization. `author` identity SHOULD be cryptographically associated with the signature of the VEX document or other exchange mechanism. | | ||
| | role | ✕ | role describes the role of the document author. | | ||
| | timestamp | ✓ | Timestamp defines the time at which the document was issued. | | ||
| | version | ✓ | Version is the document version. It must be incremented when any content within the VEX document changes, including any VEX statements included within the VEX document. | | ||
| | tooling | ✕ | Tooling expresses how the VEX document and contained VEX statements were generated. It's optional. It may specify tools or automated processes used in the document or statement generation. | | ||
| | supplier | ✕ | An optional field specifying who is providing the VEX document. | | ||
| | last_updated | ✕ | Date of last modification to the document. | | ||
| | version | ✓ | Version is the document version. It must be incremented when any content within the VEX document changes, including any VEX statements included within the VEX document. | | ||
| | tooling | ✕ | Tooling expresses how the VEX document and contained VEX statements were generated. It may specify tools or automated processes used in the document or statement generation. | | ||
|
|
||
| ### Statement | ||
|
|
||
|
|
@@ -190,12 +188,16 @@ The following table lists the fields of the OpenVEX statement struct. | |
|
|
||
| | Field | Required | Description | | ||
| | --- | --- | --- | | ||
| | 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 URIs or URLs.<br>vulnerability MAY be arbitrary and MAY be created by the VEX statement `author`. | ||
| | @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 | | ||
| | 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. | | ||
| | status | ✓ | A VEX statement MUST provide the status of the vulnerabilities with respect to the products and components listed in the statement. `status` MUST be one of the labels defined by VEX (see [Status](#Status-Labels)), some of which have further options and requirements. | | ||
| | status | ✓ | A VEX statement MUST provide the status of the vulnerabilities with respect to the products and components listed in the statement. `status` MUST be one of the labels defined by VEX (see [Status](#Status-Labels)), some of which have further options and requirements. | | ||
| | supplier | ✕ | Supplier of the product or subcomponent. | | ||
| | status_notes | ✕ | A statement MAY convey information about how `status` was determined and MAY reference other VEX information. | | ||
| | justification | ✓/✕ | For statements conveying a `not_affected` status, a VEX statement MUST include either a status justification or an impact_statement informing why the product is not affected by the vulnerability. Justifications are fixed labels defined by VEX. See [Status Justifications](#Status-Justifications) below for valid values. | | ||
| | impact_statement | ✓/✕ | For statements conveying a `not_affected` status, a VEX statement MUST include either a status justification or an impact_statement informing why the product is not affected by the vulnerability. An impact statement is a free form text containing a description of why the vulnerability cannot be exploited. This field is not intended to be machine readable so its use is highly discouraged for automated systems. | | ||
|
|
@@ -253,7 +255,7 @@ why the vulnerability is not affected by reading the justification label | |
| associated with the VEX statement. These labels are predefined and machine-readable | ||
| to enable automated uses such as deployment policies. The current label catalog | ||
| was defined by the VEX Working Group and published in the | ||
| [Status Justifications](status-doc) document on July 2022. | ||
| [Status Justifications] document on July 2022. | ||
|
|
||
|
|
||
| | Label | Description | | ||
|
|
@@ -333,7 +335,7 @@ example, the sole statement has its timestamp data derived from the document: | |
| "author": "Wolfi J Inkinson", | ||
| "role": "Document Creator", | ||
| "timestamp": "2023-01-08T18:02:03-06:00", | ||
| "version": "1", | ||
| "version": 1, | ||
| "statements": [ | ||
| { | ||
| "vulnerability": "CVE-2023-12345", | ||
|
|
@@ -358,7 +360,7 @@ to avoid duplication: | |
| "author": "Wolfi J Inkinson", | ||
| "role": "Document Creator", | ||
| "timestamp": "2023-01-09T09:08:42-06:00", | ||
| "version": "1", | ||
| "version": 1, | ||
| "statements": [ | ||
| { | ||
| "timestamp": "2023-01-08T18:02:03-06:00", | ||
|
|
@@ -448,7 +450,7 @@ the project could issue an OpenVEX document as follows: | |
| "author": "Spring Builds <[email protected]>", | ||
| "role": "Project Release Bot", | ||
| "timestamp": "2023-01-16T19:07:16.853479631-06:00", | ||
| "version": "1", | ||
| "version": 1, | ||
| "statements": [ | ||
| { | ||
| "vulnerability": "CVE-2021-44228", | ||
|
|
@@ -470,12 +472,20 @@ alert and dashboards could present users with the official guidance from the pro | |
|
|
||
| | Date | Revision | | ||
| | --- | --- | | ||
| | 2023-01-08 | First Draft of the OpenVEX Specification | | ||
| | 2023-01-16 | Updated specx draft to reflect initial review | | ||
| | 2023-01-16 | Added JSON-LD and namespace section | | ||
| | 2023-01-16 | Add example section | | ||
| | 2023-07-18 | Bumped version of the spec to v0.0.2 after update to meet the VEX-WG doc. | | ||
| | 2023-06-01 | Removed supplier from the document level (following VEX-WG doc). | | ||
| | 2023-05-29 | Specification updated to reflect the published [Minimum Requirements for VEX] document. | | ||
| | 2023-01-08 | First Draft of the OpenVEX Specification. | | ||
| | 2023-01-16 | Updated specx draft to reflect initial review. | | ||
| | 2023-01-16 | Added JSON-LD and namespace section. | | ||
| | 2023-01-16 | Add example section. | | ||
| | 2023-05-29 | Added missing fields to match the VEX-WG's [Minimum Requirements for VEX] document. | | ||
|
|
||
|
|
||
| ## Sources | ||
|
|
||
| status-doc: https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf | ||
| * Vulnerability Exploitability eXchange (VEX) - [Status Justifications] | ||
| * [Minimum Requirements for VEX] document, published by CISA. | ||
|
|
||
| [Status Justifications]: https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf | ||
| [Minimum Requirements for VEX]: https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf | ||