An API to check if an npm package is safe

1. Free lookups

If anyone has scanned the version before, its result is free:

curl https://security.togoder.click/api/package/lodash/4.17.21
curl https://security.togoder.click/api/package/@babel%2Fcore/7.23.0     # scoped: encode the slash
curl https://security.togoder.click/api/package/express/ranges           # every version, grouped by verdict
curl https://security.togoder.click/npm/express.md                       # the public report as Markdown

A 404 means that version has not been scanned yet. The ranges endpoint also takes ?ecosystem=pypi (or cargo, go, gem, composer).

2. Scan a package or a lockfile

Scanning new code takes an API key. Keys work with either a prepaid balance or a monthly plan, both paid by card. A balance is topped up from $20 on the account page, not over the API, and each scan is quoted first and deducted at the quoted price. Plans run from $30 a month for 100M LLM tokens of new code per 30 days, up to 10B on Scale. Create one on the account page and send it as Authorization: Bearer <key>.

One package with its dependency tree:

curl -X POST https://security.togoder.click/api/paid-scan \
  -H "Authorization: Bearer $NPM_SCANNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ecosystem":"npm","packageName":"left-pad","packageVersion":"1.3.0"}'

A whole lockfile:

curl -X POST https://security.togoder.click/api/paid-scan \
  -H "Authorization: Bearer $NPM_SCANNER_KEY" \
  -F "file=@package-lock.json"

From code:

const res = await fetch('https://security.togoder.click/api/paid-scan', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.NPM_SCANNER_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ecosystem: 'npm', packageName: 'left-pad', packageVersion: '1.3.0' }),
});
console.log(await res.json());

If every file was scanned before, the results come back immediately at no cost, even without a key. Otherwise only the new files count against your balance or plan. An invalid or revoked key gets 401, a key with neither an active plan nor enough balance gets 402 with the price and your balance, and a scan that would exceed your plan's monthly tokens gets 429; the balance is not used while a plan is active.

3. Read the response

• results[]: one entry per package with riskLevel (safe, low, medium, high, critical or failed) and its issues.
• issues[]: severity, type, title, description, file path, line, code snippet, recommendation and a stable findingId.
• summary.highSeverityCount and summary.packagesFailed: the two numbers to gate on in automation.

Large scans can run asynchronously with ?async=1 and a job URL to poll, and POST /api/quotes shows for free how many new files and tokens a scan would use. The full reference is on the API page.

Using it from an AI agent

A coding agent about to add a dependency can call the free lookup first, and if the version has not been scanned, call /api/paid-scan with an API key from its environment. Gate the install on riskLevel not being high, critical or failed, and show the findings to a human when it is.