Skip to content

README.md

Latest commit

 

History

History
159 lines (118 loc) · 6.26 KB

README.md

File metadata and controls

159 lines (118 loc) · 6.26 KB
Raw

socket-cli Socket CLI

Socket Badge Coverage

Follow @SocketSecurity Follow @socket.dev on Bluesky

CLI for Socket.dev - bring Socket's supply-chain security analysis to your terminal and CI.

Socket CLI is the command-line interface to Socket.dev, letting you scan dependencies, audit packages, and gate installs from your terminal or CI. This repository is the source for the published socket package on npm; end-user documentation lives on socket.dev and the socket npm page.

Install

npm install -g socket

Then run:

socket --help

Usage

# Scan a package
socket package npm/express@4.18.0

# Scan your project's dependencies
socket scan create

# Audit an install before it runs (npm, pnpm, or yarn)
socket npm install
socket pnpm install
socket yarn add <package>

socket npm, socket pnpm, and socket yarn each run the underlying package manager through Socket Firewall, which blocks known-malicious packages before they are installed. Install-time protection is no longer npm-only.

See the Socket docs for the full command reference.

MCP connections

For a local stdio connection, run socket login once, then configure your MCP client to launch socket with arguments ["mcp"]. Reuse saved authentication until it expires or the server rejects it.

For the hosted service, use your client's native remote connector with https://mcp.socket.dev/. In Claude Desktop, add it through Customize > Connectors.

Configure clients that require a stdio bridge

Clients that require a stdio bridge can use the verified mcp-remote@0.8.3 release. Install it with pnpm add --global mcp-remote@0.8.3, then configure:

{
  "mcpServers": {
    "socket": {
      "command": "mcp-remote",
      "args": ["https://mcp.socket.dev/"]
    }
  }
}

The bridge runs the OAuth callback listener on your computer. Version 0.1.49 can open authorization after connection without starting that listener. The upstream fix is included in 0.8.3. Update the bridge executable if authorization returns to an unavailable localhost callback. Reauthorization recovery was verified against the published bridge transport; a complete browser login remains a separate integration check.

Development

Contributor commands 
git clone https://github.com/SocketDev/socket-cli.git
cd socket-cli
pnpm install
pnpm run build
pnpm test

Requires Node.js (see .node-version) and pnpm (see the packageManager field in package.json).

Command Description
pnpm run build Smart build (skips unchanged)
pnpm run build --force Force rebuild everything
pnpm run build:cli Build CLI package only
pnpm run build:sea Build SEA binaries
pnpm dev Watch mode (auto-rebuild)
pnpm test Run all tests
pnpm testu Update test snapshots
pnpm run check Lint + typecheck
pnpm run fix Auto-fix lint + formatting

Run the built CLI from source:

node packages/cli/dist/index.js --help

Enable debug logging:

SOCKET_CLI_DEBUG=1 node packages/cli/dist/index.js <command>

Key development environment variables:

Variable Description
SOCKET_CLI_DEBUG Enable debug logging (1)
SOCKET_CLI_API_TOKEN Socket API token
SOCKET_CLI_ORG_SLUG Socket organization slug
SOCKET_CLI_API_BASE_URL Override API endpoint
SOCKET_CLI_NO_API_TOKEN Disable default API token
SOCKET_CLI_ALLOWED_PRIVATE_HOSTS Comma-separated hostnames allowed to be private (see below); unset by default

The API base URL and the npm registry URL both receive an Authorization header, so the CLI refuses either one when it points at a loopback, private, or link-local host - a repo-supplied SOCKET_CLI_CONFIG or .npmrc cannot aim the token at 169.254.169.254 or an internal service. An enterprise Socket instance or npm registry reached by a literal private address names that host in SOCKET_CLI_ALLOWED_PRIVATE_HOSTS:

SOCKET_CLI_ALLOWED_PRIVATE_HOSTS=10.0.0.5,registry.10.0.0.6.nip.io

It is an allowlist rather than an off switch, so allowing your own host does not allow every other private host.

Further contributor reading:

License

MIT