cve/schema

The "schema" of the files in this directory.

We are treating this directory as a "database", as hey, what else is a
filesystem but one?

This directory contains 3 "root" directories:
	- published
	- rejected
	- reserved

These 3 directories contain the CVE ids allocated to us that are in one of the
three states.


Reserved
--------

Ids become "reserved" when they are allocated from CVE for our use.  At this
point in time they are nothing more but an empty placeholder.

When allocated, new empty files are created in the reserved directory in the
following format:
	reserved/YEAR/CVE-YEAR-ID

One example would be the file
	reserved/2023/CVE-2023-00042
which would mean that the CVE id "CVE-2023-00042" is reserved by our project
and is free to be used for any issue that comes up that would need an id
assigned for the year 2023.

Note, the file may contain text information based on stuff the kernel cve team
deems is needed.  More documentation will be written in the future as we figure
out what is needed.


Published
---------

Ids become "published" when they are submitted to CVE for publication.  To do
this, normally a git commit id is used to generate the information in the CVE
entry.

When published, five files for each CVE id are created in the following naming
format:
	published/YEAR/CVE-YEAR-ID
	published/YEAR/CVE-YEAR-ID.sha1
	published/YEAR/CVE-YEAR-ID.json
	published/YEAR/CVE-YEAR-ID.mbox
	published/YEAR/CVE-YEAR-ID.dyad

The CVE-YEAR-ID file will be the original file that was in the reserved
directory, in case text information in it was present.  It can also be used to
hold notes and information about the specific CVE id that don't fit into the
other files.

The .sha1 file shall contain the git sha1 of the commit that fixes this CVE id.

The .json file shall contain the json formatted CVE entry that can be submitted
to CVE when published.

The .mbox file shall contain the mail message of the CVE entry that can be
submitted to the public mailing list for publication in human-readable format.

The .dyad file shall contain the output of the 'dyad' tool that shows the pairs
of vulnerable:fixed versions and git ids for the .sha1 of the CVE entry.  This
file is easy to parse by tools and is used by some of the existing scripts.

If a:
	published/YEAR/CVE-YEAR-ID.vulnerable
file is present, the cve_update script will use the git sha in that file as the
"commit where the vulnerability showed up" for doing the logic of creating the
.json and .mbox files.  This allows us to set the commit id for this for
commits that do NOT have a "Fixes:" tag, or if the "Fixes:" tag is incorrect.
Note, this file can contain multiple vulnerable git ids, separated by a space.

If a:
	published/YEAR/CVE-YEAR-ID.diff
file is present, the cve_update script will use that as a diff against the
kernel changelog text to replace the cve text wording with the modified text.
This allows us to modify the CVE entry text for when it is wrong or confusing.

If a:
	published/YEAR/CVE-YEAR-ID.reference
file is present, the cve_update script will use that to add a URL reference to
the json and mbox entry.  The file can contain multiple URL references, one per
line.


Rejected
--------

Ids become "rejected" when they are not deemed to be actual issues.  When
rejected, any previously published information shall move to the rejected/
directory, and the CVE will be submitted to cve.org to be rejected.