OSV.dev is an open-source vulnerability database that standardizes and distributes vulnerability data for open source packages using a precise, version-aware schema. It serves developers, security teams, and DevOps engineers who need accurate, machine-readable vulnerability information to automate remediation and reduce false positives. Unlike generic CVE databases, OSV maps vulnerabilities directly to package versions or commit hashes, enabling exact impact analysis.
Built on Google Cloud Platform with Python and Go services, OSV.dev aggregates data from GitHub Security Advisories, PyPA, RustSec, NVD, and 30+ ecosystems. It provides a REST API, a Go-based scanner, and integrations with tools like Trivy, Dependency-Track, and Renovate. The system is deployed via Terraform and Cloud Build, with workers handling bisection, impact analysis, and data ingestion from upstream sources.
What You Get
- OSV Schema - A human- and machine-readable JSON format that maps vulnerabilities to exact package versions or commit hashes, enabling precise impact analysis across ecosystems like PyPI, npm, and Go.
- OSV API - A RESTful API that allows querying vulnerabilities by commit hash or package version (e.g., curl -d ’{“commit”: “hash”}’ https://api.osv.dev/v1/query).
- osv-scanner - A Go-based CLI tool that scans SBOMs (SPDX, CycloneDX), lockfiles (package-lock.json, Pipfile, go.mod), and git repositories to identify vulnerable dependencies using the OSV database.
- Data Dumps - Public GCS buckets (gs://osv-vulnerabilities) offering full database exports in JSON format for offline analysis and integration into air-gapped environments.
- Ecosystem Coverage - Support for 30+ package ecosystems including PyPI, npm, Maven, RubyGems, Debian, Ubuntu, Alpine, Go, and GitHub Actions with version-specific vulnerability mapping.
- GitHub Actions Integration - Pre-built workflows to automatically scan dependencies and fail builds on critical vulnerabilities, directly consuming the OSV API.
Common Use Cases
- Automating dependency scanning in CI/CD - A DevOps engineer uses osv-scanner in GitHub Actions to block builds when vulnerable versions of npm or PyPI packages are detected, using exact version matching to avoid false positives.
- Integrating vulnerability data into SBOM tools - A security team uses OSV data in Dependency-Track or GUAC to enrich their software bills of materials with precise version-based vulnerability alerts.
- Running a vulnerability database for a Linux distro - Alpine or Debian maintainers publish advisories in OSV format to ensure their package versions are accurately tracked across third-party scanners and enterprise tools.
- Building a custom vulnerability scanner - A security startup uses the OSV schema and API to build a proprietary scanner that supports niche ecosystems like Chainguard or Wolfi, leveraging OSV’s standardized format.
Under The Hood
Architecture
- Modular monorepo structure with distinct services (API, workers, website, vulnfeeds) enabling independent deployment and testing
- Service-oriented design using gRPC with protobuf-defined interfaces for clean, type-safe communication between Python and Go components
- Decoupled data ingestion pipeline driven by configurable source definitions, allowing dynamic handling of diverse vulnerability sources through consistent Importer interfaces
- Flask-based REST layer abstracts gRPC backend, preserving separation between HTTP transport and core business logic
- Configuration-driven workflows via YAML files enable scalable integration of new ecosystems without code modifications
Tech Stack
- Python 3.13+ backend leveraging Flask, Google Cloud libraries (ndb, pubsub, storage), and grpcio for service orchestration
- Go-based workers and bindings utilizing gRPC for high-performance processing and cross-language API exposure
- Protocol Buffers as the central contract language, with auto-generated bindings and type safety enforced via mypy-protobuf
- Cloud Build and Makefile-driven CI/CD pipelines with Dockerized ESPv2 proxies and GCP function deployments
- Hugo-powered static website with pnpm/Webpack for modern frontend asset compilation
- Renovate and Poetry for automated, fine-grained dependency management across Python, Go, and Docker components
Code Quality
- Extensive test coverage across languages with unit, integration, and edge-case tests including mock servers and protobuf validation
- Clear separation of concerns with modular importers, version parsers, and storage handlers, each with dedicated test suites
- Robust error handling through structured logging, custom error types, and context-aware failure paths
- Consistent naming and strong typing enforced via Python type hints and Go protobuf schemas
- Comprehensive linting, schema validation for JSON advisories, and automated sitemap generation with XML compliance
- Innovative version normalization logic that handles semver pre-releases and platform-specific formats across multiple ecosystems
What Makes It Unique
- Semantic versioning and PURL-based dependency mapping enable precise vulnerability resolution across diverse package managers
- Experimental DetermineVersion API infers vulnerable versions in C/C++ binaries via hash bucketing and symbol analysis—a novel approach for languages lacking version metadata
- Granular import failure classifications surface data quality issues at ingestion, improving downstream reliability
- Protocol Buffers-first API design with auto-generated bindings enables high-performance, language-agnostic queries at scale
- Unified vulnerability database normalizing data from 50+ sources into a single schema, reducing ecosystem fragmentation
- Built-in HTTP/2 optimizations and response throttling specifically tuned for large-scale security data queries