# OSS Package Health & Vulnerability API (`ai-coding-radar/oss-package-health-monitor`) Actor

Scan installed npm and PyPI versions for OSV vulnerabilities and CISA KEV matches. Compare checked vs latest versions, licenses, repositories, and npm downloads in JSON, CSV, or Excel. Transparent source status; no login, token, proxy, or private package access.

- **URL**: https://apify.com/ai-coding-radar/oss-package-health-monitor.md
- **Developed by:** [AI Coding Radar](https://apify.com/ai-coding-radar) (community)
- **Categories:** Developer tools, Automation, Open source
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 package health records

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## OSS Package Health & Vulnerability API

An npm and PyPI version vulnerability scanner API for dependency health checks, SBOM
triage, release review, and AI-agent workflows. Each output row combines
registry metadata, npm's last-week download count, OSV vulnerability records,
and CISA's Known Exploited Vulnerabilities (KEV) matches. The Actor uses only
public official HTTP APIs: no login, cookies, API key, CAPTCHA bypass, proxy
rotation, or private dependency access is required.

- [Run the Actor on Apify](https://apify.com/ai-coding-radar/oss-package-health-monitor)
- [Try the exact-version CVE scan example](https://apify.com/ai-coding-radar/oss-package-health-monitor/examples/scan-installed-npm-and-pypi-versions-for-cves)
- [Import the n8n exact-version scan](https://github.com/Jarvis-Dong/oss-package-health-monitor/blob/main/examples/n8n-oss-exact-version-scan.json)
- [Follow the n8n and Make setup recipe](https://github.com/Jarvis-Dong/oss-package-health-monitor/blob/main/examples/README.md)

Search terms this Actor is designed for:

`npm vulnerability scanner`, `PyPI vulnerability scanner`, `OSV API`, `CISA KEV`,
`package metadata API`, `dependency health report`, and `SBOM vulnerability check`.

### What it does

- Reads npm package metadata from the npm Registry and PyPI metadata from PyPI's
  JSON API.
- Reads npm downloads from npm's public downloads API. PyPI download counts are
  intentionally marked `not_supported` in this MVP rather than guessed.
- Validates an optional installed version in npm or PyPI, compares it with the
  latest release, and queries [OSV.dev](https://osv.dev/) for vulnerabilities
  affecting that exact version. Omit `version` to check the latest release.
- Matches CVE aliases against the [CISA KEV catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog).
- Emits a visible `status`, `sourceStatus`, `errors`, and `warnings` for every
  package. If OSV fails, `vulnerabilities` is `null`; it is never changed to an
  empty array to hide a failed check.

This is an evidence collector, not a security certification, legal opinion, or
guarantee that a package is safe. A clean row means the queried public sources
reported no matching record for that version at that time.

### Copy-paste REST quickstart

Keep an Apify API token in your secret manager, then send a complete input
instead of the empty placeholder shown by some generated API clients:

```sh
curl -sS -X POST \
  'https://api.apify.com/v2/acts/ai-coding-radar~oss-package-health-monitor/run-sync-get-dataset-items?clean=1' \
  -H "Authorization: Bearer $APIFY_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"packages":[{"name":"lodash","ecosystem":"npm","version":"4.17.20"}],"includeDownloads":true,"includeVulnerabilities":true,"includeRepository":true,"includeCisaKev":true}'
```

The generated API client's empty `{}` input is also safe: it checks only the
two public package/version examples from the Store schema. Use the explicit
payload above when you want to control exactly which records are billed.

### Input

```json
{
  "packages": [
    {"name": "lodash", "ecosystem": "npm", "version": "4.17.20"},
    {"name": "requests", "ecosystem": "PyPI", "version": "2.19.0"}
  ],
  "includeDownloads": true,
  "includeVulnerabilities": true,
  "includeRepository": true,
  "includeCisaKev": true
}
```

Up to 50 unique package/ecosystem/version combinations are accepted. Supported
ecosystems are `npm` and `PyPI`. Each optional `version` must be an exact
registry version, not a range such as `^4.17.0`; unresolved versions fail closed
and are not sent to OSV as an unscoped package query.

### Output

Each package produces one dataset row. A successful no-vulnerability response
has `vulnerabilities: []`, `vulnerabilityCount: 0`, and
`sourceStatus.osv: "ok"`. A failed OSV response has
`vulnerabilities: null`, `vulnerabilityCount: null`, and
`sourceStatus.osv: "error"`, with a human-readable error type in `errors`.

Example (abridged):

```json
{
  "package": "lodash",
  "ecosystem": "npm",
  "status": "ok",
  "requestedVersion": "4.17.20",
  "checkedVersion": "4.17.20",
  "latestVersion": "4.17.21",
  "isLatest": false,
  "weeklyDownloads": 167905798,
  "vulnerabilityCount": 5,
  "cisaKevMatches": [],
  "sourceStatus": {
    "registry": "ok",
    "downloads": "ok",
    "osv": "ok",
    "cisaKev": "ok"
  },
  "errors": [],
  "warnings": []
}
```

### Pricing

The intended primary event is one `package-health-record` at `$0.0015` per
returned package, plus `$0.00005` per run start. Platform usage is included in
that price. This repository does not claim revenue; only a settled payout is
income.

### Local checks

```sh
python3 -m unittest discover -s tests -v
python3 -m compileall -q oss_package_health_monitor
python3 -m oss_package_health_monitor --live-smoke
```

The live smoke checks `react` and `requests` against the public npm Registry,
npm downloads, PyPI JSON, OSV, and CISA KEV endpoints. It does not read any
credentials. Use `--fixture path/to/input.json` for an offline run.

GitHub Actions runs the same live smoke once per day at 10:17 Asia/Shanghai
(`.github/workflows/live-smoke.yml`). The scheduled job uses no secrets and
fails when any required public source is unavailable; it prints only package
status, version, and vulnerability counts.

### Limits and attribution

Results are point-in-time API observations, not a legal or security guarantee.
Keep the source URLs returned by the APIs when redistributing data. Do not use
this Actor to access private packages or to make automatic code changes. API
outages and rate limits remain visible in each row and must be handled by the
caller.

# Actor input Schema

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

Package names, ecosystems, and optional installed versions. Duplicate name/ecosystem/version entries are removed.

## `includeDownloads` (type: `boolean`):

Include npm last-week downloads. PyPI download counts are not included in this MVP.

## `includeVulnerabilities` (type: `boolean`):

Query OSV.dev. A failed query is reported as an error, never as zero vulnerabilities.

## `includeRepository` (type: `boolean`):

Include the package's public source repository when the registry provides one.

## `includeCisaKev` (type: `boolean`):

Match OSV CVE aliases against CISA's Known Exploited Vulnerabilities catalog.

## Actor input object example

```json
{
  "packages": [
    {
      "name": "lodash",
      "ecosystem": "npm",
      "version": "4.17.20"
    },
    {
      "name": "requests",
      "ecosystem": "PyPI",
      "version": "2.19.0"
    }
  ],
  "includeDownloads": true,
  "includeVulnerabilities": true,
  "includeRepository": true,
  "includeCisaKev": true
}
```

# Actor output Schema

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

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ai-coding-radar/oss-package-health-monitor").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("ai-coding-radar/oss-package-health-monitor").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 '{}' |
apify call ai-coding-radar/oss-package-health-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ai-coding-radar/oss-package-health-monitor"
        }
    }
}

```

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/d2YixWeTmAAerFn9v/builds/Y6R3sKlnHguMMK2Pe/openapi.json