From c7cc77e2b68d5cec1598cd5df412dc49784b90b0 Mon Sep 17 00:00:00 2001 From: Jordan Harband Date: Wed, 4 Nov 2026 11:25:04 -0600 Subject: [PATCH] feat(auth): connect to Socket through browser sign-in Add a socket-connect plugin that bundles the hosted Socket MCP server (https://mcp.socket.dev/). Agents sign in with OAuth (dynamic client registration + PKCE against api.socket.dev), so users no longer paste an organization API token to use Socket from Claude Code, Cursor, or Gemini. - socket-connect: sign-in steps per agent, choosing among the organizations a sign-in covers, and linking the CLI for scans - marketplace: socket-connect entry with an inline mcpServers block; auth-dependent plugins depend on it so one sign-in serves them all - cursor/gemini: ship the same server; a structural test keeps the URL identical across all three manifests - skills: prefer browser sign-in; keep API tokens for CI; the user runs `socket login` in their own terminal, never pasting tokens into chat --- .claude-plugin/marketplace.json | 30 ++++- .cursor-plugin/mcp.json | 6 +- README.md | 9 +- agents/README.md | 7 +- gemini-extension.json | 7 +- scripts/repo/generate-cursor-plugin.mts | 12 +- skills/_shared/docs/cli-setup.md | 4 +- skills/socket-connect/SKILL.md | 105 ++++++++++++++++++ skills/socket-fix/SKILL.md | 4 +- skills/socket-fix/socket-dep-upgrade/SKILL.md | 6 +- skills/socket-inspect/SKILL.md | 8 +- skills/socket-scan/SKILL.md | 4 +- skills/socket-scan/socket-scan-setup/SKILL.md | 8 +- skills/socket-setup/SKILL.md | 25 +++-- .../repo/unit/generate-cursor-plugin.test.mts | 4 +- .../paths-manifest-consistency.test.mts | 21 ++++ .../structural/paths-skill-discovery.test.mts | 1 + 17 files changed, 217 insertions(+), 44 deletions(-) create mode 100644 skills/socket-connect/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f228a92e..ae9b6af4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,19 +12,34 @@ "name": "socket-scan", "source": "./skills/socket-scan", "skills": "./", - "description": "Run a full dependency scan using the Socket CLI. Creates a scan in the Socket dashboard, checks all dependencies for vulnerabilities and supply-chain risks, performs Tier 1 reachability analysis for enterprise customers, and provides license compliance auditing." + "description": "Run a full dependency scan using the Socket CLI. Creates a scan in the Socket dashboard, checks all dependencies for vulnerabilities and supply-chain risks, performs Tier 1 reachability analysis for enterprise customers, and provides license compliance auditing.", + "dependencies": ["socket-connect"] }, { "name": "socket-inspect", "source": "./skills/socket-inspect", "skills": "./", - "description": "Research a package before you depend on it - pull every signal from Socket (scores, alerts, malware verdicts, CVEs, supply-chain risk), check the socket.dev package page, evaluate alternatives, and surface available Socket patches." + "description": "Research a package before you depend on it - pull every signal from Socket (scores, alerts, malware verdicts, CVEs, supply-chain risk), check the socket.dev package page, evaluate alternatives, and surface available Socket patches.", + "dependencies": ["socket-connect"] + }, + { + "name": "socket-connect", + "source": "./skills/socket-connect", + "skills": "./", + "description": "Connect to Socket by signing in through the browser - no API key to paste. Bundles the hosted Socket MCP server (OAuth), lists every organization you belong to, and links the Socket CLI for scans.", + "mcpServers": { + "socket": { + "type": "http", + "url": "https://mcp.socket.dev/" + } + } }, { "name": "socket-setup", "source": "./skills/socket-setup", "skills": "./", - "description": "Set up Socket - prompt for API key, install the CLI, authenticate, configure policies and tokens, set up CI/CD for firewall or patch modes across GitHub, GitLab, Bitbucket, and other systems." + "description": "Set up Socket - connect your account through browser sign-in, install the CLI, configure policies and CI tokens, and set up CI/CD for firewall or patch modes across GitHub, GitLab, Bitbucket, and other systems.", + "dependencies": ["socket-connect"] }, { "name": "socket-dep-patch", @@ -36,7 +51,8 @@ "name": "socket-dep-upgrade", "source": "./skills/socket-fix/socket-dep-upgrade", "skills": "./", - "description": "Use socket fix to find and update vulnerable dependencies one at a time, then fix any breaking changes in the codebase. Security-audited upgrades with automated code migration." + "description": "Use socket fix to find and update vulnerable dependencies one at a time, then fix any breaking changes in the codebase. Security-audited upgrades with automated code migration.", + "dependencies": ["socket-connect"] }, { "name": "socket-dep-cleanup", @@ -54,13 +70,15 @@ "name": "socket-fix", "source": "./skills/socket-fix", "skills": "./", - "description": "Fix dependency security issues - either scan and fix everything (requires /socket-scan), or target a single named package. Orchestrates /socket-dep-cleanup, /socket-dep-replace, /socket-dep-patch, and /socket-dep-upgrade as subskills." + "description": "Fix dependency security issues - either scan and fix everything (requires /socket-scan), or target a single named package. Orchestrates /socket-dep-cleanup, /socket-dep-replace, /socket-dep-patch, and /socket-dep-upgrade as subskills.", + "dependencies": ["socket-connect"] }, { "name": "socket-scan-setup", "source": "./skills/socket-scan/socket-scan-setup", "skills": "./", - "description": "Set up prerequisites for Socket scanning - install the CLI, configure auth with the public demo token, and verify scan access." + "description": "Set up prerequisites for Socket scanning - install the CLI, sign in with your own Socket account, and verify scan access.", + "dependencies": ["socket-connect"] }, { "name": "socket-release", diff --git a/.cursor-plugin/mcp.json b/.cursor-plugin/mcp.json index da39e4ff..f0704e27 100644 --- a/.cursor-plugin/mcp.json +++ b/.cursor-plugin/mcp.json @@ -1,3 +1,7 @@ { - "mcpServers": {} + "mcpServers": { + "socket": { + "url": "https://mcp.socket.dev/" + } + } } diff --git a/README.md b/README.md index 1657a8f7..929f0832 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ For example: /plugin install socket-scan@SocketDev/skills ``` -The installable plugin names are `socket-setup`, `socket-scan`, `socket-scan-setup`, `socket-inspect`, `socket-fix`, `socket-dep-cleanup`, `socket-dep-patch`, `socket-dep-replace`, and `socket-dep-upgrade`. +The installable plugin names are `socket-connect`, `socket-setup`, `socket-scan`, `socket-scan-setup`, `socket-inspect`, `socket-fix`, `socket-dep-cleanup`, `socket-dep-patch`, `socket-dep-replace`, and `socket-dep-upgrade`. ### Codex @@ -127,7 +127,7 @@ pnpm dlx skills add SocketDev/skills 1. Or manually copy the [`agents/README.md`](agents/README.md) file into your agent's instructions/context directory as `AGENTS.md`. This file contains a summary of all available skills and their locations. -2. Skills call the Socket CLI and Batch PURL API directly, so no MCP server is required. +2. Skills call the Socket CLI and Batch PURL API directly, so no MCP server is required. The Claude Code, Cursor, and Gemini plugins also bundle the hosted Socket MCP server (`https://mcp.socket.dev/`), which signs you in through the browser instead of asking for an API key. See the `socket-connect` skill. ## Usage @@ -159,9 +159,10 @@ Install, authenticate, and configure Socket for your project. | `cargo-publish` | Operate the socket-release crates.io flow - the cargo staged model, trusted publishing (OIDC), index-propagation waits, and yank-as-rollback. | [SKILL.md](skills/socket-release/cargo-publish/SKILL.md) | | `github-release` | Cut, verify, and reconcile immutable GitHub releases - the registry-resolvability ORDER RULE, the draft-upload-undraft cut, checksums.txt, and tag-gap healing. | [SKILL.md](skills/socket-release/github-release/SKILL.md) | | `npm-publish` | Operate the socket-release npm flow end to end - bootstrap (permissive-then-staged-only publishing access), staged publish dispatch, soak, --approve promote, backfill, and rollback/deprecate. | [SKILL.md](skills/socket-release/npm-publish/SKILL.md) | +| `socket-connect` | Connect to Socket by signing in through the browser - no API key to paste. Bundles the hosted Socket MCP server (OAuth), lists every organization you belong to, and links the Socket CLI for scans. | [SKILL.md](skills/socket-connect/SKILL.md) | | `socket-release` | Stand up SocketDev publishing (npm, crates.io, GitHub releases, Homebrew tap) in a repo: copy in the release kit and run its bootstrap - name reservation, GitHub environments, npm trusted publisher, staged publish config, verification. | [SKILL.md](skills/socket-release/SKILL.md) | -| `socket-scan-setup` | Set up prerequisites for Socket scanning - install the CLI, configure auth with the public demo token, and verify scan access. | [SKILL.md](skills/socket-scan/socket-scan-setup/SKILL.md) | -| `socket-setup` | Set up Socket - prompt for API key, install the CLI, authenticate, configure policies and tokens, set up CI/CD for firewall or patch modes across GitHub, GitLab, Bitbucket, and other systems. | [SKILL.md](skills/socket-setup/SKILL.md) | +| `socket-scan-setup` | Set up prerequisites for Socket scanning - install the CLI, sign in with your own Socket account, and verify scan access. | [SKILL.md](skills/socket-scan/socket-scan-setup/SKILL.md) | +| `socket-setup` | Set up Socket - connect your account through browser sign-in, install the CLI, configure policies and CI tokens, and set up CI/CD for firewall or patch modes across GitHub, GitLab, Bitbucket, and other systems. | [SKILL.md](skills/socket-setup/SKILL.md) | #### Analysis diff --git a/agents/README.md b/agents/README.md index e33af3d0..d4c5d9b8 100644 --- a/agents/README.md +++ b/agents/README.md @@ -10,6 +10,7 @@ You have additional SKILLs documented in directories containing a "SKILL.md" fil | cargo-publish | Operate the socket-release crates.io flow - the cargo staged model (dry-run default), trusted publishing via OIDC under the cargo-publish environment, index-propagation waits, and yank-as-rollback. Use when publishing a Rust crate in a repo carrying scripts/socket-release/. | | github-release | Cut, verify, and reconcile immutable GitHub releases with the socket-release kit - the registry-resolvability ORDER RULE, the three-step draft-upload-undraft cut, checksums.txt production, and tag-gap healing. Use when tagging a release, healing a missing tag/release, or when the github-release workflow gate refuses a tag. | | npm-publish | Operate the socket-release npm flow end to end - bootstrap a package (name reservation, permissive-then-staged-only publishing access, trusted publishing), dispatch a staged publish, promote with --approve, backfill an old version, and roll back with deprecate. Use when publishing an npm package in a repo carrying scripts/socket-release/. | +| socket-connect | Connect your agent to Socket by signing in through the browser - no API key to copy or paste. Bundles the hosted Socket MCP server (OAuth), lists every organization you belong to, and links the Socket CLI for scans. | | socket-dep-cleanup | Evaluate and remove a single unused dependency from your project. Searches the entire codebase for all usages (imports, requires, config refs, scripts, type packages, indirect usage), reports findings, and performs full removal with verification. | | socket-dep-patch | Apply Socket's binary-level security patches without changing dependency versions. Uses socket-patch apply to fix vulnerabilities in-place, then verifies automated patching is configured so patches persist across installs. | | socket-dep-replace | Replace a dependency with an alternative package, eliminate it via code rewrite, or use socket-optimize for optimized replacements. | @@ -18,8 +19,8 @@ You have additional SKILLs documented in directories containing a "SKILL.md" fil | socket-inspect | Research a package before you depend on it - pull every signal from Socket (scores, alerts, malware verdicts, CVEs, supply-chain risk), check the socket.dev package page, evaluate alternatives, and surface available Socket patches. | | socket-release | Stand up SocketDev publishing (npm, crates.io, GitHub releases, Homebrew tap) in a repo - copy in the socket-release kit from a sauce checkout and run its bootstrap through name reservation, GitHub environments, npm trusted publisher, publishing-access tightening, staged publish config, and verification. | | socket-scan | Run a dependency scan using the Socket CLI. Prompt unauthenticated users to log in or create an account. If they decline, offer a local SBOM that does not include Socket analysis. 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. | -| socket-scan-setup | Set up prerequisites for Socket scanning - install the CLI, configure user-owned authentication, and verify scan access. Use this before the first scan or when encountering auth errors. | -| socket-setup | Set up Socket - prompt for API key, install the CLI, authenticate, configure policies and tokens, set up CI/CD for firewall or patch modes across GitHub, GitLab, Bitbucket, and other systems. | +| socket-scan-setup | Set up prerequisites for Socket scanning - install the CLI, sign in with your own Socket account, and verify scan access. Use this before the first scan or when encountering auth errors. | +| socket-setup | Set up Socket - connect your account through browser sign-in, install the CLI, configure policies and CI tokens, and set up CI/CD for firewall or patch modes across GitHub, GitLab, Bitbucket, and other systems. | ## Usage @@ -43,6 +44,8 @@ The skills are located in: - `skills/socket-release/npm-publish/SKILL.md` +- `skills/socket-connect/SKILL.md` + - `skills/socket-fix/socket-dep-cleanup/SKILL.md` - `skills/socket-fix/socket-dep-patch/SKILL.md` diff --git a/gemini-extension.json b/gemini-extension.json index d0cac4d6..dfaf0df8 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -2,5 +2,10 @@ "name": "socket-skills", "description": "Provides access to Socket Security Skills.", "version": "1.0.0", - "contextFileName": "agents/README.md" + "contextFileName": "agents/README.md", + "mcpServers": { + "socket": { + "httpUrl": "https://mcp.socket.dev/" + } + } } diff --git a/scripts/repo/generate-cursor-plugin.mts b/scripts/repo/generate-cursor-plugin.mts index f64a1b78..1b40b26d 100644 --- a/scripts/repo/generate-cursor-plugin.mts +++ b/scripts/repo/generate-cursor-plugin.mts @@ -92,9 +92,19 @@ export function buildCursorPluginManifest( return manifest } +/** + * The hosted Socket MCP server. It signs users in with OAuth (dynamic client + * registration + PKCE against api.socket.dev), so the plugin ships no API key + * and users never paste one. Keep in sync with the socket-connect entry in + * .claude-plugin/marketplace.json and with gemini-extension.json. + */ +export const SOCKET_MCP_URL = 'https://mcp.socket.dev/' + export function buildMcpConfig(): Record { return { - mcpServers: {}, + mcpServers: { + socket: { url: SOCKET_MCP_URL }, + }, } } diff --git a/skills/_shared/docs/cli-setup.md b/skills/_shared/docs/cli-setup.md index 6ea5b31e..1f3346dc 100644 --- a/skills/_shared/docs/cli-setup.md +++ b/skills/_shared/docs/cli-setup.md @@ -18,8 +18,8 @@ Commands that require authentication need a Socket account and a credential that Authenticate with one of these methods: -- **Interactive login**: `pnpm dlx socket login` (stores credentials in `~/.socket/`) -- **Environment variable**: Set `SOCKET_CLI_API_TOKEN` in your shell profile or CI environment +- **Interactive login**: the user runs `pnpm dlx socket login` in their own terminal (it needs an interactive TTY, so the agent cannot run it). CLI releases with browser login show a device code to approve in the browser; older releases, including the current npm release, prompt for an API token. The `/socket-connect` skill covers signing in and choosing organizations. +- **Environment variable (CI)**: Set `SOCKET_CLI_API_TOKEN` to an organization API token in CI or other non-interactive environments Verify account authentication: diff --git a/skills/socket-connect/SKILL.md b/skills/socket-connect/SKILL.md new file mode 100644 index 00000000..88bb0814 --- /dev/null +++ b/skills/socket-connect/SKILL.md @@ -0,0 +1,105 @@ +--- +name: socket-connect +description: + Connect your agent to Socket by signing in through the browser - no API key + to copy or paste. Bundles the hosted Socket MCP server (OAuth), lists every + organization you belong to, and links the Socket CLI for scans. +--- + +# Connect to Socket + +Sign in to Socket from the agent with OAuth. The user approves access in the browser, and the agent gets a token for their own account. That token covers every organization the user belongs to, so nobody copies an organization API token out of the dashboard. + +This plugin ships the hosted Socket MCP server (`https://mcp.socket.dev/`). Other Socket skills install it as a dependency, so most users already have it. + +## When to Use + +- The user wants to connect, sign in, or log in to Socket from the agent +- Another Socket skill needs account access and none is configured +- A Socket tool returns 401, "needs authentication", or "not connected" +- The user belongs to several Socket organizations and wants to pick one +- The user asks how to use Socket without pasting an API key + +## Step 1: Check Whether Socket Is Connected + +Look for a Socket MCP tool named `organizations` among your available tools. The full tool name depends on how the server was added. For example, it can be `mcp__plugin_socket-connect_socket__organizations` or `mcp__socket-mcp__organizations`. Match on the server URL or the `organizations` suffix, never on one hard-coded prefix. + +- If the tool exists, call it. A list of organizations means the user is connected. Go to Step 3. +- If the call fails with an authentication error, or the tool is missing, go to Step 2. + +## Step 2: Sign In With the Browser + +Tell the user how to sign in for their agent. Nobody needs an API key. + +| Agent | How to sign in | +| ------------------- | ---------------------------------------------------------------------------------------------- | +| Claude Code | Run `/mcp`, pick the Socket server, then choose **Authenticate**. A browser window opens. | +| Claude Code (shell) | `claude mcp login `, using the name shown by `/mcp`. Add `--no-browser` over SSH. | +| Cursor | Open **Customize** in the sidebar, select the Socket server, and sign in to it. | +| Gemini CLI | Run `/mcp auth socket`. | +| Codex | Add `https://mcp.socket.dev/` as an MCP server, then run `codex mcp login `. | + +If the Socket server is not listed at all, add it by URL. In Claude Code: + +```shell +claude mcp add --transport http socket https://mcp.socket.dev/ +``` + +The browser shows Socket's sign-in and consent pages. If the user has no account, they can create a free one there. After they approve, call `organizations` again to confirm. + +Non-interactive runs (`claude -p`, Agent SDK, CI) cannot open a browser. Sign in once interactively, or use an API token as described in Step 5. + +## Step 3: Choose Which Organizations to Use + +The `organizations` tool returns the organizations this sign-in can reach. Which ones that is depends on what the user granted on Socket's consent page. + +- **One organization:** use it. If the user wants a different organization, clear the Socket server's sign-in (in Claude Code, `/mcp` or `claude mcp logout `) and sign in again, choosing that organization on the consent page. +- **Several organizations:** use all of them by default, or the ones the user selects. Remember the selection for the rest of the session, and never narrow it silently. + +Org-scoped tools such as `alerts` and `threat_feed` take one `org_slug` per call. To cover several organizations, call the tool once per organization and label each result with its organization. + +## Step 4: Use Socket Through MCP + +Once connected, prefer the MCP tools over pasted tokens: + +- `depscore` - scores for one or more packages (used by `/socket-inspect`) +- `alerts` - open alerts across the organization's monitored packages +- `threat_feed` - recent malware and threat reports +- `package_files`, `package_file_contents`, `package_file_grep` - read a published package's files + +## Step 5: Connect the Socket CLI (Scans and Fixes) + +The MCP server does not create scans. `/socket-scan` and `/socket-fix` use the Socket CLI, which signs in separately. `socket login` needs an interactive terminal, so the agent cannot run it through its shell tool. Ask the user to run it themselves (in Claude Code, type `! pnpm dlx socket login`): + +```shell +pnpm dlx socket login +``` + +- If the CLI opens a browser and shows a device code, the user approves it the same way as Step 2. No token is pasted. +- If the CLI instead prompts for an API token, that CLI release predates browser login. The current npm release still prompts for a token. Ask the user whether they want to create an API token in the dashboard and paste it into the masked prompt (never into the chat), or skip CLI-only features for now. + +The CLI sets its default organization to the first one it finds. If that differs from the organization chosen in Step 3, pass `--org ` to CLI commands, or ask before changing the default with `pnpm dlx socket config set defaultOrg `. + +Verify the CLI without printing a credential: + +```shell +pnpm dlx socket organization list --json --no-banner --no-spinner +``` + +For CI and other non-interactive environments, an organization API token in `SOCKET_CLI_API_TOKEN` remains the right choice. See `/socket-setup` for CI configuration. + +## Error Handling + +- **No Socket tools after installing the plugin:** restart the agent or reload plugins so the bundled MCP server loads, then check `/mcp`. +- **Browser does not open:** copy the URL the agent prints into a browser. Over SSH, use the `--no-browser` option and open the URL locally. +- **`organizations` returns an empty list:** the account has no organization yet. Create one at , then call `organizations` again. +- **401 after it worked before:** the session expired or was revoked. Sign in again from Step 2. +- **Wrong account:** clear the server's authentication in `/mcp` (or `claude mcp logout `), then sign in again. + +## Tips + +- Never ask the user to paste an API token into the chat. Browser sign-in keeps the credential out of the conversation. +- Do not print credential values to confirm a connection. Call `organizations` instead. +- Use every organization the sign-in reaches unless the user selects fewer. To reach an organization the sign-in does not cover, sign in again instead of asking for a token. +- The MCP server and the Socket CLI sign in separately. Being connected over MCP does not make `pnpm dlx socket scan create` work. +- If the user has no account and does not want one, leave Socket unconnected. Public package lookups such as `depscore` may still work. diff --git a/skills/socket-fix/SKILL.md b/skills/socket-fix/SKILL.md index 07f5fddd..a0cefa77 100644 --- a/skills/socket-fix/SKILL.md +++ b/skills/socket-fix/SKILL.md @@ -66,8 +66,8 @@ Commands that require authentication need a Socket account and a credential that Authenticate with one of these methods: -- **Interactive login**: `pnpm dlx socket login` (stores credentials in `~/.socket/`) -- **Environment variable**: Set `SOCKET_CLI_API_TOKEN` in your shell profile or CI environment +- **Interactive login**: the user runs `pnpm dlx socket login` in their own terminal (it needs an interactive TTY, so the agent cannot run it). CLI releases with browser login show a device code to approve in the browser; older releases, including the current npm release, prompt for an API token. The `/socket-connect` skill covers signing in and choosing organizations. +- **Environment variable (CI)**: Set `SOCKET_CLI_API_TOKEN` to an organization API token in CI or other non-interactive environments Verify account authentication: diff --git a/skills/socket-fix/socket-dep-upgrade/SKILL.md b/skills/socket-fix/socket-dep-upgrade/SKILL.md index 72867483..e7824e2b 100644 --- a/skills/socket-fix/socket-dep-upgrade/SKILL.md +++ b/skills/socket-fix/socket-dep-upgrade/SKILL.md @@ -39,8 +39,8 @@ Commands that require authentication need a Socket account and a credential that Authenticate with one of these methods: -- **Interactive login**: `pnpm dlx socket login` (stores credentials in `~/.socket/`) -- **Environment variable**: Set `SOCKET_CLI_API_TOKEN` in your shell profile or CI environment +- **Interactive login**: the user runs `pnpm dlx socket login` in their own terminal (it needs an interactive TTY, so the agent cannot run it). CLI releases with browser login show a device code to approve in the browser; older releases, including the current npm release, prompt for an API token. The `/socket-connect` skill covers signing in and choosing organizations. +- **Environment variable (CI)**: Set `SOCKET_CLI_API_TOKEN` to an organization API token in CI or other non-interactive environments Verify account authentication: @@ -212,7 +212,7 @@ To manage context window limits without subagents: - **`socket fix` returns no results**: The project may have no fixable vulnerabilities, or the Socket API may not cover the project's ecosystems. Check that manifest and lock files exist in the repository. - **`pnpm dlx socket fix --id` fails with "GHSA not found"**: The advisory ID may be incorrect or not yet indexed. Try searching by CVE ID or PURL instead. - **`socket fix` modifies files but tests fail**: The subagent (or main agent in fallback mode) should revert the changes with `git checkout -- .` and try an alternative version. Never leave the project in a broken state. -- **Authentication required**: Run `pnpm dlx socket login` or set `SOCKET_CLI_API_TOKEN`. If the user has no account credential, ask them to log in or create an account. Leave authentication unconfigured if they decline. +- **Authentication required**: Ask the user to run `pnpm dlx socket login` in their own terminal (see `/socket-connect`), or set `SOCKET_CLI_API_TOKEN` in CI. If the user has no account credential, ask them to log in or create an account. Leave authentication unconfigured if they decline. - **Network errors during fix**: `socket fix` contacts the Socket API to compute upgrade paths. Check network connectivity and try again. ## How This Differs from `/socket-dep-patch` diff --git a/skills/socket-inspect/SKILL.md b/skills/socket-inspect/SKILL.md index 805c3e32..a34f40ab 100644 --- a/skills/socket-inspect/SKILL.md +++ b/skills/socket-inspect/SKILL.md @@ -41,8 +41,8 @@ Commands that require authentication need a Socket account and a credential that Authenticate with one of these methods: -- **Interactive login**: `pnpm dlx socket login` (stores credentials in `~/.socket/`) -- **Environment variable**: Set `SOCKET_CLI_API_TOKEN` in your shell profile or CI environment +- **Interactive login**: the user runs `pnpm dlx socket login` in their own terminal (it needs an interactive TTY, so the agent cannot run it). CLI releases with browser login show a device code to approve in the browser; older releases, including the current npm release, prompt for an API token. The `/socket-connect` skill covers signing in and choosing organizations. +- **Environment variable (CI)**: Set `SOCKET_CLI_API_TOKEN` to an organization API token in CI or other non-interactive environments Verify account authentication: @@ -57,6 +57,8 @@ If authentication fails or the CLI is not installed, use the `/socket-setup` ski +**Prefer the Socket MCP tools when connected:** if a Socket MCP `depscore` tool is available (installed by `/socket-connect`, signed in through the browser), use it for package scores instead of the Batch PURL API. It needs no API key. Use the `organizations` tool to find the `org_slug` for org-scoped tools such as `alerts`. + **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 @@ -89,7 +91,7 @@ curl -X POST https://api.socket.dev/v0/orgs/{org_slug}/purl \ -d '{"purls": ["pkg:npm/lodash@4.17.21"]}' ``` -If `SOCKET_SECURITY_API_KEY` is not set, authentication is required before proceeding. Run `pnpm dlx socket login` or set the `SOCKET_SECURITY_API_KEY` environment variable. Use the `/socket-setup` skill for guidance. +If `SOCKET_SECURITY_API_KEY` is not set, use the Socket MCP tools from `/socket-connect` (browser sign-in, no key) or the CLI fallback in Step 1b. Do not ask the user to paste a key into the chat. Extract **all** returned data: diff --git a/skills/socket-scan/SKILL.md b/skills/socket-scan/SKILL.md index 2108fc9c..797f4dd4 100644 --- a/skills/socket-scan/SKILL.md +++ b/skills/socket-scan/SKILL.md @@ -55,8 +55,8 @@ Commands that require authentication need a Socket account and a credential that Authenticate with one of these methods: -- **Interactive login**: `pnpm dlx socket login` (stores credentials in `~/.socket/`) -- **Environment variable**: Set `SOCKET_CLI_API_TOKEN` in your shell profile or CI environment +- **Interactive login**: the user runs `pnpm dlx socket login` in their own terminal (it needs an interactive TTY, so the agent cannot run it). CLI releases with browser login show a device code to approve in the browser; older releases, including the current npm release, prompt for an API token. The `/socket-connect` skill covers signing in and choosing organizations. +- **Environment variable (CI)**: Set `SOCKET_CLI_API_TOKEN` to an organization API token in CI or other non-interactive environments Verify account authentication: diff --git a/skills/socket-scan/socket-scan-setup/SKILL.md b/skills/socket-scan/socket-scan-setup/SKILL.md index 4712a19c..bfb5c53d 100644 --- a/skills/socket-scan/socket-scan-setup/SKILL.md +++ b/skills/socket-scan/socket-scan-setup/SKILL.md @@ -1,9 +1,9 @@ --- name: socket-scan-setup description: - Set up prerequisites for Socket scanning - install the CLI, configure - user-owned authentication, and verify scan access. Use this before the first scan - or when encountering auth errors. + Set up prerequisites for Socket scanning - install the CLI, sign in with your + own Socket account, and verify scan access. Use this before the first scan or + when encountering auth errors. --- # Scan Setup @@ -43,7 +43,7 @@ pnpm dlx socket --version If the user has no account credential, ask whether they want to create an account or log in. If they decline, leave authentication unconfigured. Do not write an API token or default organization. -**For users with an existing account:** Set the `SOCKET_CLI_API_TOKEN` environment variable or run `pnpm dlx socket login`. +**For users with an existing account:** Ask the user to run `pnpm dlx socket login` in their own terminal; it needs an interactive TTY. CLI releases with browser login show a device code to approve in the browser, so no token is pasted. The `/socket-connect` skill covers signing in and picking an organization. In CI, set `SOCKET_CLI_API_TOKEN` instead. ### Step 4: Verify Setup diff --git a/skills/socket-setup/SKILL.md b/skills/socket-setup/SKILL.md index 9aed01dc..0d819534 100644 --- a/skills/socket-setup/SKILL.md +++ b/skills/socket-setup/SKILL.md @@ -1,8 +1,8 @@ --- name: socket-setup -description: Set up Socket - prompt for API key, install the CLI, authenticate, - configure policies and tokens, set up CI/CD for firewall or patch modes across - GitHub, GitLab, Bitbucket, and other systems. +description: Set up Socket - connect your account through browser sign-in, + install the CLI, configure policies and CI tokens, and set up CI/CD for + firewall or patch modes across GitHub, GitLab, Bitbucket, and other systems. --- # Setup @@ -56,8 +56,7 @@ Ask the user whether they have or want to create a Socket account. There are thr - **No account**: Finish installing the CLI and leave authentication unconfigured. Commands that require authentication remain unavailable. - **Free account**: Create one at to use account features supported by your plan. - - Sign up / sign in: - - Token page: + - Sign up / sign in: , or sign in from the agent with `/socket-connect` - **Enterprise account**: All free account features plus reachability analysis (`socket scan reach`), policy configuration (`socket.yml`), and organization-level management. Store the account tier for subsequent steps. If the user has no account, do not configure a credential or default organization. @@ -83,8 +82,11 @@ If the user does not want an account, leave authentication unconfigured and cont ### Free or Enterprise account -- Interactive: `socket login` -- Manual token: `SOCKET_CLI_API_TOKEN` env var +Sign in through the browser. Do not ask the user to copy an API token out of the dashboard for local use. + +- **Agent (MCP):** run the `/socket-connect` skill. It signs in to the hosted Socket MCP server with OAuth and lists every organization the user belongs to. If the user belongs to several, use all of them unless the user selects specific ones. +- **CLI:** the user runs `socket login` in their own terminal (it needs an interactive TTY). CLI releases with browser login show a device code to approve in the browser. Older releases prompt for an API token instead; in that case, ask before having the user create one. +- **CI and other non-interactive environments:** an organization API token in `SOCKET_CLI_API_TOKEN` (see API Token Configuration below) - Verify: `socket organization list` - **Authentication is required for full-rate scanning (`socket scan create`) and `socket fix`**, dashboard access, and organization management @@ -511,7 +513,7 @@ Repository-level settings override organization-level settings, which override d ## API Token Configuration -Different Socket features use different tokens. Set up the appropriate tokens for your use case. +Different Socket features use different tokens. For local use, prefer browser sign-in (`/socket-connect` and `socket login`) over API tokens. Use API tokens for CI and other environments that cannot open a browser. ### Token Types @@ -543,7 +545,7 @@ Different Socket features use different tokens. Set up the appropriate tokens fo For local development, authenticate using one of: -- **Interactive login**: `socket login` (stores credentials in `~/.socket/`) +- **Browser sign-in (recommended)**: `/socket-connect` for the agent's Socket MCP tools, and `socket login` for the CLI. The MCP sign-in never needs a pasted token; `socket login` needs one only on CLI releases without browser login, including the current npm release. - **Environment variable**: Set `SOCKET_CLI_API_TOKEN` in your shell profile or `.env.local` - **Per-project**: Add `SOCKET_SECURITY_API_KEY` to `.env.local` (ensure `.env.local` is in `.gitignore`) @@ -552,7 +554,7 @@ For local development, authenticate using one of: ## Error Handling - **`socket: command not found`**: Ensure Node.js 18+ is installed, then run `npm install -g socket`. Check that the npm global bin directory is in `PATH` - `npm prefix -g` prints the global prefix, and the bin directory is `/bin` on macOS and Linux, or the prefix itself on Windows. -- **`socket login` fails**: Check network connectivity. If behind a proxy, ensure `HTTPS_PROXY` is set. Try setting `SOCKET_CLI_API_TOKEN` directly as an environment variable instead. +- **`socket login` fails**: Check network connectivity. If behind a proxy, ensure `HTTPS_PROXY` is set. `socket login` needs an interactive terminal: have the user run it in their own shell rather than through the agent. Use `/socket-connect` for MCP tools. Offer a manually created `SOCKET_CLI_API_TOKEN` only if the user agrees. - **`socket organization list` returns empty**: The API token may lack organization access. Verify the token at and ensure it has the correct scopes. - **`sfw` not intercepting installs**: Ensure `sfw` is in `PATH` before the package manager. In CI, verify the install step runs before any dependency install commands. - **GitHub Action fails with permission errors**: Ensure the `socket-token` secret is set correctly in the repository settings and the workflow has `contents: read` permission. @@ -561,7 +563,8 @@ For local development, authenticate using one of: ## Tips -- Never commit API tokens. Use `socket login` locally, env vars in CI. +- Never commit API tokens. Use browser sign-in (`/socket-connect`, `socket login`) locally, env vars in CI. +- Never ask the user to paste a token into the chat. - If the user has no account, leave authentication unconfigured. Do not assign a default organization or shared credential. - Account features require a user-owned account credential. Follow the feature instructions to verify access. diff --git a/test/repo/unit/generate-cursor-plugin.test.mts b/test/repo/unit/generate-cursor-plugin.test.mts index 470d51b4..2d2a5e3f 100644 --- a/test/repo/unit/generate-cursor-plugin.test.mts +++ b/test/repo/unit/generate-cursor-plugin.test.mts @@ -66,14 +66,14 @@ it('generate leaves a populated root .mcp.json byte-identical', () => { } }) -it('generate writes the empty plugin mcp config under .cursor-plugin/', () => { +it('generate writes the hosted Socket MCP server config under .cursor-plugin/', () => { const root = makeFixtureRoot() try { const result = generateCursorPlugin(root, { check: false }) expect(result.mcpPath).toBe(path.join(root, '.cursor-plugin', 'mcp.json')) expect(JSON.parse(readFileSync(result.mcpPath, 'utf-8'))).toStrictEqual({ - mcpServers: {}, + mcpServers: { socket: { url: 'https://mcp.socket.dev/' } }, }) } finally { safeDeleteSync(root) diff --git a/test/repo/unit/structural/paths-manifest-consistency.test.mts b/test/repo/unit/structural/paths-manifest-consistency.test.mts index af1daa4d..7e93c9c4 100644 --- a/test/repo/unit/structural/paths-manifest-consistency.test.mts +++ b/test/repo/unit/structural/paths-manifest-consistency.test.mts @@ -52,6 +52,27 @@ describe('Manifest Consistency', () => { 'utf-8', ) + describe('hosted Socket MCP server', () => { + it('every shipped manifest points at the same server URL', async () => { + const { SOCKET_MCP_URL } = + await import('../../../../scripts/repo/generate-cursor-plugin.mts') + /* eslint-disable typescript/no-unsafe-type-assertion -- shape checked by the expectations below */ + const connect = marketplace.plugins.find( + plugin => plugin.name === 'socket-connect', + ) as unknown as { mcpServers?: Record } + const gemini = geminiJson as unknown as { + mcpServers?: Record + } + const cursor = loadJSON('.cursor-plugin/mcp.json') as { + mcpServers: Record + } + /* eslint-enable typescript/no-unsafe-type-assertion */ + expect(connect?.mcpServers?.['socket']?.url).toBe(SOCKET_MCP_URL) + expect(gemini.mcpServers?.['socket']?.httpUrl).toBe(SOCKET_MCP_URL) + expect(cursor.mcpServers['socket']?.url).toBe(SOCKET_MCP_URL) + }) + }) + describe('marketplace.json', () => { it('every plugin source path resolves to a real SKILL.md', () => { const plugins = marketplace.plugins diff --git a/test/repo/unit/structural/paths-skill-discovery.test.mts b/test/repo/unit/structural/paths-skill-discovery.test.mts index 9b91540f..7de7a52e 100644 --- a/test/repo/unit/structural/paths-skill-discovery.test.mts +++ b/test/repo/unit/structural/paths-skill-discovery.test.mts @@ -9,6 +9,7 @@ export const SKILLS_DIR = path.join(REPO_ROOT, 'skills') * Top-level skill directories expected under skills/ */ const EXPECTED_TOP_LEVEL = [ + 'socket-connect', 'socket-fix', 'socket-inspect', 'socket-release',