diff --git a/.github/workflows/validate-schema.yml b/.github/workflows/validate-schema.yml index 6545dee93b1..4394b68cb34 100644 --- a/.github/workflows/validate-schema.yml +++ b/.github/workflows/validate-schema.yml @@ -2,12 +2,12 @@ name: Validate JSON Schemas on: push: branches: - - master + - main pull_request: types: [opened, synchronize, reopened] workflow_dispatch: branches: - - master + - main env: CVE_SCHEMA_DIR: schema CVE_SCHEMA_FILENAME: CVE_Record_Format.json @@ -22,7 +22,6 @@ jobs: - name: Install schema2markmap NPM dependencies run: | npm --prefix "${CVE_SCHEMA_DIR}/support/schema2markmap" install "${CVE_SCHEMA_DIR}/support/schema2markmap" - # Rename the schema, since AJV doesn't like non-".json" extensions - name: Prepare schema for bundling run: | sed 's/file\://g' "${CVE_SCHEMA_DIR}/${CVE_SCHEMA_FILENAME}" > "${CVE_SCHEMA_DIR}/cve-schema.json" diff --git a/README.md b/README.md index 629a16c209d..697129efd28 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,113 @@ -# Current Version of CVE Record Format - -Major changes to cve-schema repo architecture!! if you have integrations that rely on the cve-schema repo structure, please review the changes here. The latest version of the CVE JSON record format is 5.1.0. A single schema file with bundled dependencies is available [here](https://github.com/CVEProject/cve-schema/blob/master/schema/docs/CVE_Record_Format_bundled.json). - -Note: The ADP functionality in the current schema is not yet deployed in CVE Services. The ADP functionality is currently under development and is for future use. - -Note: Please refer to the CVE Services page [here](https://www.cve.org/AllResources/CveServices) for known issues with the schema. - -# CVE Record Format Overview - -cve-schema specifies the CVE record format. This is the blueprint for a rich set of JSON data that can be submitted by CVE Numbering Authorities (CNAs) and Authorized Data Publishers (ADPs) to describe a CVE record. Some examples of CVE record data include CVE ID number, affected product(s), affected version(s), and public references. While those specific items are required when assigning a CVE, there are many other optional data in the schema that can be used to enrich CVE records for community benefit. - -### Learn - -Learn more about the CVE program at: https://www.cve.org/ - -This CVE record format is defined using JSON Schema. Learn more about JSON Schema at: https://json-schema.org/ . - -### Latest - -The latest version of the record format is 5.1.0. It is specified in the JSON schema at https://github.com/CVEProject/cve-schema/blob/master/schema/CVE_Record_Format.json - -A single schema file with bundled dependencies is at https://github.com/CVEProject/cve-schema/blob/master/schema/docs/CVE_Record_Format_bundled.json - -### Documentation and Guidance - -Documentation about this format is available at https://cveproject.github.io/cve-schema/schema/docs/ - -A mindmap version of the CVE record structure is at https://cveproject.github.io/cve-schema/schema/docs/mindmap.html - -More details about Product and Version Encodings in CVE JSON 5.1.0 record is at https://github.com/CVEProject/cve-schema/blob/master/schema/docs/versions.md - -### Examples - -A basic example of a full record in 5.1.0 format with minimally required fields is available at https://github.com/cveproject/cve-schema/blob/master/schema/docs/full-record-basic-example.json - -An advanced example of a full record in 5.1.0 format is available at https://github.com/cveproject/cve-schema/blob/master/schema/docs/full-record-advanced-example.json - -A basic example of a cnaContainer, to be used with CVE Services, is available at https://github.com/cveproject/cve-schema/blob/master/schema/docs/cnaContainer-basic-example.json - -An advanced example of a cnaContainer, to be used with CVE Services, is available at https://github.com/cveproject/cve-schema/blob/master/schema/docs/cnaContainer-advanced-example.json \ No newline at end of file +# CVE Record Format + +![GitHub Tag](https://img.shields.io/github/v/tag/cveproject/cve-schema) +![GitHub License](https://img.shields.io/github/license/cveproject/cve-schema) + +The **CVE Record Format** is the [JSON schema][json_schema] defining the +structure of CVE records. It was previously called the "CVE Schema." This +repository is maintained by the [CVE Quality Working Group][qwg] (QWG) under +the [QWG Charter][qwg_charter]. + +This repository is part of the [CVE Project][cve] and is governed by CVE's +[Professional Code of Conduct][coc]. + +--- + +## Read the Record Format + +The version of the schema found on the [`main` branch][branch_main] of this +repository is the current production version used by CVE Services. The +development version, which reflects work-in-progress changes planned for future +production versions, is found on the [`develop` branch][branch_develop]. + +### Production Version + +The current production version of the CVE Record Format is available in several +forms: + +- [Separate files][fmt_1] +- [Single file][fmt_2] +- [Interactive][fmt_3] +- [Mindmap][fmt_4] + +Additionally, the CVE Record Format incorporates mechanisms for encoding +product identity and version information, which are [documented in greater +detail][products_and_versions]. + +### Development Version + +The development version of the CVE Record Format can be found in the +[`develop` branch][branch_develop]: + +- [Separate files][fmt_5] + +## Examples + +- [Example with minimum required fields][ex_1] +- [More complete example][ex_2] +- [A basic example of a `cnaContainer`, to be used with CVE Services][ex_3] +- [An advanced example of a `cnaContainer`, to be used with CVE Services][ex_4] + +## Known Issues + +The CVE Services page on the CVE site tracks +[known issues with the CVE Record Format][known_issues]. + +## Contributing + +Work in this repository is managed by the CVE [Quality Working Group][qwg]. QWG +meetings are open to CVE authorized program members, including: + +- Members of the [CVE Board][cve_board] +- Representatives of [CVE Numbering Authorities (CNAs)][cve_cnas] +- Representatives of [Authorized Data Publishers (ADPs)][cve_adps] +- Participants from the [CVE Secretariat][cve_secretariat] (currently + [The MITRE Corporation][mitre]) + +On a case-by-case basis, the QWG can invite to participate, through consensus, +individuals who are not CVE program members. To request admission to the QWG, +please contact one of the QWG Co-Chairs, currently +[Chris Coffin (MITRE)][cochair_chris_coffin], +[MegaZone (F5)][cochair_megazone], or +[David Waltermire (GSA FedRAMP)][cochair_dave_waltermire]. + +Any individual is welcome to participate via [Issues][gh_issues], +[Discussions][gh_discussions], and [Pull Requests][gh_prs], including opening +issues, creating proposals, commenting on existing proposals in Pull +Requests, and asking questions about the Record Format. Decisions on how to +proceed with any proposal are made by the Quality Working Group via consensus. +Final authority for approving or rejecting changes to the CVE Record Format +lies with the [CVE Board][cve_board]. + +All participation in this project is subject to the rules and procedures of the +[CVE Professional Code of Conduct][coc]. + +[branch_develop]: https://github.com/CVEProject/cve-schema/tree/develop +[branch_main]: https://github.com/CVEProject/cve-schema/tree/main +[cve]: https://www.cve.org/ +[cve_board]: https://www.cve.org/ProgramOrganization/Board +[cve_cnas]: https://www.cve.org/ProgramOrganization/CNAs +[cve_adps]: https://www.cve.org/ProgramOrganization/ADPs +[cve_secretariat]: https://www.cve.org/ResourcesSupport/Glossary?activeTerm=glossarySecretariat +[coc]: https://www.cve.org/ResourcesSupport/AllResources/ProfessionalCodeOfConduct +[cochair_chris_coffin]: https://www.linkedin.com/in/christopher-coffin-1573437/ +[cochair_dave_waltermire]: https://www.linkedin.com/in/david-waltermire-024b1710a/ +[cochair_megazone]: https://www.linkedin.com/in/megazone/ +[ex_1]: https://github.com/cveproject/cve-schema/blob/main/schema/docs/full-record-basic-example.json +[ex_2]: https://github.com/cveproject/cve-schema/blob/main/schema/docs/full-record-advanced-example.json +[ex_3]: https://github.com/cveproject/cve-schema/blob/main/schema/docs/cnaContainer-basic-example.json +[ex_4]: https://github.com/cveproject/cve-schema/blob/main/schema/docs/cnaContainer-advanced-example.json +[fmt_1]: https://github.com/CVEProject/cve-schema/blob/main/schema/CVE_Record_Format.json +[fmt_2]: https://github.com/CVEProject/cve-schema/blob/main/schema/docs/CVE_Record_Format_bundled.json +[fmt_3]: https://cveproject.github.io/cve-schema/schema/docs/ +[fmt_4]: https://cveproject.github.io/cve-schema/schema/docs/mindmap.html +[fmt_5]: https://github.com/CVEProject/cve-schema/blob/develop/schema/CVE_Record_Format.json +[gh_issues]: https://github.com/CVEProject/cve-schema/issues +[gh_discussions]: https://github.com/CVEProject/cve-schema/discussions +[gh_prs]: https://github.com/CVEProject/cve-schema/pulls +[json_schema]: https://json-schema.org/ +[known_issues]: https://www.cve.org/AllResources/CveServices +[mitre]: https://www.mitre.org/ +[products_and_versions]: https://github.com/CVEProject/cve-schema/blob/main/schema/docs/versions.md +[qwg]: https://github.com/CVEProject/quality-workgroup +[qwg_charter]: https://github.com/CVEProject/quality-workgroup/blob/main/README.md diff --git a/rfds/0001-establishing-the-rfd-process.md b/rfds/0001-establishing-the-rfd-process.md new file mode 100644 index 00000000000..151e5e41529 --- /dev/null +++ b/rfds/0001-establishing-the-rfd-process.md @@ -0,0 +1,448 @@ +# Establishing the RFD Process + +| Field | Value | +|:-----------------|:----------------------| +| RFD Submitter | Andrew Lilley Brinker | +| RFD Pull Request | [RFD #0001](https://github.com/CVEProject/cve-schema/blob/main/rfds/0001-establishing-the-rfd-process.md) | + +## Summary +[summary]: #summary + +Introduce a Request for Discussion (RFD) process to manage changes to the +CVE Record Format. The goals of this process are to make proposals clearer and +easier for the [Quality Working Group][qwg] to assess, to provide a clear focal +point for community engagement with proposed changes, to increase the rigor of +the process for evolving the record format, and to provide a historic record of +prior proposals to help inform future work on the record format. + +## Problem Statement +[problem-statement]: #problem-statement + +Today, the process for evolving the CVE Record Format is often informal and +difficult to track, both as a participant in the CVE +[Quality Working Group][qwg] and for outside observers. + +This is true for several reasons. First, work within the QWG spans both a +private venue open to CVE Program participants and invited individuals (QWG +meetings and the QWG mailing list) and a public venue in which anyone may +comment (the [CVEProject/cve-schema][gh_repo] repository on GitHub). While the +QWG is generally welcoming to individuals who request admission and aren't [CVE +Program participants][qwg_members], this requirement to request admission does +create a barrier to participation that increases the friction of engaging with +CVE Project stakeholders. + +This dual-venue challenge also means that materials for proposals may be spread +across different venues: they may be shared directly with QWG members privately +via meetings and the QWG mailing list, or they may be found in Issues, +Discussions, and Pull Requests on the [cve-schema GitHub repository][gh_repo]. +While _eventually_ all proposals to amend the CVE Record Format must +materialize as Pull Requests on GitHub, this may procedurally occur after +de-facto approval via consensus by the QWG or a vote by the +[CVE Board][cve_board]. + +When proposals exist only within the QWG, they may be tracked informally in +ways which make it difficult to follow the status of proposals, both in terms +of whether they've been advanced by the QWG to the CVE Board for a vote, and +in terms of whether they've addressed all submitted concerns during the QWG's +process of deliberation. Given that the QWG is governed by consensus, in the +style of the [IETF's "lack of disagreement" / humming standard][ietf_humming], +difficulty tracking the status of open items of disagrement becomes a +meaningful barrier to progress of items out of the QWG and up to the CVE Board +for a vote. + +What's more, this messiness also makes it difficult to reconstruct a historical +record of what proposals have been considered, what trade-offs or alternatives +were part of that consideration, or even what may have motivated a prior +change. This kind of record of deliberation can be invaluable for future +efforts to review, reconsider, or expand upon prior decisions. + +In summary, the central goal of this proposal to introduce an RFD process is to +make the process of amending the CVE Record Format more [_legible_][slas], both +to members of the Quality Working Group and to outside participants. + +For QWG members, an RFD proposal can collect open questions which have not yet +been resolved by consensus, and identify use cases, goals, and other +considerations underlying proposals. The discussion around an RFD's Pull +Request can also become a focal point for collecting such feedback in advance +of actual implementation, helping to centralize any digital discussions and +thus make the process of participating in the QWG smoother and less +time-consuming. + +For outside participants, an RFD provides a convening place for feedback and +input which can happen contemporaneously with the QWG's own deliberation. By +commenting on an RFD, an outside contributor can be sure they are providing +timely input on a proposal which is still under active consideration, and can +have a better view into the reasoning which may be behind such a proposal. +This should help to make the process of gathering and organizing community +feedback easier on both sides. + +Tracking RFDs would also become a way for engaged consumers of CVE records to +stay informed about upcoming changes before they land in the CVE Services +[live testing environment][cve_test_env] or are rolled out to production users. + +## Proposed Solution +[proposed-solution]: #proposed-solution + +We propose introducing a "Request for Discussion" (RFD) process, modeled after +similar processes such as: + +- [The Oxide Computer Company's RFD process.][rfds_oxide] +- [The Python PEP process.][pep_python] +- [The OpenJDK JEP process.][jep_openjdk] +- [The Rust RFC process.][rfc_rust] + +Broadly, an RFD process is a process by which proposals for a project are made +in the form of detailed documents, which are submitted by an initial submitter, +workshopped via feedback by project stakeholders, and then eventually accepted +or rejected. Accepted RFDs are then tracked in a formal tracking system, +forming a written historic record of proposed and implemented changes for the +project. + +In our case, we propose adopting an RFD process to manage proposals to amend +the CVE Record Format. The remainder of this section will try to answer key +questions about this process, including: + +- Who can submit an RFD? +- What should require an RFD? +- How are RFDs submitted? +- What process would RFDs follow after submission? +- What happens to rejected RFDs? +- What happens to accepted RFDs? + +### Who can submit an RFD? + +RFDs may be submitted by participants in the [CVE Quality Working Group][qwg]. + +The QWG is open for participation by [CVE Project participants][qwg_members], +including: + +- Members of the CVE Board +- Representatives of CVE Numbering Authorities +- Representatives of Authorized Data Publishers +- Participants from the CVE Secretariat (currently The MITRE Corporation) + +On a case-by-case basis, the QWG can invite to participate, through consensus, +individuals who are not CVE program members. To request admission to the QWG, +please contact one of the QWG Co-Chairs. + +Individuals wishing to submit an RFD who are not QWG participants should first +request admittance to participate prior to submitting the RFD, so that they +can be present for direct synchronous discussions about their proposal. If the +scheduled time for synchronous QWG meetings is not workable for an RFD +proposer then alternative QWG meeting times or special briefings to inform the +QWG members may be discussed and approved by the QWG. + +RFDs submitted by individuals who are not QWG participants and have not +requested participation in the QWG will be responded to with a prompt to +participate in the QWG. If the submitter does not respond in a timely manner or +declines to engage with the QWG, then the RFD will be closed and rejected, +though the rejection will not preclude future consideration of the merits of +the contents of the RFD if proposed at a future time consistent with the +requirements of the RFD process. + +### What Should Require an RFD? + +Changes to the CVE Record Format of the following types will require an +approved RFD prior to implementation: + +1. Adding, modifying, or removing fields +2. Adding, modifying, or removing data constraints + +Changes to the format that do not do either of the above do not require an +RFD, although RFDs could still be submitted to aid in discussion and tracking +of a proposal. Other kinds of changes might include updating or adding +descriptions to fields, or adding or modifying field examples. + +In general, if you are in doubt about whether a proposal should start with an +RFD, ask the Quality Working Group. + +### How are RFDs submitted? + +RFDs should be submitted as Pull Requests against the [CVEProject/cve-schema +Git repository on GitHub][gh_repo], made against the +[`develop`][gh_repo_develop] branch. The precise steps for submitting a new +RFD are: + +- [Fork the CVEProject/cve-schema repository][gh_forking] to your own user + account. +- [Create a new branch for your RFD proposal][gh_branching], branching off of + the `develop` branch from CVEProject/cve-schema. +- In this new branch, copy the file `rfds/_TEMPLATE.md` from the root of your + checked out copy of your fork of CVEProject/cve-schema to a new file of the + form `rfds/0000-.md`, replacing `<TITLE>` with an [ASCII][ascii] title + for the RFD, with words separated by dashes. +- Complete the template as described within that copied document. The text in + each section of the template describes the substance of the material that + should be in that section. +- [Commit the changes][gh_commit] with a descriptive commit message describing + the proposal. +- [Open a pull request][gh_pr] from your feature branch to the `develop` branch on the + CVEProject/cve-schema repository. +- After the pull request is open, amend the RFD proposal file to link to that + Pull Request. Leave the RFD number as `0000`. Commit and push that + modification to the RFD file. If the RFD is accepted, the RFD number will be + modified by a QWG Co-Chair to take the next available integer ID for an RFD. + +### What process would RFDs follow after submission? + +The Quality Working Group operates by [consensus][ietf_humming], with +discussions taking place during QWG meetings. Submitted RFDs may be placed on +the agenda for discussion at future QWG meetings, and may remain as part of the +ongoing agenda of the QWG until a determination is reached to either advance +the proposal to the CVE Board for a final approval or rejection, or to not +advance the proposal. + +Additionally, both QWG members and outside stakeholders should voice open +questions or points of disagreement in the pull request for the RFD. These open +points should be tracked in a comment maintained by a QWG Co-Chair or by the +RFD submitter. The presence of tracked unresolved points of disagreement should +be treated as a blocker for the QWG to proceed with advancing an RFD to the +CVE Board. + +Final approval of all proposals for the CVE Record Format must be done by the +CVE Board. While the QWG has the power to refuse to advance a proposal to the +Board if they do not consider it worthwhile to pursue, the Board makes the +decision to approve or reject a proposal after the QWG advances it to them. + +When the CVE Board votes on a proposal advanced by the QWG, the results of that +vote shall be added to the discussion on the relevant RFD Pull Request by a +QWG Co-Chair. + +There is no set schedule by which an RFD must be considered, either by the QWG +or by the CVE Board, nor is there a set schedule for QWG meetings. The specific +schedule for QWG may vary at the discretion of the QWG Co-Chairs. Contact the +Co-Chairs for information on the current QWG meeting schedule. + +If an RFD remains unresolved and inactive for a period of 3 months (inactive +meaning no new points of discussion have been raised on the RFD's pull request +and the RFD has not been part of the agenda for meetings of the QWG or the +CVE Board), it may be closed by a QWG Co-Chair as a rejection. In which case it +may be resubmitted in the future as is the case with all rejections. + +If the QWG makes a determination to advance an RFD to the CVE Board, a Co-Chair +must make a comment on the RFD Pull Request indicating it has been advanced to +the Board. If the Board votes on the RFD, the results of that vote must be +recorded to the RFD Pull Request by a QWG Co-Chair. + +### What happens to rejected RFDs? + +Rejected RFDs will have their Pull Requests closed, with a final comment from +a representative of the QWG (usually a QWG Chair) indicating the disposition +of the group and optionally providing feedback on the proposal. + +Rejected RFDs may be re-proposed in the future, with a new RFD document, if +they address issues raised in a prior submission sufficiently well. RFDs which +are re-proposals should refer to and link to the Pull Request for the prior +instance of the RFD to provide a clear historic record. + +### What happens to accepted RFDs? + +Accepted RFDs, meaning RFDs which have been advanced to the CVE Board by the +QWG and which the CVE Board has voted to approve, will be merged into the +[CVEProject/cve-schema][gh_repo] repository via the following procedure. + +Upon acceptance of an RFD, a QWG Co-Chair will add a commit to the RFD's +Pull Request branch, updating the RFD document's RFD number in both the +filename prefix and within the header text of the RFD itself to use the +next-available integer ID. For example, if the most-recently-merged RFD had +the number #0003, the next RFD to be merged would use the ID #0004. + +After this commit is added, the Pull Request for the RFD will be merged by a +QWG Co-Chair, and a Tracking Issue will then be opened on the repository to +track progress on implementing the changes proposed in the RFD. The changes, +as they've in-principle been approved by the CVE Board as part of the process +of approving the RFD, will not need to be re-reviewed by the Board. + +When all implementation of the RFD is complete and has been merged, the +Tracking Issue will be closed and the changes proposed by the RFD and now +implemented subsequent to its merging will become part of the next release of +the CVE Record Format. + +If an RFD fails to pass its own self-defined success criteria within the +defined period, the changes described by the RFD will be rolled back. The +timeline for rollbacks will be coordinated between the QWG, the CVE Board, and +the AWG. Rollbacks do not require a new vote of the CVE Board or a re-review +by the QWG, except to coordinate the logistics of enacting a rollback and +communicating about it to CVE stakeholders. + +## Examples +[examples]: #examples + +This document itself, as the first RFD, is an example of the format of an RFD, +and of the process an RFD should follow for acceptance. + +As this RFD does not propose changes to the schema, this section does not +include any such example changes. In any RFD which does propose changes to the +CVE Record Format, examples should be provided in the "Examples" section, as +described in the RFD template. + +## Impact Assessment +[impact-assessment]: #impact-assessment + +The introduction of an RFD process comes with both benefits and costs. + +In terms of benefits, it helps to make the process of proposing and considering +changes to the CVE Record Format more rigorous, consistent, and transparent. +Members of the QWG can more easily track what proposals are currently open, and +what proposals have been approved but not yet implemented. For non-QWG +participants in the process, it becomes easier to identify when changes are +being discussed and to provide your independent perspective through engagement +in an RFD's Pull Request. + +RFD's also help to provide a historical record of prior accepted proposals, +including motivation and reasoning behind a proposal. This helps avoid future +"Chesterton's Fence" issues where no one involved in the QWG or the community +was present for the discussions around the introduction of a change in the +Record Format, and thus is unable to assess why such a change had been made. + +The inclusion of success metrics and a rollback mechanism within the RFD +process should also help to avoid situations where changes are made to the +format which turn out to be unnecessary and are not widely adopted by the +CVE ecosystem. Rather than new unused features becoming dead weight in the +specification, there can be a well-understood process for their removal. + +In terms of costs, the introduction of an RFD process makes proposing changes +to the CVE Record Format more time-consuming. Proposers now need to produce a +detailed written document capturing their proposal and the evidence for it +being worthwhile, which may be a barrier to new proposals. In practice this +may still be comparable to the current more ad-hoc process which often involves +the production of presentation slides, written documents, and code changes +which are submitted and shared across QWG meetings and public Pull Requests. + +RFDs also do not resolve dysfunction regarding divergence of values or goals +among the QWG or between CVE and its stakeholders. As the QWG operates by +consensus, an inability to reach consensus can, despite the RFD process, still +result in deadlock and an inability to proceed in making changes. + +## Compatibility and Migration +[compatibility-and-migration]: #compatibility-and-migration + +There are no compatibility or migration concerns for this RFD, as it concerns +the establishment of the RFD process itself, and does not contain any proposals +for amending the CVE Record Format. + +## Success Metrics +[success-metrics]: #success-metrics + +6 months after the acceptance and adoption of this RFD process, the QWG should +solicit a survey to QWG members and outside CVE stakeholders about the value +of the RFD process. The results of that survey will be scored and compared +against a threshold, and if the average results of the survey do not pass the +required minimum threshold to indicate worthwhile value from the process, then +the RFD process will be rolled back and will not be required for future +proposals. + +To limit the possibility of "gaming" the survey by choosing questions +after-the-fact which may unduly influence the outcome of the survey, the +questions to be used are included in this RFD proposal, and shall not be +changed when the survey is held. + +The initial questions on the survey will be used to determine whether answers +will be considered for scoring. Anyone who answers "false" to both of the +following questions will not have their answers considered for the purpose of +scoring the survey results to determine whether the RFD has succeeded at its +success metric: + +1. "I am a participant in the CVE Quality Working Group (have attended at least + one CVE QWG meeting in the past six months)" +2. "I am a CVE ecosystem stakeholder (have consumed CVE records in the past six + months)" + +All other question answers are given on a 5-level Likert scale, with each +answer being assigned a point value, as follows: + +- Strongly disagree (1 point) +- Disagree (2 points) +- Neither agree nor disagree (3 points) +- Agree (4 points) +- Strongly agree (5 points) + +The questions will be: + +3. "The CVE QWG's RFD process has made tracking the status of proposals to + amend the CVE Record Format easier." +4. "The CVE QWG's RFD process has improved the level of rigor applied to + proposals to amend the CVE Record Format." +5. "The CVE QWG's RFD process has made it easier to gather input on proposals + to amend the CVE record format from QWG members." +6. "The CVE QWG's RFD process has made it easier to gather input on proposals + to amend the CVE Record Format from outside stakeholders." + +To score the results, consider only answers from respondents who answered +"true" to at least one of the two qualification questions (questions 1 and 2). +Then add up the scores for all Likert scale questions from all qualifying +respondents. Add up the total scores for all qualifying respondents, and divide +them by the number of qualifying respondents. + +If the average total score is greater than 12, the success criteria has been +met, and the RFD will not be rolled back. + +If the average total score is less than or equal to 12, the success criteria +has not been met, and the RFD will be rolled back. + +12 is chosen as the threshold as it would be the total score for an all-neutral +set of responses from a single respondent. + +## Supporting Data or Research +[supporting-data-or-research]: #supporting-data-or-research + +RFD processes are well-attested within software communities. Some existing +RFD-equivalent processes are identified in the "Proposed Solution" section +above, and this is not an exhaustive list of such processes. + +In general, RFD processes are desirable in large, multi-stakeholder projects +where the threshold for enacting changes ought to be high because the impact +of any changes is broad, and where there is a broad set of stakeholders who +need to coordinate and be involved in deliberation around changes. + +The demand for this process comes from the QWG itself. QWG members have +expressed concern with a lack of rigor in the QWG's process for considering +proposals, including challenges with tracking the state of proposals, recording +evidence and success metrics, recalling key arguments for or against proposals, +and otherwise tracking and following the status of discussions around a +proposal. + +## Related Issues or Proposals +[related-issues-or-proposals]: #related-issues-or-proposals + +There are currently no alternative proposals open with the QWG to amend the +process of considering changes to the CVE Record Format. + +Alternate processes might be considered, but we do not present alternative +procedural designs here. + +## Recommended Priority +[recommended-priority]: #recommended-priority + +Medium + +## Unresolved Questions +[unresolved-questions]: #unresolved-questions + +None currently. + +## Future Possibilities +[future-possibilities]: #future-possibilities + +Future amendments to the RFD process itself may be warranted, or other +procedural changes to how the QWG operates. For example, clearer membership +rules and procedures, or a transition from a consensus to a voting-based +process for making recommendations to the CVE Board. + +[ascii]: https://developer.mozilla.org/en-US/docs/Glossary/ASCII +[cve_board]: https://www.cve.org/ProgramOrganization/Board +[cve_test_env]: https://www.cve.org/allresources/cveservices#TestEnvironment +[gh_branching]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository +[gh_commit]: https://github.com/git-guides/git-commit +[gh_forking]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo +[gh_pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request +[gh_repo]: https://github.com/CVEProject/cve-schema +[gh_repo_develop]: https://github.com/CVEProject/cve-schema/tree/develop +[ietf_humming]: https://datatracker.ietf.org/doc/html/rfc7282 +[jep_openjdk]: https://openjdk.org/jeps/1 +[qwg]: https://github.com/CVEProject/quality-workgroup +[qwg_members]: https://github.com/CVEProject/quality-workgroup?tab=readme-ov-file#2-working-group-membership +[pep_python]: https://peps.python.org/pep-0001/ +[rfc_rust]: https://github.com/rust-lang/rfcs/blob/master/text/0002-rfc-process.md +[rfds_oxide]: https://rfd.shared.oxide.computer/rfd/0001 +[slas]: https://en.wikipedia.org/wiki/Seeing_Like_a_State diff --git a/rfds/0002-supporting-package-urls.md b/rfds/0002-supporting-package-urls.md new file mode 100644 index 00000000000..a5e9022fd91 --- /dev/null +++ b/rfds/0002-supporting-package-urls.md @@ -0,0 +1,404 @@ +# Supporting Package URLs in CVE + +| Field | Value | +|:-----------------|:-------| +| RFD Submitter | Andrew Lilley Brinker | +| RFD Pull Request | [RFD #2](https://github.com/CVEProject/cve-schema/pull/407) | + +## Summary +[summary]: #summary + +Today, CVE records support identifying affected products and packages via an +`affected` array, the objects within which contain both "identifier-like" and +"version-like" fields. The "identifier-like" fields are used to indicate +specific software, while the version like fields set either a blanket status +for all instances of that software, or set specific statuses for defined +version ranges. The "identifier-like" fields are in two forms: a `vendor` and +`product` together, or a `collectionURL` and `packageName` together. + +These `affected` product entries may also include a list of `cpes`, meaning +Common Platform Enumeration (CPE) identifiers. In 2024, recognizing limitations +of this `cpes` array within the context of the `affected` array and wanting to +aid the enrichment of CVE records with CPE data in a familiar format, the +CVE project adopted an additional `cpeApplicability` structure, separate from +the `affected` array. + +Together these two structures, the `affected` array and the `cpeApplicability` +object, allow CVE consumers to determine the applicability of a CVE by +comparing them against software identifiers associated with software they use. + +While these structures are valuable to CVE consumers, they also face +limitations. CPEs are not used universally across software ecosystems, with +limited coverage of open source software (OSS) projects in particular. While +CPEs are well suited for identifying software produced by commercial entities, +the central nature of the CPE Dictionary faces scaling challenges dealing with +the large and ever-growing scope of open source software distributed across +disprarate package hosts. + +This proposal describes CVE record format changes to amend CVE’s `affected` +array to support the use of an additional software identifier format, Package +URLs, via addition of new optional fields for objects within the `affected` +array. + +While the proposal only includes support for the CPE and Package URLs formats, +their inclusion provides a template for the potential addition of other software +identification formats, should that be seen as useful by the CVE user community +and Board. + +All changes described here are backwards-compatible with the CVE record format +as it exists today. Under the SchemaVer versioning scheme adopted by CVE for +the record format, these changes are ADDITION-level changes, which are +compatible with all historic CVE data. + +## Problem Statement +[problem-statement]: #problem-statement + +While the `affected` array's "identifier-like" fields, the `cpes` array, and +the `cpeApplicability` structure provide mechanisms to express applicability +for many key vendors, they are also not the whole answer to the challenge of +matching vulnerabilities to affected systems. + +For CPE, the key challenges are its reliance on a central dictionary and the +processes used to update that dictionary. NIST, the United States' National +Institute of Standards of Technology, stewards the CPE specification and +maintains the CPE Dictionary, which is the central registry of defined terms +which may be used to identify vendors, products, and more within a CPE +identifier. The reliance on this central dictionary means that the issuance of +new CPEs for vendors or products not present in the dictionary requires NIST +to update the dictionary to support them. While anyone can request the creation +of a CPE from NIST, NIST may at times be slow to respond to these requests due +to resource limitations. + +Mechanical applicability determinations—especially searches of CVE data based +on software identifiers—are compromised if the searcher cannot rely on the +identifiers to be available when and where they are needed. + +Moreover, some vulnerability conditions cannot be expressed adequately using +CPE. For example, sometimes a vulnerability is only present when certain +modules or files are present, but CPEs do not capture software at the module or +file level. To put it another way, CPE is a relatively coarse-grained software +identifier, identifying software “products,” potentially constrained with +version information, but not components or materials within those software +products. While the `affected` array provides fields to constrain applicability +at a greater level of granularity, the `cpeApplicability` object does not, and +there is substantial ambiguity in interpreting the `cpes` field within the +`affected` array's product objects, which was part of the motivation for the +introduction of the `cpeApplicability` structure. + +CPEs are also not used universally across different software ecosystems. Open +source software projects are generally less well represented in the +NIST-maintained CPE dictionary than closed source software. This means sole +reliance on CPE as the mechanism for identifying software within the CVE record +format leaves CVE less able to identify open source software affected by a +vulnerability. + +As for the `affected` array's "identifier-like" fields, there are two variants +to assess. First, a `vendor` and `product` pair; second, a `collectionURL` and +`packageName`. + +For the `vendor` and `product` pair, they are potentially useful for human +interpreters, but are of limited value for automated applicability matching. +They express similar information to what is found within a CPE, but because +they are not constrained to use well-known terms defined within a central +dictionary, there is substantial risk of divergence, where the terms used by +a CNA to identify the vendor or product may not match the terms used by +downstream consumers to search for or match against records to determine +applicability. + +For the `collectionURL` and `packageName` pair, these function similarly to a +Package URL, but again lack a well-defined construction to ensure consistency +and easy automated cross-referencing between datasets. The `collectionURL` +field provides many example, but is not constrained beyond requiring a valid +URI. The `packageName` field is entirely unconstrained. Similarly to the first +option for identifying affected products, they are most useful for human +matching of CVE records, but not for automated processing of applicability at +scale. + +## Proposed Solution +[proposed-solution]: #proposed-solution + +Expanding the set of software identifiers that are available for use in +expressing software applicability statements gives additional tools to parties +writing and enriching CVE records to better identify the software impacted by a +vulnerability. In particular, Package URLs are widely used today by open source +software communities and are better suited than CPEs for capturing distinctions +between different distributions of particular open source software. + +Expanding the set of identifier types within the `affected` array to include +Package URLs will result in an expansion of coverage and of the expressiveness +of CVE's applicability data. + +The specific schema edit is as follows: + +### Add a field for Package URLs within the `affected` product object + +This adds a field to the `product` object, which is the object contained +within the `affected` array, called `packageURL`. This field is constrained +within the JSON schema to accept a valid URI, and would be further constrained +by CVE Services (the actual API used for submitting CVE data by CNAs and ADPs) +to ensure those URIs are valid Package URLs. + +This validation of Package URLs would not be done within the CVE Record Format +itself due to limitations of the syntactic validation facilities of JSON Schemas +and the complexity of the syntax for Package URLs. The Package URL specification +encodes a variety of naming constraints taken from the registered package hosts, +to ensure that packages identified within a Package URL have names which are +considered valid within their chosen package ecosystem. Encoding this wealth +of constraints within a Regular Expression in the CVE Record Format itself +would be excessive and difficult to maintain as new package types are added to +the Package URL specification in the future. + +Additionally, Package URLs added via this new field will __not__ be allowed to +include versions. All version information should only be included within the +existing `versions` field of the `product` object. + +This field will be an optional new field on the `product` object, and so would +still need to be used in conjunction with one of the existing sets of +"identifier-like" fields: `vendor` and `product` and/or `collectionURL` and +`packageName`. + +### Use of this as a template for future identifiers + +This proposal is intended as a template for the introduction of more types of +identifiers in the future. Specifically, future identifiers should be added +as fields within the `affected` array's `product` object, made into options +for the identifier-like field requirement currently applied to `vendor` and +`product` or `collectionURL` and `packageName`, and have additional constraints +added as appropriate to ensure `product` objects can't be made with nonsensical +field combinations. + +Additionally, if an identifier may optionally embed version information, that +version inclusion should be disallowed within the CVE Record Format. This is +to ensure that version information within the affected array, if present, is +_only_ ever found within the `versions` field. This keeps discovery and handling +of versions for CVE consumers simple and consistent. + +### Vendoring of the relevant specifications + +To ensure consistency about new identifier types added, the CVE project +should "vendor," meaning maintain its own public copy of, the relevant +specifications for Package URLs. The Package URL specification is currently +un-versioned and actively developed on GitHub. While the specification is +undergoing standardization with ECMA, a standards organization, that work is +ongoing and has not yet produced a stable, versioned instance of the Package +URL specification. Vendoring a specific reference-able version of the +Package URL specification will help ensure clarity about what "Package URL" +means in the context of a CVE record. + +## Examples +[examples]: #examples + +The following are examples of hypothetical CVE records with these new +identifier fields, presented as fragments showing only the `affected` array, +for concision. + +```json +"affected": [ + { + "collectionURL": "https://www.npmjs.com/package/fictional-package", + "packageName": "fictional-package", + "packageURL": "pkg:npm/fictional-package", + "programFiles": ["util.js"], + "versions": [ + { + "version": "6.3.1", + "status": "affected" + } + ] + } +] +``` + +## Impact Assessment +[impact-assessment]: #impact-assessment + +The proposal retains the existing CPE-centric applicability structure so as to +be completely backwards compatible. At some point in the future, it may be +worth converting existing CPE-specific applicability expressions to use the +format-neutral applicability expression structure – this should be trivial to +accomplish. However, in the near-term, the goal is full backwards +compatibility. + +The primary immediate impact would be for parties seeking to express +applicability statements for package-managed software. These parties would be +able to start using purls in applicability statements, which should be readily +available based on the package management system’s data. They will be able to +express applicability without needing to find or request a relevant CPE. + +The most significant concern that comes with supporting multiple software +identifier formats in CVE is the fact that it leads to the creation of +synonyms. This happens when a single application is associated with multiple +different software identifiers. This can happen when a single software +application has an identifier in both purl and CPE. It can also happen in purl +if are package-specific identifiers for an issue that is not package-specific. +(E.g., a vulnerability exists in the base software, but because purls are +package specific, they refer to the Debian, RPM, etc. distributions of that +base software.) This can result in false-negative results is there is a +mismatch between how software is identified in the CVE vs. how it is identified +in a query. For example, if the party authoring the CVE record uses purl to +express applicability, an attempt to compute applicability using a CPE will +fail, potentially resulting in a false-negative matching result. + +Since the primary intent of adding support for new identifier formats is to +cover gaps in CPE’s coverage, and because, when known, the new structure allows +multiple synonyms for a single software application to be captured, it remains +to be seen whether incomplete capture of synonyms occurs frequently enough to +cause problems. However, this issue will need to be monitored carefully since +frequent occurrences of incomplete synonym lists in CVE could negatively impact +the reliability of applicability evaluations. In the meantime, new conventions +have been identified to make it clearer when a CVE record author is capturing +synonyms for a given piece of software vs. noting multiple pieces of software +impacted by the same vulnerability. These conventions will need to be followed +across all parties that create and enrich CVE records. + +## Compatibility and Migration +[compatibility-and-migration]: #compatibility-and-migration + +This would be an `ADDITION`-level change. + +As noted above, the proposal is completely backwards compatible since it +retains the existing, CPE-centric applicability structures. Should measures of +the value of the new structures affirm its utility, it is likely worth +migrating all CPE-specific applicability statements to use the new +format-agnostic applicability statements and removing the CPE-specific +applicability structures from the CVE schema. Since the CPE-specific and +format-agnostic structures largely mirror each other, converting existing CVE +content to the new record format should be straightforward using simple +automation. + +Updating the infrastructure that parties use to consume CVE records to support +the new applicability format will likely take some time, but, again, the +similarity to the existing CPE-specific structure should make the process +relatively uncomplicated. Any conversion of the CVE corpus to exclusively use +the format-agnostic structure would only occur after CVE-consuming tools had +fully adopted those format-agnostic structures, and thus any eventual +conversion of the CVE corpus to use the new structures should have no impact on +CVE consumers. + +## Success Metrics +[success-metrics]: #success-metrics + +Validation of the new structures should be straightforward as they are captured +in a proposed JSON schema update. Adoption of new conventions to more clearly +manage synonyms will require additional steps since those conventions go beyond +what can be expressed in a JSON schema. Any tools used to generate CVE records +should be able to guide creators and highlight conditions where the given +structure is or is-not indicative of a synonym, but tools will be unable to +strictly enforce compliance with these conventions and it will be left to CVE +record creators and enrichers to correctly note synonyms where they occur. + +The success of this proposal will depend on the adoption of the new format, +Package URLs. There are two key measures of adoption: the degree to which these +new identifiers are added to CVE records when they are created and/or when they +are enriched, and the degree to which the new formats are used by CVE consumers +to determine applicability. + +The degree to which new identifier types appear in CVE records will be +relatively easy to measure as this can be computed using the CVE corpus. It +should be emphasized that comparisons of counts between CPE use and the use of +the other formats is unlikely to be useful since the formats serve different +needs. A better measure would be to determine whether each new format achieves +some critical mass of adoption. An initial suggestion for measures would be, +after a 6 month period, to look for approximately 5% of new CVEs having an +associated purl within 3 months of CVE creation. CVE may consider making +inclusion of software identifiers, including CPE or Package URLs a requirement +for CNA vulnrichment recognition with the Enrichment Recognition List. + +Measuring use by CVE consumers is a significantly larger challenge - the CVE +community does not currently have good measures of how often CPEs are used by +CVE consumers. A potential path would be to interview vulnerability management +tool vendors and SBOM management tool vendors, since many of these ingest and +process the CVE list, or the NVD list from which CVE’s support for CPE was +copied. Enquiring as to the role (any) software identifiers play in their +processes would provide a strong indication of the value these identifiers +provide. Of course, it will take vendors some time to adjust their processes. +As such, the measure might be to look for at least two vendors using the new +software identifier formats within a year of the adoption of the new formats. + +Adoption of a new format below a critical mass represents a problem since it +means that some number of CVE records include identifiers that are used +infrequently enough that the given identifier format is unlikely to provide +meaningful results. For example, if only a fraction of a percent of CVEs get +labeled with purls, then those purls might not be seen as needing CPEs, but +users might not feel purls were reliable enough to use due to their limited +coverage. If this happens, then the best way to back out the change would be to +create CPEs to replace the limited use of purls (which, if purl use is truly +limited, should not represent a significant lift) and then prohibit purls in +future CVEs. + +## Supporting Data or Research +[supporting-data-or-research]: #supporting-data-or-research + +The widespread use of purls within the open source community is well +documented. Similarly, the OSV vulnerability database has been using purls in +is software applicability expressions for years. Thus it seems probable that +purls will help simplify the creation of applicability expressions for the +open-source community. + +While the authors have no hard data on the impacts of using purls for capturing +software applicability to vulnerabilities, adoption of these new formats in CVE +will be measured using the aforementioned metrics. Should adoption be +insufficient to provide a benefit, the changes can be rolled back relatively +easily to avoid any potential downsides associated with this proposal. + +## Related Issues or Proposals +[related-issues-or-proposals]: #related-issues-or-proposals + +The gap in CPE’s coverage of software is a significant problem for its use in +expressing CVE applicability. One alternative would be to more heavily invest +in CPE creation to try to better close this coverage gap. In theory, +accelerating and expanding CPE creation would allow it to subsume the coverage +boost purl would provide. In practice, however, this seems highly unlikely. +For over a decade, NIST has tried to manage CPEs to keep pace with the needs of +CVE. However, the challenge and expense has proven to be significant and NIST +has expressed a desire to end its role as the provider of CPEs for CVEs. +Without a massive investment, it is unlikely that any party could produce CPEs +quickly enough to meet CVE’s needs. Moreover, even a complete CPE library would +not address CPE’s inability to capture vulnerabilities that depend on files or +modules, since those are beyond CPE’s ability to capture. + +Another alternative might be to completely replace CPE with another standard. +However, doing so ends up simply replacing one coverage gap with another while +creating a significant backwards compatibility problem. While purls can cover +all package-managed software, there is no practical proposal for them covering +software that doesn’t get distributed via a package-manager. As many major +vendors of significant interest to CVE users are not distributed via package +managers (e.g., Microsoft, Adobe, Oracle, etc.), a purl-only solution would +likely be unable to support much of the existing CVE corpus. + +A final option would be to do away with software identifier-based applicability +matching entirely. Ultimately, software identifiers are an intermediate +construct whose only real value is in their ability to serve as the connector +between data sets (e.g., between CVE records and software inventories). CVE +records almost always contain their applicability information within the prose +description of the vulnerability. However, while LLMs and similar methods can +make prose-based queries reasonably accurate, this requires fairly +sophisticated capabilities attached to both data sets, one to extract an +appropriate prose query and one to match it against a prose expression. +(E.g., one capability to extract the appropriate prose queries from a software +inventory, and then another capability to effect prose matching against the CVE +description.) While there may be ways to lower the difficulty of such prose +comparisons, no such mechanism has been publicly released. As a result, +automated applicability matching in the absence of intermediate identifiers +remains an unsolved problem. + +## Recommended Priority +[recommended-priority]: #recommended-priority + +Medium + +## Unresolved Questions +[unresolved-questions]: #unresolved-questions + +There are no remaining unresolved questions. + +## Future Possibilities +[future-possibilities]: #future-possibilities + +More identifier types may be desirable to add in the future. Any question of +what those types may be, or what they may look like within the CVE Record +Format, is not addressed here. + +It may be desirable to eventually permit new identifiers to fulfill the +"identifier-like" requirement on `product` objects, alongside `vendor` and +`product` and `collectionURL` and `packageName`. diff --git a/rfds/_TEMPLATE.md b/rfds/_TEMPLATE.md new file mode 100644 index 00000000000..22c7c3bf5a5 --- /dev/null +++ b/rfds/_TEMPLATE.md @@ -0,0 +1,184 @@ +# (Title) + +| Field | Value | +|:-----------------|:-------| +| RFD Submitter | (NAME) | +| RFD Pull Request | [RFD #0000](https://github.com/CVEProject/cve-schema/pull/1234) | + +## Summary +[summary]: #summary + +One paragraph explanation of the proposed schema change. + +## Problem Statement +[problem-statement]: #problem-statement + +Explain the motivation for the proposed change to the CVE Record Format, +including what problems it may solve for users of CVE, or what additional +capability it may provide. This should explain all necessary background in +detail, so it is understandable to someone without prior knowledge or +experience with the relevant problems. It should also make clear the severity +of the problem being described. + +The problem statement should describe who is affected by the problem, with +specific use cases where the proposed change would help users of CVE, whether +those users are CVE Numbering Authorities or Authorized Data Publishers +submitting data to CVE Services, or consumers of CVE data to forward to their +own customers or to manage their own security risks. + +This section should explicitly answer the question: "what happens if we do +nothing?" + +## Proposed Solution +[proposed-solution]: #proposed-solution + +Explain in detail the proposed change to the CVE Record Format, including +why those changes are made and how they will address the problems or provide +the capabilities described in the Problem Statement. This should be very +detailed, so as to make clear to reviewers exactly what is necessary to +implement the RFD if it is accepted. RFD proposal time is the time to identify +and resolve ambiguities and uncertainties in the actual schema changes +required for a proposal, as they provide the clearest opportunity for the +QWG members and community stakeholders to review and provide input on proposed +changes. + +If a change is to implemented in multiple parts or stages, those should be +delineated separately in the RFD document, to make clear what process would be +followed if it is accepted. + +## Examples +[examples]: #examples + +Provide examples of the relevant new or modified fields in the record format. +If an RFD is only proposing eliminating or deprecating existing fields, +examples should show what the relevant container objects would like after the +change, and how the reduced schema would continue to serve the needs and +interests of CVE users. + +Diagrams may also be included here to visualize the change in structure +proposed by an RFD. + +## Impact Assessment +[impact-assessment]: #impact-assessment + +Describe the benefits and possible risks associated with an RFD, including +the weaknening or strengthening of data quality constraints and any +requirements to enforce data quality rules via CVE Services application logic +(when not enforceable in the schema itself) or to communicate constraints or +expectations to CVE stakeholders. + +## Compatibility and Migration +[compatibility-and-migration]: #compatibility-and-migration + +Describe the impacts of the proposed change on both backward and forward +compatibility. + +To address backward compatibility, explain if and how your proposal would +impact users of the schema's ability to parse existing CVE records produced +under prior versions of the CVE Record Format. Note that CVE records returned +by CVE Services are automatically updated to use new schema versions, so +interaction with historic CVE records would only arise for records stored and +obtained outside of CVE Services. + +To address forward compatibility, explain if current users of the schema would +be able to parse all, some, or none of the records produced with the schema as +modified by your proposal. If CVE consumers would need to amend their existing +parsers for CVE records to be able to parse records produced under the new schema, +describe what amendments would be necessary for them. + +These explanations must specifically answer the following questions: + +1. Does your proposal modify an `enum` type to add, remove, or modify the set + of acceptable values? +2. Does your proposal modify a closed set of required fields to add a new + required field or a new alternative set of required fields? +3. Does your proposal involve the addition of a new format which CVE consumers + would need to parse? If it does include a new format... + 1. How complex is the format to parse? + 2. Are there parser implementations available under open source licenses, + and for what programming languages? + +You must also address considerations for planning migration of CVE stakeholders +to support your proposed changes. This includes both the impacts to CVE +producers, including CVE Numbering Authorities (CNAs) and Authorized Data +Publishers (ADPs), and impacts to CVE consumers. + +Considerations for migration, which must be addressed in your explanation, +include: + +1. How long should the proposed change be communicated to CVE stakeholders + before being implemented in production? +2. What testing would be needed before the change is implemented in production? + +As CVE is a large and multi-stakeholder system, detail and sensitivity in this +section of an RFD are extremely important. Particular scrutiny should be paid +by both RFD submitters and reviewers to understand the impacts of any proposed +change on all sides of the CVE system, including producers (CNAs, ADPs), +consumers, the CVE Board and Working Groups, and the Secretariat. + +## Success Metrics +[success-metrics]: #success-metrics + +Describe how success for an RFD will be determined, including expectations for +adoption of any new fields by CNAs or ADPs over a defined timeline. Also +describe any available options to assess adoption of new fields by CVE data +consumers, which may require engagement with known CVE consumer communities. + +Success metrics must include: + +- A fixed timeline for deciding success or failure. +- An unambiguous mechanism for determining success or failure. +- If the metric will involve qualitative assessment of success with CVE + stakeholders, for example via a survey or direct outreach, all questions for + this engagement must be pre-registered in the RFD. + +Describe a path to rollback RFD changes if the success metrics are not met +in the prescribed time. + +## Supporting Data or Research +[supporting-data-or-research]: #supporting-data-or-research + +Describe any evidence for the need to adopt the RFD proposal based on +community demand for specific new data or demand for better data quality. + +## Related Issues or Proposals +[related-issues-or-proposals]: #related-issues-or-proposals + +Identify other open proposals and alternative options which may be considered +by the QWG if the RFD is not deemed acceptable. Link to other proposals if +appropriate. + +## Recommended Priority +[recommended-priority]: #recommended-priority + +Identify a recommended priority for the proposal based on the RFD author's +assessment of the proposal's value and ecosystem demand. + +Possible values are: + +- __Low__: The RFD addresses minor inconsistencies or errors in the CVE Record + Format which ought to be fixed but which do not present a substantive problem + for CVE consumers. +- __Medium__: The RFD addresses a deficiency in the CVE Record Format which + limits the value CVE consumers get from CVE records. +- __High__: The RFD addresses a severe deficiency in the CVE Record Format + which is interfering with the ability of CVE consumers to manage risks from + vulnerabilities. + +## Unresolved Questions +[unresolved-questions]: #unresolved-questions + +Identify any unresolved questions related to the RFD. Ideally, all questions +listed in this section will be resolved during consideration of the RFD. +Questions which are deemed out of scope for an RFD should be moved to the +Future Possibilities section to make clear they remain open and can be the +subject of a future RFD. + +## Future Possibilities +[future-possibilities]: #future-possibilities + +Describe future extensions of the changes proposed in the RFD, including any +unresolved questions which the QWG may wish to resolve at a future date. If +an RFD is part of a larger strategy, identify the remaining steps in that +strategy to help contextualize the work of the RFD within the goals and values +of the QWG. diff --git a/schema/CVE_Record_Format.json b/schema/CVE_Record_Format.json index f74450c32c8..223e94b7fb3 100644 --- a/schema/CVE_Record_Format.json +++ b/schema/CVE_Record_Format.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://cveproject.github.io/cve-schema/schema/CVE_Record_Format.json", "title": "CVE JSON record format", - "description": "cve-schema specifies the CVE JSON record format. This is the blueprint for a rich set of JSON data that can be submitted by CVE Numbering Authorities (CNAs) and Authorized Data Publishers (ADPs) to describe a CVE Record. Some examples of CVE Record data include CVE ID number, affected product(s), affected version(s), and public references. While those specific items are required when assigning a CVE, there are many other optional data in the schema that can be used to enrich CVE Records for community benefit. Learn more about the CVE program at [the official website](https://cve.mitre.org). This CVE JSON record format is defined using JSON Schema. Learn more about JSON Schema [here](https://json-schema.org/).", + "description": "cve-schema specifies the CVE JSON record format. This is the blueprint for a rich set of JSON data that can be submitted by CVE Numbering Authorities (CNAs) and Authorized Data Publishers (ADPs) to describe a CVE Record. Some examples of CVE Record data include CVE ID number, affected product(s), affected version(s), and public references. While those specific items are required when assigning a CVE, there are many other optional data in the schema that can be used to enrich CVE Records for community benefit. Learn more about the CVE program at [the official website](https://www.cve.org). This CVE JSON record format is defined using JSON Schema. Learn more about JSON Schema [here](https://json-schema.org/).", "definitions": { "uriType": { "description": "A universal resource identifier (URI), according to [RFC 3986](https://tools.ietf.org/html/rfc3986).", @@ -51,8 +51,23 @@ }, "cveId": { "type": "string", + "description":"The official CVE identifier contains the string 'CVE', followed by the year, followed by a 4 to 19 digit number. Note that the year-part of the identifier should indicate either the year the vulnerability was discovered, or the year the CVE ID is published in. CVE IDs must be unique.", "pattern": "^CVE-[0-9]{4}-[0-9]{4,19}$" }, + "cpe22and23": { + "type": "string", + "description":"Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", + "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, + "cpe23": { + "type": "string", + "description":"Common Platform Enumeration (CPE) Name in 2.3 format", + "pattern": "(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, "orgId": { "description": "A UUID for an organization participating in the CVE program. This UUID can be used to lookup the organization record in the user registry service.", "$ref": "#/definitions/uuidType" @@ -106,6 +121,7 @@ ] } ], + "additionalProperties": false, "properties": { "vendor": { "type": "string", @@ -196,15 +212,12 @@ }, "cpes": { "type": "array", - "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here.", + "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here. NOTE: Consider using the newer cpeApplicability block for defining CPE data using the CPE Applicability Language which includes more options for defining CPE Names.", "uniqueItems": true, "items": { "title": "CPE Name", - "type": "string", "description":"Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", - "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", - "minLength": 1, - "maxLength": 2048 + "$ref": "#/definitions/cpe22and23" } }, "modules": { @@ -272,7 +285,7 @@ }, "versions": { "type": "array", - "description": "Set of product versions or version ranges related to the vulnerability. The versions satisfy the CNA Rules [8.1.2 requirement](https://cve.mitre.org/cve/cna/rules.html#section_8-1_cve_entry_information_requirements). Versions or defaultStatus may be omitted, but not both.", + "description": "Set of product versions or version ranges related to the vulnerability. The versions help satisfy the CNA Rules [5.1.3 requirement](https://www.cve.org/ResourcesSupport/AllResources/CNARules#section_5-1_Required_CVE_Record_Content). Versions or defaultStatus may be omitted, but not both.", "minItems": 1, "uniqueItems": true, "items": { @@ -350,6 +363,28 @@ }, "additionalProperties": false } + }, + "packageURL": { + "description": "A Package URL, a unified URL specification for identifying packages hosted by known package hosts. The Package URL MUST NOT include a version.", + "$ref": "#/definitions/uriType", + "examples": [ + "pkg:bitbucket/birkenfeld/pygments-main", + "pkg:deb/debian/curl?arch=i386&distro=jessie", + "pkg:docker/cassandra", + "pkg:docker/customer/dockerimage?repository_url=gcr.io", + "pkg:gem/jruby-launcher?platform=java", + "pkg:gem/ruby-advisory-db-check", + "pkg:github/package-url/purl-spec", + "pkg:golang/google.golang.org/genproto#googleapis/api/annotations", + "pkg:maven/org.apache.xmlgraphics/batik-anim?packaging=sources", + "pkg:maven/org.apache.xmlgraphics/batik-anim?repository_url=repo.spring.io/release", + "pkg:npm/%40angular/animation", + "pkg:npm/foobar", + "pkg:nuget/EnterpriseLibrary.Common", + "pkg:pypi/django", + "pkg:rpm/fedora/curl?arch=i386&distro=fedora-25", + "pkg:rpm/opensuse/curl?arch=i386&distro=opensuse-tumbleweed" + ] } } }, @@ -364,7 +399,7 @@ "description": "The version of the CVE schema used for validating this record. Used to support multiple versions of this format.", "type": "string", "pattern": "^5\\.(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?$", - "default": "5.1.0" + "default": "5.2.0" }, "cveMetadataPublished": { "description": "This is meta data about the CVE ID such as the CVE ID, who requested it, who assigned it, when it was requested, the current state (PUBLISHED, REJECTED, etc.) and so on. These fields are controlled by the CVE Services.", @@ -487,6 +522,87 @@ "required": ["orgId"], "additionalProperties": false }, + "cpeApplicabilityElement": { + "description": "Affected products defined using an implementation of the CPE Applicability Language, mostly copied/forked from the NIST NVD CVE API v2.0 schema (optional). An operator property allows AND or OR logic between CPEs or combinations of CPEs. The negate and vulnerable Boolean properties allow CPEs to be inverted and/or defined as vulnerable or not. Multiple version fields are provided for capturing ranges of products when defining a CPE Match String Range. NOTE: When defining a cpeApplicability block, it is recommended that it align with (as much as possible) the product data provided within the affected block.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_node" + } + } + }, + "required": [ + "nodes" + ] + }, + "cpe_node": { + "description": "Defines a CPE configuration node in an applicability statement.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "cpeMatch": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_match" + } + } + }, + "required": [ + "operator", + "cpeMatch" + ] + }, + "cpe_match": { + "description": "CPE match string or range", + "type": "object", + "properties": { + "vulnerable": { + "type": "boolean" + }, + "criteria": { + "$ref": "#/definitions/cpe23" + }, + "matchCriteriaId": { + "$ref": "#/definitions/uuidType" + }, + "versionStartExcluding": { + "$ref": "#/definitions/version" + }, + "versionStartIncluding": { + "$ref": "#/definitions/version" + }, + "versionEndExcluding": { + "$ref": "#/definitions/version" + }, + "versionEndIncluding": { + "$ref": "#/definitions/version" + } + }, + "required": [ + "vulnerable", + "criteria" + ], + "additionalProperties": false + }, "cnaPublishedContainer": { "description": "An object containing the vulnerability information provided by a CVE Numbering Authority (CNA) for a published CVE ID. There can only be one CNA container per CVE record since there can only be one assigning CNA. The CNA container must include the required information defined in the CVE Rules, which includes a product, version, problem type, prose description, and a reference.", "type": "object", @@ -514,6 +630,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -620,6 +742,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, diff --git a/schema/docs/CVE_Record_Format_bundled.json b/schema/docs/CVE_Record_Format_bundled.json index 4b8f98b4cf6..fe8e214c5d7 100644 --- a/schema/docs/CVE_Record_Format_bundled.json +++ b/schema/docs/CVE_Record_Format_bundled.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled.json", + "$id": "https://cveproject.github.io/cve-schema/schema/CVE_Record_Format.json", "title": "CVE JSON record format", - "description": "cve-schema specifies the CVE JSON record format. This is the blueprint for a rich set of JSON data that can be submitted by CVE Numbering Authorities (CNAs) and Authorized Data Publishers (ADPs) to describe a CVE Record. Some examples of CVE Record data include CVE ID number, affected product(s), affected version(s), and public references. While those specific items are required when assigning a CVE, there are many other optional data in the schema that can be used to enrich CVE Records for community benefit. Learn more about the CVE program at [the official website](https://cve.mitre.org). This CVE JSON record format is defined using JSON Schema. Learn more about JSON Schema [here](https://json-schema.org/).", + "description": "cve-schema specifies the CVE JSON record format. This is the blueprint for a rich set of JSON data that can be submitted by CVE Numbering Authorities (CNAs) and Authorized Data Publishers (ADPs) to describe a CVE Record. Some examples of CVE Record data include CVE ID number, affected product(s), affected version(s), and public references. While those specific items are required when assigning a CVE, there are many other optional data in the schema that can be used to enrich CVE Records for community benefit. Learn more about the CVE program at [the official website](https://www.cve.org). This CVE JSON record format is defined using JSON Schema. Learn more about JSON Schema [here](https://json-schema.org/).", "definitions": { "uriType": { "description": "A universal resource identifier (URI), according to [RFC 3986](https://tools.ietf.org/html/rfc3986).", @@ -77,8 +77,23 @@ }, "cveId": { "type": "string", + "description": "The official CVE identifier contains the string 'CVE', followed by the year, followed by a 4 to 19 digit number. Note that the year-part of the identifier should indicate either the year the vulnerability was discovered, or the year the CVE ID is published in. CVE IDs must be unique.", "pattern": "^CVE-[0-9]{4}-[0-9]{4,19}$" }, + "cpe22and23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", + "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, + "cpe23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in 2.3 format", + "pattern": "(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, "orgId": { "description": "A UUID for an organization participating in the CVE program. This UUID can be used to lookup the organization record in the user registry service.", "$ref": "#/definitions/uuidType" @@ -154,6 +169,7 @@ ] } ], + "additionalProperties": false, "properties": { "vendor": { "type": "string", @@ -244,15 +260,12 @@ }, "cpes": { "type": "array", - "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here.", + "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here. NOTE: Consider using the newer cpeApplicability block for defining CPE data using the CPE Applicability Language which includes more options for defining CPE Names.", "uniqueItems": true, "items": { "title": "CPE Name", - "type": "string", "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", - "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", - "minLength": 1, - "maxLength": 2048 + "$ref": "#/definitions/cpe22and23" } }, "modules": { @@ -333,7 +346,7 @@ }, "versions": { "type": "array", - "description": "Set of product versions or version ranges related to the vulnerability. The versions satisfy the CNA Rules [8.1.2 requirement](https://cve.mitre.org/cve/cna/rules.html#section_8-1_cve_entry_information_requirements). Versions or defaultStatus may be omitted, but not both.", + "description": "Set of product versions or version ranges related to the vulnerability. The versions help satisfy the CNA Rules [5.1.3 requirement](https://www.cve.org/ResourcesSupport/AllResources/CNARules#section_5-1_Required_CVE_Record_Content). Versions or defaultStatus may be omitted, but not both.", "minItems": 1, "uniqueItems": true, "items": { @@ -431,6 +444,28 @@ }, "additionalProperties": false } + }, + "packageURL": { + "description": "A Package URL, a unified URL specification for identifying packages hosted by known package hosts. The Package URL MUST NOT include a version.", + "$ref": "#/definitions/uriType", + "examples": [ + "pkg:bitbucket/birkenfeld/pygments-main", + "pkg:deb/debian/curl?arch=i386&distro=jessie", + "pkg:docker/cassandra", + "pkg:docker/customer/dockerimage?repository_url=gcr.io", + "pkg:gem/jruby-launcher?platform=java", + "pkg:gem/ruby-advisory-db-check", + "pkg:github/package-url/purl-spec", + "pkg:golang/google.golang.org/genproto#googleapis/api/annotations", + "pkg:maven/org.apache.xmlgraphics/batik-anim?packaging=sources", + "pkg:maven/org.apache.xmlgraphics/batik-anim?repository_url=repo.spring.io/release", + "pkg:npm/%40angular/animation", + "pkg:npm/foobar", + "pkg:nuget/EnterpriseLibrary.Common", + "pkg:pypi/django", + "pkg:rpm/fedora/curl?arch=i386&distro=fedora-25", + "pkg:rpm/opensuse/curl?arch=i386&distro=opensuse-tumbleweed" + ] } } }, @@ -445,7 +480,7 @@ "description": "The version of the CVE schema used for validating this record. Used to support multiple versions of this format.", "type": "string", "pattern": "^5\\.(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?$", - "default": "5.1.0" + "default": "5.2.0" }, "cveMetadataPublished": { "description": "This is meta data about the CVE ID such as the CVE ID, who requested it, who assigned it, when it was requested, the current state (PUBLISHED, REJECTED, etc.) and so on. These fields are controlled by the CVE Services.", @@ -573,6 +608,87 @@ ], "additionalProperties": false }, + "cpeApplicabilityElement": { + "description": "Affected products defined using an implementation of the CPE Applicability Language, mostly copied/forked from the NIST NVD CVE API v2.0 schema (optional). An operator property allows AND or OR logic between CPEs or combinations of CPEs. The negate and vulnerable Boolean properties allow CPEs to be inverted and/or defined as vulnerable or not. Multiple version fields are provided for capturing ranges of products when defining a CPE Match String Range. NOTE: When defining a cpeApplicability block, it is recommended that it align with (as much as possible) the product data provided within the affected block.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_node" + } + } + }, + "required": [ + "nodes" + ] + }, + "cpe_node": { + "description": "Defines a CPE configuration node in an applicability statement.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "cpeMatch": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_match" + } + } + }, + "required": [ + "operator", + "cpeMatch" + ] + }, + "cpe_match": { + "description": "CPE match string or range", + "type": "object", + "properties": { + "vulnerable": { + "type": "boolean" + }, + "criteria": { + "$ref": "#/definitions/cpe23" + }, + "matchCriteriaId": { + "$ref": "#/definitions/uuidType" + }, + "versionStartExcluding": { + "$ref": "#/definitions/version" + }, + "versionStartIncluding": { + "$ref": "#/definitions/version" + }, + "versionEndExcluding": { + "$ref": "#/definitions/version" + }, + "versionEndIncluding": { + "$ref": "#/definitions/version" + } + }, + "required": [ + "vulnerable", + "criteria" + ], + "additionalProperties": false + }, "cnaPublishedContainer": { "description": "An object containing the vulnerability information provided by a CVE Numbering Authority (CNA) for a published CVE ID. There can only be one CNA container per CVE record since there can only be one assigning CNA. The CNA container must include the required information defined in the CVE Rules, which includes a product, version, problem type, prose description, and a reference.", "type": "object", @@ -600,6 +716,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -706,6 +828,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -3414,4 +3542,4 @@ "additionalProperties": false } ] -} \ No newline at end of file +} diff --git a/schema/docs/CVE_Record_Format_bundled_adpContainer.json b/schema/docs/CVE_Record_Format_bundled_adpContainer.json index c225c381d44..7cdb33a417b 100644 --- a/schema/docs/CVE_Record_Format_bundled_adpContainer.json +++ b/schema/docs/CVE_Record_Format_bundled_adpContainer.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_adpContainer.json", - "title": "CVE JSON adpContainer sub schema", - "description": "CVE JSON adpContainer format", + "title": "CVE Record Format adpContainer sub schema", + "description": "CVE Record Format adpContainer format", "definitions": { "uriType": { "description": "A universal resource identifier (URI), according to [RFC 3986](https://tools.ietf.org/html/rfc3986).", @@ -77,8 +77,23 @@ }, "cveId": { "type": "string", + "description": "The official CVE identifier contains the string 'CVE', followed by the year, followed by a 4 to 19 digit number. Note that the year-part of the identifier should indicate either the year the vulnerability was discovered, or the year the CVE ID is published in. CVE IDs must be unique.", "pattern": "^CVE-[0-9]{4}-[0-9]{4,19}$" }, + "cpe22and23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", + "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, + "cpe23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in 2.3 format", + "pattern": "(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, "orgId": { "description": "A UUID for an organization participating in the CVE program. This UUID can be used to lookup the organization record in the user registry service.", "$ref": "#/definitions/uuidType" @@ -154,6 +169,7 @@ ] } ], + "additionalProperties": false, "properties": { "vendor": { "type": "string", @@ -244,15 +260,12 @@ }, "cpes": { "type": "array", - "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here.", + "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here. NOTE: Consider using the newer cpeApplicability block for defining CPE data using the CPE Applicability Language which includes more options for defining CPE Names.", "uniqueItems": true, "items": { "title": "CPE Name", - "type": "string", "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", - "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", - "minLength": 1, - "maxLength": 2048 + "$ref": "#/definitions/cpe22and23" } }, "modules": { @@ -333,7 +346,7 @@ }, "versions": { "type": "array", - "description": "Set of product versions or version ranges related to the vulnerability. The versions satisfy the CNA Rules [8.1.2 requirement](https://cve.mitre.org/cve/cna/rules.html#section_8-1_cve_entry_information_requirements). Versions or defaultStatus may be omitted, but not both.", + "description": "Set of product versions or version ranges related to the vulnerability. The versions help satisfy the CNA Rules [5.1.3 requirement](https://www.cve.org/ResourcesSupport/AllResources/CNARules#section_5-1_Required_CVE_Record_Content). Versions or defaultStatus may be omitted, but not both.", "minItems": 1, "uniqueItems": true, "items": { @@ -431,6 +444,28 @@ }, "additionalProperties": false } + }, + "packageURL": { + "description": "A Package URL, a unified URL specification for identifying packages hosted by known package hosts. The Package URL MUST NOT include a version.", + "$ref": "#/definitions/uriType", + "examples": [ + "pkg:bitbucket/birkenfeld/pygments-main", + "pkg:deb/debian/curl?arch=i386&distro=jessie", + "pkg:docker/cassandra", + "pkg:docker/customer/dockerimage?repository_url=gcr.io", + "pkg:gem/jruby-launcher?platform=java", + "pkg:gem/ruby-advisory-db-check", + "pkg:github/package-url/purl-spec", + "pkg:golang/google.golang.org/genproto#googleapis/api/annotations", + "pkg:maven/org.apache.xmlgraphics/batik-anim?packaging=sources", + "pkg:maven/org.apache.xmlgraphics/batik-anim?repository_url=repo.spring.io/release", + "pkg:npm/%40angular/animation", + "pkg:npm/foobar", + "pkg:nuget/EnterpriseLibrary.Common", + "pkg:pypi/django", + "pkg:rpm/fedora/curl?arch=i386&distro=fedora-25", + "pkg:rpm/opensuse/curl?arch=i386&distro=opensuse-tumbleweed" + ] } } }, @@ -445,7 +480,7 @@ "description": "The version of the CVE schema used for validating this record. Used to support multiple versions of this format.", "type": "string", "pattern": "^5\\.(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?$", - "default": "5.1.0" + "default": "5.2.0" }, "cveMetadataPublished": { "description": "This is meta data about the CVE ID such as the CVE ID, who requested it, who assigned it, when it was requested, the current state (PUBLISHED, REJECTED, etc.) and so on. These fields are controlled by the CVE Services.", @@ -573,6 +608,87 @@ ], "additionalProperties": false }, + "cpeApplicabilityElement": { + "description": "Affected products defined using an implementation of the CPE Applicability Language, mostly copied/forked from the NIST NVD CVE API v2.0 schema (optional). An operator property allows AND or OR logic between CPEs or combinations of CPEs. The negate and vulnerable Boolean properties allow CPEs to be inverted and/or defined as vulnerable or not. Multiple version fields are provided for capturing ranges of products when defining a CPE Match String Range. NOTE: When defining a cpeApplicability block, it is recommended that it align with (as much as possible) the product data provided within the affected block.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_node" + } + } + }, + "required": [ + "nodes" + ] + }, + "cpe_node": { + "description": "Defines a CPE configuration node in an applicability statement.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "cpeMatch": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_match" + } + } + }, + "required": [ + "operator", + "cpeMatch" + ] + }, + "cpe_match": { + "description": "CPE match string or range", + "type": "object", + "properties": { + "vulnerable": { + "type": "boolean" + }, + "criteria": { + "$ref": "#/definitions/cpe23" + }, + "matchCriteriaId": { + "$ref": "#/definitions/uuidType" + }, + "versionStartExcluding": { + "$ref": "#/definitions/version" + }, + "versionStartIncluding": { + "$ref": "#/definitions/version" + }, + "versionEndExcluding": { + "$ref": "#/definitions/version" + }, + "versionEndIncluding": { + "$ref": "#/definitions/version" + } + }, + "required": [ + "vulnerable", + "criteria" + ], + "additionalProperties": false + }, "cnaPublishedContainer": { "description": "An object containing the vulnerability information provided by a CVE Numbering Authority (CNA) for a published CVE ID. There can only be one CNA container per CVE record since there can only be one assigning CNA. The CNA container must include the required information defined in the CVE Rules, which includes a product, version, problem type, prose description, and a reference.", "type": "object", @@ -600,6 +716,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -706,6 +828,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -3332,10 +3460,11 @@ } } }, + "type": "object", "properties": { "adpContainer": { "$ref": "#/definitions/adpContainer" } }, "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json b/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json index db7dffd02ce..3297a8495fa 100644 --- a/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json +++ b/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json", - "title": "CVE JSON cnaPublishedContainer sub schema", - "description": "CVE JSON cnaPublishedContainer format", + "title": "CVE Record Format cnaPublishedContainer sub schema", + "description": "CVE Record Format cnaPublishedContainer format", "definitions": { "uriType": { "description": "A universal resource identifier (URI), according to [RFC 3986](https://tools.ietf.org/html/rfc3986).", @@ -77,8 +77,23 @@ }, "cveId": { "type": "string", + "description": "The official CVE identifier contains the string 'CVE', followed by the year, followed by a 4 to 19 digit number. Note that the year-part of the identifier should indicate either the year the vulnerability was discovered, or the year the CVE ID is published in. CVE IDs must be unique.", "pattern": "^CVE-[0-9]{4}-[0-9]{4,19}$" }, + "cpe22and23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", + "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, + "cpe23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in 2.3 format", + "pattern": "(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, "orgId": { "description": "A UUID for an organization participating in the CVE program. This UUID can be used to lookup the organization record in the user registry service.", "$ref": "#/definitions/uuidType" @@ -154,6 +169,7 @@ ] } ], + "additionalProperties": false, "properties": { "vendor": { "type": "string", @@ -244,15 +260,12 @@ }, "cpes": { "type": "array", - "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here.", + "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here. NOTE: Consider using the newer cpeApplicability block for defining CPE data using the CPE Applicability Language which includes more options for defining CPE Names.", "uniqueItems": true, "items": { "title": "CPE Name", - "type": "string", "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", - "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", - "minLength": 1, - "maxLength": 2048 + "$ref": "#/definitions/cpe22and23" } }, "modules": { @@ -333,7 +346,7 @@ }, "versions": { "type": "array", - "description": "Set of product versions or version ranges related to the vulnerability. The versions satisfy the CNA Rules [8.1.2 requirement](https://cve.mitre.org/cve/cna/rules.html#section_8-1_cve_entry_information_requirements). Versions or defaultStatus may be omitted, but not both.", + "description": "Set of product versions or version ranges related to the vulnerability. The versions help satisfy the CNA Rules [5.1.3 requirement](https://www.cve.org/ResourcesSupport/AllResources/CNARules#section_5-1_Required_CVE_Record_Content). Versions or defaultStatus may be omitted, but not both.", "minItems": 1, "uniqueItems": true, "items": { @@ -431,6 +444,28 @@ }, "additionalProperties": false } + }, + "packageURL": { + "description": "A Package URL, a unified URL specification for identifying packages hosted by known package hosts. The Package URL MUST NOT include a version.", + "$ref": "#/definitions/uriType", + "examples": [ + "pkg:bitbucket/birkenfeld/pygments-main", + "pkg:deb/debian/curl?arch=i386&distro=jessie", + "pkg:docker/cassandra", + "pkg:docker/customer/dockerimage?repository_url=gcr.io", + "pkg:gem/jruby-launcher?platform=java", + "pkg:gem/ruby-advisory-db-check", + "pkg:github/package-url/purl-spec", + "pkg:golang/google.golang.org/genproto#googleapis/api/annotations", + "pkg:maven/org.apache.xmlgraphics/batik-anim?packaging=sources", + "pkg:maven/org.apache.xmlgraphics/batik-anim?repository_url=repo.spring.io/release", + "pkg:npm/%40angular/animation", + "pkg:npm/foobar", + "pkg:nuget/EnterpriseLibrary.Common", + "pkg:pypi/django", + "pkg:rpm/fedora/curl?arch=i386&distro=fedora-25", + "pkg:rpm/opensuse/curl?arch=i386&distro=opensuse-tumbleweed" + ] } } }, @@ -445,7 +480,7 @@ "description": "The version of the CVE schema used for validating this record. Used to support multiple versions of this format.", "type": "string", "pattern": "^5\\.(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?$", - "default": "5.1.0" + "default": "5.2.0" }, "cveMetadataPublished": { "description": "This is meta data about the CVE ID such as the CVE ID, who requested it, who assigned it, when it was requested, the current state (PUBLISHED, REJECTED, etc.) and so on. These fields are controlled by the CVE Services.", @@ -573,6 +608,87 @@ ], "additionalProperties": false }, + "cpeApplicabilityElement": { + "description": "Affected products defined using an implementation of the CPE Applicability Language, mostly copied/forked from the NIST NVD CVE API v2.0 schema (optional). An operator property allows AND or OR logic between CPEs or combinations of CPEs. The negate and vulnerable Boolean properties allow CPEs to be inverted and/or defined as vulnerable or not. Multiple version fields are provided for capturing ranges of products when defining a CPE Match String Range. NOTE: When defining a cpeApplicability block, it is recommended that it align with (as much as possible) the product data provided within the affected block.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_node" + } + } + }, + "required": [ + "nodes" + ] + }, + "cpe_node": { + "description": "Defines a CPE configuration node in an applicability statement.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "cpeMatch": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_match" + } + } + }, + "required": [ + "operator", + "cpeMatch" + ] + }, + "cpe_match": { + "description": "CPE match string or range", + "type": "object", + "properties": { + "vulnerable": { + "type": "boolean" + }, + "criteria": { + "$ref": "#/definitions/cpe23" + }, + "matchCriteriaId": { + "$ref": "#/definitions/uuidType" + }, + "versionStartExcluding": { + "$ref": "#/definitions/version" + }, + "versionStartIncluding": { + "$ref": "#/definitions/version" + }, + "versionEndExcluding": { + "$ref": "#/definitions/version" + }, + "versionEndIncluding": { + "$ref": "#/definitions/version" + } + }, + "required": [ + "vulnerable", + "criteria" + ], + "additionalProperties": false + }, "cnaPublishedContainer": { "description": "An object containing the vulnerability information provided by a CVE Numbering Authority (CNA) for a published CVE ID. There can only be one CNA container per CVE record since there can only be one assigning CNA. The CNA container must include the required information defined in the CVE Rules, which includes a product, version, problem type, prose description, and a reference.", "type": "object", @@ -600,6 +716,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -706,6 +828,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -3332,10 +3460,11 @@ } } }, + "type": "object", "properties": { "cnaContainer": { "$ref": "#/definitions/cnaPublishedContainer" } }, "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/docs/CVE_Record_Format_bundled_cnaRejectedContainer.json b/schema/docs/CVE_Record_Format_bundled_cnaRejectedContainer.json index 7a404c3af02..0b0195f862d 100644 --- a/schema/docs/CVE_Record_Format_bundled_cnaRejectedContainer.json +++ b/schema/docs/CVE_Record_Format_bundled_cnaRejectedContainer.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaRejectedContainer.json", - "title": "CVE JSON cnaRejectedContainer sub schema", - "description": "CVE JSON cnaRejectedContainer format", + "title": "CVE Record Format cnaRejectedContainer sub schema", + "description": "CVE Record Format cnaRejectedContainer format", "definitions": { "uriType": { "description": "A universal resource identifier (URI), according to [RFC 3986](https://tools.ietf.org/html/rfc3986).", @@ -77,8 +77,23 @@ }, "cveId": { "type": "string", + "description": "The official CVE identifier contains the string 'CVE', followed by the year, followed by a 4 to 19 digit number. Note that the year-part of the identifier should indicate either the year the vulnerability was discovered, or the year the CVE ID is published in. CVE IDs must be unique.", "pattern": "^CVE-[0-9]{4}-[0-9]{4,19}$" }, + "cpe22and23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", + "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, + "cpe23": { + "type": "string", + "description": "Common Platform Enumeration (CPE) Name in 2.3 format", + "pattern": "(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", + "minLength": 1, + "maxLength": 2048 + }, "orgId": { "description": "A UUID for an organization participating in the CVE program. This UUID can be used to lookup the organization record in the user registry service.", "$ref": "#/definitions/uuidType" @@ -154,6 +169,7 @@ ] } ], + "additionalProperties": false, "properties": { "vendor": { "type": "string", @@ -244,15 +260,12 @@ }, "cpes": { "type": "array", - "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here.", + "description": "Affected products defined by CPE. This is an array of CPE values (vulnerable and not), we use an array so that we can make multiple statements about the same version and they are separate (if we used a JSON object we'd essentially be keying on the CPE name and they would have to overlap). Also, this allows things like cveDataVersion or cveDescription to be applied directly to the product entry. This also allows more complex statements such as \"Product X between versions 10.2 and 10.8\" to be put in a machine-readable format. As well since multiple statements can be used multiple branches of the same product can be defined here. NOTE: Consider using the newer cpeApplicability block for defining CPE data using the CPE Applicability Language which includes more options for defining CPE Names.", "uniqueItems": true, "items": { "title": "CPE Name", - "type": "string", "description": "Common Platform Enumeration (CPE) Name in either 2.2 or 2.3 format", - "pattern": "([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9._\\-~%]*){0,6})|(cpe:2\\.3:[aho*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[*\\-]))(:(((\\?*|\\*?)([a-zA-Z0-9\\-._]|(\\\\[\\\\*?!\"#$%&'()+,/:;<=>@\\[\\]\\^`{|}~]))+(\\?*|\\*?))|[*\\-])){4})", - "minLength": 1, - "maxLength": 2048 + "$ref": "#/definitions/cpe22and23" } }, "modules": { @@ -333,7 +346,7 @@ }, "versions": { "type": "array", - "description": "Set of product versions or version ranges related to the vulnerability. The versions satisfy the CNA Rules [8.1.2 requirement](https://cve.mitre.org/cve/cna/rules.html#section_8-1_cve_entry_information_requirements). Versions or defaultStatus may be omitted, but not both.", + "description": "Set of product versions or version ranges related to the vulnerability. The versions help satisfy the CNA Rules [5.1.3 requirement](https://www.cve.org/ResourcesSupport/AllResources/CNARules#section_5-1_Required_CVE_Record_Content). Versions or defaultStatus may be omitted, but not both.", "minItems": 1, "uniqueItems": true, "items": { @@ -431,6 +444,28 @@ }, "additionalProperties": false } + }, + "packageURL": { + "description": "A Package URL, a unified URL specification for identifying packages hosted by known package hosts. The Package URL MUST NOT include a version.", + "$ref": "#/definitions/uriType", + "examples": [ + "pkg:bitbucket/birkenfeld/pygments-main", + "pkg:deb/debian/curl?arch=i386&distro=jessie", + "pkg:docker/cassandra", + "pkg:docker/customer/dockerimage?repository_url=gcr.io", + "pkg:gem/jruby-launcher?platform=java", + "pkg:gem/ruby-advisory-db-check", + "pkg:github/package-url/purl-spec", + "pkg:golang/google.golang.org/genproto#googleapis/api/annotations", + "pkg:maven/org.apache.xmlgraphics/batik-anim?packaging=sources", + "pkg:maven/org.apache.xmlgraphics/batik-anim?repository_url=repo.spring.io/release", + "pkg:npm/%40angular/animation", + "pkg:npm/foobar", + "pkg:nuget/EnterpriseLibrary.Common", + "pkg:pypi/django", + "pkg:rpm/fedora/curl?arch=i386&distro=fedora-25", + "pkg:rpm/opensuse/curl?arch=i386&distro=opensuse-tumbleweed" + ] } } }, @@ -445,7 +480,7 @@ "description": "The version of the CVE schema used for validating this record. Used to support multiple versions of this format.", "type": "string", "pattern": "^5\\.(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?$", - "default": "5.1.0" + "default": "5.2.0" }, "cveMetadataPublished": { "description": "This is meta data about the CVE ID such as the CVE ID, who requested it, who assigned it, when it was requested, the current state (PUBLISHED, REJECTED, etc.) and so on. These fields are controlled by the CVE Services.", @@ -573,6 +608,87 @@ ], "additionalProperties": false }, + "cpeApplicabilityElement": { + "description": "Affected products defined using an implementation of the CPE Applicability Language, mostly copied/forked from the NIST NVD CVE API v2.0 schema (optional). An operator property allows AND or OR logic between CPEs or combinations of CPEs. The negate and vulnerable Boolean properties allow CPEs to be inverted and/or defined as vulnerable or not. Multiple version fields are provided for capturing ranges of products when defining a CPE Match String Range. NOTE: When defining a cpeApplicability block, it is recommended that it align with (as much as possible) the product data provided within the affected block.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_node" + } + } + }, + "required": [ + "nodes" + ] + }, + "cpe_node": { + "description": "Defines a CPE configuration node in an applicability statement.", + "properties": { + "operator": { + "type": "string", + "enum": [ + "AND", + "OR" + ] + }, + "negate": { + "type": "boolean" + }, + "cpeMatch": { + "type": "array", + "items": { + "$ref": "#/definitions/cpe_match" + } + } + }, + "required": [ + "operator", + "cpeMatch" + ] + }, + "cpe_match": { + "description": "CPE match string or range", + "type": "object", + "properties": { + "vulnerable": { + "type": "boolean" + }, + "criteria": { + "$ref": "#/definitions/cpe23" + }, + "matchCriteriaId": { + "$ref": "#/definitions/uuidType" + }, + "versionStartExcluding": { + "$ref": "#/definitions/version" + }, + "versionStartIncluding": { + "$ref": "#/definitions/version" + }, + "versionEndExcluding": { + "$ref": "#/definitions/version" + }, + "versionEndIncluding": { + "$ref": "#/definitions/version" + } + }, + "required": [ + "vulnerable", + "criteria" + ], + "additionalProperties": false + }, "cnaPublishedContainer": { "description": "An object containing the vulnerability information provided by a CVE Numbering Authority (CNA) for a published CVE ID. There can only be one CNA container per CVE record since there can only be one assigning CNA. The CNA container must include the required information defined in the CVE Rules, which includes a product, version, problem type, prose description, and a reference.", "type": "object", @@ -600,6 +716,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -706,6 +828,12 @@ "affected": { "$ref": "#/definitions/affected" }, + "cpeApplicability": { + "type": "array", + "items": { + "$ref": "#/definitions/cpeApplicabilityElement" + } + }, "problemTypes": { "$ref": "#/definitions/problemTypes" }, @@ -3332,10 +3460,11 @@ } } }, + "type": "object", "properties": { "cnaContainer": { "$ref": "#/definitions/cnaRejectedContainer" } }, "additionalProperties": false -} \ No newline at end of file +} diff --git a/schema/docs/cnaContainer-advanced-example.json b/schema/docs/cnaContainer-advanced-example.json index c255d81b336..a5091d79d06 100644 --- a/schema/docs/cnaContainer-advanced-example.json +++ b/schema/docs/cnaContainer-advanced-example.json @@ -37,8 +37,9 @@ "MacOS", "XT-4500" ], - "collectionURL": "https://example.org/packages", - "packageName": "example_enterprise", + "collectionURL": "https://npmjs.com", + "packageName": "example", + "packageURL": "pkg:npm/example", "repo": "git://example.org/source/example_enterprise", "modules": [ "Web-Management-Interface" @@ -84,26 +85,69 @@ "defaultStatus": "unaffected" } ], + "cpeApplicability": [ + { + "operator": "AND", + "nodes": [ + { + "operator": "OR", + "negate": false, + "cpeMatch": [ + { + "vulnerable": true, + "criteria": "cpe:2.3:a:example_org:example_enterprise:*:*:*:*:*:*:*:*", + "versionStartIncluding": "1.0.0", + "versionEndExcluding": "1.0.6" + }, + { + "vulnerable": true, + "criteria": "cpe:2.3:a:example_org:example_enterprise:*:*:*:*:*:*:*:*", + "versionStartIncluding": "2.1.6", + "versionEndExcluding": "2.1.9" + } + ] + }, + { + "operator": "OR", + "negate": false, + "cpeMatch": [ + { + "vulnerable": false, + "criteria": "cpe:2.3:o:microsoft:windows:*:*:*:*:*:*:*:*" + }, + { + "vulnerable": false, + "criteria": "cpe:2.3:o:apple:macos:*:*:*:*:*:*:*:*" + }, + { + "vulnerable": false, + "criteria": "cpe:2.3:h:some_company:xt-4500:*:*:*:*:*:*:*:*" + } + ] + } + ] + } + ], "descriptions": [ { "lang": "en", - "value": "OS Command Injection vulnerability parseFilename function of example.php in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges. This issue affects: 1.0 versions before 1.0.6, 2.1 versions from 2.16 until 2.1.9.", + "value": "OS Command Injection vulnerability parseFilename function of example.php in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges. This issue affects: 1.0 versions before 1.0.6, 2.1 versions from 2.1.6 until 2.1.9.", "supportingMedia": [ { "type": "text/html", "base64": false, - "value": "OS Command Injection vulnerability <tt>parseFilename</tt> function of <tt>example.php</tt> in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges.<br><br>This issue affects:<br><ul><li>1.0 versions before 1.0.6</li><li>2.1 versions from 2.16 until 2.1.9.</li></ul>" + "value": "OS Command Injection vulnerability <tt>parseFilename</tt> function of <tt>example.php</tt> in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges.<br><br>This issue affects:<br><ul><li>1.0 versions before 1.0.6</li><li>2.1 versions from 2.1.6 until 2.1.9.</li></ul>" } ] }, { "lang": "eo", - "value": "OS-komand-injekta vundebleco parseFilename funkcio de example.php en la Web Administrado-Interfaco de Example.org Example Enterprise \u0109e Windows, macOS kaj XT-4500 permesas al malproksimaj nea\u016dtentikigitaj atakantoj eskaladi privilegiojn. \u0108i tiu afero efikas: 1.0-versioj anta\u016d 1.0.6, 2.1-versioj de 2.16 \u011dis 2.1.9.", + "value": "OS-komand-injekta vundebleco parseFilename funkcio de example.php en la Web Administrado-Interfaco de Example.org Example Enterprise \u0109e Windows, macOS kaj XT-4500 permesas al malproksimaj nea\u016dtentikigitaj atakantoj eskaladi privilegiojn. \u0108i tiu afero efikas: 1.0-versioj anta\u016d 1.0.6, 2.1-versioj de 2.1.6 \u011dis 2.1.9.", "supportingMedia": [ { "type": "text/html", "base64": false, - "value": "OS-komand-injekta vundebleco <tt>parseFilename</tt> funkcio de <tt>example.php</tt> en la Web Administrado-Interfaco de Example.org Example Enterprise \u0109e Windows, macOS kaj XT-4500 permesas al malproksimaj nea\u016dtentikigitaj atakantoj eskaladi privilegiojn.<br><br> \u0108i tiu afero efikas:<br><ul><li>1.0-versioj anta\u016d 1.0.6</li><li>2.1-versioj de 2.16 \u011dis 2.1.9.</li></ul>" + "value": "OS-komand-injekta vundebleco <tt>parseFilename</tt> funkcio de <tt>example.php</tt> en la Web Administrado-Interfaco de Example.org Example Enterprise \u0109e Windows, macOS kaj XT-4500 permesas al malproksimaj nea\u016dtentikigitaj atakantoj eskaladi privilegiojn.<br><br> \u0108i tiu afero efikas:<br><ul><li>1.0-versioj anta\u016d 1.0.6</li><li>2.1-versioj de 2.1.6 \u011dis 2.1.9.</li></ul>" } ] } @@ -250,7 +294,7 @@ ], "references": [ { - "url": "https://example.org/ESA-22-11-CVE-1337-1234", + "url": "https://example.org/ESA-22-11-CVE-1900-1234", "name": "ESA-22-11", "tags": [ "vendor-advisory" @@ -285,6 +329,9 @@ "advisory": "ESA-22-11", "discovery": "EXTERNAL" }, + "tags": [ + "unsupported-when-assigned" + ], "taxonomyMappings": [ { "taxonomyName": "ATT&CK", diff --git a/schema/docs/cnaContainer-basic-example.json b/schema/docs/cnaContainer-basic-example.json index 0b474d3e5f6..04ca59c65fd 100644 --- a/schema/docs/cnaContainer-basic-example.json +++ b/schema/docs/cnaContainer-basic-example.json @@ -36,7 +36,7 @@ ], "references": [ { - "url": "https://example.org/ESA-22-11-CVE-1337-1234" + "url": "https://example.org/ESA-22-11-CVE-1900-1234" } ] } diff --git a/schema/docs/cnaContainer-rejected-example.json b/schema/docs/cnaContainer-rejected-example.json index dce4296a3b3..e9d0f9fc479 100644 --- a/schema/docs/cnaContainer-rejected-example.json +++ b/schema/docs/cnaContainer-rejected-example.json @@ -7,8 +7,8 @@ "rejectedReasons": [ { "lang": "en", - "value": "This CVE ID has been rejected or withdrawn by its CVE Numbering Authority." + "value": "This CVE Record has been rejected because it is a duplicate of CVE-1900-12345." } ] } -} \ No newline at end of file +} diff --git a/schema/docs/full-record-advanced-example.json b/schema/docs/full-record-advanced-example.json index da1532278cd..c49bd0d82c3 100644 --- a/schema/docs/full-record-advanced-example.json +++ b/schema/docs/full-record-advanced-example.json @@ -1,8 +1,8 @@ { "dataType": "CVE_RECORD", - "dataVersion": "5.1", + "dataVersion": "5.2", "cveMetadata": { - "cveId": "CVE-1337-1234", + "cveId": "CVE-1900-1234", "assignerOrgId": "b3476cb9-2e3d-41a6-98d0-0f47421a65b6", "assignerShortName": "example", "requesterUserId": "b3476cb9-2e3d-41a6-98d0-0f47421a65b6", @@ -50,8 +50,9 @@ "MacOS", "XT-4500" ], - "collectionURL": "https://example.org/packages", - "packageName": "example_enterprise", + "collectionURL": "https://npmjs.com", + "packageName": "example", + "packageURL": "pkg:npm/example", "repo": "git://example.org/source/example_enterprise", "modules": [ "Web-Management-Interface" @@ -97,29 +98,72 @@ "defaultStatus": "unaffected" } ], + "cpeApplicability": [ + { + "operator": "AND", + "nodes": [ + { + "operator": "OR", + "negate": false, + "cpeMatch": [ + { + "vulnerable": true, + "criteria": "cpe:2.3:a:example_org:example_enterprise:*:*:*:*:*:*:*:*", + "versionStartIncluding": "1.0.0", + "versionEndExcluding": "1.0.6" + }, + { + "vulnerable": true, + "criteria": "cpe:2.3:a:example_org:example_enterprise:*:*:*:*:*:*:*:*", + "versionStartIncluding": "2.1.6", + "versionEndExcluding": "2.1.9" + } + ] + }, + { + "operator": "OR", + "negate": false, + "cpeMatch": [ + { + "vulnerable": false, + "criteria": "cpe:2.3:o:microsoft:windows:*:*:*:*:*:*:*:*" + }, + { + "vulnerable": false, + "criteria": "cpe:2.3:o:apple:macos:*:*:*:*:*:*:*:*" + }, + { + "vulnerable": false, + "criteria": "cpe:2.3:h:some_company:xt-4500:*:*:*:*:*:*:*:*" + } + ] + } + ] + } + ], "descriptions": [ { "lang": "en", - "value": "OS Command Injection vulnerability parseFilename function of example.php in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges. This issue affects: 1.0 versions before 1.0.6, 2.1 versions from 2.16 until 2.1.9.", + "value": "OS Command Injection vulnerability parseFilename function of example.php in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges. This issue affects: 1.0 versions before 1.0.6, 2.1 versions from 2.1.6 until 2.1.9.", "supportingMedia": [ { "type": "text/html", "base64": false, - "value": "OS Command Injection vulnerability <tt>parseFilename</tt> function of <tt>example.php</tt> in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges.<br><br>This issue affects:<br><ul><li>1.0 versions before 1.0.6</li><li>2.1 versions from 2.16 until 2.1.9.</li></ul>" + "value": "OS Command Injection vulnerability <tt>parseFilename</tt> function of <tt>example.php</tt> in the Web Management Interface of Example.org Example Enterprise on Windows, macOS, and XT-4500 allows remote unauthenticated attackers to escalate privileges.<br><br>This issue affects:<br><ul><li>1.0 versions before 1.0.6</li><li>2.1 versions from 2.1.6 until 2.1.9.</li></ul>" } ] }, { "lang": "eo", - "value": "OS-komand-injekta vundebleco parseFilename funkcio de example.php en la Web Administrado-Interfaco de Example.org Example Enterprise ĉe Windows, macOS kaj XT-4500 permesas al malproksimaj neaŭtentikigitaj atakantoj eskaladi privilegiojn. Ĉi tiu afero efikas: 1.0-versioj antaŭ 1.0.6, 2.1-versioj de 2.16 ĝis 2.1.9.", + "value": "OS-komand-injekta vundebleco parseFilename funkcio de example.php en la Web Administrado-Interfaco de Example.org Example Enterprise ĉe Windows, macOS kaj XT-4500 permesas al malproksimaj neaŭtentikigitaj atakantoj eskaladi privilegiojn. Ĉi tiu afero efikas: 1.0-versioj antaŭ 1.0.6, 2.1-versioj de 2.1.6 ĝis 2.1.9.", "supportingMedia": [ { "type": "text/html", "base64": false, - "value": "OS-komand-injekta vundebleco <tt>parseFilename</tt> funkcio de <tt>example.php</tt> en la Web Administrado-Interfaco de Example.org Example Enterprise ĉe Windows, macOS kaj XT-4500 permesas al malproksimaj neaŭtentikigitaj atakantoj eskaladi privilegiojn.<br><br> Ĉi tiu afero efikas:<br><ul><li>1.0-versioj antaŭ 1.0.6</li><li>2.1-versioj de 2.16 ĝis 2.1.9.</li></ul>" + "value": "OS-komand-injekta vundebleco <tt>parseFilename</tt> funkcio de <tt>example.php</tt> en la Web Administrado-Interfaco de Example.org Example Enterprise ĉe Windows, macOS kaj XT-4500 permesas al malproksimaj neaŭtentikigitaj atakantoj eskaladi privilegiojn.<br><br> Ĉi tiu afero efikas:<br><ul><li>1.0-versioj antaŭ 1.0.6</li><li>2.1-versioj de 2.1.6 ĝis 2.1.9.</li></ul>" } ] - } + } ], "metrics": [ { @@ -263,7 +307,7 @@ ], "references": [ { - "url": "https://example.org/ESA-22-11-CVE-1337-1234", + "url": "https://example.org/ESA-22-11-CVE-1900-1234", "name": "ESA-22-11", "tags": [ "vendor-advisory" @@ -298,6 +342,9 @@ "advisory": "ESA-22-11", "discovery": "EXTERNAL" }, + "tags": [ + "unsupported-when-assigned" + ], "taxonomyMappings": [ { "taxonomyName": "ATT&CK", diff --git a/schema/docs/full-record-basic-example.json b/schema/docs/full-record-basic-example.json index b1c3f5eaac0..5f9425c1817 100644 --- a/schema/docs/full-record-basic-example.json +++ b/schema/docs/full-record-basic-example.json @@ -1,8 +1,8 @@ { "dataType": "CVE_RECORD", - "dataVersion": "5.1", + "dataVersion": "5.2", "cveMetadata": { - "cveId": "CVE-1337-1234", + "cveId": "CVE-1900-1234", "assignerOrgId": "b3476cb9-2e3d-41a6-98d0-0f47421a65b6", "state": "PUBLISHED" }, @@ -44,9 +44,9 @@ ], "references": [ { - "url": "https://example.org/ESA-22-11-CVE-1337-1234" + "url": "https://example.org/ESA-22-11-CVE-1900-1234" } ] } } -} \ No newline at end of file +} diff --git a/schema/docs/versions.md b/schema/docs/versions.md index e87a6a26a17..073457e5aed 100644 --- a/schema/docs/versions.md +++ b/schema/docs/versions.md @@ -259,7 +259,7 @@ or `"lessThan": "*"`, which denotes a range with no upper bound at all. Note that `*` is “infinity”, not a wildcard pattern. For example, { - "version": "1.0", + "version": "1.0.0", "versionType": "semver", "lessThan": "2.*", "status": "affected" diff --git a/schema/support/bundling-scripts/README.md b/schema/support/bundling-scripts/README.md new file mode 100644 index 00000000000..53613b736fc --- /dev/null +++ b/schema/support/bundling-scripts/README.md @@ -0,0 +1,47 @@ +# Creating the bundled CVE Record Format JSON schema files +Use the scripts in this directory to create the bundled CVE Record Format JSON schema files. + +## Steps +1. Create a directory structure where all of these files, and no others, exist and +the files correspond to the current version of the CVE Record Format: +- schema/tags/reference-tags.json +- schema/tags/adp-tags.json +- schema/tags/cna-tags.json +- schema/CVE_Record_Format.json +- schema/imports/cvss/cvss-v4.0.json +- schema/imports/cvss/cvss-v2.0.json +- schema/imports/cvss/cvss-v3.0.json +- schema/imports/cvss/cvss-v3.1.json +- schema/docs/cnaContainer-rejected-example.json +- schema/docs/full-record-advanced-example.json +- schema/docs/full-record-basic-example.json +- schema/docs/cnaContainer-basic-example.json +- schema/docs/cnaContainer-advanced-example.json +- schema/support/schema2markmap/package.json +- schema/support/schema2markmap/schema-bundle.js + +2. Run the Linux or Windows Bash script + +5. Observe that the bundled files are created in schema/docs/, and that all of the example files are valid according to the schema files. + +6. In the process, several types of error messages will occur, which can be ignored at least temporarily. There should be no other distinct types of errors: + +- A. Complaints about EOL software packages: + npm warn deprecated json-schema-ref-parser@9.0.9: Please switch to @apidevtools/json-schema-ref-parser + +- B. Complaints about unfixed vulnerabiliies: + 11 vulnerabilities (2 moderate, 9 high) + +- C. Complaints about performance/usability: + npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful. + +- D. Complains about EOL versions: + npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported + +- E. "strict mode" errors related to https://github.com/CVEProject/cve-schema/issues/272 such as: + strict mode: missing type "object" for keyword "additionalProperties" at "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json#" (strictTypes) + strict mode: missing type "object" for keyword "properties" at "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json#" (strictTypes) + strict mode: missing type "object" for keyword "required" at "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json#" (strictTypes) + strict mode: missing type "object" for keyword "properties" at "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json#" (strictTypes) + strict mode: missing type "object" for keyword "required" at "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json#" (strictTypes) + strict mode: missing type "object" for keyword "properties" at "https://cveproject.github.io/cve-schema/schema/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json#" (strictTypes) diff --git a/schema/support/bundling-scripts/bundle-script-linux.sh b/schema/support/bundling-scripts/bundle-script-linux.sh new file mode 100644 index 00000000000..bae0a6e24ac --- /dev/null +++ b/schema/support/bundling-scripts/bundle-script-linux.sh @@ -0,0 +1,14 @@ +export CVE_SCHEMA_DIR=schema +export CVE_SCHEMA_FILENAME=CVE_Record_Format.json +mkdir ~/.npm-global +npm config set prefix ~/.npm-global +export PATH=~/.npm-global/bin:$PATH +npm --prefix "${CVE_SCHEMA_DIR}/support/schema2markmap" install "${CVE_SCHEMA_DIR}/support/schema2markmap" +npm install --loglevel verbose -g yargs ajv-formats@"^1.5.x" ajv-cli@"^4.0.x" +sed 's/file\://g' "${CVE_SCHEMA_DIR}/${CVE_SCHEMA_FILENAME}" > "${CVE_SCHEMA_DIR}/cve-schema.json" +node "${CVE_SCHEMA_DIR}/support/schema2markmap/schema-bundle.js" "${CVE_SCHEMA_DIR}/cve-schema.json" "${CVE_SCHEMA_DIR}/docs/" +ajv compile -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled.json" -d "${CVE_SCHEMA_DIR}/docs/full-record-basic-example.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled.json" -d "${CVE_SCHEMA_DIR}/docs/full-record-advanced-example.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json" -d "${CVE_SCHEMA_DIR}/docs/cnaContainer-advanced-example.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json" -d "${CVE_SCHEMA_DIR}/docs/cnaContainer-basic-example.json" diff --git a/schema/support/bundling-scripts/bundle-script-win.sh b/schema/support/bundling-scripts/bundle-script-win.sh new file mode 100644 index 00000000000..8f3474d31fb --- /dev/null +++ b/schema/support/bundling-scripts/bundle-script-win.sh @@ -0,0 +1,13 @@ +export CVE_SCHEMA_DIR=$(pwd)/schema +export CVE_SCHEMA_FILENAME=CVE_Record_Format.json +npm install --loglevel verbose -g yargs ajv-formats@"^1.5.x" ajv-cli@"^4.0.x" +pushd "${CVE_SCHEMA_DIR}/support/schema2markmap" +npm install +popd +sed 's/file\://g' "${CVE_SCHEMA_DIR}/${CVE_SCHEMA_FILENAME}" > "${CVE_SCHEMA_DIR}/cve-schema.json" +node "${CVE_SCHEMA_DIR}/support/schema2markmap/schema-bundle.js" "${CVE_SCHEMA_DIR}/cve-schema.json" "${CVE_SCHEMA_DIR}/docs/" +ajv compile -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled.json" -d "${CVE_SCHEMA_DIR}/docs/full-record-basic-example.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled.json" -d "${CVE_SCHEMA_DIR}/docs/full-record-advanced-example.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json" -d "${CVE_SCHEMA_DIR}/docs/cnaContainer-advanced-example.json" +ajv validate -c ajv-formats -s "${CVE_SCHEMA_DIR}/docs/CVE_Record_Format_bundled_cnaPublishedContainer.json" -d "${CVE_SCHEMA_DIR}/docs/cnaContainer-basic-example.json" diff --git a/schema/support/schema2markmap/index.js b/schema/support/schema2markmap/index.js index 3703dc2d55b..ba4d572e927 100644 --- a/schema/support/schema2markmap/index.js +++ b/schema/support/schema2markmap/index.js @@ -1,5 +1,5 @@ // Author: Chandan BN (c) 2021 -// (1) convert CVE JSON schema to a mindmap +// (1) convert CVE Record Format JSON schema to a mindmap var ml = require('markmap-lib') var Transformer = ml.Transformer; @@ -16,7 +16,7 @@ const { Markmap, loadCSS, loadJS } = markmap; let forDeletion = ['properties', 'items', 'anyOf', 'allOf', 'oneOf']; -var markdown = "# CVE JSON Record\n"; +var markdown = "# CVE Record Format\n"; function postfunc(obj, path, parent, parentPath) { if (path[1] && isNaN(path[1])) { @@ -56,7 +56,7 @@ async function schemaMindMap() { // create mindmap html var html = fillTemplate(root, assets); - html = html.replace('<title>Markmap', 'CVE JSON v5 Mindmap'); + html = html.replace('Markmap', 'CVE Record Format Mindmap'); console.log(html); } diff --git a/schema/support/schema2markmap/schema-bundle.js b/schema/support/schema2markmap/schema-bundle.js index 7409ce807b3..d229c0eac8b 100644 --- a/schema/support/schema2markmap/schema-bundle.js +++ b/schema/support/schema2markmap/schema-bundle.js @@ -23,13 +23,13 @@ async function schemaBundle() { delete metricProperties.cvssV2_0.license; - fs.writeFile(`${dirName}/CVE_Record_Format.json`, + fs.writeFile(`${dirName}/CVE_Record_Format_bundled.json`, JSON.stringify(cveSchemaBundle, null, 2), err => { if(err) throw err; else - console.log('CVE_Record_Format.json created'); + console.log('CVE_Record_Format_bundled.json created'); } ); @@ -40,6 +40,7 @@ async function schemaBundle() { "title": `CVE Record Format ${t} sub schema`, "description": `CVE Record Format ${t} format`, "definitions": cveSchemaBundle.definitions, + "type": "object", "properties": { }, "additionalProperties": false diff --git a/schema/support/tests/README.md b/schema/support/tests/README.md index 0b66406df59..1f42589b9e5 100644 --- a/schema/support/tests/README.md +++ b/schema/support/tests/README.md @@ -1,11 +1,11 @@ -# All records in vald directory must validate: +# All records in valid directory must validate: $ node ../Node_validator/validate.js valid/*.json ... Summary: All files PASSED validation. -# All records in invald directory must fail to validate: +# All records in invalid directory must fail to validate: $ node ../Node_validator/validate.js invalid/*.json