name: socket-scan description: Run a dependency scan using the Socket CLI. Prompts unauthenticated users to log in or create a free account. If the user skips login, falls back to cdxgen with greatly reduced alert accuracy and poor SBOM accuracy. Authenticated users get temporary read-only scans by default (--tmp). Creates a persistent dashboard scan only when explicitly requested. Includes reachability analysis for enterprise customers and license compliance auditing.

Research Scan

Run a dependency scan using the Socket CLI. For authenticated users, scans run in temporary read-only mode (--tmp) by default — results are returned locally without creating a persistent entry in the Socket dashboard.

For unauthenticated users (no token or demo token only), the skill prompts the user to log in or create a free account. If the user skips login, the scan falls back to cdxgen — but alert accuracy will be greatly reduced and SBOM accuracy will be poor.

When the user is authenticated with a full account (free or enterprise) and explicitly wants results saved, the scan can be promoted to a persistent dashboard scan.

When to Use

• The user wants to scan their project's dependencies for vulnerabilities or supply-chain risks
• The user wants to create a scan visible in the Socket dashboard
• The user wants reachability analysis to determine if vulnerabilities are actually exploitable in their code
• The user is adding or updating dependencies and wants to verify security posture
• The user asks for a full security audit of their dependency tree
• The user wants to check for malware in their dependencies
• The user needs to construct an SBOM from scan data for compliance
• The user wants to audit licenses across all dependencies
• The user needs to check for GPL, SSPL, or other restrictive licenses in a commercial project
• The user wants a compliance report for a security review or procurement process
• The user asks about license compatibility across their dependency tree

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 enterprise features (reachability analysis), an enterprise subscription is required in addition to authentication.

If setup fails or this is a first-time scan, use the /socket-scan-setup subskill for guided setup including auto-configuration of the public demo token.

Quick Start

First, check whether the user has a Socket account:

npx socket organization list --json --no-banner --no-spinner

If the user has a real organization (not SocketDemo or empty):

npx socket scan create . --tmp --json --no-banner --no-spinner

If the user has no token, the demo token, or is in the SocketDemo org, prompt them to log in or create an account:

You're not currently logged in to Socket. To scan your project, log in with npx socket login or create a free account at https://socket.dev.

Would you like to log in now?

If the user logs in, re-run npx socket organization list and proceed with the authenticated scan above.

If the user skips login, fall back to cdxgen. Warn them before proceeding:

I'll run a scan using cdxgen as a fallback. Please note: without a Socket account, alert accuracy will be greatly reduced and SBOM accuracy will be poor. You will not get malware detection, supply-chain risk analysis, or Socket scores.

npx @cyclonedx/cdxgen -o bom.json -p

Scan Workflow

1. Determine Scan Tier

Before scanning, check the auth state to determine the user's tier:

npx socket organization list --json --no-banner --no-spinner

Use the result to decide the scan approach:

1. No organizations returned, or the only org is SocketDemo — the user has no account or only the demo token. Prompt the user to log in or create an account:

   You're not currently logged in to Socket. To scan your project, log in with npx socket login or create a free account at https://socket.dev.

   Would you like to log in now?

   If the user logs in, re-run npx socket organization list to confirm, then proceed with Step 2a.

   If the user skips login, proceed to Step 2b (cdxgen fallback). Warn them that alert accuracy will be greatly reduced and SBOM accuracy will be poor.

2. One or more real organizations returned — the user has a full account. Decide on scan mode:

   • Ask whether they want results saved to the dashboard:
     • If yes (or if they explicitly asked to "create a scan") → persistent mode
     • If no, or if the scan is for development/exploration purposes → temporary mode (default)

Default to temporary mode. Only use persistent mode when the user has a full account AND wants results saved.

2a. Run the Scan (Authenticated Users)

Skip to Step 2b if the user has no account or only the demo token.

Temporary mode (default)

Run a read-only scan that returns results locally without persisting to the Socket dashboard:

npx socket scan create . --tmp --json --no-banner --no-spinner

This is the default for authenticated users. It does not create a dashboard entry and is safe to run repeatedly during development.

Persistent mode (authenticated users only)

Run a full scan that creates a persistent entry in the Socket dashboard:

npx socket scan create . --json --no-banner --no-spinner

The scan is uploaded to the Socket dashboard where results can be viewed, shared, and tracked over time.

For enterprise customers, specify the organization to associate the scan:

npx socket scan create . --org <org-slug> --json --no-banner --no-spinner

Flags:

2b. cdxgen Fallback (User Skipped Login)

Only use this path if the user was prompted to log in (Step 1) and chose to skip. Before running cdxgen, display this warning:

Warning: Without a Socket account, alert accuracy will be greatly reduced and SBOM accuracy will be poor. You will not get malware detection, supply-chain risk analysis, Socket scores, or reachability analysis. To get accurate results, run npx socket login or create a free account at https://socket.dev.

Generate an SBOM with cdxgen:

npx @cyclonedx/cdxgen -o bom.json -p

cdxgen auto-detects the project type (npm, pip, Go, Maven, etc.) and produces a CycloneDX SBOM with dependency and known-vulnerability data.

cdxgen flags:

Interpreting cdxgen output

The bom.json file is a CycloneDX SBOM. Extract dependency and vulnerability information from:

• components[] — list of all dependencies with name, version, purl, and license info
• vulnerabilities[] (if present) — known CVEs with severity, description, and affected version ranges
• dependencies[] — dependency graph (which component depends on which)

Limitations of cdxgen fallback (alert accuracy greatly reduced, SBOM accuracy poor):

• No malware detection, typosquatting detection, or install script analysis
• No Socket scores (security, quality, maintenance, license)
• No reachability analysis
• Vulnerability data comes from public advisory databases (OSV, NVD) — significantly less complete than Socket's curated data, expect many false negatives
• SBOM component resolution is less accurate — transitive dependencies and version pinning may be incomplete or incorrect
• No dashboard integration or historical tracking

For license auditing from cdxgen output, parse the components[].licenses[] field in bom.json instead of relying on Socket's license analysis.

3. Interpret Results

When using --json, the raw output may include non-JSON prefix lines (banners, spinners, ANSI escape codes). Always use --no-banner --no-spinner flags, or use the helper script which strips noise automatically. If parsing manually, filter for lines starting with { or [.

The JSON output is an object with an issues[] array:

{
  "id": "scan-id-string",
  "url": "https://socket.dev/dashboard/org/.../scan/...",
  "issues": [
    {
      "type": "criticalCVE",
      "value": {
        "severity": "critical",
        "title": "...",
        "description": "...",
        "package": "lodash",
        "version": "4.17.20"
      }
    }
  ]
}

Note: The exact schema may vary by CLI version. Always inspect actual --json output for the complete structure.

Issue Type Taxonomy

Use the type field and value.severity to programmatically filter and prioritize findings.

Triage issues by severity:

• Critical / High severity (criticalCVE, cve): Stop and report these to the user immediately. These represent known vulnerabilities with available exploits or severe supply-chain risks that require urgent attention.
• Malware (malware): If any issue has type malware, display a prominent warning. Malware findings should be treated as the highest priority — advise the user to remove the package immediately.
• Medium / Low severity (mediumCVE, mildCVE): Summarize these for the user. Group by type and provide a brief overview rather than listing each one individually.
• License issues (licenseSpdxDisj, mixedLicense): Flag for the license audit step (Section 6).

Additional Native Audit Tools

In addition to cdxgen (Step 2b), native package manager audit tools can supplement findings:

• npm: npm audit --json
• pnpm: pnpm audit --json
• yarn v1: yarn audit --json
• yarn v2+: yarn npm audit --json
• bun: bun has no built-in audit; run npm install --package-lock-only then npm audit --json

These are narrower than cdxgen (single ecosystem, no SBOM) but can catch advisories cdxgen misses. Use both when thoroughness matters.

4. Reachability Analysis (Enterprise Only)

For enterprise customers, run Tier 1 reachability analysis to determine whether vulnerabilities are actually reachable in the project's code:

npx socket scan reach --org <org-slug> .

This analyzes the project's dependency graph and source code to classify each vulnerability by reachability:

Reachability analysis generates a .socket.facts.json file in the project root with detailed findings. This helps prioritize which vulnerabilities to fix first — focus effort on reachable issues rather than wasting time on unreachable ones.

Skip this step entirely for non-enterprise users — reachability analysis requires an enterprise subscription with an authenticated organization.

5. Act on Findings

Based on scan results, cross-reference other skills to resolve issues:

• Vulnerabilities with available fixes — use the /socket-dep-upgrade skill to apply safe upgrades
• Packages needing deeper investigation — use the /socket-inspect skill to research specific packages
• Packages with Socket patches available — use the /socket-dep-patch skill to apply security patches
• Unused dependencies — use the /socket-dep-cleanup skill to remove packages that are no longer needed

6. License & Compliance Audit

Scan results already include license issues. Filter the issues[] array for types licenseSpdxDisj and mixedLicense to identify packages with license problems.

Categorize all discovered licenses into risk tiers:

Flag the following issues for user attention:

• Strong copyleft in commercial projects: GPL/AGPL dependencies in projects not licensed under GPL/AGPL
• SSPL or non-commercial licenses: Dependencies that restrict commercial use
• No license detected: Dependencies with no license file or an unrecognized license
• License conflicts: Dependencies whose licenses are incompatible with each other or with the project's own license
• Dual-licensed packages: Note when packages offer multiple license options (e.g., MIT OR Apache-2.0)

7. Generate SBOM

The Socket CLI does not natively generate SBOMs. To produce one, use scan results to build a CycloneDX 1.5 (bom.json) or SPDX 2.3 (sbom.spdx.json) document manually. Ask the user which format they prefer; default to CycloneDX.

8. Compliance Summary

Produce a human-readable compliance summary:

License Summary

Issues Found

• List each flagged issue from Step 5 with the package name, version, and recommended action

SBOM (if generated)

• Note the filename and format of the generated SBOM

Recommendation

• Overall compliance status: Clean / Issues Found / Action Required
• Specific actions for each flagged issue

Error Handling

• socket: command not found: Use npx socket as a prefix for all commands. If you prefer a global install, run npm install -g socket@latest. If you need a permanent installation, use the /socket-setup skill.
• npx socket scan create fails with 403 / authentication error: The public demo token cannot create scans. Prompt the user to log in with npx socket login or create a free account at https://socket.dev. If they skip login, fall back to cdxgen (npx @cyclonedx/cdxgen -o bom.json -p) — see Step 2b — but warn them that alert accuracy will be greatly reduced and SBOM accuracy will be poor. Use the /socket-setup skill for guided configuration.
• npx socket scan reach returns "not available": Reachability analysis requires an enterprise subscription. Skip this step for free-tier users.
• No manifest/lock files found: The scan relies on manifest files (package.json, requirements.txt, go.mod, etc.). Ensure the target path points to a directory containing these files. For bun projects, if only bun.lock exists, run npm install --package-lock-only to generate a package-lock.json that Socket can parse.
• Scan times out: Large monorepos with many manifest files may take longer. Try limiting the scan to a specific subdirectory (e.g., npx socket scan create ./path/to/subdir --tmp --json).
• License not recognized: If Socket returns an unknown or custom license, note it as "Unknown" and flag for manual review. Include the package's repository URL so the user can check the license file directly.

Tips

• Default to --tmp (temporary mode) for all scans — it's safe, fast, and works with the public token
• Only omit --tmp when the user has a full account and explicitly wants results saved to the dashboard
• Always run a scan after adding, updating, or removing dependencies to verify the project's security posture
• Use --json for machine-readable output that is easier to parse and summarize
• Combine with the /socket-inspect skill for deep-dives into specific flagged packages
• Combine with the /socket-dep-upgrade skill to fix vulnerabilities discovered during the scan
• Enterprise customers should use reachability analysis to prioritize fixes — focus on reachable vulnerabilities first
• Persistent scan results are available in the Socket dashboard for team visibility and historical tracking
• Use npx socket for all commands — it always uses the latest CLI version
• Run a compliance audit before releasing a new version to catch license issues early
• Re-audit after adding or updating dependencies — license information can change between versions
• When flagging GPL dependencies, check if they are dev-only — GPL in devDependencies is generally lower risk for commercial projects
• Use the /socket-inspect skill to deep-dive into specific packages flagged during the audit
• If the user is not logged in, always prompt them to log in (npx socket login) or create a free account at https://socket.dev before falling back to cdxgen. cdxgen has greatly reduced alert accuracy and poor SBOM accuracy
• For bun projects without a package-lock.json, generate one with npm install --package-lock-only before scanning or auditing