Skip to main content

Socket Security CLI

Socket Python CLI for Socket scans, diff reporting, reachability analysis, and SARIF/GitLab exports.

Comprehensive docs are available in docs/ for full flag reference, CI/CD-specific guidance, and contributor setup.

Quick start

1) Install

pip install socketsecurity

2) Authenticate

export SOCKET_SECURITY_API_TOKEN="<token>"

The token needs more than scan-creation access. Most missing scopes fail the run, and a token without the diff-scans scopes falls back with only a warning. See docs/troubleshooting.md#api-token-permissions.

3) Run a basic scan

socketcli --target-path .

Common use cases

This section covers the paved path/common workflows. For advanced options and exhaustive details, see docs/cli-reference.md. For CI/CD-specific guidance, see docs/ci-cd.md.

Basic policy scan (no SARIF)

socketcli --target-path .

GitLab dependency-scanning report

socketcli --enable-gitlab-security --gitlab-security-file gl-dependency-scanning-report.json

PR scan diffed against the merge base

By default, PR scans are diffed against the repository's latest matching head scan. To prefer the commit your PR branched from as the baseline, pass the merge base:

BASE_SHA=$(git merge-base origin/main HEAD)
socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"

The CLI uses the exact commit's newest matching full scan when one exists. Otherwise, it searches up to 100 first-parent commits in the local checkout and uses the nearest scanned ancestor, with a warning that the diff is wider than the merge base. Run socketcli regularly on your default branch and ensure PR checkouts contain enough history for that walk. The run fails with the configured API-error exit code only when no scanned ancestor is reachable (or when the scan lookup itself fails). See docs/cli-reference.md for the full behavior and an optional exact-baseline backfill pattern.

A specific full scan ID also works: --base-scan-id <id>.

SARIF use cases

Full-scope reachable SARIF (grouped alerts)

socketcli \
  --reach \
  --sarif-file results.sarif \
  --sarif-scope full \
  --sarif-grouping alert \
  --sarif-reachability reachable \
  --disable-blocking

Diff-scope reachable SARIF (PR/CI gating)

socketcli \
  --reach \
  --sarif-file results.sarif \
  --sarif-scope diff \
  --sarif-reachability reachable \
  --strict-blocking

Full-scope SARIF (instance-level detail)

socketcli \
  --reach \
  --sarif-file results.sarif \
  --sarif-scope full \
  --sarif-grouping instance \
  --sarif-reachability all \
  --disable-blocking

Choose your mode

Use case Recommended mode Key flags
Basic policy enforcement in CI Diff-based policy check --strict-blocking
Legal/compliance artifact generation Legal preset --legal
Reachable-focused SARIF for reporting Full-scope grouped SARIF --reach --sarif-scope full --sarif-grouping alert --sarif-reachability reachable --sarif-file <path>
Detailed reachability export for investigations Full-scope instance SARIF --reach --sarif-scope full --sarif-grouping instance --sarif-reachability all --sarif-file <path>
Net-new PR findings only Diff-scope SARIF --reach --sarif-scope diff --sarif-reachability reachable --sarif-file <path>

Dashboard parity note:

Config files (--config)

Use --config <path> with .toml or .json to avoid long command lines.

Precedence order:

CLI flags > environment variables > config file > built-in defaults

Example:

[socketcli]
repo = "example-repo"
reach = true
sarif_scope = "full"
sarif_grouping = "alert"
sarif_reachability = "reachable"
sarif_file = "reachable.sarif"

Equivalent JSON:

{
  "socketcli": {
    "repo": "example-repo",
    "reach": true,
    "sarif_scope": "full",
    "sarif_grouping": "alert",
    "sarif_reachability": "reachable",
    "sarif_file": "reachable.sarif"
  }
}

Run:

socketcli --config .socketcli.toml --target-path .

Legal/compliance preset example:

socketcli --legal --target-path .

This preset enables license generation and writes default artifacts unless you override them:

  • socket-report.json
  • socket-summary.txt
  • socket-report-link.txt
  • socket-sbom.json
  • socket-license.json

FOSSA-compatibility shaped legal artifacts:

socketcli --legal-format fossa --target-path .

This switches the JSON report and legal artifact payloads to FOSSA-style compatibility shapes:

  • the analyze artifact becomes a project / vulnerability / licensing / quality report
  • the SBOM artifact becomes a FOSSA-attribution-style payload with copyrightsByLicense, deepDependencies, directDependencies, licenses, and project keys

When --legal-format fossa is used without explicit output paths, the defaults are closer to the FOSSA pipeline contract:

  • fossa-analyze.json
  • fossa-test.txt
  • fossa-link.txt
  • fossa-sbom.json

Reference sample configs:

TOML:

JSON:

CI/CD examples

Prebuilt workflow examples:

Minimal pattern:

- name: Run Socket CLI
  run: socketcli --config .socketcli.toml --target-path .
  env:
    SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}

Exit codes

Code Meaning
0 Successful report, skipped SCM event, or --disable-blocking set; findings gate only evaluated diffs
1 Blocking security finding(s) detected
2 Invalid flags or configuration (usage error), including argparse's own errors
3 Infrastructure or API error: missing API or SCM token, permission or plan problem, timeout, network failure, incomplete scan comparison, unexpected error
130 Scan interrupted (SIGINT / Ctrl+C)

--exit-code-on-api-error <N> remaps the infrastructure-error code (3) to any value — e.g. a Buildkite soft_fail code, or 0 to swallow infra errors. Exit 3 is a Socket convention, not an industry standard.

This mapping applies to errors the CLI receives and handles. An external process supervisor (for example GNU timeout) can terminate the CLI before it handles an error, so the supervisor's exit status (commonly 124 or 137) takes precedence.

How these options interact

The two flags that affect exit codes can cancel each other out, so the order of precedence matters:

  • --disable-blocking forces exit 0 for findings, infrastructure errors and interrupts. It takes precedence over --exit-code-on-api-error and --strict-blocking. Usage errors still exit 2.
  • --exit-code-on-api-error only applies when --disable-blocking is not set. It changes the infrastructure-error code, including unexpected runtime failures. Findings (1), usage errors (2) and Ctrl+C (130) keep their codes.

So for the common "don't let Socket outages block my pipeline, but still fail on real findings" goal, use --exit-code-on-api-error without --disable-blocking:

# Buildkite: soft-fail only on infrastructure errors, still block on findings
steps:
  - label: ":lock: Socket Security Scan"
    command: "socketcli --exit-code-on-api-error 100 ..."   # NOT --disable-blocking
    soft_fail:
      - exit_status: 100

Combining --disable-blocking with --exit-code-on-api-error 100 would make the scan exit 0 on both findings and outages — the soft_fail: 100 rule would never match, and real findings would stop blocking. That's usually not what you want.

Upgrading to 2.13.0

Update pipeline rules and wrapper scripts that match specific exit codes:

Outcome Before 2.13.0 From 2.13.0
Invalid flags or configuration CLI validation: 1; argparse: 2 2 for both; never suppressed by --disable-blocking
Ctrl+C 2 130, or 0 with --disable-blocking
Missing token or other setup failure Fixed 2 or 3, depending on the failure Infrastructure-error code (3 by default); both exit-code flags now apply

Blocking findings still exit 1. With --strict-blocking, existing blocking alerts can now fail jobs that previously passed. GitLab report findings also get new IDs once; see the release notes.

Configuration is validated before credentials or network setup. Use native JSON/TOML booleans such as false, a positive integer timeout, and an array of file paths for files. Invalid or unreadable configuration exits 2 even when credentials are missing or blocking is disabled.

For a compact comparison of failure-handling policies, see Exit codes in CI.

Common gotchas

See docs/troubleshooting.md.

Quick verification checks

After generating SARIF files, validate shape/count quickly:

jq '.runs[0].results | length' results.sarif
jq -r '.runs[0].results[]?.properties.reachability' results.sarif | sort -u

For side-by-side comparisons:

jq '.runs[0].results | length' sarif-dashboard-parity-reachable.sarif
jq '.runs[0].results | length' sarif-full-instance-all.sarif
jq '.runs[0].results | length' sarif-diff-reachable.sarif

Documentation reference

Metadata

Release files for socketsecurity 2.13.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for socketsecurity 2.13.2
File Size Uploaded Provenance Actions
socketsecurity-2.13.2.tar.gz 1.1 MB With provenance Details for socketsecurity-2.13.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for socketsecurity 2.13.2
File Interpreter ABI Platform Actions
socketsecurity-2.13.2-py3-none-any.whl Python 3 none any Details for socketsecurity-2.13.2-py3-none-any.whl

Total release size: 1.2 MB

Release files / socketsecurity-2.13.2.tar.gz

Download URL socketsecurity-2.13.2.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
378de0d0694be4a2b6b655eb3118f985b33a910ee471a0885ee9f44b96ab3fdb
BLAKE2b-256 checksum
How to use checksums
a058a92838310279c36f7a55c5fce659c63039f7781609091b2b64410bce2b15
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / socketsecurity-2.13.2-py3-none-any.whl

Download URL socketsecurity-2.13.2-py3-none-any.whl
Size 173.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1feaf8fce4e435d66f8a6e6fd495d5cc87a28148742d83dfc4249731e88991a1
BLAKE2b-256 checksum
How to use checksums
b8950faf3c6a6159a68f11a602a4d77710c3e2d22cc02bd7c1462a8cd8f781ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for socketsecurity 2.13.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for socketsecurity-2.13.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.13.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page