├── ATTESTING.md ├── LICENSE ├── MAINTAINERS.md ├── OPENVEX-SPEC.md ├── README.md ├── context.json ├── governance ├── 0._CS_Contributor_License_Agreement.md ├── 1._Community_Specification_License-v1.md ├── 2._Scope.md ├── 3._Notices.md ├── 4._License.md ├── 5._Governance.md ├── 6._Contributing.md ├── 7._CS_Template.md ├── 8._Code_of_Conduct.md └── Readme.md ├── ns └── v0.2.0 │ ├── README.md │ └── context.json └── openvex_json_schema.json /ATTESTING.md: -------------------------------------------------------------------------------- 1 | # Attesting OpenVEX Documents 2 | 3 | ## What is an Attestation? 4 | 5 | An attestation is an assertion made about a piece of software. There are many 6 | kinds of attestations in use today such as provenance attestation defined by 7 | SLSA or those asserting to the results of vulnerability scans. 8 | 9 | OpenVEX was conceived to be able to be embedded in 10 | [in-toto attestations](https://github.com/in-toto/attestation). The format defined 11 | by the in-toto project is composed of a number of subjects (the pieces of 12 | software the attestation is talking about) and a predicate that defines what is 13 | being said about the subjects. 14 | 15 | [DIAGRAM] 16 | 17 | Here is an example of an empty attestation 18 | 19 | ```json 20 | { 21 | "_type": "https://in-toto.io/Statement/v0.1", 22 | "predicateType": "", 23 | "subject": [], 24 | "predicate": {} 25 | } 26 | ``` 27 | 28 | ## Embedding and Inheritance 29 | 30 | OpenVEX documents are designed to be embeddable in other formats. This is not a 31 | unique feature of OpenVEX: the VEX minimum elements define the notion of an 32 | "encapsulating format", a document that contains the VEX document and its 33 | statements. VEX also defines an inheritance model where the required data to 34 | complete VEX metadata cascades down from the encapsulating format to the 35 | document, to the statement. This allows VEX to leverage the capabilities of the 36 | encapsulating formats while defining a compatibility flow among implementations. 37 | 38 | OpenVEX documents do not require an encapsulating document. Nevertheless, they 39 | were designed to be embeddable and they can be used as in-toto predicates. This 40 | lets software authors assert VEX data about a piece of software. 41 | 42 | When embedding OpenVEX in attestations, the only field of data that "cascades" 43 | is the VEX statement's `product`, or `subject` in in-toto lingo. 44 | 45 | ### The VEX Product and the Attestation's Subject 46 | 47 | In VEX, all statements apply to one or more products. A "product" in VEX is a 48 | loose term meaning any piece of software that can be listed in an SBOM. For a 49 | statement to be valid, it needs to have one or more statements. Here's an example 50 | of a VEX statement: 51 | 52 | ```json 53 | { 54 | "vulnerability": { 55 | "name": "CVE-2014-123456" 56 | }, 57 | "products": [ 58 | {"@id": "pkg:apk/distro/git@2.39.0-r1?arch=armv7"}, 59 | {"@id": "pkg:apk/distro/git@2.39.0-r1?arch=x86_64"} 60 | ], 61 | "status": "fixed" 62 | } 63 | ``` 64 | 65 | In the previous example, the statement specifies two packages of git (for armv7 and x86_64). 66 | 67 | Attestations define their subjects natively. Following the VEX inheritance model 68 | the subjects in an attestation containing a VEX document will cascade down and 69 | become the VEX "product" of any statements that don't specify a subject. 70 | 71 | Here is an example of an attestation with the same packages as subjects. Note that 72 | the predicate type is set to the OpenVEX context (the predicate contents have been 73 | removed for clarity): 74 | 75 | ```json 76 | { 77 | "_type": "https://in-toto.io/Statement/v0.1", 78 | "predicateType": "https://openvex.dev/ns", 79 | "subject": [ 80 | { 81 | "name": "pkg:apk/distro/git@2.39.0-r1?arch=armv7", 82 | "digest": { 83 | "sha256": "74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99" 84 | }, 85 | }, 86 | { 87 | "name": "pkg:apk/distro/git@2.39.0-r1?arch=x86_64", 88 | "digest": { 89 | "sha256": "6bd98fe56e4d91439343d123d98522005874957ea1cb6075e75544d7753bd8d7" 90 | }, 91 | } 92 | ], 93 | "predicate": { 94 | // ... 95 | } 96 | } 97 | 98 | ``` 99 | 100 | When embedding OpenVEX inside an attestation, the subjects SHOULD move from the 101 | VEX statement product to the attestation subjects. This makes the attestation usable 102 | in systems that already know how to process them while still keeping the VEX metadata 103 | valid via the inheritance model. This is the complete attestation with the 104 | embedded OpenVEX document: 105 | 106 | ```json 107 | { 108 | "_type": "https://in-toto.io/Statement/v0.1", 109 | "predicateType": "text/vex", 110 | "subject": [ 111 | { 112 | "name": "pkg:apk/distro/git@2.39.0-r1?arch=armv7", 113 | "digest": { 114 | "sha256": "74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99" 115 | }, 116 | }, 117 | { 118 | "name": "pkg:apk/distro/git@2.39.0-r1?arch=x86_64", 119 | "digest": { 120 | "sha256": "6bd98fe56e4d91439343d123d98522005874957ea1cb6075e75544d7753bd8d7" 121 | }, 122 | } 123 | ], 124 | "predicate": { 125 | "@context": "https://openvex.dev/ns", 126 | "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57", 127 | "author": "Wolfi J Inkinson", 128 | "role": "Security Researcher", 129 | "timestamp": "2023-01-08T18:02:03.647787998-06:00", 130 | "version": "1", 131 | "statements": [ 132 | { 133 | "vulnerability": {"name": "CVE-2023-12345"}, 134 | "status": "fixed" 135 | } 136 | ] 137 | } 138 | } 139 | ``` 140 | 141 | Note in the finished example how the products in the statement have moved 142 | toward the attestation's subject section. This example assumes that the 143 | subjects' digests can be computed externally. 144 | 145 | The product entries MAY remain in the VEX statement. In that case, they MUST 146 | be repeated and matched in the attestation subject section. An attestation SHOULD 147 | remain complete when composed with an OpenVEX predicate. 148 | 149 | ## Handling Product/Subject Granularity 150 | 151 | An attestation's predicate is a singleton. It is a set of exactly one predicate 152 | that applies to any number of subjects. VEX, on the other hand, defines a document 153 | model that can host any number of statements, possibly with different subjects: 154 | 155 | ```json 156 | "statements": [ 157 | { 158 | "vulnerability": "CVE-2014-123456", 159 | "products": [ 160 | "pkg:apk/distro/git@2.39.0-r1?arch=armv7" 161 | ], 162 | "status": "fixed" 163 | }, 164 | { 165 | "vulnerability": { 166 | "name": "CVE-2014-123456" 167 | }, 168 | "products": [ 169 | {"@id": "pkg:apk/distro/git@2.39.0-r1?arch=x86_64"} 170 | ], 171 | "status": "under_investigation" 172 | }, 173 | ] 174 | ``` 175 | 176 | The nature of the data models implies that an attestation can only refer to 177 | VEX statements that contain one or more of the `subject` entries in their product 178 | section. To attest the example above, an attestation can use any of the following 179 | subject structs: 180 | 181 | ```json 182 | "subject": { 183 | "pkg:apk/distro/git@2.39.0-r1?arch=armv7" 184 | } 185 | ``` 186 | 187 | ```json 188 | "subject": { 189 | "pkg:apk/distro/git@2.39.0-r1?arch=x86_64" 190 | } 191 | ``` 192 | 193 | ```json 194 | subject: { 195 | "pkg:apk/distro/git@2.39.0-r1?arch=armv7", 196 | "pkg:apk/distro/git@2.39.0-r1?arch=x86_64" 197 | } 198 | ``` 199 | 200 | When an identifier is listed in the subject section, it signals any processor 201 | to look for data about it in the predicate. When looking at the VEX statements, 202 | the following rules define how statements are to be considered: 203 | 204 | 1. Any VEX statements that don't define products are considered to be attested. 205 | 2. Any VEX statements listing products but not having the attestation's subjects 206 | in the product list are to be ignored. 207 | 3. Any VEX statements including one of the attestation's subjects in its `product` 208 | section are to be considered only for that identifier and others that match. 209 | 4. If a VEX statement lists one of the attestation's subjects in the product list 210 | but not another, it MUST be considered for the former but not for the latter. 211 | 212 | ## Digital Signatures 213 | 214 | Attestations are meant to be digitally signed. While the signature envelope is 215 | not a part of the attestation or OpenVEX specifications, it should be noted that 216 | VEX recommends that the document `author` _SHOULD be cryptographically associated 217 | with the signature of the VEX document_. Signing an attestation SHOULD follow this 218 | convention and sign the attestation when possible using the same identity 219 | expressed in the author field. Since statements can originate from third parties 220 | exploring the same product, this may not be possible in all circumstances. 221 | 222 | An identity signing an attestation containing VEX statements from third parties 223 | implies that the signer trusts those statements and has decided to include them 224 | in the VEX impact history. 225 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | # Maintainers 2 | 3 | This file lists all current maintainers of the `spec` repository. 4 | 5 | - Dan Luhring (@luhring), Chainguard 6 | - Adolfo García Veytia (@puerco), Chainguard 7 | - Brandon Lum (@lumjjb), Google 8 | - Alex Goodman (@wagoodman), Anchore 9 | - Rose Judge (@rnjudge), VMWare 10 | 11 | New maintainers can be added via the process outlined in the OpenVEX community's [governance](https://github.com/openvex/community/blob/main/GOVERNANCE.md) document. 12 | -------------------------------------------------------------------------------- /OPENVEX-SPEC.md: -------------------------------------------------------------------------------- 1 | # OpenVEX Specification v0.2.0 2 | 3 | ## Overview 4 | 5 | OpenVEX is an implementation of Vulnerability Exploitability eXchange (VEX) 6 | designed to be lightweight, and embeddable while meeting all requirements of 7 | a valid VEX implementation as defined in the [Minimum Requirements for VEX] 8 | document published on April 2023 as defined by the VEX Working Group coordinated 9 | by the [Cybersecurity & Infrastructure Security Agency][CISA] (CISA). 10 | 11 | ## The VEX Statement 12 | 13 | VEX centers on the notion of a _statement_. In short, a statement can be defined 14 | as an assertion intersecting product, a vulnerability, and an impact status: 15 | 16 | ```text 17 | statement = product(s) + vulnerability + status 18 | │ │ │ 19 | └ The software product └ Typically a CVE related └ One of the impact 20 | we are talking about to one of the product's statuses as identified 21 | components by the VEX working group. 22 | ``` 23 | 24 | The `product` is a piece of software that can be correlated to an entry in an 25 | SBOM (see [Product](#product) below). `vulnerability` is the ID of a security 26 | vulnerability as understood by scanners, which can be looked up in a vulnerability 27 | tracking system. `status` is one of the impact status labels defined by VEX 28 | (see [Status](#status)). 29 | 30 | Another key part of VEX is time. It matters _when_ statements are made. VEX is 31 | designed to be a sequence of statements, each overriding, but also enriching 32 | the previous ones with new information. Each statement has a timestamp 33 | associated with it, either explicitly in the markup or derived from containing 34 | structures (see [Inheritance Flow](#inheritance-flow)). 35 | 36 | ## VEX Documents 37 | 38 | A VEX document is a data structure grouping one or more VEX statements. 39 | Documents also have timestamps, which may cascade down to statements (see 40 | [Inheritance Flow](#inheritance-flow)). Documents can also be versioned. 41 | 42 | ### A Sample Scenario 43 | 44 | As an example, consider the following evolution of a hypothetical impact analysis: 45 | 46 | 1. A software author becomes aware of a new CVE related to their product. 47 | Immediately, the author starts to check if it affects them. 48 | 2. The investigation determines the product is affected. 49 | 3. To protect their users, the author mitigates the CVE impact via a patch or 50 | other method before the vulnerable component issues a patch. 51 | 52 | Without VEX data, users scanning the author's software will simply get 53 | a third party alert with no details on how the status is evolving. Most critically, 54 | when the product is patched (in #3), the alert becomes a false positive. 55 | 56 | To inform consumers downstream of the vulnerability evolution, the author can 57 | issue a VEX document (in #1) when the CVE is published to let their users 58 | know it is under investigation. In #2, when the product is known to be affected, 59 | the author can ship a new VEX document, stating the product is affected and 60 | possibly some additional advice, like temporary mitigation instructions. Finally 61 | when the product is patched, its SBOM can be complemented with a new VEX document 62 | informing it is no longer affected by the CVE. Scanners could consume this 63 | document and stop alerting about the CVE as it no longer impacts the product. 64 | 65 | ## OpenVEX Specification 66 | 67 | ### Definitions 68 | 69 | The following definitions are used throughout this document. 70 | 71 | The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 72 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as 73 | described in [RFC2119]. 74 | 75 | #### Document 76 | 77 | A data structure that groups together one or more VEX statements. A document 78 | MUST define a timestamp to express when it was issued. 79 | 80 | #### Encapsulating Document 81 | 82 | While OpenVEX defines a self-sustaining document format, VEX data can often be 83 | found embedded or incorporated in other formats, examples of this include 84 | in-toto attestations or CSAF and CycloneDX documents. "Encapsulating document" 85 | refers to these formats that can contain VEX data. 86 | 87 | #### Product 88 | 89 | A logical unit representing a piece of software. The concept is intentionally 90 | broad to allow for a wide variety of use cases but generally speaking, anything 91 | that can be described in a Software Bill of Materials (SBOM) can be thought of 92 | as a product. 93 | 94 | #### Status 95 | 96 | The known relationship a vulnerability has to a software product. The status 97 | expresses if the product is impacted by the vulnerability or not, if the authors 98 | are investigating it, or if it has already been fixed. 99 | 100 | #### Vulnerability 101 | 102 | A cataloged defect in a software product. Documents SHOULD use global, well-known 103 | identifying schemas. For internal identifying schemes, the only requirement 104 | for a vulnerability to be listed in a VEX document is that it needs to have an ID 105 | string to address it. Public identifiers (such as CVE IDs) are the most 106 | common case, but private internal identifiers can be used if they are 107 | understood by all participants of the supply chain where the VEX metadata is 108 | expected to flow. 109 | 110 | #### Subcomponent 111 | 112 | Any components possibly included in the product where the vulnerability originates. 113 | The subcomponents SHOULD also list software identifiers and they SHOULD also be 114 | listed in the product SBOM. `subcomponents` will most often be one or more of the 115 | product's dependencies. 116 | 117 | ### Document 118 | 119 | A VEX document consists of two parts: The document metadata and a collection 120 | of statements. Some fields in the document metadata are required. 121 | 122 | OpenVEX documents are serialized in json-ld structs. File encoding MUST be UTF8. 123 | 124 | Here is a sample of a minimal OpenVEX document: 125 | 126 | ```json 127 | { 128 | "@context": "https://openvex.dev/ns/v0.2.0", 129 | "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57", 130 | "author": "Wolfi J Inkinson", 131 | "role": "Document Creator", 132 | "timestamp": "2023-01-08T18:02:03.647787998-06:00", 133 | "version": 1, 134 | "statements": [ 135 | { 136 | "vulnerability": { 137 | "name": "CVE-2023-12345" 138 | }, 139 | "products": [ 140 | {"@id": "pkg:apk/wolfi/git@2.39.0-r1?arch=armv7"}, 141 | {"@id": "pkg:apk/wolfi/git@2.39.0-r1?arch=x86_64"} 142 | ], 143 | "status": "fixed" 144 | } 145 | ] 146 | } 147 | 148 | ``` 149 | 150 | #### Document Struct Fields 151 | 152 | The following table lists the fields in the document struct 153 | 154 | | Field | Required | Description | 155 | | --- | --- | --- | 156 | | @context | ✓ | The URL linking to the OpenVEX context definition. The URL is structured as https://openvex.dev/ns/v[version], where [version] represents the specific version number, such as v0.2.0. If the version is omitted, it defaults to v0.0.1. | 157 | | @id | ✓ | The IRI identifying the VEX document. | 158 | | 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. | 159 | | role | ✕ | role describes the role of the document author. | 160 | | timestamp | ✓ | Timestamp defines the time at which the document was issued. | 161 | | last_updated | ✕ | Date of last modification to the document. | 162 | | 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. | 163 | | 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. | 164 | | statements | ✓ | The list of statements to contain within the document. | 165 | 166 | ### Statement 167 | 168 | A statement is an assertion made by the document's author about the impact 169 | a vulnerability has on one or more software "products". The statement has 170 | three key components that are valid at a point in time: `status`, a `vulnerability`, 171 | and the `product` to which these apply (see diagram above). 172 | 173 | A statement in an OpenVEX document looks like the following snippet: 174 | 175 | ```json 176 | "statements": [ 177 | { 178 | "vulnerability": { 179 | "name": "CVE-2023-12345" 180 | }, 181 | "products": [ 182 | {"@id": "pkg:apk/wolfi/git@2.39.0-r1?arch=armv7"}, 183 | {"@id": "pkg:apk/wolfi/git@2.39.0-r1?arch=x86_64"} 184 | ], 185 | "status": "fixed" 186 | } 187 | ] 188 | ``` 189 | 190 | #### Statement Fields 191 | 192 | The following table lists the fields of the OpenVEX statement struct. 193 | 194 | | Field | Required | Description | 195 | | --- | --- | --- | 196 | | @id | ✕ | Optional IRI identifying the statement to make it externally referenceable. | 197 | | version | ✕ | Optional integer representing the statement's version number. Defaults to zero, required when incremented. | 198 | | vulnerability | ✓ | A struct identifying the vulnerability. See the [Vulnerability Data Structure](#vulnerability-data-structure) section below for the complete data structure reference. | 199 | | 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-flow). | 200 | | last_updated | ✕ | Timestamp when the statement was last updated. | 201 | | 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-flow). | 202 | | 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. | 203 | | supplier | ✕ | Supplier of the product or subcomponent. | 204 | | status_notes | ✕ | A statement MAY convey information about how `status` was determined and MAY reference other VEX information. | 205 | | 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. | 206 | | 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. | 207 | | action_statement | ✕ | For a statement with "affected" status, a VEX statement MUST include a statement that SHOULD describe actions to remediate or mitigate the vulnerability. | 208 | | action_statement_timestamp | ✕ | The timestamp when the action statement was issued. | 209 | 210 | ##### Note on `justification` and `impact_statement` 211 | 212 | The Minimal Requirements for VEX document states that a `not_affected` statement 213 | MUST provide either a machine readable `justification` label or a free form 214 | text `impact_statement`. OpenVEX defines both required fields but highly discourages 215 | the use of the impact statement textual form as it breaks VEX automation and 216 | interoperability. 217 | 218 | The recommended pattern from OpenVEX is that issuers SHOULD use the machine 219 | readable justification labels and optionally enrich the statement with an 220 | `impact_statement`: 221 | 222 | ```json 223 | { 224 | "vulnerability": { 225 | "name": "CVE-2023-12345", 226 | } 227 | "products": [ 228 | {"@id": "pkg:apk/wolfi/product@1.23.0-r1?arch=armv7"} 229 | ], 230 | "status": "not_affected", 231 | "justification": "component_not_present", 232 | "impact_statement": "The vulnerable code was removed with a custom patch" 233 | } 234 | 235 | ``` 236 | 237 | ### Product Data Structure 238 | 239 | The subject of an VEX statement is the _product_, a piece of software that MUST be 240 | addressable via one of the mechanisms offered by OpenVEX. The spec provides an 241 | expressive `product` struct with fields to address the product using identifiers, 242 | hashes. Note that all mechanisms to address the product are optional but a 243 | valid statement MUST identify a product to be valid. 244 | 245 | The optional `@id` field takes an [IRI][IRI] to make the product referenceable 246 | inside the document and addressable externally. As Package URLs are valid IRIs, 247 | the `@id` can take a purl as a value. 248 | 249 | The product field should list as many software identifiers as possible to 250 | help VEX processors when matching the product. The use of 251 | [Package URLs][purl-spec] (purls) is recommended. 252 | 253 | The product and its subcomponents fields share an abstract type called 254 | `Component` that defines the fields that can be used to identify them. 255 | The only difference in `product` is the nested `subcomponents` field. 256 | 257 | #### Example Product Struct 258 | 259 | ```json 260 | { 261 | "@id": "pkg:apk/wolfi/product@1.23.0-r1?arch=armv7", 262 | "identifiers": { 263 | "purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.4", 264 | "cpe23": "cpe:2.3:a:apache:log4j:2.4:-:*:*:*:*:*:*", 265 | "cpe22": "cpe:/a:apache:log4j:2.4:-", 266 | }, 267 | "hashes": { 268 | "sha-256": "402fa523b96591d4450ace90e32d9f779fcfd938903e1c5bf9d3701860b8f856", 269 | "sha-512": "d2eb65b083923d90cf55111c598f81d3d9c66f4457dfd173f01a6b7306f3b222541be42a35fe47191a9ca00e017533e8c07ca192bd22954e125557c72d2a3178" 270 | }, 271 | "subcomponents": [] 272 | } 273 | 274 | ``` 275 | 276 | #### Component Fields 277 | 278 | These fields are shared by both the `product` and `subcomponent` structs: 279 | 280 | | Field | Required | Description | 281 | | --- | --- | --- | 282 | | @id | ✕ | Optional [IRI][IRI] identifying the component to make it externally referenceable. | 283 | | 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) | 284 | | hashes | ✕ | Map of cryptographic hashes of the component. The key is the algorithm name based on the [Hash Function Textual Names][iana-hash-function-names] from IANA. See [Hash Names Table](#appendix-a-hash-names-table) for the full supported list. | 285 | 286 | The `product` struct uses the above listed fields but has a list of subcomponents, 287 | each itself a `component` subclass: 288 | 289 | | Field | Required | Description | 290 | | --- | --- | --- | 291 | | subcomponents | ✕ | List of `component` structs describing the subcomponents subject of the VEX statement. | 292 | 293 | ### Vulnerability Data Structure 294 | 295 | The vulnerability field in an OpenVEX statement takes the value of a struct that 296 | has the capability to enumerate the vulnerability name and other aliases that may 297 | be used to track it in different databases and systems. 298 | 299 | As with the product field, the vulnerability has an optional "@id" field that 300 | takes an IRI to make the field referenceable in the document and linkable from 301 | other linked data resources. 302 | 303 | #### Example Vulnerability Struct 304 | 305 | ```json 306 | { 307 | "vulnerability": { 308 | "@id": "https://nvd.nist.gov/vuln/detail/CVE-2019-17571", 309 | "name": "CVE-2019-17571", 310 | "description": "The product deserializes untrusted data without sufficiently verifying that the resulting data will be valid.", 311 | "aliases": [ 312 | "GHSA-2qrg-x229-3v8q", 313 | "openSUSE-SU-2020:0051-1", 314 | "SNYK-RHEL7-LOG4J-1472071", 315 | "DSA-4686-1", 316 | "USN-4495", 317 | "DLA-2065-1", 318 | ], 319 | } 320 | } 321 | ``` 322 | 323 | #### Vulnerability Struct Fields 324 | 325 | The only required field in the vulnerability field is `name`, the main identifier 326 | of the vulnerability. Note that it is not an error to include the identifier used 327 | in the `name` field in the list of aliases. 328 | 329 | | Field | Required | Description | 330 | | --- | --- | --- | 331 | | @id | ✕ | An Internationalized Resource Identifier (IRI) identifying the struct. Used to reference and link the vulnerability data. | 332 | | name | ✓ | A string with the main identifier used to name the vulnerability. | 333 | | description | ✕ | Optional free form text describing the vulnerability. | 334 | | aliases | ✕ | A list of strings enumerating other names under which the vulnerability may be known. | 335 | 336 | ### Status Labels 337 | 338 | Status labels inform the impact of a vulnerability in the products listed 339 | in a statement. Security tooling such as vulnerability scanners consuming OpenVEX 340 | documents can key on the status labels to alter their behavior when a vulnerable 341 | component is detected. Security dashboards can provide users and auditors 342 | with contextual data about the evolution of the vulnerability impact. 343 | 344 | | Label | Description | 345 | | --- | --- | 346 | | `not_affected` | No remediation is required regarding this vulnerability. A `not_affected` status required the addition of a `justification` to the statement. | 347 | | `affected` | Actions are recommended to remediate or address this vulnerability. | 348 | | `fixed` | These product versions contain a fix for the vulnerability. | 349 | | `under_investigation` | It is not yet known whether these product versions are affected by the vulnerability. Updates should be provided in further VEX documents as knowledge evolves. | 350 | 351 | Any of these key data points are required to form a valid statement but 352 | they are not necessarily required to be defined in the statement's data struct. 353 | Consider the following scenarios: 354 | 355 | ### Status Justifications 356 | 357 | When assessing risk, consumers of a `not_affected` software product can know 358 | why the vulnerability is not affected by reading the justification label 359 | associated with the VEX statement. These labels are predefined and machine-readable 360 | to enable automated uses such as deployment policies. The current label catalog 361 | was defined by the VEX Working Group and published in the 362 | [Status Justifications] document on July 2022. 363 | 364 | | Label | Description | 365 | | --- | --- | 366 | | `component_not_present` | The product is not affected by the vulnerability because the component is not included. The status justification may be used to preemptively inform product users who are seeking to understand a vulnerability that is widespread, receiving a lot of attention, or is in similar products. | 367 | | `vulnerable_code_not_present` | The vulnerable component is included in artifact, but the vulnerable code is not present. Typically, this case occurs when source code is configured or built in a way that excluded the vulnerable code. | 368 | | `vulnerable_code_not_in_execute_path` | The vulnerable code (likely in `subcomponents`) can not be executed as it is used by the product.

Typically, this case occurs when the product includes the vulnerable `subcomponent` but does not call or use the vulnerable code. | 369 | | `vulnerable_code_cannot_be_controlled_by_adversary` | The vulnerable code cannot be controlled by an attacker to exploit the vulnerability.

This justification could be difficult to prove conclusively. | 370 | | `inline_mitigations_already_exist` | The product includes built-in protections or features that prevent exploitation of the vulnerability. These built-in protections cannot be subverted by the attacker and cannot be configured or disabled by the user. These mitigations completely prevent exploitation based on known attack vectors.

This justification could be difficult to prove conclusively. History is littered with examples of mitigation bypasses, typically involving minor modifications of existing exploit code. 371 | 372 | ## Data Inheritance 373 | 374 | VEX statements can inherit values from their document and/or, when embedded or 375 | incorporated into another format, from its [encapsulating document](#encapsulating-document). 376 | 377 | A valid VEX statement needs to have four key data points which act as 378 | the grammatical parts of a sentence: 379 | 380 | - One or more products. These are the direct objects of the statement. 381 | - A status. The status can be thought of as the verb. 382 | - A vulnerability. The vulnerability is the indirect object. 383 | - A timestamp. This is the time complement of the statement. A statement is useless without a timestamp as it cannot be related to others talking about the same subject. 384 | 385 | In OpenVEX, timestamps and product identifiers can be defined outside the 386 | statements to avoid defining redundant info or to leverage external features. 387 | 388 | __Note:__ While this specification lists these data fields as optional in the 389 | statement data struct, the data MUST be defined to have complete statements. A 390 | document with incomplete statements is not valid. 391 | 392 | #### Data Economy 393 | 394 | A document defining multiple statements, all issued at the same time can be 395 | made less verbose by just inferring the statement timestamps from the date the 396 | document was issued. 397 | 398 | #### Encapsulating Format 399 | 400 | VEX is designed to be encapsulated in other document formats which may have 401 | redundant features or be better at expressing the required data points. For 402 | example, an in-toto attestation can contain a VEX document in its predicate 403 | while its subject section lists the software the VEX data applies to. 404 | 405 | Another example is CSAF. The format defines a sophisticated tree that 406 | can specify complex groups and families of products. In this case, product 407 | identification can be left blank in the VEX statement and leverage CSAF's 408 | powerful product tree features. 409 | 410 | ### Inheritance Flow 411 | 412 | As mentioned data specifying a statement's product or timestamp can originate 413 | outside. As the data cascades, more specific elements can override the data 414 | defined in more general ones. The following two phrases define how the 415 | inheritance flow works: 416 | 417 | #### Timestamps 418 | 419 | A timestamp in a `statement` entry overrides a timestamp defined at the 420 | document level which in turn overrides timestamps defined on the encapsulating 421 | document. 422 | 423 | #### Product ID 424 | 425 | A product identifier defined in a `statement` entry overrides any product 426 | identification data defined on the encapsulating document. 427 | 428 | ### Updating Statements with Inherited Data 429 | 430 | When updating a document with statements with data implied via inheritance, 431 | the integrity of the untouched statements MUST be preserved. In the following 432 | example, the sole statement has its timestamp data derived from the document: 433 | 434 | ```json 435 | { 436 | "@context": "https://openvex.dev/ns/v0.2.0", 437 | "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57", 438 | "author": "Wolfi J Inkinson", 439 | "role": "Document Creator", 440 | "timestamp": "2023-01-08T18:02:03-06:00", 441 | "version": 1, 442 | "statements": [ 443 | { 444 | "vulnerability": { 445 | "name": "CVE-2023-12345" 446 | }, 447 | "products": [ 448 | {"@id": "pkg:apk/wolfi/git@2.39.0-r1?arch=armv7"} 449 | ], 450 | "status": "under_investigation" 451 | } 452 | ] 453 | } 454 | ``` 455 | 456 | When adding a second statement, the document date needs to be updated, but to 457 | preserve the integrity of the original statement we need to keep the original 458 | document timestamp. The newly added statement can inherit the document's date 459 | to avoid duplication: 460 | 461 | ```json 462 | { 463 | "@context": "https://openvex.dev/ns/v0.2.0", 464 | "@id": "https://openvex.dev/docs/example/vex-84822c4e5028c", 465 | "author": "Wolfi J Inkinson", 466 | "role": "Document Creator", 467 | "timestamp": "2023-01-09T09:08:42-06:00", 468 | "version": 1, 469 | "statements": [ 470 | { 471 | "timestamp": "2023-01-08T18:02:03-06:00", 472 | "vulnerability": { 473 | "name": "CVE-2023-12345" 474 | }, 475 | "products": [ 476 | {"@id": "pkg:apk/wolfi/git@2.39.0-r1?arch=armv7"}, 477 | ], 478 | "status": "under_investigation" 479 | }, 480 | { 481 | "vulnerability": { 482 | "name": "CVE-2023-12345" 483 | }, 484 | "products": [ 485 | {"@id": "pkg:apk/wolfi/git@2.39.0-r1?arch=armv7"} 486 | ], 487 | "status": "fixed" 488 | }, 489 | ] 490 | } 491 | ``` 492 | 493 | ## OpenVEX and JSON-LD 494 | 495 | OpenVEX documents express data that is by nature interlinked. Documents and are 496 | designed to be understood by [JSON-LD][JSON-LD] parsers, 497 | this lets them reference resources expressed in other json-ld formats such as 498 | [SPDX 3][SPDX3]. 499 | 500 | ### VEX Extensions 501 | 502 | To make VEX documents JSON-LD compatible, OpenVEX extends the VEX minimum 503 | requirements in the the following two ways: 504 | 505 | 1. OpenVEX extends the document identifier required by VEX to make the strings 506 | compatible with the Internationalized Resource Identifier (IRI) specification 507 | (see [RFC3987]). 508 | 509 | 2. Addition of the `@context` field at the document level. The additional field is 510 | not required by VEX but it is added to make the documents parseable by json-ld 511 | processors. 512 | 513 | ### Public IRI Namespaces 514 | 515 | As all documents are required to be identified by an IRI, OpenVEX defines a 516 | public namespace that can be used by documents. Users of OpenVEX MAY choose to 517 | use the shared namespace. 518 | 519 | The shared namespace is defined under the openvex.dev domain name: 520 | 521 | `https://openvex.dev/docs/[name]` 522 | 523 | Users can start issuing IRIs for their documents by appending a IRI valid string 524 | to the shared namespace: 525 | 526 | `https://openvex.dev/docs/[myproject]` 527 | 528 | There are two reserved shared namespaces with special meanings: 529 | 530 | - `public` this is a public shared name where anybody that needs a valid IRI can 531 | issue identifiers. Only recommended for demos or experiments where name collisions 532 | do not matter. 533 | - `example` a namespace for documentation, demos or other uses where no systems 534 | are expected to run. 535 | 536 | Please note that initially, OpenVEX does not provide a registry of namespaces or 537 | hosting or redirection of IRIs. 538 | 539 | For more information check the OpenVEX [JSON-LD](JSON-LD.md) document and the 540 | W3C's [JSON-LD recommendation][JSON-LD]. 541 | 542 | ## Example 543 | 544 | To illustrate how OpenVEX can specify a document switching off a false positive, 545 | let's look at an example. According to the 546 | [Spring Blog][log4j-spring-boot], 547 | the included log4j library in Spring Boot 2.6.0 is within the versions affected by 548 | the [log4shell vulnerability][log4shell-vulnerability]. 549 | In the post, however the project maintainers explain that it is not exploitable 550 | as shipped and they provide some details and guidance to users. 551 | 552 | To capture Spring's advise in an OpenVEX document and fend off any false positives, 553 | the project could issue an OpenVEX document as follows: 554 | 555 | ```json 556 | { 557 | "@context": "https://openvex.dev/ns/v0.2.0", 558 | "@id": "https://openvex.dev/docs/public/vex-2e67563e128250cbcb3e98930df948dd053e43271d70dc50cfa22d57e03fe96f", 559 | "author": "Spring Builds ", 560 | "role": "Project Release Bot", 561 | "timestamp": "2023-01-16T19:07:16.853479631-06:00", 562 | "version": 1, 563 | "statements": [ 564 | { 565 | "vulnerability": { 566 | "@id": "https://nvd.nist.gov/vuln/detail/CVE-2021-44228", 567 | "name": "CVE-2021-44228", 568 | "description": "Remote code injection in Log4j", 569 | "aliases": [ 570 | "GHSA-jfh8-c2jp-5v3q" 571 | ] 572 | }, 573 | "products": [ 574 | { 575 | "@id": "pkg:maven/org.springframework.boot/spring-boot@2.6.0-M3", 576 | "identifiers": { 577 | "purl": "pkg:maven/org.springframework.boot/spring-boot@2.6.0-M3", 578 | } 579 | "hashes":{ 580 | "sha-256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" 581 | } 582 | } 583 | ], 584 | "status": "not_affected", 585 | "justification": "vulnerable_code_not_in_execute_path" 586 | "impact_statement": "Spring Boot users are only affected by this vulnerability if they have switched the default logging system to Log4J2. The log4j-to-slf4j and log4j-api jars that we include in spring-boot-starter-logging cannot be exploited on their own. Only applications using log4j-core and including user input in log messages are vulnerable.", 587 | } 588 | ] 589 | } 590 | ``` 591 | 592 | VEX-enabled security scanners could use the vex document to turn off the security 593 | alert and dashboards could present users with the official guidance from the project. 594 | 595 | ## Appendix A: Hash Names Table 596 | 597 | The following list of hash names can be used as keys in the `hashes` field of the 598 | product field. These labels follow and extend the 599 | [Hash Function Textual Names][iana-hash-function-names] 600 | document from IANA. 601 | 602 | | Hash Label | 603 | | --- | 604 | | md5 | 605 | | sha1 | 606 | | sha-256 | 607 | | sha-384 | 608 | | sha-512 | 609 | | sha3-224 | 610 | | sha3-256 | 611 | | sha3-384 | 612 | | sha3-512 | 613 | | blake2s-256 | 614 | | blake2b-256 | 615 | | blake2b-512 | 616 | 617 | ## Appendix B: Software Identifier Types Table 618 | 619 | The following labels can be used as keys when enumerating software identifiers 620 | in the product data structure. 621 | 622 | | Type Label | Identifier type | 623 | | --- | --- | 624 | | purl | [Package URL][purl-spec] | 625 | | cpe22 | [Common Platform Enumeration v2.2][CPE-2.2] | 626 | | cpe23 | [Common Platform Enumeration v2.3][CPE-2.3] | 627 | 628 | ## Revisions 629 | 630 | | Date | Revision | 631 | | --- | --- | 632 | | 2023-07-18 | Added hash and identifier label catalog tables | 633 | | 2023-07-18 | Updated spec to reflect changes in [OPEV-0015: Expansion of the Vulnerability Field][OPEV-0015] | 634 | | 2023-07-18 | Updated spec to reflect changes in [OPEV-0014: Expansion of the VEX Product Field][OPEV-0014] | 635 | | 2023-07-18 | Bumped version of the spec to v0.0.2 after update to meet the VEX-WG doc. | 636 | | 2023-06-01 | Removed supplier from the document level (following VEX-WG doc). | 637 | | 2023-05-29 | Specification updated to reflect the published [Minimum Requirements for VEX] document. | 638 | | 2023-01-08 | First Draft of the OpenVEX Specification. | 639 | | 2023-01-16 | Updated spec draft to reflect initial review. | 640 | | 2023-01-16 | Added JSON-LD and namespace section. | 641 | | 2023-01-16 | Add example section. | 642 | | 2023-05-29 | Added missing fields to match the VEX-WG's [Minimum Requirements for VEX] document. | 643 | 644 | ## Sources 645 | 646 | - Vulnerability Exploitability eXchange (VEX) - [Status Justifications] 647 | - [Minimum Requirements for VEX] document, published by CISA. 648 | 649 | [CISA]: https://www.cisa.gov/ 650 | [CPE-2.2]: https://cpe.mitre.org/files/cpe-specification_2.2.pdf 651 | [CPE-2.3]: https://csrc.nist.gov/pubs/ir/7695/final 652 | [iana-hash-function-names]: https://www.iana.org/assignments/named-information/named-information.xhtml 653 | [IRI]: https://www.ietf.org/rfc/rfc3987.txt 654 | [JSON-LD]: https://www.w3.org/TR/json-ld11/ 655 | [log4j-spring-boot]: https://spring.io/blog/2021/12/10/log4j2-vulnerability-and-spring-boot 656 | [log4shell-vulnerability]: https://nvd.nist.gov/vuln/detail/CVE-2021-44228 657 | [Minimum Requirements for VEX]: https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf 658 | [OPEV-0014]: https://github.com/openvex/community/blob/main/enhancements/opev-0014.md 659 | [OPEV-0015]: https://github.com/openvex/community/blob/main/enhancements/opev-0015.md 660 | [purl-spec]: https://github.com/package-url/purl-spec 661 | [RFC2119]: https://www.rfc-editor.org/rfc/rfc2119 662 | [RFC3987]: https://www.rfc-editor.org/rfc/rfc3987 663 | [SPDX3]: https://github.com/spdx/spdx-3-model 664 | [Status Justifications]: https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf 665 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OpenVEX Specification 2 | 3 | OpenVEX is an implementation of the 4 | [Vulnerability Exploitability Exchange](https://www.ntia.gov/files/ntia/publications/vex_one-page_summary.pdf) 5 | (VEX for short) that is designed to be minimal, compliant, interoperable, and 6 | embeddable. 7 | The specification is available in the [OPENVEX-SPEC.md](OPENVEX-SPEC.md) file of this repository. 8 | 9 | **Note**: The OpenVEX specification is currently a draft. We don't anticipate large changes, but are open to them. 10 | 11 | ## Principles 12 | 13 | OpenVEX is designed with the following principles in mind: 14 | 15 | ### Meet the requirements defined by the [CISA SBOM and VEX Efforts](https://www.cisa.gov/sbom). 16 | 17 | We believe OpenVEX meets these requirements now, and will do our best to ensure it continues to meet them as requirements 18 | change. 19 | 20 | ### SBOM Agnostic 21 | 22 | We believe VEX is most useful when decoupled from specific SBOM formats. 23 | 24 | Several SBOM formats include ways to express VEX (both within and outside of the SBOM), but we feel a single VEX format 25 | can be used across any SBOM format. 26 | Further, while we do anticipate VEX will primarily be used with SBOMs, VEX is useful without them. 27 | 28 | ### Minimal 29 | 30 | OpenVEX is minimal. 31 | The specification is primarily intended to serve the use cases outlined in the CISA VEX definition. 32 | 33 | ## About VEX 34 | 35 | Vulnerability Exploitability eXchange is a vulnerability document designed to 36 | complement a Software Bill of Materials (SBOM) that informs users of a software 37 | product about the applicability of one or more vulnerability findings. 38 | 39 | Security scanners will detect and flag components in software that have 40 | been identified as being vulnerable. Often, software is not necessarily affected 41 | as signaled by security scanners for many reasons such as: the vulnerable component may 42 | have been already patched, may not be present, or may not be able to be executed. To turn off 43 | false alerts like these, a scanner may consume VEX data from the software supplier. 44 | 45 | The extreme transparency brought by SBOMs into how software is composed will 46 | most likely increase the number of these kind of false positives, requiring an 47 | automated solution to avoid an explosion in the false positive rate of security 48 | scans. Hence VEX. 49 | 50 | ## OpenVEX is... 51 | 52 | ### A Specification 53 | 54 | OpenVEX documents are minimal JSON-LD files that capture the minimal requirements 55 | for VEX as defined by the VEX working group organized by CISA. The 56 | [OpenVEX Specification](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md) 57 | is owned and steered by the community. 58 | 59 | ### A Go Library 60 | 61 | The project has a go library 62 | ([openvex/go-vex](https://github.com/openvex/go-vex)) that lets projects generate, 63 | transform and consume OpenVEX files. It enables the ingestion of VEX metadata 64 | expressed in other VEX implementations. 65 | 66 | ### A Set of Tools 67 | 68 | Work is underway to create the tools software authors and consumers need to 69 | handle VEX metadata. The current flagship project is 70 | [`vexctl`](https://github.com/openvex/vexctl), a CLI to create, merge and 71 | attest VEX documents. 72 | 73 | ## What Does an OpenVEX Document Look Like? 74 | 75 | An OpenVEX document is composed of a JSON-LD structure that contains the 76 | [document metadata](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#vex-documents) 77 | and one or more 78 | [VEX statements](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#the-vex-statement): 79 | 80 | ```json 81 | { 82 | "@context": "https://openvex.dev/ns/v0.2.0", 83 | "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57", 84 | "author": "Wolfi J Inkinson", 85 | "role": "Document Creator", 86 | "timestamp": "2023-01-08T18:02:03.647787998-06:00", 87 | "version": "1", 88 | "statements": [ 89 | { 90 | "vulnerability": { 91 | "name": "CVE-2014-123456" 92 | }, 93 | "products": [ 94 | {"@id": "pkg:apk/distro/git@2.39.0-r1?arch=armv7"}, 95 | {"@id": "pkg:apk/distro/git@2.39.0-r1?arch=x86_64"} 96 | ], 97 | "status": "fixed" 98 | } 99 | ] 100 | } 101 | ``` 102 | 103 | Check out 104 | [the OpenVEX specification](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md) 105 | and our [examples repository](https://github.com/openvex/examples) for more 106 | information and use cases. 107 | 108 | ## How can I check if my OpenVEX document is valid? 109 | 110 | There is a [JSON Schema](https://github.com/openvex/spec/blob/main/openvex_json_schema.json) for the OpenVEX specification. You can use tools listed on https://json-schema.org/implementations to check the validity of your OpenVEX document. 111 | 112 | ## OpenVEX Roadmap 113 | 114 | The OpenVEX specification is currently a draft. 115 | We believe the specification is usable today, but will focus on implementation and adoption in the short term. 116 | We can't be fully confident the specification works until it has been implemented by a wide range of users, tools 117 | and systems. 118 | 119 | We're hoping for a 1.0 release in 2023. 120 | 121 | ## Frequently Asked Questions 122 | 123 | #### How does this compare to CSAF? 124 | 125 | OpenVEX is designed to be more Lightweight, easy to be recorded in 126 | [Sigstore](https://sigstore.dev), and embedded in [in-toto](https://in-toto.io/) 127 | attestations. While CSAF has a rich mechanism to express product trees, 128 | OpenVEX favors [package URLs](https://github.com/package-url/purl-spec) (purl) 129 | as its software identifier of choice. 130 | 131 | #### How does this compare to CycloneDX VEX? 132 | 133 | OpenVEX aims to be SBOM format agnostic. While there are plans to have both 134 | CycloneDX and SPDX VEX implementations, we feel that VEX metadata should be 135 | kept separate from the SBOM. 136 | 137 | On the implementation details, the CycloneDX VEX implementation defines a 138 | different set of 139 | [status](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-labels) and 140 | [justification](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-justifications) 141 | labels than those defined by the VEX Working Group. To match CDX VEX documents to the unified labels documents have to be translated, which is not ideal. 142 | 143 | #### Does it work with SBOMs? 144 | 145 | Yes, OpenVEX is designed to be SBOM format agnostic. It can reference software 146 | described in both SPDX and CycloneDX Software Bills of Materials. 147 | 148 | #### Why not use CSAF or CycloneDX? 149 | 150 | When OpenVEX was released, both the CSAF and CycloneDX implementations of VEX 151 | are missing a few pieces of the minimum elements of VEX. Nevertheless, OpenVEX 152 | can be used along with CSAF and CycloneDX documents. The OpenVEX tooling can 153 | generate a complete VEX impact history from files expressed in the other 154 | implementations 155 | 156 | #### Who is behind this project? 157 | 158 | This project uses a community governance model defined in the [community repository](https://github.com/openvex/community). 159 | Contributions are welcome! 160 | -------------------------------------------------------------------------------- /context.json: -------------------------------------------------------------------------------- 1 | ns/v0.2.0/context.json -------------------------------------------------------------------------------- /governance/0._CS_Contributor_License_Agreement.md: -------------------------------------------------------------------------------- 1 | # Community Specification Contributor License Agreement 1.0 2 | 3 | By making a Contribution to this repository, I agree to the terms of the following documents located at [https://github.com/CommunitySpecification/1.0](https://github.com/CommunitySpecification/1.0): 4 | 5 | (a) Community Specification License 1.0 (.0_Community_Specification_License-v1.md) 6 | 7 | (b) Community Specification Governance Policy 1.0 (5._Governance.md) 8 | 9 | (c) Community Specification Contribution Policy 1.0 (6._Contributing.md) 10 | 11 | (d) Community Specification Code of Conduct (8._Code_of_Conduct.md) 12 | 13 | 14 | In addition, for source code contributions, I certify that: 15 | 16 | (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this working group and the contribution may be public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this agreement or the open source license(s) involved. 17 | 18 | I represent that I am legally entitled to make the grants set forth in the documents above. If my employer(s) has rights to intellectual property that may be infringed by the materials developed by this Working Group, I represent that I have received permission to enter these agreements on behalf of that employer. 19 | -------------------------------------------------------------------------------- /governance/1._Community_Specification_License-v1.md: -------------------------------------------------------------------------------- 1 | # Community Specification License 1.0 2 | 3 | **The Purpose of this License.** This License sets forth the terms under which 1) Contributor will participate in and contribute to the development of specifications, standards, best practices, guidelines, and other similar materials under this Working Group, and 2) how the materials developed under this License may be used. It is not intended for source code. Capitalized terms are defined in the License’s last section. 4 | 5 | **1. Copyright.** 6 | 7 | **1.1. Copyright License.** Contributor grants everyone a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) copyright license, without any obligation for accounting, to reproduce, prepare derivative works of, publicly display, publicly perform, and distribute any materials it submits to the full extent of its copyright interest in those materials. Contributor also acknowledges that the Working Group may exercise copyright rights in the Specification, including the rights to submit the Specification to another standards organization. 8 | 9 | **1.2. Copyright Attribution.** As a condition, anyone exercising this copyright license must include attribution to the Working Group in any derivative work based on materials developed by the Working Group. That attribution must include, at minimum, the material’s name, version number, and source from where the materials were retrieved. Attribution is not required for implementations of the Specification. 10 | 11 | **2. Patents.** 12 | 13 | **2.1. Patent License.** 14 | 15 | **2.1.1. As a Result of Contributions.** 16 | 17 | **2.1.1.1. As a Result of Contributions to Draft Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims in 1) Contributor’s Contributions and 2) to the Draft Specification that is within Scope as of the date of that Contribution, in both cases for Licensee’s Implementation of the Draft Specification, except for those patent claims excluded by Contributor under Section 3. 18 | 19 | **2.1.1.2. For Approved Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims included the Approved Specification that are within Scope for Licensee’s Implementation of the Approved Specification, except for those patent claims excluded by Contributor under Section 3. 20 | 21 | **2.1.2. Patent Grant from Licensee.** Licensee grants each other Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims for its Implementation, except for those patent claims excluded under Section 3. 22 | 23 | **2.1.3. Licensee Acceptance.** The patent grants set forth in Section 2.1 extend only to Licensees that have indicated their agreement to this License as follows: 24 | 25 | **2.1.3.1. Source Code Distributions.** For distribution in source code, by including this License in the root directory of the source code with the Implementation; 26 | 27 | **2.1.3.2. Non-Source Code Distributions.** For distribution in any form other than source code, by including this License in the documentation, legal notices, via notice in the software, and/or other written materials provided with the Implementation; or 28 | 29 | **2.1.3.3. Via Notices.md.** By issuing pull request or commit to the Specification’s repository’s Notices.md file by the Implementer’s authorized representative, including the Implementer’s name, authorized individual and system identifier, and Specification version. 30 | 31 | **2.1.4. Defensive Termination.** If any Licensee files or maintains a claim in a court asserting that a Necessary Claim is infringed by an Implementation, any licenses granted under this License to the Licensee are immediately terminated unless 1) that claim is directly in response to a claim against Licensee regarding an Implementation, or 2) that claim was brought to enforce the terms of this License, including intervention in a third-party action by a Licensee. 32 | 33 | **2.1.5. Additional Conditions.** This License is not an assurance (i) that any of Contributor’s copyrights or issued patent claims cover an Implementation of the Specification or are enforceable or (ii) that an Implementation of the Specification would not infringe intellectual property rights of any third party. 34 | 35 | **2.2. Patent Licensing Commitment.** In addition to the rights granted in Section 2.1, Contributor agrees to grant everyone a no charge, royalty-free license on reasonable and non-discriminatory terms to Contributor’s Necessary Claims that are within Scope for: 36 | 1) Implementations of a Draft Specification, where such license applies only to those Necessary Claims infringed by implementing Contributor's Contribution(s) included in that Draft Specification, and 37 | 2) Implementations of the Approved Specification. 38 | 39 | This patent licensing commitment does not apply to those claims subject to Contributor’s Exclusion Notice under Section 3. 40 | 41 | **2.3. Effect of Withdrawal.** Contributor may withdraw from the Working Group by issuing a pull request or commit providing notice of withdrawal to the Working Group repository’s Notices.md file. All of Contributor’s existing commitments and obligations with respect to the Working Group up to the date of that withdrawal notice will remain in effect, but no new obligations will be incurred. 42 | 43 | **2.4. Binding Encumbrance.** This License is binding on any future owner, assignee, or party who has been given the right to enforce any Necessary Claims against third parties. 44 | 45 | **3. Patent Exclusion.** 46 | 47 | **3.1. As a Result of Contributions.** Contributor may exclude Necessary Claims from its licensing commitments incurred under Section 2.1.1 by issuing an Exclusion Notice within 45 days of the date of that Contribution. Contributor may not issue an Exclusion Notice for any material that has been included in a Draft Deliverable for more than 45 days prior to the date of that Contribution. 48 | 49 | **3.2. As a Result of a Draft Specification Becoming an Approved Specification.** Prior to the adoption of a Draft Specification as an Approved Specification, Contributor may exclude Necessary Claims from its licensing commitments under this Agreement by issuing an Exclusion Notice. Contributor may not issue an Exclusion Notice for patents that were eligible to have been excluded pursuant to Section 3.1. 50 | 51 | **4. Source Code License.** Any source code developed by the Working Group is solely subject the source code license included in the Working Group’s repository for that code. If no source code license is included, the source code will be subject to the MIT License. 52 | 53 | **5. No Other Rights.** Except as specifically set forth in this License, no other express or implied patent, trademark, copyright, or other rights are granted under this License, including by implication, waiver, or estoppel. 54 | 55 | **6. Antitrust Compliance.** Contributor acknowledge that it may compete with other participants in various lines of business and that it is therefore imperative that they and their respective representatives act in a manner that does not violate any applicable antitrust laws and regulations. This License does not restrict any Contributor from engaging in similar specification development projects. Each Contributor may design, develop, manufacture, acquire or market competitive deliverables, products, and services, and conduct its business, in whatever way it chooses. No Contributor is obligated to announce or market any products or services. Without limiting the generality of the foregoing, the Contributors agree not to have any discussion relating to any product pricing, methods or channels of product distribution, division of markets, allocation of customers or any other topic that should not be discussed among competitors under the auspices of the Working Group. 56 | 57 | **7. Non-Circumvention.** Contributor agrees that it will not intentionally take or willfully assist any third party to take any action for the purpose of circumventing any obligations under this License. 58 | 59 | **8. Representations, Warranties and Disclaimers.** 60 | 61 | **8.1. Representations, Warranties and Disclaimers.** Contributor and Licensee represents and warrants that 1) it is legally entitled to grant the rights set forth in this License and 2) it will not intentionally include any third party materials in any Contribution unless those materials are available under terms that do not conflict with this License. IN ALL OTHER RESPECTS ITS CONTRIBUTIONS ARE PROVIDED "AS IS." The entire risk as to implementing or otherwise using the Contribution or the Specification is assumed by the implementer and user. Except as stated herein, CONTRIBUTOR AND LICENSEE EXPRESSLY DISCLAIM ANY WARRANTIES (EXPRESS, IMPLIED, OR OTHERWISE), INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, CONDITIONS OF QUALITY, OR TITLE, RELATED TO THE CONTRIBUTION OR THE SPECIFICATION. IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Any obligations regarding the transfer, successors in interest, or assignment of Necessary Claims will be satisfied if Contributor or Licensee notifies the transferee or assignee of any patent that it knows contains Necessary Claims or necessary claims under this License. Nothing in this License requires Contributor to undertake a patent search. If Contributor is 1) employed by or acting on behalf of an employer, 2) is making a Contribution under the direction or control of a third party, or 3) is making the Contribution as a consultant, contractor, or under another similar relationship with a third party, Contributor represents that they have been authorized by that party to enter into this License on its behalf. 62 | 63 | **8.2. Distribution Disclaimer.** Any distributions of technical information to third parties must include a notice materially similar to the following: “THESE MATERIALS ARE PROVIDED “AS IS.” The Contributors and Licensees expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.” 64 | 65 | **9. Definitions.** 66 | 67 | **9.1. Affiliate.** “Affiliate” means an entity that directly or indirectly Controls, is Controlled by, or is under common Control of that party. 68 | 69 | **9.2. Approved Specification.** “Approved Specification” means the final version and contents of any Draft Specification designated as an Approved Specification as set forth in the accompanying Governance.md file. 70 | 71 | **9.3. Contribution.** “Contribution” means any original work of authorship, including any modifications or additions to an existing work, that Contributor submits for inclusion in a Draft Specification, which is included in a Draft Specification or Approved Specification. 72 | 73 | **9.4. Contributor.** “Contributor” means any person or entity that has indicated its acceptance of the License 1) by making a Contribution to the Specification, or 2) by entering into the Community Specification Contributor License Agreement for the Specification. Contributor includes its Affiliates, assigns, agents, and successors in interest. 74 | 75 | **9.5. Control.** “Control” means direct or indirect control of more than 50% of the voting power to elect directors of that corporation, or for any other entity, the power to direct management of such entity. 76 | 77 | **9.6. Draft Specification.** “Draft Specification” means all versions of the material (except an Approved Specification) developed by this Working Group for the purpose of creating, commenting on, revising, updating, modifying, or adding to any document that is to be considered for inclusion in the Approved Specification. 78 | 79 | **9.7. Exclusion Notice.** “Exclusion Notice” means a written notice made by making a pull request or commit to the repository’s Notices.md file that identifies patents that Contributor is excluding from its patent licensing commitments under this License. The Exclusion Notice for issued patents and published applications must include the Draft Specification’s name, patent number(s) or title and application number(s), as the case may be, for each of the issued patent(s) or pending patent application(s) that the Contributor is excluding from the royalty-free licensing commitment set forth in this License. If an issued patent or pending patent application that may contain Necessary Claims is not set forth in the Exclusion Notice, those Necessary Claims shall continue to be subject to the licensing commitments under this License. The Exclusion Notice for unpublished patent applications must provide either: (i) the text of the filed application; or (ii) identification of the specific part(s) of the Draft Specification whose implementation makes the excluded claim a Necessary Claim. If (ii) is chosen, the effect of the exclusion will be limited to the identified part(s) of the Draft Specification. 80 | 81 | **9.8. Implementation.** “Implementation” means making, using, selling, offering for sale, importing or distributing any implementation of the Specification 1) only to the extent it implements the Specification and 2) so long as all required portions of the Specification are implemented. 82 | 83 | **9.9. License.** “License” means this Community Specification License. 84 | 85 | **9.10. Licensee.** “Licensee” means any person or entity that has indicated its acceptance of the License as set forth in Section 2.1.3. Licensee includes its Affiliates, assigns, agents, and successors in interest. 86 | 87 | **9.11. Necessary Claims.** “Necessary Claims” are those patent claims, if any, that a party owns or controls, including those claims later acquired, that are necessary to implement the required portions (including the required elements of optional portions) of the Specification that are described in detail and not merely referenced in the Specification. 88 | 89 | **9.12. Specification.** “Specification” means a Draft Specification or Approved Specification included in the Working Group’s repository subject to this License, and the version of the Specification implemented by the Licensee. 90 | 91 | **9.13. Scope.** “Scope” has the meaning as set forth in the accompanying Scope.md file included in this Specification’s repository. Changes to Scope do not apply retroactively. If no Scope is provided, each Contributor’s Necessary Claims are limited to that Contributor’s Contributions. 92 | 93 | **9.14. Working Group.** “Working Group” means this project to develop specifications, standards, best practices, guidelines, and other similar materials under this License. 94 | 95 | 96 | 97 | *The text of this Community Specification License is Copyright 2020 Joint Development Foundation and is licensed under the Creative Commons Attribution 4.0 International License available at https://creativecommons.org/licenses/by/4.0/.* 98 | 99 | SPDX-License-Identifier: CC-BY-4.0 100 | -------------------------------------------------------------------------------- /governance/2._Scope.md: -------------------------------------------------------------------------------- 1 | # Scope 2 | 3 | [Include a detailed description of this Working Group’s Scope. This Scope is important is it establishes the bounds of each contributor's and licensee's patent commitment. For guidance on drafting an appropriate Scope, you may find [ISO's guidance (see page 5)](https://www.iso.org/files/live/sites/isoorg/files/developing_standards/docs/en/how-to-write-standards.pdf "ISO How To Write Standards Guide") helpful.] 4 | 5 | Any changes of Scope are not retroactive. 6 | -------------------------------------------------------------------------------- /governance/3._Notices.md: -------------------------------------------------------------------------------- 1 | # Notices 2 | 3 | ## Code of Conduct 4 | 5 | Contact for Code of Conduct issues or inquires: _________________ 6 | 7 | [Ideally list two different individuals above (not a generic mailing list) as someone submitting a Code of Conduct complaint will want to know exactly who is receiving the complaint. We recommend two individuals in the case one of the individuals is the subject of or directly involved in the subject of a complaint.] 8 | 9 | 10 | ## License Acceptance 11 | 12 | Per Community Specification License 1.0 Section 2.1.3.3, Licensees may indicate their acceptance of the Community Specification License by issuing a pull request to the Specification’s repository’s Notice.md file, including the Licensee’s name, authorized individuals' names, and repository system identifier (e.g. GitHub ID), and specification version. 13 | 14 | A Licensee may consent to accepting the current Community Specification License version or any future version of the Community Specification License by indicating "or later" after their specification version. 15 | 16 | --------------------------------------------------------------------------------- 17 | 18 | Licensee’s name: 19 | 20 | Authorized individual and system identifier: 21 | 22 | Specification version: 23 | 24 | --------------------------------------------------------------------------------- 25 | 26 | ## Withdrawals 27 | 28 | Name of party withdrawing: 29 | 30 | Date of withdrawal: 31 | 32 | --------------------------------------------------------------------------------- 33 | 34 | ## Exclusions 35 | 36 | This section includes any Exclusion Notices made against a Draft Deliverable or Approved Deliverable as set forth in the Community Specification Development License. Each Exclusion Notice must include the following information: 37 | 38 | - Name of party making the Exclusion Notice: 39 | 40 | - Name of patent owner: 41 | 42 | - Specification: 43 | 44 | - Version number: 45 | 46 | **For issued patents and published patent applications:** 47 | 48 | (i) patent number(s) or title and application number(s), as the case may be: 49 | 50 | (ii) identification of the specific part(s) of the Specification whose implementation makes the excluded claim a Necessary Claim. 51 | 52 | **For unpublished patent applications must provide either:** 53 | 54 | (i) the text of the filed application; or 55 | 56 | (ii) identification of the specific part(s) of the Specification whose implementation makes the excluded claim a Necessary Claim. 57 | 58 | ----------------------------------------------------------------------------------------- 59 | -------------------------------------------------------------------------------- /governance/4._License.md: -------------------------------------------------------------------------------- 1 | # Licenses 2 | 3 | ## Specification License 4 | 5 | Specifications in the repository are subject to the **Community Specification License 1.0** available at [https://github.com/CommunitySpecification/1.0](https://github.com/CommunitySpecification/1.0). 6 | 7 | ## Source Code License 8 | 9 | If source code is included in this repository, or for sample or reference code included in the specification itself, that code is subject to the MIT license unless otherwise designated. In the case of any conflict or confusion within this specification repository between the Community Specification License and the MIT or other designated license, the terms of the Community Specification License shall apply. 10 | 11 | If source code is included in this repository, or for sample or reference code included in the specification itself, that code is subject to the MIT license unless otherwise marked. 12 | 13 | In the case of any conflict or confusion within this specification repository between the Community Specification License and the designated source code license, the terms of the Community Specification License shall apply. 14 | -------------------------------------------------------------------------------- /governance/5._Governance.md: -------------------------------------------------------------------------------- 1 | # Community Specification Governance Policy 1.0 2 | 3 | This document provides the governance policy for specifications and other documents developed using the Community Specification process in a repository (each a “Working Group”). Each Working Group and must adhere to the requirements in this document. 4 | 5 | ## 1. Roles. 6 | 7 | Each Working Group may include the following roles. Additional roles may be adopted and documented by the Working Group. 8 | 9 | **1.1. Maintainer.** “Maintainers” are responsible for organizing activities around developing, maintaining, and updating the specification(s) developed by the Working Group. Maintainers are also responsible for determining consensus and coordinating appeals. Each Working Group will designate one or more Maintainer for that Working Group. A Working Group may select a new or additional Maintainer(s) upon Approval of the Working Group Participants. 10 | 11 | **1.2. Editor.** “Editors” are responsible for ensuring that the contents of the document accurately reflect the decisions that have been made by the group, and that the specification adheres to formatting and content guidelines. Each Working Group will designate an Editor for that Working Group. A Working Group may select a new Editor upon Approval of the Working Group Participants. 12 | 13 | **1.3. Participants.** “Participants” are those that have made Contributions to the Working Group subject to the Community Specification License. 14 | 15 | ## 2. Decision Making. 16 | 17 | **2.1. Consensus-Based Decision Making.** Working Groups make decisions through a consensus process (“Approval” or “Approved”). While the agreement of all Participants is preferred, it is not required for consensus. Rather, the Maintainer will determine consensus based on their good faith consideration of a number of factors, including the dominant view of the Working Group Participants and nature of support and objections. The Maintainer will document evidence of consensus in accordance with these requirements. 18 | 19 | **2.2. Appeal Process.** Decisions may be appealed be via a pull request or an issue, and that appeal will be considered by the Maintainer in good faith, who will respond in writing within a reasonable time. 20 | 21 | ## 3. Ways of Working. 22 | 23 | Inspired by [ANSI’s Essential Requirements for Due Process](https://share.ansi.org/Shared%20Documents/Standards%20Activities/American%20National%20Standards/Procedures,%20Guides,%20and%20Forms/2020_ANSI_Essential_Requirements.pdf), Community Specification Working Groups must adhere to consensus-based due process requirements. These requirements apply to activities related to the development of consensus for approval, revision, reaffirmation, and withdrawal of Community Specifications. Due process means that any person (organization, company, government agency, individual, etc.) with a direct and material interest has a right to participate by: a) expressing a position and its basis, b) having that position considered, and c) having the right to appeal. Due process allows for equity and fair play. The following constitute the minimum acceptable due process requirements for the development of consensus. 24 | 25 | **3.1. Openness.** Participation shall be open to all persons who are directly and materially affected by the activity in question. There shall be no undue financial barriers to participation. Voting membership on the consensus body shall not be conditional upon membership in any organization, nor unreasonably restricted on the basis of technical qualifications or other such requirements. Membership in a Working Group’s parent organization, if any, may be required. 26 | 27 | **3.2. Lack of Dominance.** The development process shall not be dominated by any single interest category, individual or organization. Dominance means a position or exercise of dominant authority, leadership, or influence by reason of superior leverage, strength, or representation to the exclusion of fair and equitable consideration of other viewpoints. 28 | 29 | **3.3. Balance.** The development process should have a balance of interests. Participants from diverse interest categories shall be sought with the objective of achieving balance. 30 | 31 | **3.4. Coordination and Harmonization.** Good faith efforts shall be made to resolve potential conflicts between and among deliverables developed under this Working Group and existing industry standards. 32 | 33 | **3.5. Consideration of Views and Objections.** Prompt consideration shall be given to the written views and objections of all Participants. 34 | 35 | **3.6. Written procedures.** This governance document and other materials documenting the Community Specification development process shall be available to any interested person. 36 | 37 | ## 4. Specification Development Process. 38 | 39 | **4.1. Pre-Draft.** Any Participant may submit a proposed initial draft document as a candidate Draft Specification of that Working Group. The Maintainer will designate each submission as a “Pre-Draft” document. 40 | 41 | **4.2. Draft.** Each Pre-Draft document of a Working Group must first be Approved to become a” Draft Specification”. Once the Working Group approves a document as a Draft Specification, the Draft Specification becomes the basis for all going forward work on that specification. 42 | 43 | **4.3. Working Group Approval.** Once a Working Group believes it has achieved the objectives for its specification as described in the Scope, it will Approve that Draft Specification and progress it to “Approved Specification” status. 44 | 45 | **4.4. Publication and Submission.** Upon the designation of a Draft Specification as an Approved Specification, the Maintainer will publish the Approved Specification in a manner agreed upon by the Working Group Participants (i.e., Working Group Participant only location, publicly available location, Working Group maintained website, Working Group member website, etc.). The publication of an Approved Specification in a publicly accessible manner must include the terms under which the Approved Specification is being made available under. 46 | 47 | **4.5. Submissions to Standards Bodies.** No Draft Specification or Approved Specification may be submitted to another standards development organization without Working group Approval. Upon reaching Approval, the Maintainer will coordinate the submission of the applicable Draft Specification or Approved Specification to another standards development organization. Working Group Participants that developed that Draft Specification or Approved Specification agree to grant the copyright rights necessary to make those submissions. 48 | 49 | ## 5. Non-Confidential, Restricted Disclosure. 50 | 51 | Information disclosed in connection with any Working Group activity, including but not limited to meetings, Contributions, and submissions, is not confidential, regardless of any markings or statements to the contrary. Notwithstanding the foregoing, if the Working Group is collaborating via a private repository, the Participants will not make any public disclosures of that information contained in that private repository without the Approval of the Working Group. 52 | -------------------------------------------------------------------------------- /governance/6._Contributing.md: -------------------------------------------------------------------------------- 1 | # Community Specification Contribution Policy 1.0 2 | 3 | This document provides the contribution policy for specifications and other documents developed using the Community Specification process in a repository (each a “Working Group”). Additional or alternate contribution policies may be adopted and documented by the Working Group. 4 | 5 | ## 1. Contribution Guidelines. 6 | 7 | This Working Group accepts contributions via pull requests. The following section outlines the process for merging contributions to the specification 8 | 9 | **1.1. Issues.** Issues are used as the primary method for tracking anything to do with this specification Working Group. 10 | 11 | **1.1.1. Issue Types.** There are three types of issues (each with their own corresponding label): 12 | 13 | **1.1.1.1. Discussion.** These are support or functionality inquiries that we want to have a record of for future reference. Depending on the discussion, these can turn into "Spec Change" issues. 14 | 15 | **1.1.1.2. Proposal.** Used for items that propose a new ideas or functionality that require a larger discussion. This allows for feedback from others before a specification change is actually written. All issues that are proposals should both have a label and an issue title of "Proposal: [the rest of the title]." A proposal can become a "Spec Change" and does not require a milestone. 16 | 17 | **1.1.1.3. Spec Change:** These track specific spec changes and ideas until they are complete. They can evolve from "Proposal" and "Discussion" items, or can be submitted individually depending on the size. Each spec change should be placed into a milestone. 18 | 19 | ## 2. Issue Lifecycle. 20 | 21 | The issue lifecycle is mainly driven by the Maintainer. All issue types follow the same general lifecycle. Differences are noted below. 22 | 23 | **2.1. Issue Creation.** 24 | 25 | **2.2. Triage.** 26 | 27 | o The Editor in charge of triaging will apply the proper labels for the issue. This includes labels for priority, type, and metadata. 28 | 29 | o (If needed) Clean up the title to succinctly and clearly state the issue. Also ensure that proposals are prefaced with "Proposal". 30 | 31 | **2.3. Discussion.** 32 | 33 | o "Spec Change" issues should be connected to the pull request that resolves it. 34 | 35 | o Whoever is working on a "Spec Change" issue should either assign the issue to themselves or make a comment in the issue saying that they are taking it. 36 | 37 | o "Proposal" and "Discussion" issues should stay open until resolved. 38 | 39 | **2.4. Issue Closure.** 40 | 41 | ## 3. How to Contribute a Patch. 42 | 43 | The Working Group uses pull requests to track changes. To submit a change to the specification: 44 | 45 | **3.1 Fork the Repo, modify the Specification to Address the Issue.** 46 | 47 | **3.2. Submit a Pull Request.** 48 | 49 | ## 4. Pull Request Workflow. 50 | 51 | The next section contains more information on the workflow followed for Pull Requests. 52 | 53 | **4.1. Pull Request Creation.** 54 | 55 | o We welcome pull requests that are currently in progress. They are a great way to keep track of important work that is in-flight, but useful for others to see. If a pull request is a work in progress, it should be prefaced with "WIP: [title]". You should also add the wip label Once the pull request is ready for review, remove "WIP" from the title and label. 56 | 57 | o It is preferred, but not required, to have a pull request tied to a specific issue. There can be circumstances where if it is a quick fix then an issue might be overkill. The details provided in the pull request description would suffice in this case. 58 | 59 | **4.2. Triage** 60 | 61 | o The Editor in charge of triaging will apply the proper labels for the issue. This should include at least a size label, a milestone, and awaiting review once all labels are applied. 62 | 63 | **4.3. Reviewing/Discussion.** 64 | 65 | o All reviews will be completed using the review tool. 66 | 67 | o A "Comment" review should be used when there are questions about the spec that should be answered, but that don't involve spec changes. This type of review does not count as approval. 68 | 69 | o A "Changes Requested" review indicates that changes to the spec need to be made before they will be merged. 70 | 71 | o Reviewers should update labels as needed (such as needs rebase). 72 | 73 | o When a review is approved, the reviewer should add LGTM as a comment. 74 | 75 | o Final approval is required by a designated Editor. Merging is blocked without this final approval. Editors will factor reviews from all other reviewers into their approval process. 76 | 77 | **4.4. Responsive.** Pull request owner should try to be responsive to comments by answering questions or changing text. Once all comments have been addressed, the pull request is ready to be merged. 78 | 79 | **4.5. Merge or Close.** 80 | 81 | o A pull request should stay open until a Maintainer has marked the pull request as approved. 82 | 83 | o Pull requests can be closed by the author without merging. 84 | 85 | o Pull requests may be closed by a Maintainer if the decision is made that it is not going to be merged. 86 | -------------------------------------------------------------------------------- /governance/7._CS_Template.md: -------------------------------------------------------------------------------- 1 | # Community Specification Template 1.0 2 | 3 | Community Specifications are recommended to be drafted in accordance with international best practices. Doing so provides clarity, helps adoption, and also eases the transition of this specification to other standards body if so desired. Accordingly, the recommended template below is based on ISO standard drafting conventions. 4 | 5 | To help you, this guide on writing standards was produced by the ISO/TMB and is available at https://www.iso.org/iso/how-to-write-standards.pdf. 6 | 7 | A model manuscript of a draft International Standard (known as “The Rice Model”) is available at https://www.iso.org/iso/model_document-rice_model.pdf. 8 | 9 | In addition, we recommend using the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" as described in RFC 2119 - https://tools.ietf.org/html/rfc2119 10 | 11 | 12 | ## Title 13 | ### Version _______ 14 | ### Status (Pre-draft, Draft, Approved) 15 | 16 | 17 | © _________________ 18 | 19 | This specification is subject to the Community Specification License 1.0, available at [https://github.com/CommunitySpecification/1.0](https://github.com/CommunitySpecification/1.0). 20 | 21 |   22 | 23 | ## Contents 24 | Foreword i 25 | 26 | Introduction i 27 | 28 | 1 Scope (mandatory) 1 29 | 30 | 2 Normative references (mandatory) 1 31 | 32 | 3 Terms and definitions (mandatory) 1 33 | 34 | 4 Clause title autonumber 1 35 | 36 | 5 Clause title 1 37 | 38 | 5.1 Subclause autonumber 1 39 | 40 | 5.1.1 Subclause autonumber 1 41 | 42 | 6 Clause title 1 43 | 44 | Annex A (informative) 45 | 46 | Bibliography 1 47 | 48 | 49 | ## Foreword 50 | 51 | Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. No party shall not be held responsible for identifying any or all such patent rights. 52 | 53 | Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement. 54 | 55 | This document was prepared by [Insert name of group]. 56 | 57 | This second/third/… edition cancels and replaces the first/second/… edition (#####:####), which has been technically revised. 58 | The main changes compared to the previous edition are as follows: 59 | — xxx xxxxxxx xxx xxxx 60 | 61 | Known patent licensing exclusions are available in the specification’s repository’s Notices.md file. 62 | 63 | Any feedback or questions on this document should be directed to specifications repository, located at _________________. 64 | 65 | THESE MATERIALS ARE PROVIDED “AS IS.” The Contributors and Licensees expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 66 | 67 | Introduction 68 | Type text. 69 | 70 | 71 | ## Title (Introductory element — Main element — Part : Part title) 72 | 1 Scope (mandatory) 73 | 74 | Type text. 75 | 76 | 2 Normative references (mandatory) 77 | 78 | Two options of text (remove the inappropriate option). 79 | 80 | 1) The normative references shall be introduced by the following wording. 81 | 82 | The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. 83 | 84 | ISO ##### #, General title — Part #: Title of part 85 | 86 | ISO ##### ##:20##, General title — Part ##: Title of part 87 | 88 | 2) If no references exist, include the following phrase below the clause title: 89 | There are no normative references in this document. 90 | 91 | 3 Terms and definitions (mandatory) 92 | 93 | Four options of text (remove the inappropriate options). 94 | 95 | 1) If all the specific terms and definitions are provided in Clause 3, use the following introductory text: 96 | 97 | For the purposes of this document, the following terms and definitions apply. 98 | 99 | 2) If reference is given to an external document, use the following introductory text: 100 | 101 | For the purposes of this document, the terms and definitions given in [external document reference xxx] apply. 102 | 103 | 3) If terms and definitions are provided in Clause 3, in addition to a reference to an external document, use the following introductory text: 104 | 105 | For the purposes of this document, the terms and definitions given in [external document reference xxx] and the following apply. 106 | 107 | 4) If there are no terms and definitions provided, use the following introductory text: 108 | 109 | No terms and definitions are listed in this document. 110 | 111 | The list below is always included after each option: 112 | 113 | ISO and IEC maintain terminological databases for use in standardization at the following addresses: 114 | 115 | — ISO Online browsing platform: available at https://www.iso.org/obp 116 | 117 | — IEC Electropedia: available at http://www.electropedia.org/ 118 | 119 | 120 | 3.1 121 | 122 | term 123 | 124 | text of the definition 125 | 126 | Note 1 to entry: Text of the note. 127 | 128 | [SOURCE: …] 129 | 130 | 3.2 131 | 132 | term 133 | 134 | text of the definition 135 | 136 | 4 Clause title 137 | 138 | Type text. 139 | 140 | 5 Clause title 141 | 142 | Type text. 143 | 144 | Use subclauses if required e.g. 5.1 or 5.1.1. For example: 145 | 146 | 5.1 Subclause 147 | 148 | 5.1.1 Subclause 149 | 150 | 6 Clause title 151 | 152 | Example of codes: 153 | 154 | ## Annex A 155 | 156 | (informative) 157 | 158 | Annex title e.g. Example of a figure and a table 159 | 160 | A.1 Clause title autonumber 161 | 162 | Use subclauses if required e.g. A.1.1 or A.1.1.1. For example: 163 | 164 | A.1.1 Subclause autonumber 165 | 166 | A.1.1.1 Subclause autonumber 167 | 168 | Type text. 169 | 170 | Dimensions in millimetres 171 | 172 | ## Bibliography 173 | 174 | [1] ISO ##### #, General title — Part #: Title of part 175 | 176 | [2] ISO ##### ##:20##, General title — Part ##: Title of part 177 | -------------------------------------------------------------------------------- /governance/8._Code_of_Conduct.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. 6 | 7 | We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. 8 | 9 | ## Our Standards 10 | 11 | Examples of behavior that contributes to a positive environment for our community include: 12 | 13 | * Demonstrating empathy and kindness toward other people 14 | * Being respectful of differing opinions, viewpoints, and experiences 15 | * Giving and gracefully accepting constructive feedback 16 | * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience 17 | * Focusing on what is best not just for us as individuals, but for the overall community 18 | 19 | Examples of unacceptable behavior include: 20 | 21 | * The use of sexualized language or imagery, and sexual attention or 22 | advances of any kind 23 | * Trolling, insulting or derogatory comments, and personal or political attacks 24 | * Public or private harassment 25 | * Publishing others' private information, such as a physical or email 26 | address, without their explicit permission 27 | * Other conduct which could reasonably be considered inappropriate in a 28 | professional setting 29 | 30 | ## Enforcement Responsibilities 31 | 32 | Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. 33 | 34 | Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. 35 | 36 | ## Scope 37 | 38 | This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. 39 | 40 | ## Enforcement 41 | 42 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement as set forth in the repository's Notice.md file. All complaints will be reviewed and investigated promptly and fairly. 43 | 44 | All community leaders are obligated to respect the privacy and security of the reporter of any incident. 45 | 46 | ## Enforcement Guidelines 47 | 48 | Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: 49 | 50 | ### 1. Correction 51 | 52 | **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. 53 | 54 | **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. 55 | 56 | ### 2. Warning 57 | 58 | **Community Impact**: A violation through a single incident or series of actions. 59 | 60 | **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. 61 | 62 | ### 3. Temporary Ban 63 | 64 | **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. 65 | 66 | **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. 67 | 68 | ### 4. Permanent Ban 69 | 70 | **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. 71 | 72 | **Consequence**: A permanent ban from any sort of public interaction within the project community. 73 | 74 | ## Attribution 75 | 76 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, 77 | available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. 78 | 79 | Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). 80 | 81 | [homepage]: https://www.contributor-covenant.org 82 | 83 | For answers to common questions about this code of conduct, see the FAQ at 84 | https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. 85 | -------------------------------------------------------------------------------- /governance/Readme.md: -------------------------------------------------------------------------------- 1 | # Community Specification 2 | 3 | This project utilizes the [Community Specification License and Framework](https://communityspec.dev) for contributions to the specification deliverable. 4 | 5 | ## What is the Community Specification For? 6 | 7 | The Community Specification process is a repository-based approach for creating standards and specifications in version control systems, such as Git. 8 | 9 | ## What is the benefit? 10 | 11 | The Community Specification allows you to start a specification development effort as easily as an open source project. The Community Specification incorporates the terms and processes required for standards and specification development, including legal terms, intellectual property issues, due process, and governance. It also provides the mechanisms to allow your project to grow and scale. For example, the Community Specification provides the basis to take your specification to other standards bodies, including international standards bodies, for formal standardization if your community desires to pursue those options. 12 | 13 | ## How to get started? 14 | 15 | Instructions for using the Community Specification are included in the ..Getting Started.md file. 16 | 17 | ## Could I just use an open source license for my specifications? Why should I use a specification license? 18 | 19 | Open source is collaboration around a specific codebase, while specifications provide a blueprint developers implement in different ways in many different codebases. Accordingly, open source licenses provide terms to use and modify a particular codebase and specification licenses are designed to provide terms for separate independent implementations of the specification. Because of this, if you use an open source license for specifications, people implementing those specifications may be doing so without the meaningful copyright or patent grants that you expect. 20 | 21 | A second difference is that common open source software and specification licenses tend to have different coverage scopes for intellectual property terms. Open source licenses generally grant terms scoped only to a contributor's contributions. Specification licenses, however, generally cover implementations of the entire specification, regardless of who made the actual contribution. Because the specification will often be developed with contributions from multiple organizations, the various contributing organizations will often want to review and approve the full specification before extending patent commitments to the final, combined result. 22 | 23 | ## Who developed the Community Specification 24 | 25 | The Community Specification has been developed via the [Joint Development Foundation](http://www.jointdevelopment.org), with inspiration from the [Open Web Foundation agreements](http://openwebfoundation.org) and the [Alliance for Open Media Patent License 1.0](http://aomedia.org/license/patent-license/). 26 | -------------------------------------------------------------------------------- /ns/v0.2.0/README.md: -------------------------------------------------------------------------------- 1 | # JSON-LD Context 2 | 3 | This directory contains v0.2.0 of the OpenVEX JSON-LD context. This file is intended 4 | to be consumed via the OpenVEX context URL: 5 | 6 | https://openvex.dev/ns/v0.2.0/ 7 | 8 | The most recent version of the context file should always be linked at the root 9 | directory of the repository. 10 | 11 | -------------------------------------------------------------------------------- /ns/v0.2.0/context.json: -------------------------------------------------------------------------------- 1 | { 2 | "xsd": "http://www.w3.org/2001/XMLSchema#", 3 | "rdfs": "http://www.w3.org/2000/01/rdf-schema#", 4 | "openvex": "https://openvex.dev/ns/v0.2.0#", 5 | "author": { 6 | "@id":"openvex:author", 7 | "@type": "xsd:string" 8 | }, 9 | "role": { 10 | "@id": "openvex:role", 11 | "@type": "xsd:string" 12 | }, 13 | "version": { 14 | "@id": "openvex:version", 15 | "@type": "xsd:integer" 16 | }, 17 | "softwareIdentifier": { 18 | "@id":"openvex:softwareIdentifier", 19 | "@type": "xsd:string" 20 | }, 21 | "vexStatus": { 22 | "@id":"openvex:vexStatus", 23 | "@type":"xsd:string" 24 | }, 25 | "status": { 26 | "@type": "openvex:vexStatus", 27 | "@id": "openvex:status" 28 | }, 29 | "timestamp": { 30 | "@type": "xsd:dateTime", 31 | "@id": "openvex:timestamp" 32 | }, 33 | "name": { 34 | "@type": "xsd:string", 35 | "@id": "openvex:vulnName" 36 | }, 37 | "hashes": { 38 | "@id": "openvex:hash", 39 | "@type": "xsd:string", 40 | "@container": "@index" 41 | }, 42 | 43 | "statements": { 44 | "@id": "openvex:statement", 45 | "@type":"openvex:vexStatement", 46 | "@container":"@set" 47 | }, 48 | "subcomponents": { 49 | "@id":"openvex:subcomponent", 50 | "@type":"openvex:component", 51 | "@container":"@set" 52 | }, 53 | "products": { 54 | "@id": "openvex:product", 55 | "@container": "@set", 56 | "@context": {} 57 | }, 58 | 59 | "identifiers": { 60 | "@id": "openvex:identifier", 61 | "@type": "openvex:softwareIdentifier", 62 | "@container": "@index" 63 | }, 64 | 65 | "vulnerability": { 66 | "@id": "openvex:vulnerability", 67 | "@context": { 68 | "name": { 69 | "@id": "openvex:name", 70 | "@type": "openvex:vulnName" 71 | }, 72 | "aliases": { 73 | "@id":"openvex:alias", 74 | "@type":"openvex:vulnName", 75 | "@container":"@set" 76 | } 77 | } 78 | } 79 | } 80 | -------------------------------------------------------------------------------- /openvex_json_schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://json-schema.org/draft/2020-12/schema", 3 | "$id": "https://github.com/openvex/spec/openvex_json_schema_0.2.0.json", 4 | "title": "OpenVEX", 5 | "description": "OpenVEX is an implementation of the Vulnerability Exploitability Exchange (VEX for short) that is designed to be minimal, compliant, interoperable, and embeddable.", 6 | "type": "object", 7 | "$defs": { 8 | "vulnerability": { 9 | "type": "object", 10 | "properties": { 11 | "@id": { 12 | "type": "string", 13 | "format": "iri", 14 | "description": "An Internationalized Resource Identifier (IRI) identifying the struct." 15 | }, 16 | "name": { 17 | "type": "string", 18 | "description": "A string with the main identifier used to name the vulnerability." 19 | }, 20 | "description": { 21 | "type": "string", 22 | "description": "Optional free form text describing the vulnerability." 23 | }, 24 | "aliases": { 25 | "type": "array", 26 | "uniqueItems": true, 27 | "items": { 28 | "type": "string" 29 | }, 30 | "description": "A list of strings enumerating other names under which the vulnerability may be known." 31 | } 32 | }, 33 | "required": [ 34 | "name" 35 | ], 36 | "additionalProperties": false 37 | }, 38 | "identifiers": { 39 | "type": "object", 40 | "properties": { 41 | "purl": { 42 | "type": "string", 43 | "description": "Package URL" 44 | }, 45 | "cpe22": { 46 | "type": "string", 47 | "description": "Common Platform Enumeration v2.2" 48 | }, 49 | "cpe23": { 50 | "type": "string", 51 | "description": "Common Platform Enumeration v2.3" 52 | } 53 | }, 54 | "additionalProperties": false, 55 | "anyOf": [ 56 | { "required": ["purl"] }, 57 | { "required": ["cpe22"] }, 58 | { "required": ["cpe23"] } 59 | ] 60 | }, 61 | "hashes": { 62 | "type": "object", 63 | "properties": { 64 | "md5": { 65 | "type": "string" 66 | }, 67 | "sha1": { 68 | "type": "string" 69 | }, 70 | "sha-256": { 71 | "type": "string" 72 | }, 73 | "sha-384": { 74 | "type": "string" 75 | }, 76 | "sha-512": { 77 | "type": "string" 78 | }, 79 | "sha3-224": { 80 | "type": "string" 81 | }, 82 | "sha3-256": { 83 | "type": "string" 84 | }, 85 | "sha3-384": { 86 | "type": "string" 87 | }, 88 | "sha3-512": { 89 | "type": "string" 90 | }, 91 | "blake2s-256": { 92 | "type": "string" 93 | }, 94 | "blake2b-256": { 95 | "type": "string" 96 | }, 97 | "blake2b-512": { 98 | "type": "string" 99 | } 100 | }, 101 | "additionalProperties": false 102 | }, 103 | "subcomponent": { 104 | "type": "object", 105 | "properties": { 106 | "@id": { 107 | "type": "string", 108 | "format": "iri", 109 | "description": "Optional IRI identifying the component to make it externally referenceable." 110 | }, 111 | "identifiers": { 112 | "$ref": "#/$defs/identifiers", 113 | "description": "Optional IRI identifying the component to make it externally referenceable." 114 | }, 115 | "hashes": { 116 | "$ref": "#/$defs/hashes", 117 | "description": "Map of cryptographic hashes of the component." 118 | } 119 | }, 120 | "additionalProperties": false, 121 | "anyOf": [ 122 | { "required": ["@id"] }, 123 | { "required": ["identifiers"] } 124 | ] 125 | }, 126 | "component": { 127 | "type": "object", 128 | "properties": { 129 | "@id": { 130 | "type": "string", 131 | "format": "iri", 132 | "description": "Optional IRI identifying the component to make it externally referenceable." 133 | }, 134 | "identifiers": { 135 | "$ref": "#/$defs/identifiers", 136 | "description": "A map of software identifiers where the key is the type and the value the identifier." 137 | }, 138 | "hashes": { 139 | "$ref": "#/$defs/hashes", 140 | "description": "Map of cryptographic hashes of the component." 141 | }, 142 | "subcomponents": { 143 | "type": "array", 144 | "uniqueItems": true, 145 | "description": "List of subcomponent structs describing the subcomponents subject of the VEX statement.", 146 | "items": { 147 | "$ref": "#/$defs/subcomponent" 148 | } 149 | } 150 | }, 151 | "additionalProperties": false, 152 | "anyOf": [ 153 | { "required": ["@id"] }, 154 | { "required": ["identifiers"] } 155 | ] 156 | } 157 | }, 158 | "properties": { 159 | "@context": { 160 | "type": "string", 161 | "format": "uri", 162 | "description": "The URL linking to the OpenVEX context definition." 163 | }, 164 | "@id": { 165 | "type": "string", 166 | "format": "iri", 167 | "description": "The IRI identifying the VEX document." 168 | }, 169 | "author": { 170 | "type": "string", 171 | "description": "Author is the identifier for the author of the VEX statement." 172 | }, 173 | "role": { 174 | "type": "string", 175 | "description": "Role describes the role of the document author." 176 | }, 177 | "timestamp": { 178 | "type": "string", 179 | "format": "date-time", 180 | "description": "Timestamp defines the time at which the document was issued." 181 | }, 182 | "last_updated": { 183 | "type": "string", 184 | "format": "date-time", 185 | "description": "Date of last modification to the document." 186 | }, 187 | "version": { 188 | "type": "integer", 189 | "minimum": 1, 190 | "description": "Version is the document version." 191 | }, 192 | "tooling": { 193 | "type": "string", 194 | "description": "Tooling expresses how the VEX document and contained VEX statements were generated." 195 | }, 196 | "statements": { 197 | "type": "array", 198 | "uniqueItems": true, 199 | "minItems": 1, 200 | "description": "A statement is an assertion made by the document's author about the impact a vulnerability has on one or more software 'products'.", 201 | "items": { 202 | "properties": { 203 | "@id": { 204 | "type": "string", 205 | "format": "iri", 206 | "description": "Optional IRI identifying the statement to make it externally referenceable." 207 | }, 208 | "version": { 209 | "type": "integer", 210 | "minimum": 1, 211 | "description": "Optional integer representing the statement's version number." 212 | }, 213 | "vulnerability": { 214 | "$ref": "#/$defs/vulnerability", 215 | "description": "A struct identifying the vulnerability." 216 | }, 217 | "timestamp": { 218 | "type": "string", 219 | "format": "date-time", 220 | "description": "Timestamp is the time at which the information expressed in the statement was known to be true." 221 | }, 222 | "last_updated": { 223 | "type": "string", 224 | "format": "date-time", 225 | "description": "Timestamp when the statement was last updated." 226 | }, 227 | "products": { 228 | "type": "array", 229 | "uniqueItems": true, 230 | "description": "List of product structs that the statement applies to.", 231 | "items": { 232 | "$ref": "#/$defs/component" 233 | } 234 | }, 235 | "status": { 236 | "type": "string", 237 | "enum": [ 238 | "not_affected", 239 | "affected", 240 | "fixed", 241 | "under_investigation" 242 | ], 243 | "description": "A VEX statement MUST provide the status of the vulnerabilities with respect to the products and components listed in the statement." 244 | }, 245 | "supplier": { 246 | "type": "string", 247 | "description": "Supplier of the product or subcomponent." 248 | }, 249 | "status_notes": { 250 | "type": "string", 251 | "description": "A statement MAY convey information about how status was determined and MAY reference other VEX information." 252 | }, 253 | "justification": { 254 | "type": "string", 255 | "enum": [ 256 | "component_not_present", 257 | "vulnerable_code_not_present", 258 | "vulnerable_code_not_in_execute_path", 259 | "vulnerable_code_cannot_be_controlled_by_adversary", 260 | "inline_mitigations_already_exist" 261 | ], 262 | "description": "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." 263 | }, 264 | "impact_statement": { 265 | "type": "string", 266 | "description": "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." 267 | }, 268 | "action_statement": { 269 | "type": "string", 270 | "description": "For a statement with affected status, a VEX statement MUST include a statement that SHOULD describe actions to remediate or mitigate the vulnerability." 271 | }, 272 | "action_statement_timestamp": { 273 | "type": "string", 274 | "format": "date-time", 275 | "description": "The timestamp when the action statement was issued." 276 | } 277 | }, 278 | "required": [ 279 | "vulnerability", 280 | "status" 281 | ], 282 | "additionalProperties": false, 283 | "allOf": [ 284 | { 285 | "if": { 286 | "properties": { "status": { "const": "not_affected" }} 287 | }, 288 | "then": { 289 | "anyOf": [ 290 | { "required": ["justification"]}, 291 | { "required": ["impact_statement"]} 292 | ] 293 | } 294 | }, 295 | { 296 | "if": { 297 | "properties": { "status": { "const": "affected" }} 298 | }, 299 | "then": { 300 | "required": ["action_statement"] 301 | } 302 | } 303 | ] 304 | } 305 | } 306 | }, 307 | "required": [ 308 | "@context", 309 | "@id", 310 | "author", 311 | "timestamp", 312 | "version", 313 | "statements" 314 | ], 315 | "additionalProperties": false 316 | } 317 | --------------------------------------------------------------------------------