Skip to content

Add a severity source field #510

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

Merged
another-rex merged 4 commits into from
Jul 9, 2026
Merged

Add a severity source field #510

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6753517
add severity source property
conorfitch Feb 3, 2026
393feff
add enum for source
conorfitch May 24, 2026
a32803c
change CVE-CNA due to proto constraint
conorfitch May 26, 2026
9cdcb9d
proto bindings and build script output
conorfitch May 26, 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
164 changes: 117 additions & 47 deletions bindings/go/osvschema/vulnerability.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 26 additions & 8 deletions docs/schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ A JSON Schema for validation is also available
"details": string,
"severity": [ {
"type": string,
"score": string
"score": string,
"source": string
} ],
"affected": [ {
"package": {
Expand All @@ -67,7 +68,8 @@ A JSON Schema for validation is also available
},
"severity": [ {
"type": string,
"score": string
"score": string,
"source": string
} ],
"ranges": [ {
"type": string,
Expand Down Expand Up @@ -143,8 +145,8 @@ string of the format `<DB>-<ENTRYID>`, where `DB` names the database and
`ENTRYID` is in the format used by the database. For example: "OSV-2020-111",
"CVE-2021-3114", or "GHSA-vp9c-fpxx-744v".

The `x_` prefix can be used to denote a local database that isn't aggregated
by OSV.dev, allowing external records to be schema-compliant. For example:
The `x_` prefix can be used to denote a local database that isn't aggregated
by OSV.dev, allowing external records to be schema-compliant. For example:
"x_CUSTOM-0001".

The defined database prefixes and their "home" databases are:
Expand Down Expand Up @@ -789,15 +791,16 @@ display sites to unnecessary vulnerabilities.)
{
"severity": [ {
"type": string,
"score": string
"score": string,
"source": string
} ]
}
```

The `severity` field is a JSON array that allows generating systems to describe
the severity of a vulnerability using one or more quantitative scoring methods.
Each `severity` item is a JSON object specifying a `type` and `score` property,
described below.
as well as an optional `source` property, described below.

### severity[].type field

Expand All @@ -817,6 +820,20 @@ describes the quantitative method used to calculate the associated `score`.
The `severity[].score` property is a string representing the severity score based
on the selected `severity[].type`, as described above.

### severity[].source field

The `severity[].source` property is an optional string indicating the origin of the
severity assessment.

If `source` is omitted, the rating is implicitly attributed to the home database
(as identified by the record's `id` field), whether as author or endorser.

| Source | Description |
| --------- | ----------- |
| `NVD` | The severity was provided by the [National Vulnerability Database (NVD)](https://nvd.nist.gov/). |
| `CNA` | The severity was provided by the [CVE Numbering Authority (CNA)](https://www.cve.org/ProgramOrganization/CNAs) that assigned the CVE. |
| `SELF` | The severity was provided by the home database. Unlike omitting `source`, this is an explicit declaration of provenance. |

## affected fields

```json
Expand All @@ -829,7 +846,8 @@ on the selected `severity[].type`, as described above.
},
"severity": [ {
"type": string,
"score": string
"score": string,
"source": string
} ],
"ranges": [ {
"type": string,
Expand Down Expand Up @@ -1070,7 +1088,7 @@ Only **a single type** (either `introduced`, `fixed`, `last_affected`,
`limit`) is allowed in each event object. For instance,
`{"introduced": "1.0.0", "fixed": "1.0.2"}` is **invalid**.

Entries in the `events` array may be "last_affected" or "fixed" events,
Entries in the `events` array may be "last_affected" or "fixed" events,
but not both. It's **strongly recommended** to use `fixed` instead of
`last_affected` where possible, as it precisely identifies the version which
contains the fix. `last_affected` should be thought of as the hard ceiling
Expand Down
9 changes: 9 additions & 0 deletions proto/vulnerability.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,10 +127,19 @@ message Severity {
CVSS_V4 = 3;
Ubuntu = 4;
}
// Source of the severity.
enum Source {
SOURCE_UNSPECIFIED = 0;

@jess-lowe jess-lowe May 27, 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.

I think because if it's unspecified, it's implicitly SELF, maybe we just set SELF as 0 and remove SOURCE_UNSPECIFIED?

@conorfitch conorfitch May 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Ah yes, that's a good point - is there any special meaning of "0" that this would have other implications for depending on how this is used?

Also would you say there's any semantic difference between specifying SELF vs omitting it, that should be preserved? e.g. omitting might not necessarily say that the db produced it (but it at least endorses it), whilst an explicit SELF states that the severity originates from that db - or do they just represent the same thing?

@conorfitch conorfitch Jun 17, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Hey @jess-lowe I'm just coming back to this now - I don't have much knowledge in this area but I was looking at the docs and found this section: https://protobuf.dev/best-practices/dos-donts/#unspecified-enum
Would it make sense to still keep SOURCE_UNSPECIFIED then based on that description?

@another-rex another-rex Jun 18, 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.

I can see it being fine both ways. Let's keep the UNSPECIFIED there then, in-case we ever want to change the default interpretation in the future.

FYI: Our team is traveling next week, so this will likely get merged in the week after.

NVD = 1;
CNA = 2;
SELF = 3;
}
// The type of this severity entry.
Type type = 1;
// The quantitative score.
string score = 2;
// Optional. The source of this severity assessment.
Source source = 3;
}

message Credit {
Expand Down
8 changes: 8 additions & 0 deletions tools/osv-linter/internal/checks/schema_generated.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,14 @@
},
"score": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"NVD",
"CNA",
"SELF"
]
}
},
"allOf": [
Expand Down
8 changes: 8 additions & 0 deletions validation/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,14 @@
},
"score": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"NVD",
"CNA",
"SELF"
]
}
},
"allOf": [
Expand Down
Loading