# Socket Scan

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

- Skill: `socketdev/socket-scan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add socketdev/socket-scan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/socketdev/socket-scan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: socketdev (https://skillmd.com/u/socketdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/socketdev/socket-scan

---


# 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

<!-- BEGIN_SECTION:cli-setup.md -->

### 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:

```shell
pnpm dlx socket --version
```

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

<details><summary>Authentication: demo token or account login, plus the optional global install</summary>

**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:

```shell
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:

```shell
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.

</details>
<!-- END_SECTION:cli-setup.md -->

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:

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

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

```shell
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.

```shell
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:

```shell
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.**

<details><summary>Temporary vs persistent mode, the enterprise org flag, and the full flag table</summary>

#### Temporary mode (default)

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

```shell
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:

```shell
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:

```shell
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)                          |

</details>

### 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>.

<details><summary>The cdxgen command, its flags, and the reduced-accuracy limitations</summary>

Generate an SBOM with cdxgen:

```shell
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 `bom.json` instead of relying on Socket's license analysis.

</details>

### 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 `[`.

<details><summary>The JSON shape, the issue-type taxonomy, and the severity triage order</summary>

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

```json
{
  "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`     | 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:

- **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).

</details>

### 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:

```shell
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