# OSV Package Vulnerability Audit: npm, PyPI, Go, Maven (`atesen-software/osv-package-vulnerability-audit`) Actor

Check exact package versions against the OSV vulnerability database. Get every matching advisory with severity data and upstream license notices, or a clear no-match result. npm, PyPI, Go, Maven, RubyGems, crates.io, NuGet.

- **URL**: https://apify.com/atesen-software/osv-package-vulnerability-audit.md
- **Developed by:** [Atesen Software](https://apify.com/atesen-software) (community)
- **Categories:** Developer tools, Open source
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00 / 1,000 package assessments

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## OSV Package Vulnerability Audit: npm, PyPI, Go, Maven

Is the exact version of lodash, requests or log4j you ship affected by a known vulnerability? Paste up to 20 package versions and get one row per package with every matching OSV advisory (GitHub, PyPA, Go and RustSec sources), its severity data and the license notice to keep with it.

### OSV Package Vulnerability Audit

Check 1–20 exact package versions against the public OSV vulnerability API. Export a complete assessment when all advisory sources can be verified, or a zero-match assessment when OSV returns no advisories. A package with an unverified advisory source produces a free `license_unverified` status without advisory data. No package installation, code execution, repository downloads, lockfile upload, login or active website scanning.

### Why use this Actor

- **Before you pin a dependency**: check whether the exact version you are about to pin has advisories recorded in OSV's aggregated sources (GitHub Security Advisories, PyPA, the Go vulnerability database and others) before it goes into your builds.
- **Version triage**: submit 1–20 exact installed versions from your inventory to OSV. The Actor does not resolve dependencies.
- **Polyglot checks**: one ecosystem-consistent query format across npm, PyPI, Go, Maven, RubyGems, crates.io and NuGet, including Maven `groupId:artifactId` names.
- **Upgrade decisions with evidence**: each assessment keeps the full OSV advisory records, so you can read severity vectors and affected ranges from the source data instead of a summarized risk score.

### Input

```json
{"packages":[{"ecosystem":"npm","name":"lodash","version":"4.17.20"}],"maxRequests":10,"maxPagesPerPackage":5}
```

| Field | Default | Behavior |
| --- | --- | --- |
| `packages` | required | 1–20 objects with `ecosystem`, `name`, `version`. Duplicate name/version/ecosystem triples are checked once |
| `maxRequests` | `50` | Serial request limit (1–50) including retries and pagination; incomplete assessments are never billed |
| `maxPagesPerPackage` | `5` | Page ceiling per package (1–10); stops with a free `page_limit` status when OSV still has another page |

Use a version copied from the installed package. The supported version formats are:

| Ecosystem | Version format | Example |
| --- | --- | --- |
| npm, crates.io | Three-part SemVer with optional prerelease and build metadata | `1.2.3-rc.1+build` |
| Go | Three-part SemVer with optional `v` prefix, prerelease or pseudo-version, and `+incompatible` when applicable | `v1.2.3-0.20240102030405-abcdef123456` |
| PyPI | PEP 440 version, including epochs, prereleases, post releases, dev releases and local versions | `1!2.0rc1.post2.dev3+vendor.5` |
| Maven | Numeric-leading version with alphanumeric qualifiers separated by dots, underscores or hyphens. Use a fixed timestamped version for snapshots | `5.0.0.Final` |
| RubyGems | Numeric-leading gem version with optional alphanumeric suffix | `7.0.0.pre.1` |
| NuGet | One to four numeric components with optional SemVer prerelease and build metadata | `1.2.3.4` |

If any entry is invalid, the run checks nothing and charges nothing; the status message names the entry. Ecosystem names are case sensitive. Maven package names use `groupId:artifactId`. Tags such as `latest`, version ranges, wildcard segments and Maven `-SNAPSHOT` aliases are rejected. Format validation does not verify that a package version exists in its registry. OSV applies its own version-matching rules. The Actor sends package names and versions to OSV, so only provide identifiers you are allowed to share.

### Output

Excerpt from a completed Apify run on 10 November 2026. The run found four advisories for `lodash@4.17.20`. The example shows the first advisory ID and its attribution. The dataset contains all four full advisory records and their notices.

```json
{
  "recordType": "assessment",
  "status": "completed",
  "package": "lodash",
  "ecosystem": "npm",
  "version": "4.17.20",
  "vulnerabilityCount": 4,
  "vulnerabilities": [
    {
      "id": "GHSA-29mw-wpgm-hmr9",
      "modified": "2025-09-29T21:12:31.102523Z"
    }
  ],
  "attributions": [
    {
      "advisoryId": "GHSA-29mw-wpgm-hmr9",
      "source": "GitHub Advisory Database",
      "sourceUrl": "https://github.com/github/advisory-database/blob/main/advisories/github-reviewed/2022/01/GHSA-29mw-wpgm-hmr9/GHSA-29mw-wpgm-hmr9.json",
      "attributionUrl": "https://github.com/advisories/GHSA-29mw-wpgm-hmr9",
      "license": "CC-BY-4.0",
      "licenseUrl": "https://creativecommons.org/licenses/by/4.0/",
      "processing": "Enriched by OSV.dev; returned unchanged by this Actor."
    }
  ],
  "sourceUrl": "https://api.osv.dev/v1/query",
  "queriedAt": "2026-11-10T16:05:30.98Z"
}
```

Each `assessment` row contains `status: completed`, package, ecosystem, version, `vulnerabilityCount`, full OSV `vulnerabilities`, official `sourceUrl` and UTC `queriedAt`. Advisory IDs are deduplicated across pages. Different advisory IDs can reference the same underlying issue through aliases; the count is an advisory count, not a count of distinct exploitable flaws. A completed zero-match assessment means OSV returned no matching records at query time; it is not a guarantee that a package is secure or an endorsement of that version.

`attributions` carries the upstream source, record link, and license for every copied advisory. Keep these notices with exported advisory data. Verified paths cover the [GitHub Advisory Database](https://github.com/github/advisory-database), the [Python Packaging Advisory Database](https://github.com/pypa/advisory-database), the [Go Vulnerability Database](https://pkg.go.dev/golang.org/x/vulndb), and explicitly CC0-marked records from the [RustSec Advisory Database](https://github.com/rustsec/advisory-db). A RustSec CC BY record requires one verified, reciprocal GitHub advisory in the same assessment. Its `sourceUrl` identifies the RustSec import and `attributionUrl` credits the original GitHub advisory. A CVE alias is a reference. A separate CVE record or other unverified record returns a free `license_unverified` status for the package, with no advisory payload or result charge. A valid zero-match response has empty `vulnerabilities` and `attributions` arrays. [OSV data sources](https://google.github.io/osv.dev/data/)

### How much does OSV Package Vulnerability Audit cost?

Pay per event: **$0.005 per checked package** ($5 per 1,000 completed package assessments) using the `result` event. No start fee. A fully checked package with zero advisory matches is also one billable assessment. `STATUS_RECORDS` in the default key-value store holds input errors, upstream failures, rate limits, request ceilings and incomplete pagination. Writing these diagnostics does not generate result or dataset-item events. Set a maximum cost per run and the Actor stops before a package it can no longer pay for, so you are never charged for a half-checked package. Platform usage is included in the price.

### Limits, retries and error handling

Requests are serial, with a hard ceiling of 50 including retries and a configurable 1–10 page ceiling per package. OSV may paginate even a response containing no advisories. All pages must complete before an assessment is saved. Each response is capped at 8 MiB. A complete assessment is capped at 5,000 unique advisory records and 8 MiB of serialized UTF-8 JSON across all pages. If either assessment limit is exceeded, the Actor writes a free `result_limit` diagnostic to `STATUS_RECORDS` and does not save or charge that assessment. HTTP 429 and HTTP 503 with Retry-After allow at most one retry after waiting at most 5 seconds. Longer waits produce `rate_limited` with `retryAt`. Unavailable data never indicates safety. Upstream and parser errors do not fail the run: already completed assessments stay in the dataset, the problem is written as a free diagnostic, and the run status message names it.

`OUTPUT` contains status, completed assessment count, status-row count, partial flag and actual OSV request count. Read `STATUS_RECORDS` alongside `OUTPUT` when automating. The run status message also names the first problem, for example which package had an invalid version.

If you stop a run, packages already checked stay in the dataset.

Only unexpected SDK or storage errors fail the run; they log a redacted error name, message and stack. The `errorSummary` record keeps those details.

### Run locally

Requires Node.js 22 or newer. No credentials needed.

```powershell
npm ci --ignore-scripts
npm test
$env:LOCAL_MODE='1'
$env:INPUT_PATH='input.example.json'
npm start
```

Local output goes to `data/dataset.json`, `data/STATUS_RECORDS.json` and `data/OUTPUT.json`. Set `OUTPUT_DIR` to choose a different directory. Local mode does not bill or enforce a monetary cap. In Apify cloud, the SDK adapter applies real event and dataset costs.

### Sources and limitations

- [Official OSV query API and pagination](https://google.github.io/osv.dev/post-v1-query/)
- [Official OSV schema and ecosystem names](https://ossf.github.io/osv-schema/#affectedpackage-field)
- [OSV data sources and coverage](https://google.github.io/osv.dev/data/)

Use the returned advisory records and their source references to assess applicability and remediation. This Actor preserves source severity vectors and affected ranges; it does not invent CVSS scores or automatically install an upgrade.

### Use via API

One request runs the Actor, waits for it and returns the dataset items as JSON. Send your token in the `Authorization` header, not in the URL:

```bash
curl -X POST "https://api.apify.com/v2/acts/atesen-software~osv-package-vulnerability-audit/run-sync-get-dataset-items?timeout=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"packages":[{"ecosystem":"npm","name":"lodash","version":"4.17.20"}]}'
```

The synchronous endpoint waits up to 300 seconds. For longer jobs start a run with `POST https://api.apify.com/v2/acts/atesen-software~osv-package-vulnerability-audit/runs` and read the dataset when it finishes.

**JavaScript** (`npm install apify-client`):

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('atesen-software/osv-package-vulnerability-audit').call({ packages: [{ecosystem: "npm", name: "lodash", version: "4.17.20"}] });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Use with AI agents (MCP)

Claude Desktop, Cursor, VS Code and other MCP clients can call this Actor as a tool through the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). Load only this Actor with:

```text
https://mcp.apify.com?tools=atesen-software/osv-package-vulnerability-audit
```

Client config (sign in with Apify OAuth when the browser opens, or add an `Authorization: Bearer <APIFY_TOKEN>` header instead):

```json
{
  "mcpServers": {
    "apify": { "url": "https://mcp.apify.com?tools=atesen-software/osv-package-vulnerability-audit" }
  }
}
```

Then ask in plain words, for example: "Does lodash 4.17.20 on npm have known vulnerabilities, and which version fixes them?" The agent fills the same input fields you see on the Input tab, and runs are billed to your Apify account at the prices on the Pricing tab.

### FAQ

**How many packages can one run audit?**
Between 1 and 20 named package version triples per run, within a serial limit of 50 OSV requests including retries and pagination. For a bigger inventory, split versions across several runs.

**Does it scan my whole dependency tree?**
No, deliberately. You provide explicit package names and versions — no lockfile upload, no dependency resolution and no transitive traversal. Enumerate your versions with your package manager, then batch-check them here.

**A package reports zero vulnerabilities. Is it safe?**
Not guaranteed. A zero-match assessment means only that OSV returned no matching advisory records at query time. New advisories can appear at any time, and OSV's version-matching rules decide what matches. Schedule re-runs when you track long-lived deployments.

**What does a free `status` row mean?**
The package did not produce a billable assessment. Check `STATUS_RECORDS` for the reason, such as invalid input, upstream failure, unverified provenance, rate limit, request ceiling or page ceiling. `OUTPUT` provides the run summary.

**What ecosystems and identifiers work?**
Official OSV ecosystem names, case-sensitive: `npm`, `PyPI`, `Go`, `Maven`, `RubyGems`, `crates.io`, `NuGet`. Maven names are `groupId:artifactId`. Versions must be provided explicitly, e.g. `4.17.20`.

**Is any personal data involved?**
Only package names, versions and public advisory data are sent to OSV's official API; no personal data, credentials or private identifiers are collected. Package name/version combinations are shareable by design — do not enter confidential internal naming if you consider it sensitive.

### Support and disclaimers

Problems, feature requests and questions belong on the **Issues** tab of the Actor's page on Apify. This Actor is an independent tool: it is not affiliated with Google, the Open Source Security Foundation (OpenSSF) or OSV.dev, and advisory coverage is determined by OSV's data sources. Vulnerability information is provided as-is for research and engineering use; use the returned advisory records and their source references to assess applicability and plan remediation.

Advisory data: OSV.dev and the upstream databases named in each `attributions` entry, under the licenses listed there. Built and maintained by Atesen Software.

### Related actors

- [npm Package Intelligence](https://apify.com/atesen-software/npm-package-intelligence)
- [Drupal Module Health Monitor: Releases & Security Advisories](https://apify.com/atesen-software/drupal-module-health-monitor)
- [Tech Stack Detector: Website Technology Lookup, 3,600+ Techs](https://apify.com/atesen-software/website-tech-stack-detector)

# Actor input Schema

## `packages` (type: `array`):

1-20 objects with ecosystem, name and version. Supported case-sensitive ecosystems: npm, PyPI, Go, Maven, RubyGems, crates.io, NuGet. Duplicate triples are checked once.

## `maxRequests` (type: `integer`):

Shared serial request limit including retries and pagination. Incomplete assessments are never billed.

## `maxPagesPerPackage` (type: `integer`):

Stop with a free page_limit status when OSV still has another page; never label partial data completed.

## Actor input object example

```json
{
  "packages": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20"
    }
  ],
  "maxRequests": 50,
  "maxPagesPerPackage": 5
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset assessment records.

## `statuses` (type: `string`):

Validation, source and quota diagnostics without result or dataset-item events.

## `summary` (type: `string`):

Counts, status, partial flag and request count.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "packages": [
        {
            "ecosystem": "npm",
            "name": "lodash",
            "version": "4.17.20"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("atesen-software/osv-package-vulnerability-audit").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "packages": [{
            "ecosystem": "npm",
            "name": "lodash",
            "version": "4.17.20",
        }] }

# Run the Actor and wait for it to finish
run = client.actor("atesen-software/osv-package-vulnerability-audit").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "packages": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20"
    }
  ]
}' |
apify call atesen-software/osv-package-vulnerability-audit --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,atesen-software/osv-package-vulnerability-audit"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Pi31IFq8zZZbdG1l1/builds/7jhsNp3KFlAqV1juA/openapi.json
