To check one package version, query an advisory database with three facts: the ecosystem, the package name and the exact version. OSV.dev, an aggregator of vulnerability databases, answers this through its query endpoint, which returns the advisories whose affected ranges include that version. An empty result means nothing matched at that moment.
Definitions
Ecosystem. The package registry family, such as PyPI, npm or RubyGems. Names are case sensitive in the OSV API.
Advisory record. An OSV entry with an identifier, summary, references and affected ranges.
Package URL. A standard identifier that can carry the ecosystem, name and version in one string.
What OSV.dev is
OSV.dev aggregates vulnerability databases that use the OpenSSF vulnerability format. It also checks that affected versions are recorded accurately, using bisection and version analysis. Its API includes a query endpoint, a batch query endpoint and a lookup by identifier.
The query request
The query endpoint accepts a package and a version. You may give the name with the ecosystem, or a package URL. You must not put the version in both places. The API returns a list of advisory records, and a page token if results are paginated.
curl -s -X POST https://api.osv.dev/v1/query -d '{"package": {"name": "jinja2", "ecosystem": "PyPI"}, "version": "3.1.4"}'
curl -s -X POST https://api.osv.dev/v1/query -d '{"package": {"purl": "pkg:pypi/jinja2@3.1.4"}}'
Ways to check, compared
| Method | Best for | Limit |
|---|---|---|
| Advisory API query | One package, scripts | You supply name and version |
| Scanner on a lockfile | Whole project | Needs a lockfile |
| Registry audit command | Day to day | Tied to one ecosystem |
| Reading advisories by hand | Understanding impact | Slow, easy to miss one |
Steps
- Confirm the exact resolved version from your lockfile, not the range in your manifest.
- Run the query with the right ecosystem name and case.
- Read each returned record for affected ranges, fixed version and any mitigations.
- Check aliases, since one flaw can appear under several identifiers.
- If results are empty, note the date. New advisories can change the answer tomorrow.
Common mistakes
- Using a version range instead of an exact version.
- Getting the ecosystem name case wrong, which returns nothing.
- Treating an empty answer as a permanent all clear.
Try it yourself
Click through it at your own pace, or open it full screen.
Open a finding and compare its affected range with the version in use.
Quick check
Does the query work for commit hashes?
Yes. The API accepts a commit hash in place of a version, and you then omit the version field.
Is an empty result proof the version is safe?
No. It means no advisory matched at that time. Re-check on a schedule.
Safeguard checks dependency versions against advisory data and flags newly published matches through continuous monitoring. Try a free scan.
Sources
Last reviewed: 19 October 2026.
