Documentation
  1. Socket CLI
  2. Socket CLI Commands

socket fix

Update dependencies with fixable Socket alerts

The socket fix command automatically upgrades vulnerable dependencies in your project to secure versions, using intelligent upgrade planning to minimize the risk of breaking changes.

socket fix --help

  Fix CVEs in dependencies

  Usage
    $ socket fix [options] [CWD=.]

  API Token Requirements
    - Quota: 101 units
    - Permissions: fixes:list, full-scans:create, and packages:list

  Options
    --all               Process all discovered vulnerabilities in local mode. Cannot be used with --id.
    --autopilot         Enable auto-merge for pull requests that Socket opens.
                        See GitHub documentation (https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository) for managing auto-merge for pull requests in your repository.
    --debug             Enable debug logging in the Coana-based Socket Fix CLI invocation.
    --disable-external-tool-checks  Disable external tool checks during fix analysis.
    --dynamic-sbom-inference  For Gradle, sbt, and Maven: generate a Socket facts SBOM (produced directly by each package manager) per independent build root, instead of one synthetic root. Fixes are then attributed to the projects/modules that actually resolve each vulnerable dependency. The generated files are removed afterwards.
    --ecosystems        Limit fix analysis to specific ecosystems. Accepts space- or comma-separated values and is case-insensitive. Defaults to all ecosystems.
    --exclude-paths     Skip matching paths from the scan entirely: manifests under these paths are not uploaded, and fixes are not applied to workspaces under them. Patterns are anchored micromatch globs matched relative to the target directory (CWD); `data/postgres/pgdata` matches that exact path, `**/pgdata` matches at any depth. Use this to skip directories the current user cannot read so they do not abort manifest collection. Negation patterns (`!path`) are not supported. Accepts a comma-separated value or multiple flags.
    --fix-version       Override the version of @coana-tech/cli used for fix analysis. Defaults to the bundled version.
    --id                Provide a list of vulnerability identifiers to compute fixes for:
                            - GHSA IDs (https://docs.github.com/en/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database#about-ghsa-ids) (e.g., GHSA-xxxx-xxxx-xxxx)
                            - CVE IDs (https://cve.mitre.org/cve/identifiers/) (e.g., CVE-2026-1234) - automatically converted to GHSA
                            - PURLs (https://github.com/package-url/purl-spec) (e.g., pkg:npm/[email protected]) - automatically converted to GHSA
                            Can be provided as comma separated values or as multiple flags. Cannot be used with --all.
    --include           Include workspaces matching these glob patterns. Can be provided as comma separated values or as multiple flags
    --json              Output as JSON
    --markdown          Output as Markdown
    --minimum-release-age  Set a minimum age requirement for suggested upgrade versions (e.g., 1h, 2d, 3w). A higher age requirement reduces the risk of upgrading to malicious versions. For example, setting the value to 1 week (1w) gives ecosystem maintainers one week to remove potentially malicious versions.
    --no-apply-fixes    Compute fixes only, do not apply them. Logs what upgrades would be applied. If combined with --output-file, the output file will contain the upgrades that would be applied.
    --no-major-updates  Do not suggest or apply fixes that require major version updates of direct or transitive dependencies
    --output-file       Path to store upgrades as a JSON file at this path.
    --package-managers  Limit fix analysis to specific package managers within an ecosystem (e.g. NPM, PNPM, YARN, MAVEN, POETRY). Accepts space- or comma-separated values and is case-insensitive. When combined with --ecosystems, an artifact must satisfy both filters.
    --pr-limit          Maximum number of pull requests to create in CI mode (default 10). Has no effect in local mode.
    --range-style       Define how dependency version ranges are updated in package.json (default 'preserve').
                        Available styles:
                          * pin - Use the exact version (e.g. 1.2.3)
                          * preserve - Retain the existing version range style as-is
    --show-affected-direct-dependencies  List the direct dependencies responsible for introducing transitive vulnerabilities and list the updates required to resolve the vulnerabilities
    --silence           Silence all output except the final result

  Environment Variables (for CI/PR mode)
    CI                          Set to enable CI mode
    SOCKET_CLI_GITHUB_TOKEN     GitHub token for PR creation (or GITHUB_TOKEN)
    SOCKET_CLI_GIT_USER_NAME    Git username for commits
    SOCKET_CLI_GIT_USER_EMAIL   Git email for commits

  Examples
    $ socket fix
    $ socket fix --id CVE-2021-23337
    $ socket fix ./path/to/project --range-style pin

Overview

Socket Fix gives developers a faster, safer way to clear vulnerabilities without endless manual upgrades. With Socket Fix, you can now:

  • Target specific vulnerabilities - Fix the CVEs that matter most to your team
  • Apply fixes locally - Test changes before committing
  • Support multiple ecosystems - Works with npm, pnpm, Yarn, Maven and many more
  • Use intelligent upgrade planning - Finds the least disruptive upgrade path

How Socket Fix Works

Socket Fix uses an advanced compute-and-apply fix engine to intelligently resolve vulnerabilities:

  1. Scans your dependencies - Identifies all vulnerable packages in your project
  2. Computes upgrade paths - Determines the minimal set of changes needed to fix vulnerabilities
  3. Applies updates - Modifies your manifest and lock files with the secure versions

Example Fix Scenario

Suppose your application depends on [email protected]:

  • This version has a dependency constraint of ^1.3.0 on estree-util-value-to-estree (link)
  • A vulnerability (GHSA-f7f6-9jq7-3rqj) affects all versions of estree-util-value-to-estree below 3.3.3
  • The patched [email protected] updates its constraint to ^3.3.3 (link)
  • Socket Fix automatically upgrades:
    • estree-util-value-to-estree to version 3.3.3 to fix the vulnerability
    • remark-reading-time to version 2.0.2 to ensure it's compatible with the new estree-util-value-to-estree version

When Socket Fix can't apply a fix

Socket Fix can leave a vulnerability unresolved for a few reasons:

  • No patched version exists yet. The maintainer of the vulnerable package has not published a fixed release. Reported as noFixAvailable.

  • No upgrade path through the dependency tree. A patched version of the vulnerable package exists, but no version of an upstream dependency is compatible with the patched version. For example, given a chain App → [email protected] → [email protected] where B < 2.0.0 is vulnerable: if no version of A accepts [email protected], there is no upgrade path that respects the existing dependency tree. Resolving this typically requires a manual override (e.g. pnpm overrides or npm overrides) to force A to accept the patched B. Overrides quickly bloat package.json and are difficult to remove later, so Socket Fix does not introduce them automatically. Reported as fixNotApplicable, or as a per-package entry in the unfixablePurls list of a partialFixFound result.

  • --no-major-updates is set and the only patched version is a major bump. Socket Fix will skip the fix rather than apply a major version change. Reported the same way as the no-upgrade-path case (as fixNotApplicable if no fix can be applied at all, or as an entry in unfixablePurls).

  • A yarn resolutions entry excludes the fixed version. Socket Fix doesn't rewrite resolutions. A resolution whose range still allows the fixed version is left alone and the fix goes ahead. One that excludes it stops the fix for that project, and the message names the version to put in resolutions. A resolution that doesn't point at a registry version, such as a patch:, portal:, file: or workspace: pin, also stops the fix, and the message asks you to update or remove it.

  • The package manager rejects the upgrade. For Python, NuGet, Cargo and RubyGems, Socket Fix updates each lock file with the project's own tool and reads the lock back to confirm the upgrade landed. When the tool refuses an upgrade, for example because the fixed version needs a newer Python than the project declares, the upgrade is reported with the tool's reason.

When a fix can't be applied, the CLI prints the affected package and a short reason explaining why. The same reason is surfaced in the dashboard alert details and in the fetch-fixes API response.

Usage

Target Specific Vulnerabilities

Fix only specific CVEs or GHSA advisories using the --id flag:

# Fix a specific GHSA
$ socket fix --id GHSA-hhq3-ff78-jv3g

# Fix multiple vulnerabilities
$ socket fix --id GHSA-xxxx-xxxx-xxxx,GHSA-yyyy-yyyy-yyyy

# Using multiple flags
$ socket fix --id GHSA-xxxx-xxxx-xxxx --id GHSA-yyyy-yyyy-yyyy

Fix all CVEs

Run socket fix --all in your project directory to automatically fix all fixable vulnerabilities:

$ socket fix --all

In local mode, running socket fix with neither --all nor --id also fixes everything, but that is deprecated and prints a warning. Pass --all explicitly.

Notice: Use this mode with care. Upgrading many dependencies simultaneously makes it difficult to uncover the culprit if something breaks.

Developer Workflow (Local Mode)

The developer-friendly workflow makes it easy to apply fixes locally:

  1. Run Socket Fix in your project directory
  2. Review the changes to your manifest and lock files
  3. Test your application to ensure everything still works
  4. Open a pull request with the changes

This workflow allows you to:

  • Apply fixes locally before committing
  • Test changes thoroughly
  • Maintain control over what gets merged
  • Document security updates in your commit history

Create and Merge PRs (Autopilot Mode)

Run socket fix --autopilot in a GitHub action to automatically create PRs with the fixes that merge automatically if all checks pass.

In CI mode, socket fix opens one pull request per vulnerability, on a branch named socket/fix/<GHSA ID>. It skips vulnerabilities that already have an open Socket Fix PR. --autopilot also turns on auto-merge for each new PR, so the repository must allow auto-merge. Each PR contains every file the fix wrote, including build files that aren't manifests, such as gradle.properties or sbt project/*.scala files, and new files the fix creates.

CI mode needs the CI environment variable (GitHub Actions sets it) and a GitHub token in SOCKET_CLI_GITHUB_TOKEN or GITHUB_TOKEN. SOCKET_CLI_GIT_USER_NAME and SOCKET_CLI_GIT_USER_EMAIL default to the github-actions[bot] identity. Without a GitHub token, socket fix falls back to local mode and applies the fixes to the working directory. The workflow also needs a Socket API token in SOCKET_CLI_API_TOKEN.

Below is an example of how to set up the autopilot fix to run twice a day for a pnpm project:

name: Socket Fix
on:
  schedule:
    - cron: '0 0 * * *'
    - cron: '0 12 * * *'
permissions:
  contents: write
  pull-requests: write
jobs:
  socket-fix:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8

      - name: Setup pnpm
        uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda
        with:
          version: '^10.16.0'

      - name: Setup Node.js with pnpm cache
        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
        with:
          node-version: "22"
          cache: 'pnpm'

      - name: Install dependencies
        shell: bash
        run: >
          pnpm dlx socket pnpm install --config '{"issueRules":{"malware":true}}'

      - name: Run Socket Fix CLI
        env:
          SOCKET_CLI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SOCKET_CLI_GIT_USER_EMAIL: socket-fix[bot]@users.noreply.github.com
          SOCKET_CLI_GIT_USER_NAME: socket-fix[bot]
          SOCKET_CLI_API_TOKEN: ${{ secrets.SOCKET_CLI_API_TOKEN }}
        run: pnpm dlx socket fix --autopilot

Options

--id

Target specific vulnerabilities by their identifiers:

  • GHSA IDs: GitHub Security Advisory Database identifiers
  • CVE IDs: converted to the matching GHSA ID
  • PURLs: converted to the GHSA IDs that affect that package version

IDs in any other format are skipped with a warning.

# Target a specific vulnerability
$ socket fix --id GHSA-f7f6-9jq7-3rqj

# Target a CVE
$ socket fix --id CVE-2021-23337

# Target every advisory that affects a package version
$ socket fix --id pkg:npm/[email protected]

--include / --exclude-paths

--include limits fixes to workspaces matching these glob patterns. --exclude-paths skips matching paths entirely: manifests under them are not uploaded, and fixes are not applied to workspaces under them. Patterns are matched relative to the target directory. Both flags can be provided as comma separated values or as multiple flags:

# Fix GHSA-f7f6-9jq7-3rqj in workspaces/utils
socket fix --id GHSA-f7f6-9jq7-3rqj --include "workspaces/utils"

# Fix GHSA-f7f6-9jq7-3rqj in all subprojects located in workspaces
socket fix --id GHSA-f7f6-9jq7-3rqj --include "workspaces/*"

# Fix GHSA-f7f6-9jq7-3rqj everywhere except workspaces/utils
socket fix --id GHSA-f7f6-9jq7-3rqj --exclude-paths "workspaces/utils"

Notice that socket fix may make changes to manifest files outside the included folders if necessary to fix the vulnerability. For example, if fixing a vulnerability in folder workspaces/utils requires making updates to the package-lock.json in the root project.

--pr-limit

Control the maximum number of PRs to open when running in a GitHub Actions workflow (default: 10). For example, if you set the limit to 10 and already have 6 open Socket Fix PRs, at most 4 new PRs will be opened. --pr-limit has no effect in local mode.

# Fix and open PRs for at most 5 vulnerabilities
$ socket fix --pr-limit 5

# Fix and open PRs for at most 10 vulnerabilities
$ socket fix

--range-style

Define how dependency version ranges are updated:

  • preserve (default): Retains existing version range style
  • pin: Uses exact versions (e.g., 1.2.3 instead of ^1.2.3)
# Keep existing range style
$ socket fix --range-style preserve

# Pin to exact versions
$ socket fix --range-style pin

--no-major-updates

Do not suggest or apply fixes that require changing the major version number in direct or transitive dependencies. This option reduces the probability that a fix breaks the application, but it also increases the probability that Socket is unable to find a valid fix for a CVE.

socket fix --no-major-updates

--minimum-release-age

Set a minimum age requirement for suggested upgrade versions (e.g., 1h, 2d, 3w). A higher age requirement reduces the risk of updating to malicious package versions. For example, setting the value to 1 week (1w) gives ecosystem maintainers one week to remove potentially malicious versions from the ecosystem registry.

# Only update to package versions that are at least 3 days old
socket fix --minimum-release-age 3d

# Only update to package versions that are at least 2 weeks old
socket fix --minimum-release-age 2w

Without the flag, socket fix follows the minimumReleaseAge your project sets for pnpm, reading it with pnpm config get so it finds the value wherever pnpm does. That way a fix never points at a version pnpm would refuse to install. The setting only holds back JavaScript upgrades (npm, pnpm or Yarn), not fixes in other ecosystems, and the packages you list in minimumReleaseAgeExclude are exempt. When several pnpm projects in the repository set different ages, the longest one wins. Their exclude lists are only used when they are identical, since pnpm's first-match rules can't be merged safely. pnpm's built-in default doesn't count, only a value you set yourself.

--minimum-release-age takes precedence over the pnpm setting, and --minimum-release-age 0m turns it off.

--dynamic-sbom-inference

For Gradle, sbt, and Maven projects, generate a Socket facts file (.socket.facts.json) for every independent build under the target directory before computing fixes. Each file comes from the build tool's own dependency resolution, and Socket Fix attributes JVM (Maven-type) dependencies only through these files. A fix then lands only in the projects and modules that actually resolve the vulnerable dependency.

socket fix --all --dynamic-sbom-inference

This runs your real Gradle, sbt, or Maven builds, so the build tool must be installed and able to resolve dependencies. The generated files are deleted when the fix finishes. In CI mode they are put back in the working tree after each pull request branch is reset, and they are never committed to the pull requests. socket fix stops if the project already contains a .socket.facts.json, so delete any leftover facts files first. See socket manifest for how the files are generated.

Output Formats

--json

Output results in JSON format for programmatic processing:

$ socket fix --json

--markdown

socket fix accepts --markdown, but it prints the same output as the default text mode. Use --json or --output-file for results you want to process.

Getting Suggested Fixes

--no-apply-fixes

Computes the dependency upgrades necessary to fix the CVE, but does not apply the upgrades to the project. The suggested upgrades are printed to the console.

socket fix --no-apply-fixes

--output-file

Specify the file path where upgrades should be stored. The file is written as JSON. It is only written in local mode.

socket fix --output-file suggested-fixes.json

--show-affected-direct-dependencies

Shows you which direct dependencies introduced CVEs in transitive or direct dependencies.

# Show affected direct dependencies
socket fix --show-affected-direct-dependencies --id GHSA-6chw-6frg-f759,GHSA-v6h2-p8h4-qcjw --output-file fixes.json

# Upgrade the direct dependency, acorn, to version 5.7.4 to fix vulnerability GHSA-6chw-6frg-f759.
# Upgrade transitive dependency, brace-expansion, to version 1.1.12 to fix GHSA-v6h2-p8h4-qcjw. No direct dependency upgrades are required.
cat fixes.json
{
  "type": "only-direct-dependency-upgrades",
  "fixes": {
    "GHSA-6chw-6frg-f759": {
      "directDependencies": [
        {
          "purl": "pkg:npm/[email protected]",
          "fixedVersion": "5.7.4"
        }
      ]
    },
    "GHSA-v6h2-p8h4-qcjw": {
      "directDependencies": [
        {
          "purl": "pkg:npm/[email protected]",
          "transitiveFixes": [
            {
              "purl": "pkg:npm/[email protected]",
              "fixedVersion": "1.1.12"
            }
          ]
        }
      ]
    }
  }
}

Supported Ecosystems

Socket Fix supports:

  • C# (NuGet, including MSBuild properties and imports, Central Package Management with Directory.Packages.props, packages.config, and packages.lock.json)

  • Golang (go.sum/go.mod)

  • Java and Kotlin (Maven and Gradle). For Gradle, Socket Fix upgrades build scripts in Groovy and Kotlin, version catalogs, gradle.properties, buildSrc and convention plugins, and regenerates lock state.

  • JavaScript/TypeScript (npm, pnpm v6 or newer, Yarn classic and berry, Rush)

  • Python (uv including workspaces, Poetry 1 and 2, Pipenv, pip-compile and uv pip compile outputs, and hand-written requirements files). PDM, pylock.toml, setup.py and Hatch projects are skipped with a notice.

  • Ruby (RubyGems)

  • Rust (Cargo, including workspaces)

  • Scala (sbt)

Socket Fix updates lock files with the project's own package manager, for example npm, pnpm, uv, Poetry, Pipenv, Gradle, dotnet, Cargo or Bundler, so that tool must be installed. A Python lock file whose tool isn't installed is skipped. Maven projects are fixed from the POM files alone, without running Maven.

For Maven, Gradle, sbt and NuGet, a transitive dependency is fixed with the build tool's own mechanism for forcing a version. That is a dependencyManagement entry in Maven, a constraints entry in Gradle, dependencyOverrides in sbt, and a PackageVersion or PackageReference in NuGet.

API Token Requirements

To use socket fix, your API token needs:

  • Quota: 101 units per execution
  • Permissions:
    • full-scans:create - to scan your dependencies
    • packages:list - to retrieve package information
    • fixes:list - to compute available fixes for detected vulnerabilities

Examples

Fix all vulnerabilities in current directory

$ socket fix --all

Fix vulnerabilities in a specific project

$ socket fix --all ./proj/tree

Target high-priority CVEs

$ socket fix --id GHSA-hhq3-ff78-jv3g

Generate a fix report

$ socket fix --all --no-apply-fixes --output-file security-fixes.json

Conservative approach with exact versions

$ socket fix --pr-limit 1 --range-style pin

--pr-limit only applies in CI mode. In local mode, use --id to limit which vulnerabilities get fixed.

Best Practices

  1. Test locally first - Run Socket Fix locally and test before pushing changes
  2. Use version control - Commit before running Socket Fix for easy rollback
  3. Review changes - Always review what Socket Fix changed in your dependencies
  4. Incremental updates - Use --pr-limit (CI mode) or --id for gradual updates in large projects

Notes

  • Socket Fix respects your project's .gitignore file and the projectIgnorePaths setting in socket.yml
  • Only dependencies with known safe fixes are updated
  • The command will not downgrade packages
  • In npm, pnpm and Yarn projects, each project is upgraded completely or not at all. If any step fails, the files the earlier steps wrote are put back.
  • In npm, pnpm and Yarn projects, Socket Fix updates package.json and the lockfile but not node_modules. Run npm install, pnpm install or yarn install afterwards.
  • The fix engine uses sophisticated upgrade planning to minimize breaking changes

Updated 3 days ago

Did this page help you?