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 socketsecurity
export 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.json
socketcli \ --reach \ --sarif-file results.sarif \ --sarif-scope full \ --sarif-grouping alert \ --sarif-reachability reachable \ --disable-blocking
socketcli \ --reach \ --sarif-file results.sarif \ --sarif-scope diff \ --sarif-reachability reachable \ --strict-blocking
socketcli \ --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 -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
- Full CLI reference:
docs/cli-reference.md - CI/CD guide:
docs/ci-cd.md - Troubleshooting guide:
docs/troubleshooting.md - Development guide:
docs/development.md