Skip to content

docs: add documentation for CVE records #1182

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.

Sign up for GitHub

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

Draft
DarshanCode2005 wants to merge 6 commits into
base: main
Choose a base branch
from
+17 −0
Draft

docs: add documentation for CVE records #1182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0dc1b5b
docs: add documentation for CVE records
DarshanCode2005 Jul 11, 2026
f76731f
Update docs/cve_records.md
DarshanCode2005 Jul 13, 2026
781cb53
Update docs/cve_records.md
DarshanCode2005 Jul 13, 2026
1870449
fix: remove unused from doc
DarshanCode2005 Jul 13, 2026
a7d9fb9
docs: remove the duplication of implementation
DarshanCode2005 Jul 13, 2026
c807853
docs: adding implementation for automatic linkage
DarshanCode2005 Jul 13, 2026
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
1 change: 1 addition & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ Resources to help you get started:

- [**Quickstart guide**](./docs/quickstart.md): Set up a database, run the service locally.
- [**Manual data ingestion and matching**](./docs/data_ingestion_and_matching.md): Ingest Nixpkgs metadata and CVEs into your local instance.
- [**CVE records**](./docs/cve_records.md): What the tracker stores for each CVE and why matching needs manual triage.

@fricklerhandwerk fricklerhandwerk Jul 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [**CVE records**](./docs/cve_records.md): What the tracker stores for each CVE and why matching needs manual triage.
- [**CVE records**](./docs/cve_records.md): What the tracker stores for each CVE

- [**Architecture Overview**](docs/README.md): High-level system design and component interaction.
- [**Architecture Diagram**](docs/architecture.mermaid): Visual representation of the system (Mermaid source).
- [**Design Documents**](docs/design/): Detailed design specifications for individual features (E.g., linkage).
Expand Down
16 changes: 16 additions & 0 deletions docs/cve_records.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# CVE records

The tracker parses [CVE JSON 5.0](https://github.com/CVEProject/cve-schema) records from the [official CVE List](https://github.com/CVEProject/cvelistV5) and stores them in the database.
The schema follows the upstream format; see the [CVE record content rules](https://www.cve.org/ResourcesSupport/AllResources/CNARules#section_5_CVE_Record_Content) and the [schema reference](https://cveproject.github.io/cve-schema/schema/docs/) for field definitions.

Implementation: [`src/shared/models/cve.py`](../src/shared/models/cve.py).

A `CveRecord` has one or more `Container`s (CNA or ADP). Matching mainly uses each container's `AffectedProduct` entries: vendor/product names, package names, CPE strings, and version constraints.

@fricklerhandwerk fricklerhandwerk Jul 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A `CveRecord` has one or more `Container`s (CNA or ADP). Matching mainly uses each container's `AffectedProduct` entries: vendor/product names, package names, CPE strings, and version constraints.
A `CveRecord` has one or more `Container`s (CNA or ADP).
Matching mainly uses each container's `AffectedProduct` entries: vendor/product names, package names, CPE strings, and version constraints.

https://rhodesmill.org/brandon/2012/one-sentence-per-line/


## Why matching needs manual triage

@fricklerhandwerk fricklerhandwerk Jul 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@DarshanCode2005 DarshanCode2005 Jul 13, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's discuss in sync, for now not moving this.

@fricklerhandwerk fricklerhandwerk Jul 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's move it into a new docs/design/README.md since this is where the explanations live as far as we have them.


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 information in CVE data is often incomplete or imprecise.

The tracker [proposes links automatically](../src/shared/listeners/automatic_linkage.py), but a human must verify each match, ignore irrelevant packages, and publish an issue when Nixpkgs is actually affected.

@fricklerhandwerk fricklerhandwerk Jul 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is conflating two ideas:

  1. Why the design is the way it is (goes to the design README)
  2. Where the implementation lives and how it works.

It's fine to link from this sentence to a document which talks about the implementation overall, like the upper part of the current file. But the specifics, including the link to the code, should be in that other document IMO.