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

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.9.4

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.9.4
File	Size	Uploaded
socketsecurity-2.9.4.tar.gz	1.0 MB	Sep 18, 2026	Details

Built distribution (wheel)

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

Total release size:1.2 MB

Release files / socketsecurity-2.9.4.tar.gz

Download URL	socketsecurity-2.9.4.tar.gz
Size	1.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`7df1537bad30da9584d4ebccf16f6a2dd23e02b79e8fcf0d2a797f40814ff4eb`
BLAKE2b-256 checksum How to use checksums	`6808982f2d90132064022d3283979e55c9bce3b911a018bd974beb9935e49550`
Upload date	Sep 18, 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/ccd4a45e88b49edebe077ee63ff6cdf361371715

Workflow

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

Artifact

Subject: socketsecurity-2.9.4.tar.gz
SHA-256 checksum: 7df1537bad30da9584d4ebccf16f6a2dd23e02b79e8fcf0d2a797f40814ff4eb Verifying attestations

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

Download URL	socketsecurity-2.9.4-py3-none-any.whl
Size	159.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f7a92c10bede7d6351e5e75525f099fdbb41d788ed0e976e0cf747ab9045e11c`
BLAKE2b-256 checksum How to use checksums	`903151c50e83e84b7f711d5cf41c0e7b34b5ef6d4e3bc792f5fd3d191cea6122`
Upload date	Sep 18, 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/ccd4a45e88b49edebe077ee63ff6cdf361371715

Workflow

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

Artifact

Subject: socketsecurity-2.9.4-py3-none-any.whl
SHA-256 checksum: f7a92c10bede7d6351e5e75525f099fdbb41d788ed0e976e0cf747ab9045e11c Verifying attestations