Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update spec to final VEX-WG document #25

Merged
merged 4 commits into from
Jul 18, 2023
Merged

Update spec to final VEX-WG document #25

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
de91c7a
Update spec to final VEX-WG document
puerco May 30, 2023
fd7a195
Update reusable links and add table of contents
puerco May 30, 2023
7d74dc9
Remove supplier from document
puerco Jun 1, 2023
4a0fbbd
Bump spec version to v0.0.2
puerco Jul 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 34 additions & 24 deletions OPENVEX-SPEC.md
View file
Open in desktop
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
puerco marked this conversation as resolved.
Show resolved Hide resolved
Agency](https://www.cisa.gov/) (CISA).


## The VEX Statement
Expand Down Expand Up @@ -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",
Expand All @@ -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

Expand Down Expand Up @@ -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. |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please clarify how this fulfills the requirement of https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf:

[supplier] MUST clearly indicate the [product_id] or [subcomponent_id] to which [supplier]
applies.

If I understand the description correctly, subcomponents and products might come from different suppliers...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, this is an issue we're tackling in an upcoming revision. Right now subcomponents cannot be easily tied back to products (and thus to their suppliers).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one will be handled in the first revision to the spec coming up in August.

| 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. |
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand All @@ -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