Skip to content

About

Socket Python CLI to use in integrations

Resources

Code of conduct

Contributing

Security policy

Stars

16 stars

Watchers

16 watching

Forks

Latest commit

 

History

334 Commits

Folders and files

Repository files navigation

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:

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

About

Socket Python CLI to use in integrations

Resources

Code of conduct

Contributing

Security policy

Stars

16 stars

Watchers

16 watching

Forks

Releases

Packages

Used by

Contributors

Languages