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.
pip install socketsecurityexport SOCKET_SECURITY_API_TOKEN="<token>"socketcli --target-path .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.
socketcli --target-path .socketcli --enable-gitlab-security --gitlab-security-file gl-dependency-scanning-report.jsonsocketcli \
--reach \
--sarif-file results.sarif \
--sarif-scope full \
--sarif-grouping alert \
--sarif-reachability reachable \
--disable-blockingsocketcli \
--reach \
--sarif-file results.sarif \
--sarif-scope diff \
--sarif-reachability reachable \
--strict-blockingsocketcli \
--reach \
--sarif-file results.sarif \
--sarif-scope full \
--sarif-grouping instance \
--sarif-reachability all \
--disable-blocking| Use case | Recommended mode | Key flags |
|---|---|---|
| Basic policy enforcement in CI | Diff-based policy check | --strict-blocking |
| 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.
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 .Reference sample configs:
TOML:
examples/config/sarif-dashboard-parity.tomlexamples/config/sarif-instance-detail.tomlexamples/config/sarif-diff-ci-cd.toml
JSON:
examples/config/sarif-dashboard-parity.jsonexamples/config/sarif-instance-detail.jsonexamples/config/sarif-diff-ci-cd.json
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 }}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 -uFor 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- Full CLI reference:
docs/cli-reference.md - CI/CD guide:
docs/ci-cd.md - Troubleshooting guide:
docs/troubleshooting.md - Development guide:
docs/development.md