check_package
PG1 Sovereign Threat Intelligence: a pre-install check for one npm or PyPI package - check before you install. No payment required - this tool is always free, and no AI model is involved. SIBLING DIFFERENTIATION: Use before installing or recommending a software package (npm or PyPI) only. Do NOT use for domains (use check_domain_age / check_hostname_reputation), CVE ids (use get_cve_details) or products by vendor name (use get_cve_by_product). BEHAVIOR: Returns { ecosystem, name, version_checked, exists, version_exists, first_published, age_days, latest_version, latest_published, reported_malicious, malicious_reports, vulnerabilities, lookalike_of, deprecated, install_scripts, attribution }. Signals: whether the package (and the version, if given) exists in the registry - a package that does not exist is a key signal, since names AI assistants invent get registered by attackers; first and latest publish dates; public malicious-package reports (OpenSSF Malicious Packages, via OSV.dev) for the version checked; known vulnerabilities for that version (OSV.dev: ids and severity only); whether the name looks like a popular package's (typosquat patterns); and, for npm only, the deprecated flag and install scripts (preinstall/install/postinstall). With no version, the latest version is checked. STATUS: "flagged" when the version is reported malicious (PACKAGE_REPORTED_MALICIOUS - worded "reported malicious" because such reports can be false positives), the package or version does not exist (PACKAGE_NOT_FOUND / PACKAGE_VERSION_NOT_FOUND), or the package is under 30 days old AND its name looks like a popular package's (PACKAGE_NEW_LOOKALIKE); otherwise "unknown" if any lookup did not complete (a failed registry lookup gives exists: null, never false); otherwise "no_flags". A look-alike name alone, a new package alone, known vulnerabilities, deprecation and install scripts are informational reasons that never flag on their own. This tool never returns "safe" or "clean"; no_flags means nothing was found in the sources checked. VALIDATION: one package per call; malformed input returns an MCP tool error (isError: true, code invalid_ecosystem, invalid_package_name or invalid_version). Registry answers are cached for 1 hour and malicious/vulnerability answers for 15 minutes. Rate-limited to 60 calls/hour per caller when unauthenticated; a valid Gumroad license key (X-API-KEY header) exempts the limit. Data sources and licences: https://pg1-ai-agent.vercel.app/docs/attributions
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Mandatory package name, exactly one, e.g. 'lodash', '@types/node' or 'requests'. | |
| version | No | Optional exact version to check, e.g. '4.17.21'. No ranges or tags. Defaults to the latest published version. | |
| ecosystem | Yes | Mandatory package ecosystem: 'npm' or 'pypi'. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name as given (trimmed). | |
| note | No | ||
| cached | Yes | ||
| checks | No | Which underlying sources were checked for this result and whether each one completed. | |
| exists | Yes | Whether the package exists in the registry; null when the registry lookup did not complete (never false on a failure). | |
| status | No | "unknown" whenever a source needed for this answer timed out, errored, or was skipped - never "no_flags" in that case. | |
| reasons | No | Machine-readable reason codes for anything flagged in this result. Empty when nothing was flagged. | |
| age_days | Yes | Days since the first publish. | |
| ecosystem | Yes | ||
| deprecated | Yes | npm only: whether version_checked is deprecated. null for PyPI or when unknown. | |
| request_id | No | UUID for this request, also sent as the X-Request-Id response header. | |
| attribution | Yes | Always present: the data sources and a link to their licences. | |
| lookalike_of | Yes | The popular package this name looks like, if any. | |
| test_fixture | No | true only when the input was a documented integration test fixture and this response is canned; absent on real results. | |
| canonical_name | No | The name as the registry spells it, when the package exists. | |
| latest_version | Yes | ||
| version_exists | Yes | Whether version_checked is published; null when unknown. | |
| first_published | Yes | ISO timestamp of the first publish. | |
| install_scripts | Yes | npm only: the install-time scripts version_checked runs. null for PyPI or when unknown. | |
| version_checked | Yes | The version the malicious-report, vulnerability, deprecation and install-script signals describe: the requested version, or the latest one. | |
| vulnerabilities | Yes | Known vulnerabilities for version_checked: id and severity only. null when not checked. | |
| latest_published | Yes | ISO timestamp of the latest version's publish. | |
| lookalike_pattern | No | ||
| malicious_reports | Yes | Report ids (MAL-...). | |
| version_requested | Yes | ||
| reported_malicious | Yes | true when a public malicious-package report covers the version checked (or the package, when no version could be determined); null when that lookup did not complete. Reports can be false positives. | |
| deprecation_message | No | npm only: the publisher's deprecation message (untrusted text, cut to 300 characters). | |
| vulnerabilities_omitted | No | Advisories left out because they come from a source outside PG1's licence-checked list. |