OSV (Open Source Vulnerabilities)

OSV (Open Source Vulnerabilities) is a service that enables developers to identify known third-party open source dependency vulnerabilities. It acts as an aggregator of vulnerability databases that use the OpenSSF Vulnerability format.

Key features include:

• Vulnerability Aggregation: Collects data from multiple sources using a standardized schema.
• Version Analysis: Uses bisection and version analysis to ensure affected versions are accurately represented in vulnerability entries.
• Querying: Users can query for known vulnerabilities using version numbers or commit hashes.
• OSV-Scanner: A first-party tool that leverages the OSV.dev API to scan dependencies.

The OSV API supports five primary types of requests:

1. Query vulnerabilities: Check for vulnerabilities in a specific project using a commit hash or version.
2. Batched query vulnerabilities: Perform batch queries for multiple package versions and commit hashes.
3. Get vulnerability by ID: Retrieve a specific Vulnerability object using its OSV ID.
4. Determine probable versions (Experimental): Returns a list of probable versions for a specified C/C++ project.
5. Retrieve import findings (Experimental): Retrieve records that failed import-time quality checks, filtered by record source.

Several community-built tools integrate with OSV to provide vulnerability scanning and dependency analysis. Note that these tools are not officially supported or endorsed by the core OSV maintainers. Popular integrations include:

• Cortex XSOAR
• dep-scan
• Dependency-Track
• GUAC
• OSS Review Toolkit (ORT)
• pip-audit
• Renovate
• Trivy

OSV.dev does not mirror all CVE records. The ingestion pipeline specifically targets vulnerabilities where the following two criteria can be deterministically identified:

1. An open-source code repository (e.g., GitHub, GitLab, Bitbucket).
2. Resolvable version tags or Git commit hashes.

If a CVE relates to closed-source software or lacks identifiable repository data (such as repository links and fix details), it will not be included in OSV's automated CVE ingestion. For ecosystem-specific mappings (like PyPI, npm, or Cargo), OSV relies on dedicated advisory databases like GHSA, PyPA, and RustSec.

The determineversion API is an experimental OSV endpoint designed to help C/C++ developers identify the likely version of vendored or submoduled dependencies. Because C/C++ lacks a centralized package manager, this API helps bridge the gap between source code (often identified by git hashes) and known vulnerabilities (often associated with specific versions).

Supported Projects: Currently, the API supports C/C++ repositories that are being fuzzed by OSS-Fuzz. This is because OSV's C/C++ vulnerability data is primarily derived from OSS-Fuzz commit-level information. Coverage is expected to expand to include commit-level details from the National Vulnerability Database (NVD).

OSV.dev supports 30 ecosystems. Recent additions include several Linux distributions that adopt the OSV Schema:

• Ubuntu
• Chainguard
• Red Hat
• SUSE/openSUSE

Additionally, OSV includes CVE data from the Debian Security Tracker and vulnerability records from the curl project.

The tools/datafix directory contains several Python utility scripts for data maintenance and correction. The available tools are:

• delete_bugs_with_source.py: Deletes bugs associated with specific sources.
• delete_invalid.py: Deletes invalid records.
• reimport_gcs_record.py: Reimports records from Google Cloud Storage.
• reput_bugs.py: Reputs bugs.
• withdraw_invalid.py: Withdraws invalid records.

Refer to the individual script files for specific use cases and execution instructions.

You can extract per-year conversion metrics (percentage of successful conversions vs. in-scope CVEs) by querying Cloud Logging.

Prerequisites: Requires the following IAM roles:

• roles/logging-viewer (Logs Viewer)
• roles/serviceusage.serviceUsageConsumer (Service Usage Consumer)

Usage: Run the following command to parse logs from the oss-vdb project and calculate the success rate per year:

$ gcloud --project oss-vdb logging read --freshness=12h --format=json 'logName="projects/oss-vdb/logs/nvd-cve-osv" "Metrics:"' | jq -r '. | map(.textPayload | gsub("[\\n]"; "")) | .[]' | awk '{ 
  match($1, /nvdcve-2\.0-(....)\.json/, year); 
  match($5, /CVEsForKnownRepos:([0-9]+)/, cves_in_scope); 
  match($6, /OSVRecordsGenerated:([0-9]+)/, osvs); 
  print year[1], 100*osvs[1]/cves_in_scope[1] 
}' | tail -n $[$(date +%Y) - 2016 + 1]

OSV-Scanner v2.0.0-beta1 introduces layer-aware container scanning for Debian, Ubuntu, and Alpine images. It provides analysis on layers where packages were introduced, layer history/commands, base image identification, and the OS/Distro running in the container. Supported language artifacts include Go, Java, Node, and Python.

osv-scanner scan image <image-name>:<tag>

The Debian Converter is a tool designed to convert Debian Security Tracker information into the OSV format. It automates the process of downloading Debian Security Tracker data and Distro Info, mapping release names to version numbers, loading existing CVEs, and generating OSV vulnerabilities. The results can be written to the local filesystem or uploaded directly to a Google Cloud Storage (GCS) bucket.

go run main.go [flags]

To extract all valid versions for PyPI packages, you can run a BigQuery query against the public PyPI dataset using a SQL file (e.g., pypi_versions.sql).

A continuously updated version of these versions is also available at: https://storage.googleapis.com/pypa-advisory-db/triage/pypi_versions.json

bq query --max_rows=10000000 --format=json --nouse_legacy_sql < pypi_versions.sql > pypi_versions.json