Repository navigation
Conversation
The docs named the scopes `full-scans` and `socket-basics`, which are not scope names; the API checks `full-scans:create` and `socket-basics:read`. They also left out that Socket Tier 1 needs `full-scans:create`, and that a missing scope never fails the run. - Add an API token scopes section to the parameters reference: a least-privilege scope table, then every Socket API call by step (dashboard configuration, result upload, Socket Tier 1) with the scope it checks, when it is called and how a denial shows up in the log - Note that on an Enterprise organization a key without `socket-basics:read` also loses organization discovery, so `SOCKET_ORG` must be set for the upload - Note which token variables each step reads, and that the Socket npm CLI prefers its own variables over the one Tier 1 passes - Correct the scope names in the README, the GitHub Action guide and the Docker guide, and link them to the new section
PR SummaryLow Risk Overview
Troubleshooting and configuration-precedence text is aligned everywhere on Enterprise org discovery requiring Reviewed by Cursor Bugbot for commit be47b1e. Configure here. |
|
bugbot run |
Eric Hibbs (flowstate)
left a comment
There was a problem hiding this comment.
Checked the scope table and call flow against the Basics source and the API handlers. The two-scope token is correct and the quoted log strings match. A few accuracy fixes inline, none of which would leave anyone with a non-working token.
On the description: full-scans and socket-basics are valid scopes. They're the parents, and a parent satisfies its children in hasRequiredApiTokenScopes, so the old docs over-granted rather than named something invalid. Related question: socket-basics:read is the only child of socket-basics, and normalizeScopes collapses a full set of children into the parent. Does the dashboard show a token created with socket-basics:read as socket-basics? If so, users may be looking for a name they won't see.
…names - The organization is discovered from the key without socket-basics:read on non-Enterprise plans, where the settings call is never made. Four places said discovery always needs the scope. - POST coana-cli/artifacts checks full-scans:create or fixes:list in its handler; it was listed as needing no scope. - A denied settings call logs one warning, "Error loading Socket Basics config: Insufficient permissions", not a separate line before it. - full-scans and socket-basics are the scope groups, which also work. socket-basics:read is the only scope in its group, so the API reports it as socket-basics. - The setup-guide paragraph no longer states which scopes that guide lists, since the list is changing.
|
Thanks, the three inline notes are fixed in be47b1e, with replies on each thread. On the description: you are right, On the dashboard question: a token created with |
|
bugbot run |
There was a problem hiding this comment.
✅ 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 be47b1e. Configure here.
Summary
Socket Basics needs two API token scopes:
full-scans:createandsocket-basics:read. The docs named the scope groups,full-scansandsocket-basics. Those work, because a group covers every scope in it, butfull-scansgrants more than Socket Basics uses. The docs also said nothing about Socket Tier 1 or about what a missing scope does. A missing scope never fails the run. It only logs, so a misconfigured token goes unnoticed.Changes
docs/parameters.md:full-scans:create. The engine-download endpoint,coana-cli/artifacts, acceptsfull-scans:createorfixes:list.socket-basics:readis the only scope in thesocket-basicsgroup, so selecting either is the same token: the dashboard shows both checked, and the API reports the scope assocket-basics.README.md,docs/github-action.mdanddocs/local-install-docker.mdnow name the specific scopes. The README keeps a short version that links to the new subsection.socket-basics:read.socket-basics:readmakes the dashboard-config step fail. That step also throws away the org it discovered, so results don't upload unlessSOCKET_ORGis set.SOCKET_SECURITY_API_KEY,SOCKET_SECURITY_API_TOKENandINPUT_SOCKET_SECURITY_API_KEY. A key set only asSOCKET_API_KEYskips it.SOCKET_SECURITY_API_KEY, but that CLI prefersSOCKET_CLI_API_TOKEN,SOCKET_CLI_API_KEYorSOCKET_SECURITY_API_TOKENwhen one is set. If several are set to different tokens, Tier 1 can use a different token from the rest of the run.full-scans:createfor that.socket-basics:read, so check for it before relying on dashboard configuration.socketcli, the docs link to its permissions guide rather than repeating it. Improve documentation for requisite API token permissions socket-python-cli#353 adds that guide, so merge this after #353, or at the same time.Questions this answers
security-policy:reador thetriage:*scopes? No. It makes no triage or security-policy calls, and neither doessocketcli. So those three scopes on the CI/CD key guide aren't there for either Python tool. The npm CLI'ssocket ciusedsecurity-policy:readbefore version 1.15.0.socket scan reach, neither of which calls the diff-scans endpoints.docs/parameters.md, with a short version in the README). A docs-site page would be a separate change.Related PRs
#api-token-scopessection, so merge this PR before that one.Testing
Docs only.
python3 scripts/check_release_docs.py --checkpasses. Each call was traced in the source: the directsocketdevSDK calls, and the published Socket npm CLI that runssocket scan reachfor Tier 1. Options passed throughsocket_additional_paramscan make more calls, and the docs say those aren't covered.Fixes: CE-463
Refs: CE-384