Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

docs(vers): clarify what is (not) NVD #330

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions VERSION-RANGE-SPEC.rst
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ conventions in use:
version. And also provides a concrete enumeration of the available ranges as
a daily feed.

- The version 5 of the NVD CVE JSON data format at
- The version 5 of the CVE JSON data format at
https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0.schema#L303
defines version ranges with a starting version, a versionType, and an upper
limit for the version range as lessThan or lessThanOrEqual; or an enumeration
Expand Down Expand Up @@ -752,7 +752,7 @@ most vulnerable ranges yet:
and vulnerable ranges when a version must be excluded and the set of existing
versions is not yet known,

- this make some ranges more verbose such as with the NVD CVE v5 API ranges
- this make some ranges more verbose such as with the CVE v5 API ranges
notation that can include their upper limit and would need two constraints.

Another high level difference between the two specifications are the
Expand All @@ -761,15 +761,15 @@ the Package URL package "type" used in ``vers``. This spec will provide a strict
mapping between the OSV ecosystem and the ``vers`` versioning schemes values.


Why not use the NVD CVE v5 API Ranges?
Why not use the CVE v5 API Ranges?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See:

- https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json#L303
- https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json#L123

The version 5 of the NVD CVE JSON data format defines version ranges with a
The version 5 of the CVE JSON data format defines version ranges with a
starting version, a versionType, and an upper limit for the version range as
lessThan or lessThanOrEqual or as an enumeration of versions. The versionType
and the package collectionURL possible values are only indicative and left out
Expand All @@ -778,16 +778,16 @@ of this specification and both seem strictly equivalent to the Package URL

The semantics and expressiveness of each range are similar and ``vers`` provides
a compact notation rather than a more verbose JSON notation. ``vers`` supports
strictly the conversion of any NVD v5 range to its notation and further
strictly the conversion of any CVE v5 range to its notation and further
provides a concrete list of well known versioning schemes. ``vers`` design was
informed by the NVD CVE v5 API schema spec and its authors.
informed by the CVE v5 API schema spec and its authors.

When NVD v5 becomes active, this spec will provide a strict mapping between the
NVD versionType and the ``vers`` versioning schemes values. Furthermore, this
When CVE v5 becomes active, this spec will provide a strict mapping between the
CVE ``versionType`` and the ``vers`` versioning schemes values. Furthermore, this
spec and the Package URL "types" should be updated accordingly to provide
a mapping with the upcoming NVD collectionURL that will be effectively used.
a mapping with the upcoming CVE ``collectionURL`` that will be effectively used.

There is one issue with NVD v5: it introduces a new trailing "*" notation that
There is one issue with CVE v5: it introduces a new trailing "*" notation that
does not exists in most version ranges notations and may not be computable
easily in many cases. The description of the "lessThan" property is:

Expand All @@ -806,7 +806,7 @@ The conversion to ``vers`` range should be:
computed for ``semver`` versions as ``>=1.0|<2`` but is not accurate unless
as versioning schemes have different rules. For instance, pre-release may be
treated in some case as part of the v1. branch and in some other cases as part
of the v2. branch. It is not clear if with "2.*" the NVD spec means:
of the v2. branch. It is not clear if with "2.*" the CVE v5 spec means:

- ``<2``
- or something that excludes any version string that starts with ``2.``
Expand Down