GeezerVison

⚠️ This PR is not ready for review until the below TODO regarding scope names is complete.

Why

The repo documented exactly one thing about token permissions: a troubleshooting note about the diff-scans comparison path. It had three problems.

It described the APIAccessDenied fallback as a PR/MR-only condition, which was wrong in both directions. Runs without an SCM integration (--scm api, the default) compare and were not covered. And when this note was written, SCM-integrated branch pushes compared too — #302 has since moved those onto a full scan in 2.9.0, so that half is now correct by accident rather than by description. The docs now carry a table of which runs compare, plus the pre-2.9.0 behavior, since the warning still turns up in older logs with no pull request in sight.

It listed full-scans:list alongside the two diff-scans:* scopes. The streaming fallback is GET orgs/{org}/full-scans/diff, itself a full-scans read, so if the fallback returns results the token already has that permission. Readers were pointed at a permission they demonstrably had.

And it never documented the baseline set, conceding as much with "in addition to whatever the scan itself needs". A token could not be provisioned from the docs.

The setup guide omits two scopes this CLI requires

The published CI/CD token setup guide tells readers to select nine scopes:

repo:list, repo:create, repo:update, security-policy:read, triage:alerts-list, triage:alerts-update, full-scans:list, full-scans:create, packages:list

It does not list diff-scans:create or diff-scans:list.

Every diff-producing run tries the diff-scans endpoints first, so a token provisioned exactly as that guide describes fails that call with APIAccessDenied and silently falls back to the legacy streaming comparison. The only signal is a warning in the log. This is not a misconfiguration a user can be blamed for — following the documented setup produces it, and it affects every CLI user who provisioned that way.

The converse also holds. socketcli makes no triage or security-policy API calls at all, verified against the full SDK call surface, so security-policy:read, triage:alerts-list and triage:alerts-update are not exercised by this CLI. They are on the guide's list for other Socket tooling.

The guide itself is separate tooling and out of scope here; this PR documents the gap so CLI users can work around it.

What changed

docs/troubleshooting.md carries the substance: three tables covering what every run calls, what diff-producing runs add, and what each flag adds; the nine documented scope names plus the two missing ones, mapped to the calls they cover; and sections on the APIAccessDenied fallback, temporary baseline scans, reachability vs. full-scan IDs, and the exit-2 caveat.

Supporting changes: permissions pointers in README.md, docs/cli-reference.md, and docs/ci-cd.md; all four accepted token environment variables documented in priority order; and a $SOCKET_API_TOKEN reference in the GitLab requirements section corrected to SOCKET_SECURITY_API_TOKEN.

TODO

• Confirm the scope identifiers that the setup guide does not publish.

Two calls every run makes — GET organizations and GET report/supported — map to no scope on the guide's list. They appear to be available to any valid org token, but that is inference, and the docs currently say so. Also unmapped: license-metadata, export/cdx, the reachability manifest upload, and finalize_tier1.

The scope-to-call mapping in the tables is likewise inferred from the names, since the guide publishes no per-endpoint mapping. It is labelled as inferred in the docs. Someone who owns the scope definitions should confirm both before this leaves draft.

Notes for the reviewer

Every claim was re-verified against 2.9.7 after rebasing: the SDK call surface, the four sys.exit(2) sites, the temporary empty baseline, and the reachability scan ID are all unchanged. The diff flow was the one thing that moved, and it is corrected in its own commit.

README.md's exit code table now notes that exit 2 also covers repository lookup/creation failure, and that neither exit-code flag remaps it. That behavior is a bug, tracked separately — this PR only documents it.

This bumps to 2.9.8 despite being docs-only. check_version has since lost its paths: filter — a required check behind one never reports, which blocks the merge — and is now a required context, so every PR has to land ahead of the latest PyPI release. 2.9.7 is published, so riding main's version fails the gate. All three copies of the version move together, since the job asserts pyproject.toml and socketsecurity/__init__.py agree and python-tests runs uv lock --locked.

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