OSV and Open Source Vulnerability Databases: Using OSV, GHSA and Ecosystem Feeds Well

Dependency scanners are only as good as the vulnerability data behind them, and CVE records written for products rarely say precisely which package versions in npm, PyPI or Maven are affected. OSV (Open Source Vulnerability) addresses this with an OpenSSF schema that describes affected packages and version ranges in machine-readable form, and OSV.dev, a free aggregated database and API that collects advisories from GitHub, language ecosystems and Linux distributions. This guide explains what the OSV schema, OSV.dev, the GitHub Advisory Database (GHSA) and OSV-Scanner each do, how defenders use them, how to deploy them safely in pipelines, and when other sources fit better. It is for vulnerability management, AppSec and platform teams, and complements the broader Open Source Security Guide.

This is an independent guide from NHI Mgmt Group, based on OSV.dev's public documentation as of November 2026. It is not sponsored or reviewed by OSV.dev. Product features change, so confirm settings against OSV.dev's current documentation.

Key takeaways

• OSV is a format first. The OSV schema (version 1.9.2, dated 13 October 2026) gives each advisory precise affected package names, ecosystems and version ranges, which is what makes automated matching accurate.
• OSV.dev aggregates many sources. GHSA, Go, PyPI, RustSec, the OpenSSF Malicious Packages repository, Linux distributions and converted NVD CVEs are searchable through one API and bulk download.
• Aliases link the same flaw across IDs. A CVE, a GHSA and an ecosystem ID can describe one vulnerability; deduplicate on aliases or you will triage it three times.
• Malicious packages are a separate class. MAL records and GHSA malware advisories have no fixed version: the response is removal and credential rotation, not upgrade.
• Scanning leaks your dependency list unless you choose otherwise. Online queries send package names and versions to the API; OSV-Scanner's offline mode keeps them local.

What the tool does

"OSV" refers to three related things, and confusing them causes most design mistakes.

The schema fields that matter

• id, modified and schema_version: the only required fields. IDs use a database prefix such as GHSA, GO, PYSEC, RUSTSEC, MAL or CVE, and the schema recommends that new IDs be semantically neutral (no severity or package name in the ID).
• affected[].package: ecosystem and name, with an optional Package URL (purl), which is how scanners match exactly rather than guessing from product names.
• affected[].ranges: type SEMVER, ECOSYSTEM (ordering defined by the ecosystem) or GIT (commit hashes), with events introduced (where "0" means all earlier versions), fixed, last_affected and limit.
• aliases, upstream and related: aliases are the same vulnerability under another ID (symmetric and transitive); upstream points from a distribution advisory to the original flaw; related covers looser links.
• severity: typed scores, CVSS_V2, CVSS_V3, CVSS_V4 or Ubuntu priority, with an optional source of NVD, CNA or SELF.
• withdrawn: a timestamp marking an advisory that should no longer be used. Bulk exports include withdrawn records, so consumers must filter them.

Minor schema versions only add fields, so a client built for an older 1.x version can process newer records by ignoring unknown fields. For how OSV relates to CVE, CWE and CPE identifiers, see the CVE, CWE and CPE Guide.

Defender use cases

• Precise dependency matching: because ranges are expressed in the ecosystem's own versioning, matching a lockfile entry against OSV avoids the false positives common when product-level CPE data is applied to packages.
• Triage when the NVD lags: ecosystem databases often publish package-level ranges before or without NVD enrichment. See the CVE Programme and NVD Backlog Guide.
• SBOM enrichment: OSV-Scanner reads SPDX and CycloneDX inputs, and OSV.dev batch queries can enrich an SBOM inventory held in another platform. See the SBOM operations.
• Container image review: osv-scanner scan image (or --archive for an exported tar) inspects OS packages (APK, dpkg), Go and Rust binaries, Java jars, node_modules and Python wheels, and attributes findings to image layers, which separates base image debt from application debt.
• Malicious package detection: OSV.dev includes the OpenSSF Malicious Packages repository (MAL IDs), and GHSA carries malware advisories from the npm security team and that repository. When a malicious version is matched, remove it and rotate every secret it could reach. See the Malicious Package and Dependency Confusion Guide.
• Remediation planning: the experimental osv-scanner fix command proposes npm in-place or relock changes and Maven overrides to clear many findings with few steps. It is experimental and may change, so treat its output as a proposal for review.
• Publishing your own advisories: projects and vendors can export OSV records so downstream tooling consumes them without manual mapping. See the Open Source Project Maintainer Security Guide.

Deployment and safe use

1. Decide online or offline. Online scanning queries the OSV.dev API with package names and versions. For private or sensitive code, use --offline with a local database: OSV-Scanner then sends no project or dependency information anywhere. Note that offline mode also disables Maven transitive resolution through deps.dev; --offline-vulnerabilities keeps only the vulnerability lookup local.
2. Mirror the data deliberately. Bulk exports live at gs://osv-vulnerabilities/all.zip and per ecosystem at <ECOSYSTEM>/all.zip. For incremental sync, read modified_id.csv, which is sorted newest first, until you reach a timestamp you have already processed. Point OSV-Scanner at the mirror with OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY and refresh it at least daily, or offline scans silently go stale.
3. Check data licences before redistributing. Sources carry different licences: OSV.dev lists GHSA, PyPI and Go data as CC-BY 4.0, RustSec as CC0 1.0, OpenSSF Malicious Packages as Apache 2.0, Ubuntu as CC-BY-SA 4.0 and Chainguard/Wolfi as CC-BY-NC-ND 4.0. Internal use is usually simple; embedding data in a commercial product needs review.
4. Pilot in report-only mode. Run OSV-Scanner on a sample of repositories with --format sarif or json, compare results against your current scanner and resolve differences (often lockfile coverage or alias duplicates) before gating builds.
5. Govern exceptions in configuration. Use osv-scanner.toml with [[IgnoredVulns]] entries that carry a reason and an effectiveUntil expiry. The file applies only to its own directory, ignoring an ID also ignores its aliases, and a --config flag overrides every directory file, so review config changes in pull requests. Avoid broad [[PackageOverrides]] with ignore = true.
6. Gate, then widen. Fail builds on new critical findings and on any MAL match first, then extend to high severity. Keep a documented rollback (switch the gate back to report-only) for data incidents such as a bad bulk import.
7. Protect the pipeline identities. The scanner job needs read access to code and, if it uploads SARIF, a findings write token. Scope both to the job. Mirror refresh jobs that hold cloud storage credentials are non-human identities too: inventory and rotate them. See the CI/CD Pipeline Identity Security Guide.

Detection and hardening value

OSV data is a detection source for supply chain risk (MITRE ATT&CK T1195.001 Compromise Software Dependencies and Development Tools) and a control input for vulnerability management.

What to monitor: scan coverage per repository and image, mirror freshness (time since last modified_id.csv sync), new MAL matches, ignore entries past expiry and findings with no fixed version.

Metrics:

• Share of production repositories and images scanned on every default-branch build.
• Mean time from OSV published or modified timestamp to a ticket in your tracker.
• Median age of open critical and high dependency findings, after alias deduplication.
• Time from a MAL match to package removal and credential rotation.
• Number of active ignore entries without a reason or expiry (target: zero).

Common failure patterns

• Counting aliases as separate findings: a CVE, a GHSA and a PYSEC ID for one flaw inflate backlogs and confuse SLAs.
• Treating malware like a vulnerability: waiting for a "fixed" version that will never exist, instead of removing the package and rotating credentials it could reach.
• Stale offline databases: air-gapped scanners that pass every build because the mirror stopped updating months ago.
• Ignoring withdrawn records incorrectly: raising alerts on withdrawn advisories from bulk data, or the opposite, losing track of a withdrawal that cleared a finding.
• Lockfile blind spots: manifests without lockfiles, vendored C/C++ code and unsupported package managers produce no results, which reads as "clean".

Alternatives

Small teams usually get most value from GHSA-backed alerts plus OSV-Scanner in CI. Larger organisations often mirror OSV data into a central platform so findings from SCA, SBOM tools and container scanners share one alias-aware key, and pair it with exploitation signals such as the EPSS Guide describes.

Practitioner checklist

• Decide per repository class whether online API queries are acceptable or offline mode is required.
• Mirror OSV bulk data with incremental modified_id.csv sync and alert on stale mirrors.
• Deduplicate findings on OSV aliases before measuring SLAs.
• Filter withdrawn records and track withdrawals that close findings.
• Treat every MAL or malware advisory match as an incident: remove, investigate, rotate credentials.
• Require reason and effectiveUntil on every ignore entry and review config changes.
• Confirm lockfile and image coverage, and flag repositories that produce no scan output.
• Review data licences before redistributing OSV-sourced data outside the organisation.
• Scope scanner, upload and mirror credentials to their jobs and rotate them.

Standards and references

• OpenSSF: Open Source Vulnerability format (OSV schema)
• OSV.dev: API documentation
• OSV.dev: Data sources and data dumps
• OSV-Scanner: Documentation
• GitHub Docs: About the GitHub Advisory Database
• OpenSSF: Malicious Packages repository
• NIST: SP 800-53 Rev. 5
• MITRE ATT&CK: Compromise Software Dependencies and Development Tools

Related NHI Mgmt Group resources: Open Source Security Guide · OWASP Dependency-Track Guide · VEX Guide · SARIF · Vulnerability Prioritisation Guide