[lelia]

Why

Before this PR, the repo said one thing about token permissions: a troubleshooting note on the diff-scans comparison. That note described the APIAccessDenied fallback as PR/MR-only, when it applies to every run that compares scans. It also told readers to grant full-scans:list, which the fallback path already proves the token has. It never listed the baseline set of scopes, so a token couldn't be provisioned from the docs.

The setup guide's scope list doesn't match this CLI

The CI/CD token setup guide lists nine scopes. It leaves out diff-scans:create and diff-scans:list. Every diff-producing run calls the diff-scans endpoints first, so a token set up exactly as the guide says gets APIAccessDenied there and falls back to the streaming comparison. The only sign is a warning in the log. Following the documented setup is enough to cause this, so every CLI user who did that is affected.

The converse also holds. socketcli never uses four of the guide's scopes: repo:update, security-policy:read, triage:alerts-list and triage:alerts-update. That includes repo:update: POST full-scans checks only full-scans:create, even when it sets the repository head.

This PR documents the gap for CLI users. SocketDev/docs#195 fixes the guide itself.

What changed

docs/troubleshooting.md carries the substance:

• The least-privilege scope set, and what each scope is used for.
• Each API call by run type (every run, diff-producing runs, per flag), with the scope that endpoint checks.
• The APIAccessDenied fallback, which runs compare, and how to tell which scope is missing.
• Three results that look like failures but aren't: the temporary empty baseline on a first scan, reachability scan IDs, and exit 2 when the token can't create the repository.

Supporting changes:

• Permissions pointers in README.md, docs/cli-reference.md and docs/ci-cd.md.
• All four accepted token environment variables, in priority order.
• The GitLab requirements section named $SOCKET_API_TOKEN. It now says SOCKET_SECURITY_API_TOKEN.

How the mapping was verified

Each endpoint-to-scope mapping is the scope the API itself checks. For public endpoints that's the security block in the API reference. For the three hidden ones (upload-manifest-files, tier1-reachability-scan/finalize, and the telemetry post), it's each route's requiredScopes. The draft of this PR inferred mappings from scope names, and checking them against the API changed three of them:

• repo:update: unused (see above).
• --sbom-file makes no API call. The CycloneDX export it was mapped to has no caller, and the license-metadata and full-scan metadata reads are reached only from tests.
• GET organizations, GET report/supported and the ignore-comment telemetry post check no scope at all, which resolves the draft's open question.

The call surface was re-audited against 2.12.0 after rebasing: SDK calls, the sys.exit(2) sites, the diff/full-scan flow decision, the empty-baseline path, and the log strings the docs quote.

Notes for the reviewer

• README.md's exit code table now notes that exit 2 also covers repository lookup and creation failures, and that neither exit-code flag remaps it. That behavior is a bug, tracked separately. This PR only documents it.
• This bumps to 2.12.1 even though it's docs-only, because check_version is a required, unfiltered check that wants a version ahead of PyPI. If another PR claims 2.12.1 first, this one rides it.

Related PRs

The same scope audit for the other two Python repos, and the docs-site fix. Each links to this PR's troubleshooting section, so merge this one first.

• SocketDev/docs#195: adds the two diff-scans scopes to the CI/CD token setup guide.
• Document the API token scopes each SDK method needs socket-sdk-python#130: the scope each SDK method needs.
• docs: List the API token scopes Socket Basics needs socket-basics#140: the scopes Socket Basics needs.

Fixes: CE-461
Refs: CE-384, CE-460, CE-481

[lelia]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[lelia]

bugbot run

[cursor]

PR Summary

Low Risk
Docs and version bump only; no runtime behavior changes beyond publishing 2.12.1 metadata.

Overview
This release (2.12.1) is documentation-only: it expands how operators should provision Socket API tokens for socketcli and links that guidance across the repo.

The main addition is docs/troubleshooting.md#api-token-permissions, which documents the least-privilege scope set, maps API calls to scopes by run type and flags, calls out that the external CI/CD token guide omits diff-scans:create and diff-scans:list, and explains silent fallbacks (APIAccessDenied on comparisons) versus hard failures (exit 2 when the token cannot look up or create a repository). It also clarifies confusing outcomes: temporary empty baselines, reachability scan IDs vs full-scan IDs.

README.md, docs/cli-reference.md, and docs/ci-cd.md now point at that guide, document the four accepted token environment variables in priority order, and update the exit-code table so 2 covers repository lookup/creation failures and is not remapped by --disable-blocking or --exit-code-on-api-error.

^{Reviewed by Cursor Bugbot for commit 5fc3b67. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[lelia]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 5fc3b67. Configure here.}