Repository navigation
docs: List the API token scopes Socket Basics needs - #140
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 Bundled dependency updates (recorded in Reviewed by Cursor Bugbot for commit 2369579. 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 |
socketdev 3.6.3 fixes settings.integration_events(), which Socket Basics does not call. The lockfile moves so the image runs the current SDK. The >=3.6.2 floor stays, because the bundled Socket Python CLI pins 3.6.2 exactly and installs on the same system interpreter.
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
bugbot run |
The heavy and app-tests images move the bundled Socket Python CLI from 2.12.0 to 2.13.1. That release pins socketdev 3.6.3 exactly, so the source-install floor moves to >=3.6.3 with it. The changelog carries the upgrade notes that reach heavy-image users: 2.13.0 changed the CLI's exit codes and made --strict-blocking fail on existing blocking alerts. Socket Basics does not run socketcli itself. The bundled CLI also pins the Coana engine 15.15.2, while Socket Tier 1 still runs 15.15.0 through the npm CLI.
|
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 2369579. 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.Dependency changes
Two dependency changes ride along, both recorded under
[Unreleased]in the changelog:Dockerfile.heavyandapp_tests/Dockerfile. Socket Basics does not runsocketcliitself, but heavy-image users who do get the CLI's 2.13.0 changes: new exit codes (2for invalid flags,130for Ctrl+C, setup failures now follow the exit-code flags) and--strict-blockingfailing on existing blocking alerts. The changelog has an upgrade note for that. The bundled CLI also pins the Coana engine 15.15.2, while Socket Tier 1 still runs 15.15.0 through the npm CLI.socketdev) 3.6.2 → 3.6.3, inuv.lock, with thepyproject.tomlfloor raised to>=3.6.3. CLI 2.13.1 pins 3.6.3 exactly and installs on the same system interpreter in the heavy image, so the floor moves with it. The SDK release fixessettings.integration_events(), which Socket Basics does not call.This branch also has
main(3.5.0) merged in, so both changes apply on top of the current release.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
uv lock --locked,python3 scripts/check_release_docs.py --checkandpython3 scripts/sync_release_version.py --checkpass, and the test suite passes onsocketdev3.6.3 (508 passed, 1 skipped).scripts/check_core_tools.py --mode watchreads both Dockerfile pins as 2.13.1 and reports the Python CLI as current. Socket Basics andsocketsecurity==2.13.1resolve together withsocketdev3.6.3. The rest of the PR is docs. 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