What Is OSV? The Complete Guide to the Open Source Vulnerabilities Database

What Is OSV?

OSV stands for Open Source Vulnerabilities. It is a distributed vulnerability database created by Google in 2021 that aggregates security advisories from dozens of ecosystem-specific sources into a single, machine-readable format. Unlike traditional vulnerability databases that rely on product names and vendor identifiers, OSV describes every vulnerability in terms that developers actually use: package names and version strings from their native package manager.

The central insight behind OSV is that the Common Platform Enumeration (CPE) system used by the NVD creates unnecessary ambiguity. A CPE string like cpe:2.3:a:openssl:openssl:3.0.2 could match multiple distributions of OpenSSL across different Linux distros, forks, and bundled copies. By contrast, an OSV advisory for the Alpine ecosystem's openssl package at version 3.0.2-r0 is unambiguous. There is exactly one package with that name in that ecosystem, and the version string follows Alpine's versioning scheme.

OSV is not a vulnerability reporting service. It does not assign CVE numbers, conduct original research, or evaluate severity scores. Its role is aggregation and normalization: it pulls advisories from upstream sources like the GitHub Advisory Database, RustSec, the Go Vulnerability Database, and Linux distribution security trackers, then re-publishes them in a common JSON format with a free API at api.osv.dev.

The database is fully open source, the API requires no authentication, and the data is licensed under CC-BY-4.0. This makes it one of the most accessible vulnerability data sources available to the security community.

How OSV Differs from NVD, GHSA, and Vendor Advisories

Understanding where OSV fits requires comparing it with the other major vulnerability data sources. Each serves a different purpose and uses a different identification and matching system.

The NVD remains the authoritative source for CVE identifiers and CVSS severity scores. However, its CPE-based matching system often produces false positives because CPE strings are ambiguous. A CPE for "curl" might match the standalone curl binary, a vendor-patched version bundled in a Linux distro, or a completely unrelated product that happens to include "curl" in its name.

GHSA (GitHub Security Advisories) is high-quality but limited to the six ecosystems GitHub supports natively. Vendor advisories like Red Hat's RHSA or Ubuntu's USN are authoritative for their respective distributions but require querying each vendor separately.

OSV's advantage is breadth plus precision: it covers 24+ ecosystems with exact package matching, all through a single API. For a deeper comparison of NVD scoring, see our guide on understanding the NVD and CVSS.

The OSV Advisory Format — Explained with Examples

Every OSV advisory is a JSON document that follows the OSV Schema specification, maintained by the Open Source Security Foundation (OpenSSF). The schema is designed to be machine-parseable while remaining human-readable. Here is a real advisory for the Log4Shell vulnerability (CVE-2021-44228), annotated with explanations:

{
  // Unique identifier — prefixed by the source database
  "id": "GHSA-jfh8-c2jp-5v3q",

  // Human-readable one-line description
  "summary": "Apache Log4j2 JNDI features do not protect against
              attacker-controlled LDAP and other JNDI related endpoints",

  // Cross-references to the same vuln in other databases
  "aliases": ["CVE-2021-44228"],

  // When this advisory was last updated
  "modified": "2024-02-16T08:18:32Z",

  // The affected packages — this is the core of the format
  "affected": [
    {
      "package": {
        "ecosystem": "Maven",                              // Package manager
        "name": "org.apache.logging.log4j:log4j-core"     // Exact Maven coordinate
      },
      "ranges": [
        {
          "type": "ECOSYSTEM",                              // Use Maven versioning
          "events": [
            { "introduced": "2.0-beta9" },                 // First vulnerable version
            { "fixed": "2.15.0" }                          // First patched version
          ]
        }
      ]
    }
  ],

  // CVSS severity vector string
  "severity": [
    {
      "type": "CVSS_V3",
      "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"  // 10.0 Critical
    }
  ],

  // Links to patches, advisories, and articles
  "references": [
    { "type": "ADVISORY", "url": "https://nvd.nist.gov/vuln/detail/CVE-2021-44228" },
    { "type": "FIX", "url": "https://github.com/apache/logging-log4j2/pull/608" },
    { "type": "PACKAGE", "url": "https://central.sonatype.com/artifact/..." }
  ]
}

The key fields to understand are:

• id — A globally unique identifier. The prefix indicates the source: GHSA- for GitHub, RUSTSEC- for Rust, GO- for Go, DLA- for Debian LTS, etc.
• aliases — Other identifiers for the same vulnerability. This is how OSV links a GHSA advisory to its CVE number.
• affected[].package — The ecosystem and exact package name. This is what makes OSV matching precise: there is no ambiguity about which "log4j" is affected.
• affected[].ranges[].events — A list of version events that define the affected range. introduced marks where the vulnerability was added, fixed marks where it was patched, and last_affected (optional) marks the last known vulnerable version when no fix exists.
• severity — Optional CVSS vector strings. Not all advisories include severity data, which is why scanners often supplement OSV with NVD CVSS scores.

A single advisory can list multiple affected packages (e.g., when the same library is published to both Maven and PyPI), and each package can have multiple affected version ranges (e.g., when a vulnerability affects both the 2.x and 3.x release lines with separate fixes).

All 24+ Supported Ecosystems

OSV aggregates vulnerability data from the following ecosystem sources. Each source maintains its own advisory database, which OSV normalizes into the common schema. Advisory counts are approximate and change daily.

Language Ecosystems

Linux Distributions

Other Sources

When a package exists in multiple ecosystems (for example, a Python library published to both PyPI and as a Debian package), OSV maintains separate advisories for each ecosystem. This means a single query for the correct ecosystem returns only the advisories relevant to your specific installation method.

How to Query the OSV API

The OSV API is a REST API at https://api.osv.dev/v1/. It requires no API key, no authentication, and supports cross-origin requests (CORS). There are three main endpoints:

Query a single package

Send a POST request to /v1/query with a package ecosystem, name, and optionally a version. If you omit the version, you get all known vulnerabilities for that package across all versions.

# Query a specific version of a package
curl -X POST https://api.osv.dev/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "package": {
      "ecosystem": "npm",
      "name": "lodash"
    },
    "version": "4.17.20"
  }'

Batch query

The batch endpoint at /v1/querybatch accepts an array of queries and returns results for each one. This is essential for vulnerability scanners that need to check hundreds of packages at once.

# Batch query multiple packages at once
curl -X POST https://api.osv.dev/v1/querybatch \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "package": { "ecosystem": "PyPI", "name": "requests" },
        "version": "2.25.0"
      },
      {
        "package": { "ecosystem": "npm", "name": "express" },
        "version": "4.17.1"
      },
      {
        "package": { "ecosystem": "Go", "name": "golang.org/x/net" },
        "version": "0.0.0-20211209124913-491a49abca63"
      }
    ]
  }'

Get a specific vulnerability by ID

# Fetch full details for a specific advisory
curl https://api.osv.dev/v1/vulns/GHSA-jfh8-c2jp-5v3q

# Works with any ecosystem ID format
curl https://api.osv.dev/v1/vulns/RUSTSEC-2021-0078
curl https://api.osv.dev/v1/vulns/GO-2022-0969

Python example

import requests

resp = requests.post("https://api.osv.dev/v1/query", json={
    "package": {"ecosystem": "PyPI", "name": "django"},
    "version": "3.2.0"
})

for vuln in resp.json().get("vulns", []):
    severity = ""
    if vuln.get("severity"):
        severity = f" [{vuln['severity'][0].get('score', '')}]"
    print(f"{vuln['id']}: {vuln.get('summary', 'No summary')}{severity}")

# Output:
# GHSA-v6rh-hp5x-86rv: Django QuerySet.order_by() SQL injection
# GHSA-qrw5-5h28-modded: ...

JavaScript / Node.js example

const res = await fetch("https://api.osv.dev/v1/query", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    package: { ecosystem: "npm", name: "express" },
    version: "4.17.1",
  }),
});
const { vulns = [] } = await res.json();
console.log(`Found ${vulns.length} vulnerabilities`);
vulns.forEach(v => console.log(`  ${v.id}: ${v.summary}`));

For production use, keep these best practices in mind: always send batch queries when checking multiple packages (one HTTP round-trip instead of hundreds), cache responses with the modified timestamp as a cache key, and handle the case where an advisory has no severity field (not all ecosystem sources include CVSS scores).

How OSV Aggregates Vulnerability Data

OSV acts as a central aggregator, pulling advisories from upstream ecosystem sources, normalizing them into the OSV Schema, and serving them through a unified API. Here is how data flows from source to scanner:

Each upstream source publishes advisories in its own format. OSV normalizes them into the common OSV Schema, deduplicates entries that describe the same vulnerability, and cross-links them via the aliases field. The resulting unified database is available both as an API and as bulk JSON exports in Google Cloud Storage.

Live OSV Lookup Tool

Try querying the OSV database right now. This tool sends requests directly to the api.osv.dev API from your browser — no server-side processing, no data collection. Select an ecosystem, enter a package name, and optionally a version to see all known vulnerabilities.

Results are fetched directly from the OSV API. Click any advisory ID to view full details on osv.dev. For automated scanning of container images and source archives, try ScanRook's upload scanner.

OSV vs. Other Databases — When to Use Each

No single vulnerability database covers everything. The right choice depends on what you are scanning and what kind of matching you need.

• Use OSV when scanning application dependencies (npm packages, Python libraries, Go modules, etc.) or Linux distribution packages. OSV's ecosystem-native matching gives you the most precise results with the fewest false positives.
• Use the NVD when you need CVE numbers, official CVSS scores, or when scanning binaries and proprietary software that do not belong to any OSV ecosystem. The NVD's CPE matching can match vulnerabilities to any software product, regardless of how it was installed. Read more in our NVD and CVSS guide.
• Use GHSA when you are already in the GitHub ecosystem and want Dependabot alerts integrated into your pull request workflow.
• Use vendor advisories (RHSA, USN, DSA) when you need to know whether a specific vendor-patched version resolves a vulnerability. Vendor advisories often contain backported fixes that are not reflected in upstream version numbers.

The best practice is to query multiple sources and merge the results. This is exactly what ScanRook does: it queries OSV for package-level matches, the NVD for CVE details and CVSS scores, and Red Hat OVAL for distribution-specific advisories, then produces a unified report. Learn more about how this works in our installed state vs. advisory matching article.

Frequently Asked Questions about OSV

Further Reading

• osv.dev — Official OSV web interface and search
• github.com/google/osv.dev — Source code for the OSV platform
• github.com/google/osv-scanner — Google's official OSV scanning tool
• OSV Schema specification — The JSON schema that all advisories follow
• NIST NVD — National Vulnerability Database

Related ScanRook articles