socket scan

A Scan is the core artifact that Socket creates and this command has several sub-commands to work with them.

$ socket scan --help

  Manage Socket scans

  Usage
    $ socket scan <command>

  Commands
    create                      Create a new Socket scan and report
    del                         Delete a scan
    diff                        See what changed between two Scans
    list                        List the scans for an organization
    metadata                    Get a scan's metadata
    report                      Check whether a scan result passes the organizational policies (security, license)
    setup                       Start interactive configurator to customize default flag values for `socket scan` in this dir
    view                        View the raw results of a scan

  Options

    --no-banner                 Hide the Socket banner
    --no-spinner                Hide the console spinner

You can create, delete, view, diff Scans, its meta data, or a report of a Scan. You can see a list of scans in your org. You can also setup defaults for working with these sub-commands.

The socket scan github subcommand is not listed in socket scan --help. It has its own page.

socket scan create

This is probably the core command for this CLI. As the name suggests it creates a new scan. There are a few ways you can go about doing this:

$ socket scan create --help

  Create a new Socket scan and report

  Usage
    $ socket scan create [options] [TARGET...]

  API Token Requirements
    - Quota: 1 unit
    - Permissions: full-scans:create

  Options
    --auto-manifest     Run `socket manifest auto` before collecting manifest files, which generates them for ecosystems that need their build tool to resolve dependencies, such as Scala, Gradle, and Kotlin. See `socket manifest auto --help`. For Gradle, sbt, and Maven, --dynamic-sbom-inference generates a Socket facts SBOM per build root instead.
    --branch            Branch name
    --commit-hash       Commit hash
    --commit-message    Commit message
    --committers        Committers
    --cwd               working directory, defaults to process.cwd()
    --default-branch    Set the default branch of the repository to the branch of this full-scan. Should only need to be done once, for example for the "main" or "master" branch.
    --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. Combine with --reach to split the reachability analysis per project/module.
    --exclude-paths     List of glob patterns to exclude from the scan, including SCA/SBOM manifest discovery and (when --reach is enabled) full application reachability analysis. Patterns are anchored micromatch globs matched relative to the Socket scan root, which is the command working directory (`--cwd` if set), not the reachability target: `tests` matches only `<cwd>/tests`; use `**/tests` to match at any depth. Negation patterns (`!path`) are not supported. Accepts a comma-separated value or multiple flags.
    --interactive       Allow for interactive elements, asking for input. Use --no-interactive to prevent any input questions, defaulting them to cancel/no.
    --json              Output as JSON
    --markdown          Output as Markdown
    --org               Force override the organization slug, overrides the default org from config
    --pull-request      Pull request number
    --reach             Run full application reachability analysis
    --read-only         Similar to --dry-run except it can read from remote, stops before it would create an actual report
    --repo              Repository name
    --report            Wait for the scan creation to complete, then basically run `socket scan report` on it
    --report-level      Which policy level alerts should be reported (default 'error')
    --set-as-alerts-page  When true and if this is the "default branch" then this Scan will be the one reflected on your alerts page. See help for details. Defaults to true.
    --tmp               Set the visibility (true/false) of the scan in your dashboard.
    --uv-members        Scan each TARGET directory as a uv project, using the versions pinned in its uv.lock or its workspace root uv.lock. Uploads a CycloneDX dependency graph per TARGET in place of manifest discovery, including all extras and dependency groups. Requires uv on PATH.
    --workspace         The workspace in the Socket Organization that the repository is in to associate with the full scan.

  Reachability Options (when --reach is used)
    --reach-analysis-memory-limit  The maximum memory for the reachability analysis as a whole number optionally followed by MB or GB (e.g. 512MB, 8GB). The default is 8GB.
    --reach-analysis-timeout  Set the timeout for the reachability analysis as a whole number optionally followed by s, m or h (e.g. 90s, 10m, 1h). Defaults to 10m. Split analysis runs may cause the total scan time to exceed this timeout significantly.
    --reach-concurrency  Set the maximum number of concurrent reachability analysis runs. It is recommended to choose a concurrency level that ensures each analysis run has at least the --reach-analysis-memory-limit amount of memory available.
    --reach-continue-on-analysis-errors  Continue reachability analysis when errors occur (timeouts, OOM, parse errors, etc.), falling back to precomputed reachability results. By default, the CLI halts on analysis errors.
    --reach-continue-on-install-errors  Continue reachability analysis when package installation fails, falling back to precomputed reachability results. By default, the CLI halts on installation errors.
    --reach-continue-on-missing-lock-files  Continue reachability analysis when a Gradle or SBT project is missing its lock file (or version catalog / pre-generated SBOM). By default, the CLI halts.
    --reach-continue-on-no-source-files  Continue reachability analysis when a workspace contains no source files for its ecosystem. By default, the CLI halts.
    --reach-debug       Enable debug mode for reachability analysis. Provides verbose logging from the reachability CLI.
    --reach-detailed-analysis-log-file  A log file with detailed analysis logs is written to root of each analyzed workspace.
    --reach-disable-analytics  Disable reachability analytics sharing with Socket. Also disables caching-based optimizations.
    --reach-disable-external-tool-checks  Disable external tool checks during reachability analysis.
    --reach-ecosystems  List of ecosystems to conduct reachability analysis on, as either a comma separated value or as multiple flags. Supported: cargo, composer, gem, golang, maven, npm, nuget, pypi. Defaults to all supported ecosystems.
    --reach-enable-analysis-splitting  Allow the reachability analysis to partition CVEs into buckets that are processed in separate analysis runs. May improve accuracy, but not recommended by default.
    --reach-fallback-to-regular-scan  If reachability analysis fails, continue with a regular SCA scan (without reachability results) instead of halting. By default, the CLI halts on reachability errors.
    --reach-retain-facts-file  Keep the `.socket.facts.json` reachability report that the analysis writes to the scan directory instead of deleting it after a successful scan. IMPORTANT: you must delete this file before running a fresh full application reachability scan. A stale `.socket.facts.json` left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
    --reach-skip-cache  Skip caching-based optimizations. By default, the reachability analysis will use cached configurations from previous runs to speed up the analysis.
    --reach-use-only-pregenerated-sboms  When using this option, the scan is created based only on pre-generated CDX and SPDX files in your project.
    --reach-version     Override the version of @coana-tech/cli used for reachability analysis. Defaults to the bundled version.

  Uploads the specified dependency manifest files for Go, Gradle, JavaScript,
  Kotlin, Python, and Scala. Files like "package.json" and "requirements.txt".
  If any folder is specified, the ones found in there recursively are uploaded.

  Details on TARGET:

  - Defaults to the current dir (cwd) if none given
  - Multiple targets can be specified
  - If a target is a file, only that file is checked
  - If it is a dir, the dir is scanned for any supported manifest files
  - Dirs MUST be within the current dir (cwd), you can use --cwd to change it
  - Supports globbing such as "**/package.json", "**/requirements.txt", etc.
  - Ignores any file specified in your project's ".gitignore"
  - Also a sensible set of default ignores from the "ignore-by-default" module

  The --repo and --branch flags tell Socket to associate this Scan with that
  repo/branch. The names will show up on your dashboard on the Socket website.

  Note: for a first run you probably want to set --default-branch to indicate
        the default branch name, like "main" or "master".

  The "alerts page" (https://socket.dev/dashboard/org/YOURORG/alerts) will show
  the results from the last scan designated as the "pending head" on the branch
  configured on Socket to be the "default branch". When creating a scan the
  --set-as-alerts-page flag will default to true to update this. You can prevent
  this by using --no-set-as-alerts-page. This flag is ignored for any branch that
  is not designated as the "default branch". It is disabled when using --tmp.

  You can use `socket scan setup` to configure certain repo flag defaults.

  Examples
    $ socket scan create
    $ socket scan create ./proj --json
    $ socket scan create --repo=test-repo --branch=main ./package.json
    $ socket scan create --uv-members ./packages/api ./packages/worker

• Basic scan
  • socket scan create
  • It will search your target directory for all manifest files that we support (that's requirements.txt, package.json, pom.xml, etc.) and upload them to Socket. No real source code just meta data about which packages your project depends on.
  • The server will respond with a URL for this Scan that you can access while it works on processing the Scan. It may not be done yet when you visit it. When it's ready, this page will tell you the result.
• Report
  • socket scan create --report
  • This starts with a basic Scan.
  • The CLI then waits for the scan to finish processing.
  • Once completed it downloads the report and holds any alerts that may surface against the security and license policy set by your organization. When any alert violates any of these, the output will tell you with a "healthy" indicator.
  • Additionally, the exit code will reflect whether or not the Scan passed your org policies. The Scan fails when any alert has a policy action of error. --report-level only changes which alerts are listed in the output. It does not change the result.
  • The report step also needs the full-scans:list and security-policy:read token permissions, the same as socket scan report.
• With generated manifests
  • For certain languages we must generate concrete manifest files because the language itself does not have them. Two current examples are Scala's sbt and gradle (leveraged by Java, Kotlin, Scala).
  • These "manifests" are dynamic code that requires an unpredictable amount of files to collect as manifest files so instead we leverage the local build setup to generate the manifest files and scan those.
  • Pass --auto-manifest to run socket manifest auto as part of the scan.
  • For Gradle, sbt, and Maven you can pass --dynamic-sbom-inference to generate a Socket facts SBOM for every independent build root under the working directory. It works with or without --reach. It only covers those three build tools, so also pass --auto-manifest if you need manifests for other ecosystems.
  • See the socket manifest page for details.
• Selected members of a uv workspace
  • socket scan create --uv-members ./packages/api ./packages/worker
  • A uv workspace shares one uv.lock across all its members. Scanning that lockfile pulls in every member, and scanning a member's pyproject.toml on its own loses the pinned versions. --uv-members scans just the members you list, with the versions and dependency relationships from the shared lockfile.
  • Each TARGET is a directory with its own pyproject.toml. uv finds the uv.lock in that directory or in its workspace root, so one scan can cover members of several workspaces.
  • The scan includes each member's transitive and local workspace dependencies, all extras, and all dependency groups. Dependencies that only a dependency group uses are marked as development dependencies.
  • The CLI runs uv export --format cyclonedx1.5 --frozen --offline --no-python-downloads --all-extras twice for each target, once with --all-groups and once with --no-default-groups, so uv must be on your PATH with CycloneDX export support (uv still treats it as a preview feature). The export reads the existing lockfile and never resolves, installs or changes anything.
  • The CLI writes the result as socket-uv-cdx.json next to each member's pyproject.toml, uploads those files in place of the regular manifest discovery, and removes them when the scan ends, also on failure or Ctrl-C. It stops if a socket-uv-cdx.json is already there.
  • With --reach, pass a single target. The reachability analysis then runs on that member's directory.
  • --uv-members can't be combined with --auto-manifest or --dynamic-sbom-inference.
• With full application reachability analysis
  • socket scan create --reach
  • Requires an Enterprise plan (Enterprise trials qualify).
  • This starts with a basic Scan.
  • It then runs a static code analysis on your code and the code of your dependencies to determine the reachability of CVEs. You can filter on 'CVE Reachability' when you view the scan in the dashboard.
  • For Gradle, sbt, and Maven projects, add --dynamic-sbom-inference. Each build under the working directory generates its own Socket facts file as part of the scan, and reachability is analyzed and reported per subproject, working from the dependency graph your build tool resolves itself. This applies to the maven ecosystem only; npm, PyPI, Go and the rest are scanned and analyzed as usual. See Full Application Reachability.
  • During analysis it writes a .socket.facts.json reachability report to your project folder. By default this file is deleted once the scan completes successfully. Pass --reach-retain-facts-file to keep it for inspecting or debugging the reachability output.
  • If the reachability analysis fails, the command stops with an error and no scan is created. Pass --reach-fallback-to-regular-scan to create a regular scan without reachability results instead. The CLI prints a warning when this happens. Without --report, the --json output also includes a reachabilityFallback field.

⚠️

Warning: If you use --reach-retain-facts-file, you must delete the retained .socket.facts.json before running a fresh full application reachability scan. A stale .socket.facts.json left in the scan directory is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan's results will not be reliable.

Repo / Branch names

• --repo tells Socket to which repository this Scan belongs. If you leave it out, the CLI uses the socket.json default, then the repo name of your origin git remote, and socket-default-repository as a last resort.
• --branch tells Socket to which branch this Scan belongs. If you leave it out, the CLI uses the socket.json default, then your current git branch, and socket-default-branch as a last resort.

Repo names are required to follow these rules:

• Only a-z A-Z 0-9 and ., _, and - are allowed
• Max length is 100

Branch names are required to follow these rules, which should be roughly equal to GitHub's branch names:

• be 1–255 characters long
• cannot be exactly @ or 0
• cannot begin or end with /, ., or .lock
• cannot contain //, .., @{, any control characters, spaces, or any of ; ~ ^ : ? * [ .

Head Scan

A concept currently called Head Scan is the scan that currently reflects the "dependencies" and "alerts" page in your dashboard. This must be a Scan on the "default" branch in a project.

Default branch

Very similar to how branches in a git repository have a default branch, so do repositories on Socket have a default branch for each repository.

You can mark a branch as the default branch of its repository by passing --default-branch to socket scan create. You only need to do this once per repo.

socket scan diff

If you want to know what changed between two commits you can check a scan diff. This will take two Scan IDs and compute the delta between the before and after Scan, then tell you exactly what changed in terms of dependencies and alerts.

$ socket scan diff --help

  See what changed between two Scans

  Usage
    $ socket scan diff [options] <SCAN_ID1> <SCAN_ID2>

  API Token Requirements
    - Quota: 1 unit
    - Permissions: full-scans:list

  This command displays the package changes between two scans. The full output
  can be pretty large depending on the size of your repo and time range. It is
  best stored to disk (with --json) to be further analyzed by other tools.

  Note: While it will work in any order, the first Scan ID is assumed to be the
        older ID, even if it is a newer Scan. This is only relevant for the
        added/removed list (similar to diffing two files with git).

  Options
    --depth             Max depth of JSON to display before truncating, use zero for no limit (without --json/--file)
    --file              Path to a local file where the output should be saved. Use `-` to force stdout.
    --interactive       Allow for interactive elements, asking for input. Use --no-interactive to prevent any input questions, defaulting them to cancel/no.
    --json              Output as JSON
    --markdown          Output as Markdown
    --org               Force override the organization slug, overrides the default org from config

  Examples
    $ socket scan diff aaa0aa0a-aaaa-0000-0a0a-0000000a00a0 aaa1aa1a-aaaa-1111-1a1a-1111111a11a1
    $ socket scan diff aaa0aa0a-aaaa-0000-0a0a-0000000a00a0 aaa1aa1a-aaaa-1111-1a1a-1111111a11a1 --json

socket scan report

This downloads a Scan and the security / license policies set by your organization and checks whether the Scan had any alerts that might violate any rules in those policies.

$ socket scan report --help

  Check whether a scan result passes the organizational policies (security, license)

  Usage
    $ socket scan report [options] <SCAN_ID> [OUTPUT_PATH]

  API Token Requirements
    - Quota: 2 units
    - Permissions: full-scans:list and security-policy:read

  Options
    --fold              Fold reported alerts to some degree (default 'none')
    --interactive       Allow for interactive elements, asking for input. Use --no-interactive to prevent any input questions, defaulting them to cancel/no.
    --json              Output as JSON
    --license           Also report the license policy status. Default: false
    --markdown          Output as Markdown
    --org               Force override the organization slug, overrides the default org from config
    --report-level      Which policy level alerts should be reported (default 'warn')
    --short             Report only the healthy status

  When no output path is given the contents is sent to stdout.

  By default the result is a nested object that looks like this:
    `{
      [ecosystem]: {
        [pkgName]: {
          [version]: {
            [file]: {
              [line:col]: alert
    }}}}`
  So one alert for each occurrence in every file, version, etc, a huge response.

  You can --fold these up to given level: 'pkg', 'version', 'file', and 'none'.
  For example: `socket scan report --fold=version` will dedupe alerts to only
  show one alert of a particular kind, no matter how often it was found in a
  file or in how many files it was found. At most one per version that has it.

  By default only the warn and error policy level alerts are reported. You can
  override this and request more ('defer' < 'ignore' < 'monitor' < 'warn' < 'error')

  Short responses look like this:
    --json:     `{healthy:bool}`
    --markdown: `healthy = bool`
    neither:    `OK/ERR`

  Examples
    $ socket scan report 000aaaa1-0000-0a0a-00a0-00a0000000a0 --json --fold=version
    $ socket scan report 000aaaa1-0000-0a0a-00a0-00a0000000a0 --license --markdown --short

Here's what that would kind of look like:

$ socket scan report 000aaaa1-0000-0a0a-00a0-00a0000000a0

ℹ Scan result: success. Security policy: received policy.
✔ Generated reported in 1 ms
{
  healthy: true,
  orgSlug: 'bearDev',
  scanId: '000aaaa1-0000-0a0a-00a0-00a0000000a0',
  options: { fold: 'none', reportLevel: 'warn' },
  alerts: Map(0) {}
}

The report will include the alerts and a simple boolean flag for whether the report passes or not, called "healthy". When the Scan is not healthy, the command exits with code 1.

By default socket scan report only checks your security policy. Add --license to also check your license policy. socket scan create --report always checks both.

List / View / Del / Metadata

There are a few commands to organize Scans in your repository. These are fairly straightforward.

Run any of them with --help to see all of its flags.

Setup defaults

You can start an interactive prompt to generate a socket.json in your target directory with defaults for running scans in this directory. (More details here)

socket scan setup ./proj

This is helpful for setting up defaults for socket scan create flags like --repo (the name of the repo of this directory), --branch the name of (presumably default) branch of this directory, --workspace, --auto-manifest, and --report. It can also store defaults for socket scan github.

This way, you can just run socket scan create from inside ./proj (or pass --cwd ./proj) and it could prefill --repo website --branch main for you. socket scan create looks for socket.json in its working directory and the directories above it, not in the scan target.

Output flags

Note that most of these commands support

• --json for a raw payload (which you can forward to jq)
• --markdown for easy sharing

Automation

While we try to offer simpler ways of combining these commands, like socket ci and socket scan create --report, we recognize that there may always be desires to customize your chain. And that's totally fine!

Here is an automation example of running it as part of your CI logic

socket scan create \
  --report \
  --repo="$CI_PROJECT_NAME" \
  --branch="$CI_COMMIT_REF_NAME" \
  ./proj

This will create the scan on the ./proj directory, wait for the report, and have exit code 0 for success or 1 if the Scan does not pass your security policy or license policy. If an error occurs, the exit code is also non-zero.

Make sure you set the env vars to the appropriate values. For example, GitLab should expose the CI_PROJECT_NAME variable. Each environment will have their own set of env vars exposed.