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>"

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 head scan. To diff against the exact commit your PR branched from instead, pass the merge base as the baseline:

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

Requirement: --base-commit-sha only works if Socket already has a full scan for that exact commit. In practice this means your CI must run socketcli on every commit that lands on your default branch — not just some of them. If merges can land without a scan (skipped/canceled builds, [skip ci], path-filtered pipelines), the PR scan will fail with exit code 3 rather than silently diff against the wrong baseline. See docs/cli-reference.md for the full requirements and a backfill pattern that makes PR jobs self-sufficient.

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:

Full-scope SARIF is the closest match for dashboard-style filtering.
Exact result counts can still differ from the dashboard due to backend/API consolidation differences and grouping semantics.
See docs/troubleshooting.md#dashboard-vs-cli-result-counts.

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`	Clean scan — no blocking issues (or `--disable-blocking` set)
`1`	Blocking security finding(s) detected
`2`	Scan interrupted (SIGINT / Ctrl+C)
`3`	Infrastructure or API error (timeout, network failure, unexpected error)

--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 wins over everything. It forces exit 0 for all outcomes — security findings and infrastructure errors. If you set it, --exit-code-on-api-error has no effect (you'll always get 0).
--exit-code-on-api-error only applies when --disable-blocking is not set. It changes the infra-error code (and the generic-error code); it never touches the security-finding code (1).

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.

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

Full CLI reference: docs/cli-reference.md
CI/CD guide: docs/ci-cd.md
Troubleshooting guide: docs/troubleshooting.md
Development guide: docs/development.md

Development Status
- 4 - Beta
Intended Audience
- Developers
Programming Language
- Python :: 3.11
- Python :: 3.12

Release files for socketsecurity 2.8.0

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.8.0
File	Size	Uploaded
socketsecurity-2.8.0.tar.gz	976.2 kB	Sep 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for socketsecurity 2.8.0
File	Interpreter	ABI	Platform	Reset
socketsecurity-2.8.0-py3-none-any.whl 144.7 kB Sep 9, 2026	Python 3	none	any	Details

Total release size: 1.1 MB

Release files / socketsecurity-2.8.0.tar.gz

Download URL	socketsecurity-2.8.0.tar.gz
Size	976.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`f2a767c2b7a64c4b8e10e5fe2ddfe1c7701f1767689f56b54612498d53c3b83c`
BLAKE2b-256 checksum How to use checksums	`ab3ca0948410c1c4d4c07017b99f081b01e8d3a0838b5b3e987fd90fb7afcf81`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SocketDev/socket-python-cli
Publishing commit: github.com/SocketDev/socket-python-cli/tree/860b8eac976cced1b0ff6161d2e9bebdd149bf06

Workflow

Publishing configuration: github.com/SocketDev/socket-python-cli/blob/860b8eac976cced1b0ff6161d2e9bebdd149bf06/.github/workflows/release.yml
Publishing logs: github.com/SocketDev/socket-python-cli/actions/runs/34418140613/attempts/1

Artifact

Subject: socketsecurity-2.8.0.tar.gz
SHA-256 checksum: f2a767c2b7a64c4b8e10e5fe2ddfe1c7701f1767689f56b54612498d53c3b83c Verifying attestations

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

Download URL	socketsecurity-2.8.0-py3-none-any.whl
Size	144.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8feeadb72a2f9d68bae0229ec65ad5555dfed88a5d8beed79fccd163b4ad8975`
BLAKE2b-256 checksum How to use checksums	`d63219210592c3a91c4b202c9e3cb3fd870947c991fbc88f1e541e71e7d0a47e`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/SocketDev/socket-python-cli
Publishing commit: github.com/SocketDev/socket-python-cli/tree/860b8eac976cced1b0ff6161d2e9bebdd149bf06

Workflow

Publishing configuration: github.com/SocketDev/socket-python-cli/blob/860b8eac976cced1b0ff6161d2e9bebdd149bf06/.github/workflows/release.yml
Publishing logs: github.com/SocketDev/socket-python-cli/actions/runs/34418140613/attempts/1

Artifact

Subject: socketsecurity-2.8.0-py3-none-any.whl
SHA-256 checksum: 8feeadb72a2f9d68bae0229ec65ad5555dfed88a5d8beed79fccd163b4ad8975 Verifying attestations