Terminal
Terminal/Skill
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.
By Socket
Works with
npx skills add socketdev/sauce --skill socket-setupsocket.yml)Ask each tool for its version. A command not found error means the tool is not installed:
node --version
socket --version
sfw --version
socket-patch --version
Detect the package manager from the lock file in the project root - the command prints only the files that exist:
ls -d package-lock.json pnpm-lock.yaml yarn.lock bun.lock bun.lockb 2>/dev/null || true
package-lock.json means npm, pnpm-lock.yaml means pnpm, yarn.lock means yarn, and bun.lock or bun.lockb means bun. With no lock file, ask the user which package manager the project uses.
Handle results:
node --version fails: prompt the user to install Node.js. Suggest:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash then nvm install 20brew install nodenode --version reports below v18: warn that Node.js 18+ is required and suggest upgradingsocket --version reports below 1.0.0: warn that the Socket CLI is below 1.x and prompt to update with npm install -g socket@latestsocket --version fails: proceed to Step 3 (Install the CLI)Ask the user whether they have or want to create a Socket account. There are three tiers:
socket fix, socket scan, sfw, and socket-patch apply. Rate limits and feature restrictions apply compared to a full account, but basic vulnerability scanning and fixing work out of the box. Dashboard access, organization management, and policy configuration are NOT available without an account.socket scan reach), policy configuration (socket.yml), and organization-level management.Store the tier choice for subsequent steps.
Prerequisites: Node.js 18+ (verified in Step 1)
npm install -g socket
After install, confirm the version is >= 1.x:
socket --version
If the version is still below 1.x after install, error and suggest npm install -g socket@latest
PATH troubleshooting: if socket is not found, check that the npm global bin directory is in PATH. Print the global install prefix with npm prefix -g; the bin directory is <prefix>/bin on macOS and Linux, and the prefix itself on Windows
If the user chose no-account in Step 2, 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 configures the CLI with a limited public token that provides access to features like socket fix, socket package score, sfw, and socket-patch with rate limits. No user interaction is needed - run this in the background as part of setup. Note: The demo token cannot create scans (socket scan create requires a free account).
Verify it worked:
socket --version
The CLI is now functional. Skip socket organization list (no org exists for public-token users). Inform the user that they can create a free account at https://socket.dev later to remove rate limits, enable scanning, and access the dashboard.
socket loginSOCKET_CLI_API_TOKEN env varsocket organization listsocket scan create) and socket fix, dashboard access, and organization managementAsk the user which features to set up. Annotate each with its tier requirement:
sfw) - works with public tokensocket-patch apply) - works with public tokensocket scan create) - works with public token (rate-limited); full account removes limitssocket fix) - works with public token (rate-limited); full account removes limitssocket.yml) - enterprise onlyAll core CLI features work with the public token set up in Step 4. If the user hits rate limits or needs dashboard access, suggest creating a free account at https://socket.dev.
Route to the appropriate section(s) below.
Ask the user if they want to install Socket tools globally (for local development) or just for CI.
If global, install all tools via npm:
npm install -g socket
npm install -g sfw
npm install -g @socketsecurity/socket-patch
After installing, verify each tool is available:
socket --version
sfw --version
socket-patch --version
Confirm all three print a version rather than command not found.
If any tool fails to install, check PATH and retry. npm prefix -g prints the global install prefix; the bin directory is <prefix>/bin on macOS and Linux, and the prefix itself on Windows.
List the CI config files that exist in the project root - the command prints only the ones that are present:
ls -d .github/workflows .gitlab-ci.yml bitbucket-pipelines.yml Jenkinsfile .circleci/config.yml .travis.yml azure-pipelines.yml 2>/dev/null || true
Then identify the SCM and map the results:
git remote -v to detect the SCM:
| Package Manager | Install sfw |
|---|---|
| npm | npm install -g sfw |
| pnpm | pnpm add -g sfw |
| bun | bun add -g sfw |
| Standalone | curl -fsSL https://socket.dev/download/sfw/latest/{platform} -o /usr/local/bin/sfw && chmod +x /usr/local/bin/sfw |
Replace {platform} with linux-x64, darwin-arm64, etc. as appropriate.
All Socket tools (sfw, socket-patch, socket CLI) are npm packages. The standalone curl method remains available for CI environments that may not have npm.
Add a before_script or dedicated stage to install sfw
Install via npm: npm install -g sfw
Or install standalone binary:
curl -fsSL https://socket.dev/download/sfw/latest/linux-x64 -o /usr/local/bin/sfw && chmod +x /usr/local/bin/sfw
Prefix install commands with sfw (sfw npm install, sfw pip install, etc.)
Enterprise: set SOCKET_CLI_API_TOKEN as CI/CD variable in GitLab settings
Add pipe step to install sfw binary:
curl -fsSL https://socket.dev/download/sfw/latest/linux-x64 -o /usr/local/bin/sfw && chmod +x /usr/local/bin/sfw
Prefix install commands with sfw
Enterprise: set SOCKET_CLI_API_TOKEN as repository variable
Download sfw binary:
# Linux x64
curl -fsSL https://socket.dev/download/sfw/latest/linux-x64 -o /usr/local/bin/sfw && chmod +x /usr/local/bin/sfw
# macOS arm64
curl -fsSL https://socket.dev/download/sfw/latest/darwin-arm64 -o /usr/local/bin/sfw && chmod +x /usr/local/bin/sfw
Or install via npm: npm install -g sfw
Prefix install commands with sfw
Set SOCKET_CLI_API_TOKEN as env var for enterprise
npm install -g sfw (or standalone binary as above)sfw npm install, sfw pip install, etc.Set up automated patching so socket-patch apply runs after every dependency install. For one-time manual patching, use the /socket-dep-patch skill instead.
Identify the project's CI/CD system - the command prints only the config files that are present:
ls -d .github/workflows .gitlab-ci.yml bitbucket-pipelines.yml Jenkinsfile .circleci/config.yml .travis.yml azure-pipelines.yml 2>/dev/null || true
Before configuring automation, scan the project to find ALL places where dependencies are installed and builds happen:
| Location | What to Look For |
|---|---|
package.json scripts | install, postinstall, build, prebuild |
| CI configs (all formats) | install steps, build steps |
Makefile / Justfile | install and build targets |
Dockerfile / docker-compose | RUN install, RUN build layers |
Shell scripts (*.sh) | install/build commands |
pyproject.toml / setup.py | build system config |
Cargo.toml | build scripts |
For each location, record the file path, the install command, and where to insert socket-patch scan and socket-patch apply (after install, before build).
Present findings to the user before making changes.
Use the appropriate command to run socket-patch based on the project's package manager:
| Package Manager | Run socket-patch |
|---|---|
| npm | npx @socketsecurity/socket-patch scan then npx @socketsecurity/socket-patch apply |
| pnpm | pnpm dlx @socketsecurity/socket-patch scan then pnpm dlx @socketsecurity/socket-patch apply |
| yarn | npx @socketsecurity/socket-patch scan then npx @socketsecurity/socket-patch apply |
| bun | bunx @socketsecurity/socket-patch scan then bunx @socketsecurity/socket-patch apply |
| deno | deno run npm:@socketsecurity/socket-patch scan then deno run npm:@socketsecurity/socket-patch apply |
| Python | pipx run socket-patch scan && pipx run socket-patch apply (if pipx available), else pip install socket-patch && socket-patch scan && socket-patch apply |
| Standalone | curl -fsSL https://raw.githubusercontent.com/SocketDev/socket-patch/main/install.sh | sh then socket-patch scan && socket-patch apply |
| GitHub Actions | SocketDev/action@v1 with mode: patch (preferred - handles scan+apply automatically) |
Use the runner that matches the detected package manager in the sections below: npx for npm and yarn, pnpm dlx for pnpm, bunx for bun.
Use SocketDev/action@v1 with mode: patch:
- uses: SocketDev/action@v1
with:
mode: patch
# patch-ecosystems: npm,pypi (optional: limit to specific ecosystems)
# patch-dry-run: false (optional: dry run mode)
Place after actions/checkout, before install steps. No socket-token is needed for patch mode.
Add a step to install socket-patch and apply patches after dependency install. Use the appropriate package manager runner (see reference table above):
before_script:
- curl -fsSL https://raw.githubusercontent.com/SocketDev/socket-patch/main/install.sh | sh
- npm install
- socket-patch scan
- socket-patch apply
Add a step to install socket-patch and apply patches. Use the appropriate package manager runner (see reference table above):
script:
- curl -fsSL https://raw.githubusercontent.com/SocketDev/socket-patch/main/install.sh | sh
- npm install
- socket-patch scan
- socket-patch apply
Generic pattern for any CI system:
socket-patch via curl, npm, or the appropriate package manager runner (see reference table above)socket-patch scan to discover available patchessocket-patch apply after scan, before buildRun socket-patch setup to add a postinstall hook to package.json:
socket-patch setup
This auto-adds a postinstall hook to your package.json scripts that runs socket-patch scan && socket-patch apply every time npm install runs.
Add a RUN socket-patch apply layer after the install layer. Use the appropriate runner for the project's package manager (e.g. pnpm dlx for pnpm, bunx for bun):
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
RUN pnpm dlx @socketsecurity/socket-patch scan
RUN pnpm dlx @socketsecurity/socket-patch apply
COPY . .
RUN npm run build
Add a patch target that runs after install. Adapt commands to match the project's package manager:
install:
npm ci
socket-patch scan
socket-patch apply
build: install
npm run build
If the project uses an unusual build system, use the appropriate package manager runner (see reference table above):
socket-patch scan && socket-patch apply after pip install / bundle installsocket-patch scan && socket-patch apply after dependency fetch, before compileRUN socket-patch scan and RUN socket-patch apply layers after the install layerDetect Dockerfiles and edit them directly to integrate Socket's firewall and/or patch tools.
Find every Dockerfile in the project:
find . -type f \( -name 'Dockerfile' -o -name 'Dockerfile.*' -o -name '*.Dockerfile' -o -name 'Containerfile' \) -not -path '*/node_modules/*' -not -path '*/.git/*'
Read each file that the command lists and record, per file:
RUN line that installs dependencies - npm ci, npm install, yarn install, pnpm install, bun install, pip install, bundle install, cargo build, go mod download - along with its line number and ecosystemsfwsocket-patchIf no Dockerfiles are found or none contain dependency install steps, skip this section.
For each Dockerfile that has install steps, read the file and apply edits directly.
Determine the mode based on what the user chose in Step 5 (Firewall, Patches, or both).
For each install line recorded in Step 1:
RUN npm install -g sfw on a new line before the install step. Prefix the install command with sfw (e.g., RUN npm ci → RUN sfw npm ci).RUN pnpm dlx @socketsecurity/socket-patch scan and RUN pnpm dlx @socketsecurity/socket-patch apply on new lines after the install step, before any build or COPY steps.Rules:
FROM lines to identify stage boundaries)sfw or socket-patch to ensure idempotencynpx for npm and yarn, pnpm dlx for pnpm, bunx for bun - see Package Manager Reference table)Before writing the modified Dockerfile, present the proposed changes to the user and explain each edit:
RUN npm install -g sfw before the install step, prefixes the install command with sfwRUN pnpm dlx @socketsecurity/socket-patch scan and RUN pnpm dlx @socketsecurity/socket-patch apply after the install step, before build/copy stepsOnly write the file after the user approves.
Example - a Dockerfile before and after (both modes):
Before:
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
After:
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install -g sfw
RUN sfw npm ci
RUN pnpm dlx @socketsecurity/socket-patch scan
RUN pnpm dlx @socketsecurity/socket-patch apply
COPY . .
RUN npm run build
Enterprise only - free tier users cannot configure policies. Skip this section if on the free tier.
Configure Socket policies to control which issues are flagged during scans and CI checks.
socket.yml)Create socket.yml in the repository root with version: 2 and these default issue rules, then adjust the values with the user:
version: 2
issueRules:
# CVE severity thresholds
criticalCVE: error # Block on critical CVEs
highCVE: warn # Warn on high CVEs
mediumCVE: ignore # Ignore medium CVEs
# Supply-chain alerts
installScripts: error # Block packages with install scripts
networkAccess: warn # Warn on unexpected network access
shellAccess: warn # Warn on shell execution
filesystemAccess: ignore # Ignore filesystem access alerts
envVarsAccess: warn # Warn on environment variable reads
obfuscatedCode: error # Block obfuscated code
# Malware
malware: error # Always block malware
# License compliance
gplLicense: warn # Warn on GPL licenses
noLicense: warn # Warn on packages with no license
nonPermissiveLicense: warn # Warn on restrictive licenses
projectIgnorePaths:
- 'test/**'
- 'tests/**'
- 'examples/**'
- 'docs/**'
- '__fixtures__/**'
Issue rule values:
error - fail the check / block the PRwarn - report but don't failignore - suppress entirelyFor enterprise customers, policies can also be managed via the Socket dashboard:
https://socket.dev/dashboard/org/{ORG}/settings/policieshttps://socket.dev/dashboard/org/{ORG}/repo/{REPO}/settings/policiesWhen multiple policies exist, they are applied in this order (highest priority first):
socket.yml in repo rootRepository-level settings override organization-level settings, which override defaults.
Different Socket features use different tokens. Set up the appropriate tokens for your use case.
| Token | Environment Variable | Used By | Required For |
|---|---|---|---|
| CLI API Token | SOCKET_CLI_API_TOKEN | Socket CLI (socket commands), CI/CD | Enterprise scans, socket fix, socket organization list |
| Security API Key | SOCKET_SECURITY_API_KEY | Batch PURL API (api.socket.dev) | Package inspection, license auditing |
| GitHub Action Token | socket-token (GitHub secret) | SocketDev/action@v1 | Enterprise firewall mode in GitHub Actions |
https://socket.dev/dashboard/org/{ORG}/settings/integrations/api-tokens| CI System | How to Set Secrets |
|---|---|
| GitHub Actions | Repository Settings → Secrets and variables → Actions → New repository secret |
| GitLab CI | Settings → CI/CD → Variables → Add variable (masked, protected) |
| Bitbucket Pipelines | Repository settings → Repository variables |
| CircleCI | Project Settings → Environment Variables |
| Jenkins | Credentials → Add Credentials → Secret text |
| Azure Pipelines | Pipelines → Library → Variable groups |
For local development, authenticate using one of:
socket login (stores credentials in ~/.socket/)SOCKET_CLI_API_TOKEN in your shell profile or .env.localSOCKET_SECURITY_API_KEY to .env.local (ensure .env.local is in .gitignore)Never commit API tokens to version control. Use socket login locally and environment variables / secrets in CI.
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 <prefix>/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 organization list returns empty: The API token may lack organization access. Verify the token at https://socket.dev/dashboard 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.socket-token secret is set correctly in the repository settings and the workflow has contents: read permission.npm install -g socket@latest to update. Verify with socket --version.find command from the Dockerfile Integration section to verify which files and lines need changes. Only edit stages with dependency install steps and skip lines that already contain sfw or socket-patch.socket login locally, env vars in CI.pnpm dlx socket config set apiToken sktsec_t_--RAN5U4ivauy4w37-6aoKyYPDt5ZbaT5JBVMqiwKo_api and pnpm dlx socket config set defaultOrg SocketDemo. This gives limited access to CLI features like socket fix, socket package score, sfw, and socket-patch with rate limits. The demo token cannot create scans - socket scan create requires a free account at https://socket.dev. Always configure the demo token for no-account users during setup so the CLI is functional immediately.SocketDev/action@v1 (correct casing) in GitHub workflow files.patch-cwd to target specific directories./socket-scan skill for a first audit and the /socket-inspect skill for package inspection.socket --version, sfw --version, and socket-patch --version at any time to verify tool installation status.find command from the Dockerfile Integration section to locate all Dockerfiles before manual editing.socket.yml uses version: 2 - ensure this line is preserved when editing policies.