Table of contents
- What is the OSV database?
- Key features of the OSV database
- What OSV is used for in practice
- How the OSV database works
- Examples of OSV usage
Vulnerability management plays a key role in protecting systems and applications. This article explores the OSV database (Open Source Vulnerabilities), an open source project designed to map and monitor vulnerabilities in software projects.
We’ll explain what it is, how it works, its main features, its practical uses, and provide real-world examples of its application.
What is the OSV database?
The OSV database is an open source initiative launched by Google with the goal of creating a unified, standardized source of information about vulnerabilities in open source software packages.
OSV stands for Open Source Vulnerabilities, and the platform is built specifically to help developers access and understand security issues affecting the libraries and components they use.
Unlike other databases, OSV is tailored for developer needs. It provides structured, up-to-date, and easily searchable data. The project relies on a standardized format called the OSV schema, which allows easy integration with other security tools and development workflows.
Key features of the OSV database
The key features of the OSV database make it stand out as an essential tool in the world of cyber security, especially for developers and teams working with open source software.
More than just a vulnerability archive, OSV is designed to simplify access to security data, making it easier to understand and integrate directly into modern development workflows. Let’s explore its most important features in detail.
One of the most appreciated capabilities is the automatic integration with major source code platforms like GitHub, GitLab, and other public repositories.
This means OSV can detect vulnerability fixes, code changes, and security-related commits directly from the source. It enables a streamlined and real-time monitoring process, reducing the need for developers or security analysts to manually track dozens of different advisory sources.
Another fundamental aspect is OSV’s use of a structured, open data format, based on the OSV schema, a JSON-based standard designed for automation and interoperability.
This structure allows the OSV database to plug easily into existing tools, whether it’s vulnerability scanners, CI/CD pipelines, or internal dashboards.
For organizations embracing DevSecOps, where automation is critical, this level of compatibility significantly boosts efficiency.
The multi-ecosystem support offered by OSV is another major advantage. The database isn’t limited to a single language or environment—it includes vulnerability records for a wide range of ecosystems such as Python (PyPI), JavaScript (npm), Go, Rust, Debian, Linux Kernel, and more.
This broad scope means that OSV can provide security insights across nearly all of the technologies commonly used in modern software development.
Adding to this versatility is the public API, which allows developers and security tools to query OSV in real time. The API can be used to fetch detailed vulnerability information programmatically, integrate alerts into custom monitoring solutions, or even automate nightly scans of software dependencies. This real-time access ensures that security insights are always current, which is vital in a landscape where new threats emerge daily.
Perhaps the most distinctive feature of OSV, though, is its developer-first approach. Unlike many traditional vulnerability databases, OSV is designed to make it easy for developers to understand exactly how a vulnerability impacts specific versions of a package. Instead of listing only a vague description or a CVE reference, OSV provides detailed metadata on affected versions, patched versions, and suggested actions.
This saves developers time and helps them respond faster and more effectively.
In short, the OSV database offers a combination of automation, interoperability, ecosystem coverage, and developer-friendly design that makes it a powerful asset for anyone concerned with the security of open source software.
What OSV is used for in practice
In practical terms, the OSV database is a highly effective tool for quickly identifying whether a project uses vulnerable dependencies.
This is especially important in modern development, where applications heavily rely on open source libraries and third-party modules.
Every time a developer installs a new package or updates an existing one—whether it’s from npm, PyPI, or Go Modules—there’s a risk of introducing a known vulnerability into the codebase.
Tracking this manually is not only time-consuming but often unfeasible in fast-paced environments. That’s where OSV steps in, automating the process and integrating it directly into your development workflow.
In a DevSecOps setting, where security is embedded into continuous integration and deployment (CI/CD), OSV enables teams to:
- Manually or automatically check if a specific version of a package is vulnerable.
- Automate dependency security checks during build and deployment stages.
- Receive real-time alerts and updates using the public OSV API, ensuring that your software stack is always up to date with the latest vulnerability data.
Practical example: manual check via API
Let’s say a developer is using the Python library flask and wants to check if version 2.0.1 is vulnerable.
OSV’s API allows for easy querying with a simple HTTP POST request:
curl -X POST https://api.osv.dev/v1/query \
-H "Content-Type: application/json" \
-d '{
"package": {
"name": "flask",
"ecosystem": "PyPI"
},
"version": "2.0.1"
}'If that version is linked to known vulnerabilities, the response will include:
- The OSV ID (e.g., PYSEC-2021-…)
- A detailed description of the vulnerability
- Affected versions
- Patched versions
- Links to relevant CVEs, advisories, or source commits
Automating vulnerability checks in CI/CD pipelines
In DevOps workflows, OSV can be integrated using tools like:
- osv-scanner: the official CLI tool for scanning project dependencies.
- Other scanners like Trivy, Snyk, or Dependency-Track, which often use OSV as a data source.
Here’s an example using osv-scanner with a Python project:
osv-scanner --lockfile=requirements.txtThis command scans the requirements.txt file and provides a report of any packages that contain known vulnerabilities, including information about safe versions to upgrade to.
Continuous monitoring and notifications
For mission-critical projects, teams can automate daily vulnerability checks by writing scripts that query the OSV API regularly and send alerts through email or Slack when new issues are discovered.
With its powerful API, multi-language support, and developer-first design, the OSV database is a cornerstone of secure software development.
In a world where open source is everywhere, proactively monitoring for vulnerabilities is no longer optional—it’s essential.
How the OSV database works
The inner workings of the OSV database are based on a combination of automated analysis and community-driven input, designed to ensure a constant, reliable, and up-to-date stream of information on vulnerabilities affecting open source packages.
At its core, OSV operates through two complementary mechanisms:
- Manual submissions by package maintainers
Open source maintainers can report vulnerabilities directly by submitting issues or pull requests to the OSV GitHub repository. This allows for detailed, context-aware vulnerability records with precise technical descriptions and direct references to the affected code. - Automated analysis of public repositories
OSV uses automated tools and pipelines to scan repositories for commits related to security fixes, references to CVEs, or advisory publications. These tools detect new vulnerabilities in real-time—even before an official CVE is published—by identifying patterns that indicate a security patch has been applied.
Anatomy of an OSV record
Every vulnerability detected or reported is stored in a standardized JSON object that follows the OSV schema, making the data both machine-readable and human-friendly.
Here’s a simplified example of a vulnerability record for the Python package flask:
{
"id": "PYSEC-2022-123",
"modified": "2022-11-03T00:00:00Z",
"published": "2022-10-31T00:00:00Z",
"package": {
"name": "flask",
"ecosystem": "PyPI"
},
"affected": [
{
"ranges": [
{
"type": "ECOSYSTEM",
"events": [
{ "introduced": "0" },
{ "fixed": "2.0.2" }
]
}
],
"versions": ["2.0.0", "2.0.1"]
}
],
"summary": "Improper input validation in Flask session handling",
"details": "Flask versions 2.0.0 and 2.0.1 are affected by a vulnerability in session cookie parsing that may allow session hijacking.",
"references": [
{ "type": "ADVISORY", "url": "https://example.com/security/flask-advisory" },
{ "type": "FIX", "url": "https://github.com/pallets/flask/commit/abc123" },
{ "type": "CVE", "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-0001" }
]
}Integration with tools and workflows
Because of its structured format, OSV data can be easily consumed by a wide range of tools used in modern software development, including:
- Vulnerability scanners such as osv-scanner, Trivy, and Grype
- CI/CD systems via API calls or integrated plugins
- Dependency managers that check for vulnerable libraries during build or deploy stages
Example
You can integrate OSV scanning into a GitHub Actions pipeline to automatically check for vulnerable dependencies with every commit:
jobs:
security-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run OSV Scanner
run: |
curl -L https://github.com/google/osv-scanner/releases/latest/download/osv-scanner-linux-amd64 -o osv-scanner
chmod +x osv-scanner
./osv-scanner --lockfile=requirements.txtThis setup ensures that any introduction of insecure dependencies will be immediately flagged—and optionally, the build can be blocked or marked as failed.
The OSV database effectively combines automated vulnerability detection with trusted community input to offer a comprehensive, real-time view of security issues across open source ecosystems.
Its standardized format, open API, and seamless integration with DevSecOps pipelines make it a powerful ally for developers, security teams, and organizations seeking to reduce risk and secure their software supply chain.
Examples of OSV usage
Using the OSV database in real-world development environments is a powerful way to proactively identify and mitigate vulnerabilities introduced by third-party dependencies.
With a public API, official CLI tools, and wide integration across modern development ecosystems, OSV can be used manually or fully automated within DevSecOps workflows.
Example 1: Scanning dependencies in a Node.js project
Imagine a development team building a web application in Node.js, using a package-lock.json file to manage dependencies.
The simplest way to integrate OSV into the process is by using the official CLI tool: osv-scanner.
Local scan using osv-scanner
- Quick installation:
curl -L https://github.com/google/osv-scanner/releases/latest/download/osv-scanner-linux-amd64 -o osv-scanner
chmod +x osv-scanner- Scan the project:
./osv-scanner --lockfile=package-lock.json- Expected output:
The tool will return a report indicating:
- The name of any vulnerable packages
- The version currently used
- The vulnerability IDs (e.g., GHSA-xxxx)
- Recommended safe versions
- Links to advisories and fixes
Developer action
If vulnerabilities are found, developers can:
- Run npm update or npm audit fix
- Review release notes or changelogs for compatibility
- Create a pull request to update the affected dependency
Example 2: Nightly automated checks using the OSV API
In larger organizations, it’s helpful to automate regular scans of dependencies. This can be done with a simple script that queries the OSV API and alerts the security team or posts to a Slack channel.
Python script example
import requests
import json
def check_vulnerability(package_name, ecosystem, version):
url = "https://api.osv.dev/v1/query"
data = {
"package": {
"name": package_name,
"ecosystem": ecosystem
},
"version": version
}
response = requests.post(url, headers={"Content-Type": "application/json"}, data=json.dumps(data))
if response.status_code == 200:
vulnerabilities = response.json().get("vulns", [])
if vulnerabilities:
print(f" {package_name}@{version} has {len(vulnerabilities)} vulnerabilities:")
for vuln in vulnerabilities:
print(f"- {vuln['id']}: {vuln.get('summary', 'No summary')}")
else:
print(f" {package_name}@{version} is safe.")
else:
print("API error:", response.status_code)
# Example: check Express.js
check_vulnerability("express", "npm", "4.17.1")This script could be extended to parse your package-lock.json or requirements.txt, and run as a nightly cron jobor GitHub Action.
Example 3: Blocking vulnerable builds in CI/CD pipelines
To enforce secure builds, OSV can be integrated into CI/CD pipelines. If any critical vulnerabilities are detected, the build can be blocked automatically.
GitHub Actions integration
jobs:
osv-scan:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Download osv-scanner
run: |
curl -L https://github.com/google/osv-scanner/releases/latest/download/osv-scanner-linux-amd64 -o osv-scanner
chmod +x osv-scanner
- name: Run OSV Scanner
run: ./osv-scanner --lockfile=package-lock.jsonYou can configure this job to fail the build if a vulnerability is detected, giving teams a chance to resolve issues before deployment.
These real-world examples show that the OSV database is far more than a passive archive—it’s an active tool designed to integrate seamlessly into the software development lifecycle.
Whether you’re an individual developer or part of a large enterprise security team, OSV helps detect, prioritize, and act on vulnerabilities in your dependencies—before they become exploitable. It’s a vital ally in building secure, automated, and resilient software systems.
Questions and answers
- What is the OSV database?
It’s an open source database of vulnerabilities in software packages. - Who created OSV?
The project was started by Google to support open source software security. - Which ecosystems are supported?
It covers Python, JavaScript, Go, Rust, Debian, Linux Kernel, and more. - How can I use OSV in my project?
You can integrate it via the public API or through CI/CD tools. - Is it free to use?
Yes, OSV is completely free and open source. - How is OSV different from CVE databases?
OSV is designed with developers in mind, using a structured and queryable format. - Where does the data come from?
From automated analysis, maintainer submissions, and sync with other sources. - Can I contribute to OSV?
Yes, anyone can submit or update entries via GitHub. - Can I use OSV offline?
You can download JSON data for offline use, though it won’t update in real time. - Is OSV reliable for production environments?
Absolutely. Many large companies use it to secure their systems.
