docs: add documentation for CVE records#1182
Conversation
fricklerhandwerk
left a comment
fricklerhandwerk
left a comment
There was a problem hiding this comment.
This is pretty good and can just be made even simpler by not repeating what's already in the code.
| | `assigner` / `requester` | CNA organizations that assigned or requested the ID | | ||
| | `date_published`, `date_updated`, `date_reserved` | Timestamps from the CVE Program | | ||
| | `serial` | Record revision number | | ||
| | `triaged` | Internal flag: a security team member has reviewed this CVE | |
There was a problem hiding this comment.
That's not correct IIRC, it simply says whether it was touched by the system on ingestion (or matching, not sure). But we're not using that for anything. It was originally intended to avoid matching over a CVE twice. The new rematching logic by @adekoder allows displacing that with the fact that a suggestion is linked to it (modulo naming changes proposed by @florentc).
There was a problem hiding this comment.
Thanks, I mixed that up, because it is not doing any useful work , I will remove it from the doc
|
|
||
| Implementation: [`src/shared/models/cve.py`](../src/shared/models/cve.py). | ||
|
|
||
| ## Top-level record (`CveRecord`) |
There was a problem hiding this comment.
I'm very skeptical whether we should duplicate information that already lives in the code. It should be either avoided entirely or have an extraordinarily strong justification. You already linked to the implementation, so why repeat anything that we can find there?
There was a problem hiding this comment.
Fair point. The field tables mostly restated the model, and anyone who needs the details can read cve.py or the upstream schema. I'll drop them and keep the doc focused on structure and why triage is still manual.
|
|
||
| Each `Version` entry expresses a constraint: exact version (`version`), upper bound (`less_than`, `less_equal`), and whether that range is affected. | ||
|
|
||
| ## Why matching needs manual triage |
There was a problem hiding this comment.
This is a good question to answer, but it may be better suited for a more high-level document such as a (to be added) entry point to the design decisions (or a note in one of them), or even the top-level README. But if there's no obvious other place, it's probably fine to leave it here for now.
There was a problem hiding this comment.
Let's discuss in sync, for now not moving this.
|
|
||
| CVE records describe upstream software by vendor names, product names, and CPE strings. Nixpkgs identifies packages by attribute paths and derivation names. Those naming schemes rarely align one-to-one, and version comparison in CVE data is often incomplete or imprecise. | ||
|
|
||
| The tracker proposes links automatically, but a human must verify each match, ignore irrelevant packages, and publish an issue when Nixpkgs is actually affected. |
There was a problem hiding this comment.
A good opportunity to link to the implementation!
Co-authored-by: Valentin Gagarin <valentin@gagarin.work>
Co-authored-by: Valentin Gagarin <valentin@gagarin.work>
2 participants
Closes #182
Adding information on what the tracker stores on each CVE