Terminal
Terminal/Skill
Scans your project's dependencies for vulnerabilities and malware using the Socket CLI, with temporary read-only results by default.
By Socket
Works with
npx skills add socketdev/sauce --skill socket-scanRun 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.
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 ...).
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).
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:
pnpm dlx socket login (stores credentials in ~/.socket/)SOCKET_CLI_API_TOKEN in your shell profile or CI environmentVerify 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.
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 loginor 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
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:
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 loginor 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.
One or more real organizations returned - the user has a full account. Decide on scan mode:
Default to temporary mode. Only use persistent mode when the user has a full account AND wants results saved.
Skip to Step 2b if the user has no account or only the demo token.
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.
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) |
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 loginor create a free account at https://socket.dev.
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) |
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 infovulnerabilities[] (if present) - known CVEs with severity, description, and affected version rangesdependencies[] - dependency graph (which component depends on which)Limitations of cdxgen fallback (alert accuracy greatly reduced, SBOM accuracy poor):
For license auditing from cdxgen output, parse the components[].licenses[] field in bom.json instead of relying on Socket's license analysis.
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.
| Type | Severity | Meaning |
|---|---|---|
criticalCVE | critical | Critical-severity CVE |
cve | high | High-severity CVE |
mediumCVE | medium | Medium-severity CVE |
mildCVE | low | Low-severity CVE |
licenseSpdxDisj | varies | License mismatch or non-standard SPDX |
mixedLicense | varies | Multiple conflicting licenses |
malware | critical | Known malware detected |
Use the type field and value.severity to programmatically filter and prioritize findings.
Triage issues by 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): 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.mediumCVE, mildCVE): Summarize these for the user. Group by type and provide a brief overview rather than listing each one individually.licenseSpdxDisj, mixedLicense): Flag for the license audit step (Section 6).In addition to cdxgen (Step 2b), native package manager audit tools can supplement findings:
npm audit --jsonpnpm audit --jsonyarn audit --jsonyarn npm audit --jsonnpm install --package-lock-only then npm audit --jsonThese are narrower than cdxgen (single ecosystem, no SBOM) but can catch advisories cdxgen misses. Use both when thoroughness matters.
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.
Based on scan results, cross-reference other skills to resolve issues:
/socket-dep-upgrade skill to apply safe upgrades/socket-inspect skill to research specific packages/socket-dep-patch skill to apply security patches/socket-dep-cleanup skill to remove packages that are no longer neededScan 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:
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.
Produce a human-readable compliance summary:
| License | Count | Risk |
|---|---|---|
| MIT | 120 | Low |
| Apache-2.0 | 30 | Low |
| ISC | 15 | Low |
| GPL-3.0 | 2 | High |
| Unknown | 1 | High |
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.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.pnpm dlx socket scan create ./path/to/subdir --tmp --json).--tmp (temporary mode) for all scans - it's safe, fast, and works with the public token--tmp when the user has a full account and explicitly wants results saved to the dashboard--json for machine-readable output that is easier to parse and summarize/socket-inspect skill for deep-dives into specific flagged packages/socket-dep-upgrade skill to fix vulnerabilities discovered during the scanreachable vulnerabilities firstpnpm dlx socket for all commands - it always uses the latest CLI version/socket-inspect skill to deep-dive into specific packages flagged during the auditpnpm 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 accuracypackage-lock.json, generate one with npm install --package-lock-only before scanning or auditing