OSV npm Vulnerabilities: Database, API, and Limits

Short answer: OSV npm vulnerabilities are machine-readable advisory records that map known security issues and malicious-package reports to exact npm package versions. OSV.dev can help you query one version, scan a lockfile, or automate a CI check, but it cannot prove that an unflagged package is safe or detect a threat before an advisory exists.

Use OSV as a current source of known-vulnerability intelligence, not as a complete trust score. The strongest npm workflow combines resolved dependency data, OSV queries, lockfile review, install-script controls, registry policy, and behavioral analysis where the risk justifies it.

What are OSV npm vulnerabilities?

OSV stands for Open Source Vulnerabilities. It is both a vulnerability data format and an open service that aggregates advisory databases using that format. The official OSV documentation explains that records can identify affected open-source versions using the naming and version schemes of each package ecosystem.

For npm, an OSV record can include the package name, affected and fixed version ranges, identifiers such as a GHSA or CVE, severity information, references, publication dates, and aliases that connect equivalent records. You can browse the npm ecosystem on OSV.dev or query the API with a package name and version.

This ecosystem-aware structure matters. A generic vulnerability description might say that versions “before 3.2.1” are affected, but software needs a precise answer about the package name, version ordering, and exceptions. OSV records are designed to express those ranges in a form tools can match against real dependency versions.

How does the OSV database work for npm?

OSV.dev indexes records from open, authoritative vulnerability sources that use the OSV schema. The service normalizes identifiers and affected-version information so consumers can search across sources without inventing a separate parser for every advisory database.

A typical npm lookup follows four steps:

1. Identify the exact dependency. Use the canonical npm package name, including its scope when applicable.
2. Resolve the installed version. Prefer the exact version from package-lock.json, npm-shrinkwrap.json, or the installed dependency tree over a broad range from package.json.
3. Query the npm ecosystem. Send the name, version, and ecosystem value npm to OSV.dev.
4. Evaluate each matching record. Review affected ranges, fixes, aliases, references, publication timing, and whether the dependency is reachable or exposed in your application.

The result answers a narrow question: “Does current OSV data contain an advisory that matches this package version?” It does not answer whether the package is well maintained, whether its install script is suspicious, or whether an attacker has compromised a release that has not yet been reported.

How do you query the OSV API for an npm package?

The official OSV API supports a single package-version query and a batched query for many dependencies. A minimal request to the single-query endpoint looks like this:

curl -s https://api.osv.dev/v1/query \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "4.17.20",
    "package": {
      "name": "lodash",
      "ecosystem": "npm"
    }
  }'

The response contains a vulns array when OSV finds matching records. Each record may include several identifiers for the same underlying issue, so do not count aliases as independent vulnerabilities. Read the version events and references before choosing a fix.

For a CI service, prefer the batch endpoint instead of making one request for every package. Keep the package name, resolved version, and ecosystem together, cache responsibly, and preserve the OSV IDs in build output so developers can trace the finding back to its source.

How do you scan package-lock.json with OSV-Scanner?

OSV-Scanner is the first-party command-line frontend for OSV.dev. Its current documentation lists package-lock.json, pnpm-lock.yaml, yarn.lock, and bun.lock among the supported JavaScript lockfiles. The supported artifacts guide recommends a resolved lockfile because a manifest range may not identify the version actually installed.

After installing the scanner through an official method, a source scan can be run from the repository root:

osv-scanner scan source -r .

To target one npm lockfile and save machine-readable output, use:

osv-scanner scan -L package-lock.json \
  --format json \
  --output-file osv-results.json

In CI, pin the scanner version, keep the lockfile committed, and decide what should fail a build. A blanket “fail on any finding” rule often becomes noisy in a mature project. A practical policy may distinguish newly introduced findings, exploitable production dependencies, accepted risks with expiry dates, and fixes that would require a breaking upgrade.

What is the difference between OSV, OSV-Scanner, and npm audit?

These are overlapping tools, not interchangeable guarantees. OSV provides an open, multi-ecosystem data layer and scanner. npm audit is built into npm and fits naturally into npm projects. Teams may run both, but they should deduplicate equivalent identifiers and avoid treating a larger raw finding count as better detection.

For a broader view of tool categories, see the npm vulnerability scanner comparison. The right tool depends on whether you need inventory, remediation, behavior signals, license analysis, or enforcement before a package reaches the installer.

Can OSV detect malicious npm packages?

Yes, when a malicious-package record has been published into a source available through OSV. OpenSSF describes how its Malicious Packages project and the OSV API can expose known malicious npm and PyPI versions. That makes the same package-version query useful for some malware reports as well as conventional vulnerabilities.

The timing limitation is fundamental. A newly compromised npm version can be downloaded before researchers identify it, verify the report, and publish an advisory. An empty OSV response means “no matching record was returned from current data,” not “this package is safe.”

Behavioral-analysis tools have an advantage when they inspect code, install scripts, network indicators, permissions, or suspicious release changes before an authoritative advisory exists. Advisory-driven checks have a different advantage: the decision is reproducible, explainable, and easy to enforce consistently. Mature programs combine both signals where possible.

What are the limits of OSV npm vulnerability data?

• Advisory lag: OSV cannot return a record that has not been created or imported yet.
• Source coverage: private reports, undisclosed incidents, and databases outside the aggregation path may be absent.
• Dependency accuracy: a manifest range may not match the version actually installed; use a lockfile or inventory.
• Reachability: a version match does not prove that the vulnerable code path is used or externally reachable.
• Severity context: a score does not know your deployment, privileges, exposed data, or compensating controls.
• Malware behavior: known-version matching does not inspect a package for novel malicious behavior.
• Runtime drift: production containers and hosts can differ from the repository that was scanned.

Do not hide these limits behind a single green check. Record what was scanned, when the data was queried, which dependency source was used, and which risks were explicitly outside the check.

How should teams use OSV in an npm security workflow?

1. Commit and review the lockfile. Make dependency changes visible and keep exact versions available to scanners.
2. Scan pull requests. Highlight newly introduced advisory matches before merge, with links to the underlying records.
3. Scan on a schedule. Existing dependencies can receive new advisories without any repository change.
4. Scan build artifacts. Confirm that containers and deployed inventories match what the source scan expected.
5. Prioritize with context. Consider exposure, reachability, exploit maturity, privileges, and fix availability.
6. Control installation. Use an approved registry path, restrict lifecycle scripts, and isolate untrusted build steps.
7. Prepare for misses. Monitor runtime behavior and keep credentials, caches, and CI runners contained.

The malicious npm package response guide covers what to do when a dependency is confirmed as hostile. For prevention, an npm registry firewall can turn advisory data and package policy into an allow-or-deny decision before a tarball reaches developer machines, CI, or coding agents.

How does InstallSafe use OSV.dev?

InstallSafe uses OSV.dev advisory data and blocks package versions that are flagged in that data at the registry boundary. It can enforce the same decision for local npm clients, CI runners, containers, and AI coding agents while serving byte-for-byte npm tarballs for allowed versions.

That is not zero-hour behavioral detection. If a malicious release has no applicable advisory yet, an OSV-backed decision may allow it. InstallSafe is best used as a deterministic install-boundary control alongside lockfiles, script restrictions, least privilege, and behavioral analysis. To check a package against current advisory data without changing your registry, use the free npm package scan.

Frequently asked questions

Is OSV.dev free to use?

OSV.dev provides an open website, API, data, and scanner. Check the current official documentation before designing a high-volume integration, and use batch queries rather than unnecessary one-package requests.

Does OSV support scoped npm packages?

Yes. Query the canonical full package name, including the scope, with ecosystem npm and an exact resolved version.

Should I scan package.json or package-lock.json?

Prefer package-lock.json when it is available because it records resolved versions, including transitive dependencies. A manifest may contain ranges that do not identify what is installed.

Does no OSV result mean an npm package is safe?

No. It only means the query returned no matching known advisory in current OSV data. Review package identity, provenance, scripts, maintainership, behavior, and release age too.

Can OSV replace behavioral malware analysis?

No. OSV matches known records to package versions. Behavioral analysis can inspect suspicious code or release behavior before a public advisory exists; the two controls are complementary.

How often should npm dependencies be scanned?

Scan on dependency-changing pull requests, in CI, and on a schedule. Scheduled rescans matter because a dependency can be flagged after it was first accepted.