1.0.0 (SEMVER)
Describe the “good enough” OSV record that will be imported by OSV.dev
This does not discuss the problem of record bit rot over time, after initial successful import. The problem of continuous revalidation and treatment of records that have been successfully imported will be dealt with separately in the companion to this, Managing the Perishability of OSV Records.
Deferred to a future iteration: validating the existence of vulnerable functions in the ecosystem_specific
field, if supplied.
OSV.dev seeks to be a comprehensive, accurate and timely database of known vulnerabilities that is highly automation friendly. In order to meet this accuracy goal, a quality bar needs to be both defined and sustainably enforced.
As a prerequisite, it is assumed that a record passes JSON Schema validation for the version of the OSV Schema it declares itself to comply with in the schema_version
field, or 1.0.0 if it does not. It is also assumed that the vulnerability discussed in the OSV record is valid and affects the software described.
A high quality OSV record allows a consumer of that record to be able to answer the following questions in an automated way, at scale:
The definition of “impact” will vary depending on how fine-grained the information available is (i.e. package-level or symbol-level for software library packages). Package-level precision is the minimum standard.
affected[]
.ranges[]
.events[]
.introduced
is definedaffected[]
.ranges[]
.events[]
.fixed
over affected[]
.ranges[]
.events
.last_affected
introduced..fixed
and/or introduced..last_affected
(i.e. introduced and fixed versions or commits can’t be the same)introduced
are before/less than fixed
/last_affected
according to the canonical package registry or project version controlECOSYSTEM
and SEMVER
) ranges
GIT
) ranges
repo
(i.e. they are not from another GitHub fork)package.ecosystem
, and a unique identifier
prefix for it, are defined in the OSV Schemapackage.name
exists within the defined package.ecosystem
, and is canonically encoded to be unambiguous (i.e. normalized)package.url
field conform to the specificationreference
URLs return a 2xx or 3xx response at the time of publicationalias
to the equivalent CVE record is presentrelated
identifiers are presentintroduced
and fixed
versionsintroduced
and fixed
commits
introduced
and fixed
versionsrelated
CVE record IDs(As at version 1.6.3, generated by Gemini from the OSV JSON schema)
Top-Level Information:
Optional, but validated when present:
Additional Validation Rules:
affected
Array:
type
of range, ensuring the correct properties are present (e.g., repo
is required when type
is GIT
).last_affected
is specified in events
, then fixed
cannot be present in the same events
array.