Apply security fixes to the dependency versions your project already uses, without waiting for an upstream release or upgrading the dependency. Socket Patch updates dependency files to use patched packages, which you install with your normal package manager.
Upgrading from v4? Read the v5 migration guide.
Install a standalone binary on macOS or Linux:
curl -fsSL https://install.socket.dev/patch | shThe installer verifies release checksums and installs in /usr/local/bin or
~/.local/bin. See the installer options for a custom
directory or version, and mirror setup.
On Windows, extract a socket-patch-*-pc-windows-msvc.zip archive from
GitHub Releases into a directory
on your PATH, or install through npm:
npm install -g @socketsecurity/socket-patch
Cargo users can run cargo install socket-patch-cli. The standalone binary
requires neither Node.js nor Rust. All installation methods support the same
ecosystems; see the support matrix for platform details.
For standalone installs, run socket-patch --update to update. For npm or Cargo
installs, use that package manager's update command.
From the root of a project with a supported lockfile, including a fresh checkout before dependencies are installed:
socket-patch scan --dry-run # preview available patches and edits socket-patch scan # update dependency files; never prompts
Review and commit the dependency and configuration files the scan reports. Then install the patched packages and generate OpenVEX for your vulnerability scanner:
npm ci # use your project's normal install command
socket-patch vex --output socket.vex.json
socket-patch listFollow any reinstall warning from the CLI: some package managers reuse cached upstream packages. Agent mode needs installed packages; sbt and scala-cli need resolution records first. See the ecosystem notes.
Free patches need no token. For organization patches, set SOCKET_API_TOKEN or
use the separate Socket CLI's socket login. See configuration.
A scan with no available patches does not mean the project has no vulnerabilities.
| Mode | Command | What to commit | What installs need |
|---|---|---|---|
| Hosted (default for a new project) | socket-patch scan |
Changed lockfiles, manifests, and registry configuration | Access to Socket's patch server |
| Vendored | socket-patch scan --mode vendored |
Changed dependency files and .socket/vendor/ (artifacts and ledger) |
The committed patched packages |
| Agent | socket-patch scan --mode agent |
.socket/manifest.json and patch data; Go also uses a committed patched tree |
socket-patch apply after dependency installs |
Vendored mode stores patched dependencies, not the entire dependency graph.
Other dependencies still need their normal registry, mirror, or offline cache.
Hosted and vendored installs do not need an install hook or the Socket Patch CLI.
Once a project holds vendored or agent-mode patches, a bare scan or get keeps
that mode; pass --mode to switch.
Supported ecosystems include npm, PyPI, Cargo, Go, RubyGems, Maven, Composer, NuGet, and Deno. Check the support matrix for available modes and package-manager limitations.
socket-patch scan --package lodash # limit selection to a package socket-patch scan --max-new-patches 5 # introduce at most five new patches socket-patch scan 'apps/*' # scan projects in a monorepo socket-patch get pkg:npm/[email protected] # target one package version socket-patch vendor # eject an existing hosted patch set socket-patch repair # restore agent or vendored patch artifacts socket-patch rollback lodash # restore one package to upstream socket-patch rollback # restore upstream dependencies
get also accepts a CVE, GHSA, patch UUID, or exact package name. Hosted rollback
generally needs network access; some formats require restoring files from version
control. See usage and recovery.
Use socket-patch <command> --help for options and
socket.yml for a shared rollout policy.
Socket Patch sends usage telemetry by default: each command reports its outcome
to Socket as a small JSON event. An event holds the event name (for example
patch_applied or patch_scan_failed), the subcommand, the CLI version, the
operating system and CPU architecture, a timestamp, a random ID generated for
that one run, and a few counters and flags for the command (such as patches
applied, packages scanned, ecosystems found, the patch mode, dry_run). get
adds the patch UUID. A failure adds the error message, with URL credentials
redacted and your home directory replaced by ~. Apart from what an error
message quotes, events hold no package names, file paths, file contents, or
dependency lists.
Events go to api.socket.dev with your API token when a token and organization
are configured, otherwise anonymously to patches-api.socket.dev. They are sent
in the background: a command never waits for telemetry before it prints, a
failed send changes nothing, and an unreachable endpoint adds at most 300 ms to
the exit.
To turn telemetry off, pass --no-telemetry or set SOCKET_TELEMETRY_DISABLED=1
or DO_NOT_TRACK=1. --offline / SOCKET_OFFLINE=1 sends nothing either. See
configuration for every event, field, and switch.
- Usage: targeting, CI, vendoring, agent mode, VEX, and recovery.
- Configuration: authentication, environment, telemetry, and rollout policy.
- Ecosystem support: package-manager formats and limitations.
- Migrating to v5: changed defaults and retired install hooks.
- CLI contract: flags, JSON, diagnostics, and exit codes.
- Development: code map, builds, and test entry points.
- Release runbook and changelog.