socket-scan

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 pnpm dlx socket to run the Socket CLI - this always fetches the latest version and requires no global install. Verify it works:

pnpm dlx socket --version

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

Authentication: demo token or account login, plus the optional global install

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:

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

This provides limited access to CLI features like pnpm dlx socket fix, pnpm dlx 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 (pnpm dlx 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: pnpm dlx socket login (stores credentials in ~/.socket/)
• Environment variable: Set SOCKET_CLI_API_TOKEN in your shell profile or CI environment

Verify account authentication:

pnpm dlx 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:

pnpm dlx socket organization list --json --no-banner --no-spinner

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

pnpm dlx 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 pnpm dlx 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 pnpm dlx 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.

pnpm dlx @cyclonedx/cdxgen -o bom.json -p

Scan Workflow

1. Determine Scan Tier

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

pnpm dlx 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 pnpm dlx 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 pnpm dlx 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 vs persistent mode, the enterprise org flag, and the full flag table

Temporary mode (default)

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

pnpm dlx 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:

pnpm dlx 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:

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

Flags:

Flag	Purpose
TARGET	Positional arg - path to directory or manifest files to scan (default: .)
--repo <name>	Repository name for dashboard metadata (not the scan target)
--tmp	Temporary read-only scan - results returned locally, not persisted to dashboard (default)
--org <org-slug>	Organization slug for enterprise scans (persistent mode only)
--json	Output results as JSON for easier parsing
--no-banner	Suppress CLI banner output
--no-spinner	Suppress spinner animations
--no-interactive	Disable interactive prompts
--branch <name>	Associate the scan with a specific branch (persistent mode only)
--commit <sha>	Associate the scan with a specific commit (persistent mode only)

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 pnpm dlx socket login or create a free account at https://socket.dev.

The cdxgen command, its flags, and the reduced-accuracy limitations

Generate an SBOM with cdxgen:

pnpm dlx @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:

Flag	Purpose
-o <file>	Output file path (default: bom.json)
-p	Print the SBOM to stdout as well as writing to file
-t <type>	Force project type (npm, pip, go, maven, gradle, etc.) - auto-detected if omitted
--no-recurse	Do not scan subdirectories (useful for monorepos to target a specific package)
--spec-version 1.5	Use CycloneDX spec version 1.5 (default)

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 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 shape, the issue-type taxonomy, and the severity triage order

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

Type	Severity	Meaning
criticalCVE

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:

pnpm dlx socket scan reach --org <org-slug> .

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

Reachability	Meaning	Effective Priority
reachable	Vulnerable code path is exercised by the project	Critical - fix immediately
unreachable	Vulnerable code path is not used	Low - deprioritize
unknown	Reachability could not be determined	High - treat as potentially reachable
not_applicable	Vulnerability does not apply to this context	Filter out

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:

Tier	Licenses	Risk Level
Permissive	MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD, Unlicense	Low - safe for commercial use
Weak Copyleft	LGPL-2.1, LGPL-3.0, MPL-2.0, EPL-2.0	Medium - may require disclosure of modifications to the library itself
Strong Copyleft	GPL-2.0, GPL-3.0, AGPL-3.0	High - may require releasing your entire project under the same license
Non-Commercial / Restrictive	SSPL, BSL, CC-BY-NC, Elastic License	High - restricts commercial use
No License / Unknown	No license file, custom license, NOASSERTION	High - no explicit permission to use

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

License	Count	Risk
MIT	120	Low
Apache-2.0	30	Low
ISC	15	Low
GPL-3.0	2	High
Unknown	1	High

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 pnpm dlx 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.
• pnpm dlx socket scan create fails with 403 / authentication error: The public demo token cannot create scans. Prompt the user to log in with pnpm dlx socket login or create a free account at https://socket.dev. If they skip login, fall back to cdxgen (pnpm dlx @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.
• pnpm dlx 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., pnpm dlx 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 pnpm dlx 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 (pnpm dlx 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