Research Inspect

Research a package before you depend on it. This skill pulls every available signal from Socket — scores, alerts, malware verdicts, CVEs, and supply-chain risk indicators — checks the socket.dev package page for additional context, evaluates alternatives when warranted, and surfaces available Socket patches. Use it to make an informed decision before adding, keeping, or replacing any dependency.

When to Use

Evaluate a package before installing it
Investigate a flagged dependency from a scan
Check the security, quality, or maintenance status of a package
Compare alternatives for a dependency choice
Check if a package is malware
Check if Socket has patches available for a vulnerable package
Get a comprehensive supply-chain risk report

Prerequisites

Socket CLI Setup

Use npx socket to run the Socket CLI — this always fetches the latest version and requires no global install. Verify it works:

npx socket --version

All commands in this skill use the npx socket prefix (e.g., npx socket scan create ...).

Optional global install: If you prefer a global socket command, install with npm install -g socket@latest (must be version 1.0.0 or higher).

Authentication

For users without a Socket account: Configure the public demo token directly:

npx socket config set apiToken sktsec_t_--RAN5U4ivauy4w37-6aoKyYPDt5ZbaT5JBVMqiwKo_api --no-banner --no-spinner
npx socket config set defaultOrg SocketDemo --no-banner --no-spinner

This provides limited access to CLI features like npx socket fix, npx socket package score, sfw, and socket-patch with rate limits. No account creation is needed for basic usage. Note: The public demo token cannot create scans (npx socket scan create requires the full-scans:create permission). For scanning and full-rate access, create a free account at https://socket.dev.

For users with an account: Authenticate with one of:

Interactive login: npx socket login (stores credentials in ~/.socket/)
Environment variable: Set SOCKET_CLI_API_TOKEN in your shell profile or CI environment

Verify account authentication:

npx socket organization list

If authentication fails or the CLI is not installed, use the /socket-setup skill for detailed guidance including Node.js installation, PATH troubleshooting, and CI/CD token configuration.

For the Batch PURL API: SOCKET_SECURITY_API_KEY is required for direct API calls. Users with a free or enterprise account can create an API key at https://socket.dev/dashboard/org/{ORG}/settings/integrations/api-tokens.

Step 1 — Fetch Package Data via the Socket Batch PURL API

Query the Socket Batch PURL REST API with the package's PURL (Package URL) to retrieve scores, alerts, CVEs, and metadata.

Supported ecosystems: npm, pypi, go, maven, nuget, rubygems, cargo

API call:

curl -X POST https://api.socket.dev/v0/orgs/{org_slug}/purl \
  -H "Authorization: Bearer $SOCKET_SECURITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purls": ["pkg:<ecosystem>/<name>@<version>"]}'

Note: This endpoint requires org access and a SOCKET_SECURITY_API_KEY. The old /v0/purl endpoint is deprecated (returns empty results since Jan 2026).

Warning: The Batch PURL API may be intermittently unavailable (returns 401 or empty responses). If the API call fails, use the CLI fallback in Step 1b below.

For example, to inspect lodash@4.17.21 on npm:

curl -X POST https://api.socket.dev/v0/orgs/{org_slug}/purl \
  -H "Authorization: Bearer $SOCKET_SECURITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purls": ["pkg:npm/lodash@4.17.21"]}'

If SOCKET_SECURITY_API_KEY is not set, authentication is required before proceeding. Run npx socket login or set the SOCKET_SECURITY_API_KEY environment variable. Use the /socket-setup skill for guidance.

Extract all returned data:

Overall score and category scores (security, quality, maintenance, license)
Alerts (every alert, grouped by category)
Known vulnerabilities (CVEs) with severity and fix versions
Dependency counts (direct and transitive)
Maintainer and author information
License identifier

Step 1b — CLI Fallback

If the Batch PURL API is unavailable or returns an error, fall back to the CLI:

npx socket package score <ecosystem> <name> <version>

This returns score data without requiring SOCKET_SECURITY_API_KEY.

Step 2 — Check the socket.dev Package Page

Construct the package URL:

https://socket.dev/{ecosystem}/package/{name}/overview

For scoped npm packages (e.g. @scope/name), encode the scope:

https://socket.dev/npm/package/@scope/name/overview

Use WebFetch to visit the page and extract:

Score breakdown across all categories
Full alert list with descriptions
Dependency graph summary
Any additional context not present in the API response

Note: The socket.dev package page may be blocked by Cloudflare bot protection when accessed via WebFetch. The page URL should still be provided to the user as a manual link, but cannot be relied on as a programmatic data source.

If WebFetch is unavailable or fails (including due to bot protection), note that the report is based on API data only and include the URL so the user can check manually.

Step 3 — Evaluate Supply Chain Risk

Analyze the package across five dimensions. Always check malware first.

Each dimension draws from different data sources:

3a. Malware — Batch PURL API alerts + socket.dev package page (WebFetch)
3b. Vulnerabilities — Batch PURL API CVE data
3c. Dependency Tree — Batch PURL API dependency counts + socket.dev page (WebFetch)
3d. Maintenance Health — socket.dev package page (WebFetch) + GitHub API (for commit activity and issue counts)
3e. Author & Maintainer Trust — Batch PURL API maintainer data + socket.dev page (WebFetch)

3a. Malware (CHECK FIRST)

If the package is flagged as malware, STOP and report immediately with a prominent warning. Do not continue to other dimensions until the malware finding is clearly communicated.

Check for:

Explicit malware flags in Socket alerts
Suspicious install scripts (preinstall, postinstall)
Obfuscated or minified source code with no readable original
Unexpected network access, filesystem access, or shell execution
Data exfiltration patterns

If malware is detected, the warning MUST be the first thing in the output.

3b. Vulnerabilities

List all known CVEs with severity, affected version ranges, and whether a fix is available
Count by severity: critical, high, medium, low
Highlight any unpatched (no fix available) vulnerabilities
Note if vulnerabilities exist in transitive dependencies

3c. Dependency Tree

Report direct and transitive dependency counts
Flag if the package has more than 100 transitive dependencies
Flag unusual tree depth
Note any flagged or problematic transitive dependencies
Consider whether the dependency footprint is proportional to the package's functionality

3d. Maintenance Health

Last publish date and release cadence
Commit frequency and recent activity
Open issues and pull requests (ratio of open to closed)
Number of contributors and maintainers
Flag as potentially unmaintained if no publish in the last 12 months
Flag as potentially abandoned if no commits in the last 24 months

3e. Author & Maintainer Trust

Number of maintainers (flag if single maintainer for a widely-used package)
Recent ownership or maintainer changes
Typosquatting signals (name similarity to popular packages)
Whether maintainers publish other well-known packages

Step 4 — Research Alternatives

Research alternatives when any of the following conditions are met:

Malware detected
Critical unpatched CVEs
Package is unmaintained (>12 months since last publish)
Socket score below 40
Excessive transitive dependencies relative to functionality
User explicitly asks for alternatives

To research alternatives:

Identify the package's core functionality
Search for well-known alternatives providing similar functionality
Query the Socket Batch PURL API for the top 3-5 alternatives (or use npx socket package score CLI fallback)
Present a comparison table:

Package	Socket Score	Vulnerabilities	Dependencies	Last Published
original	...	...	...	...
alt-1	...	...	...	...
alt-2	...	...	...	...

Step 5 — Check for Socket Patches

What are Socket patches? Socket patches are binary-level fixes applied directly to installed packages without changing their version numbers. They fix known vulnerabilities in-place, which is useful when an upstream fix doesn't exist yet or when upgrading would introduce breaking changes.

Check the API response data for available Socket patches or overrides
If patches are available, mention the patched version and link to the socket.dev page
Cross-reference the /socket-dep-patch and /socket-dep-upgrade skills — remind the user they can apply patches with /socket-dep-patch (binary-level, no version change) or run a security-audited upgrade with /socket-dep-upgrade (version upgrade with code migration)

Output Format

If Malware Is Detected

When malware is detected, the output MUST begin with this warning before any other content:

MALWARE DETECTED — do NOT install this package.

Package: {name} ({ecosystem}) Malware type: {description of malware behavior}

Recommended action: Remove this package immediately if already installed. Check for alternatives below.

Then continue with the standard report sections.

Standard Report

Structure the report as follows:

{name} v{version} ({ecosystem})

Socket Score: {score}/100

Alerts List all Socket alerts grouped by category (security, quality, maintenance, license, miscellaneous).

Vulnerabilities

CVE	Severity	Affected Versions	Fixed In
...	...	...	...

Supply Chain Risk Assessment Summarize findings across the five dimensions (malware, vulnerabilities, dependency tree, maintenance health, author trust). Call out anything that warrants concern.

Socket Patches State whether Socket patches are available. If yes, mention the patched version and how to apply via /socket-dep-patch.

Alternatives (if applicable) Include the comparison table from Step 4.

Recommendation A clear, actionable recommendation: safe to use, use with caution (with reasons), or avoid (with reasons and alternatives).

Source: socket.dev/{ecosystem}/package/{name}

Error Handling

Batch PURL API returns no data: The package may not exist in the specified ecosystem, or the package name may be misspelled. Verify the exact package name and ecosystem. For scoped npm packages, include the full scope (e.g., @babel/core). If SOCKET_SECURITY_API_KEY is not set, use the /socket-setup skill to configure authentication. For users without an account, the public demo token provides limited CLI access but the Batch PURL API requires SOCKET_SECURITY_API_KEY from a free or enterprise account. As a fallback, use npx socket package score <ecosystem> <name> <version> for basic score data.
WebFetch fails on socket.dev page: Fall back to API data only. Note in the report that the review is based on API data and include the socket.dev URL for the user to check manually.
Package not found in Socket's database: Socket may not index all packages in all ecosystems. Note this limitation and suggest checking the package's own repository and issue tracker directly.
GitHub API rate limit: If GitHub API calls for maintenance data are rate-limited, skip the maintenance health dimension and note it in the report.

Tips

Always review unfamiliar packages before adding them as dependencies
Single-maintainer packages carry higher supply-chain risk
Large transitive dependency trees increase attack surface
If a package is flagged as malware, do NOT install it — recommend immediate removal if already present
Use inspect results to inform decisions with the /socket-dep-upgrade, /socket-dep-patch, and /socket-scan skills
Weigh Socket score and maintenance health over download count alone
Re-review periodically — a package's security posture changes over time
CLI-based inspection works with the public token (use /socket-setup to configure) for users without an account, subject to rate limits. The Batch PURL API requires SOCKET_SECURITY_API_KEY from a free or enterprise account.
Prefer Socket patches over manual version pinning when available

socket-inspect