Skip to content

docs: List the API token scopes Socket Basics needs - #140

Merged
lelia merged 5 commits into
mainfrom
lelia/api-token-scope-docs
Nov 20, 2026
Merged

lelia merged 5 commits into
mainfrom
lelia/api-token-scope-docs

Conversation

@lelia

@lelia lelia commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Socket Basics needs two API token scopes: full-scans:create and socket-basics:read. The docs named the scope groups, full-scans and socket-basics. Those work, because a group covers every scope in it, but full-scans grants 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

  • New "API token scopes" subsection under Socket Integration in docs/parameters.md:
    • The least-privilege scope set.
    • Every Socket API call by run type (dashboard configuration, result upload, Tier 1), with the scope each endpoint checks, when it's called, and what a failure logs. Scopes come from the API reference.
    • Three Tier 1 endpoints aren't in the reference. Two check full-scans:create. The engine-download endpoint, coana-cli/artifacts, accepts full-scans:create or fixes:list.
    • How scope groups relate to the scopes. socket-basics:read is the only scope in the socket-basics group, so selecting either is the same token: the dashboard shows both checked, and the API reports the scope as socket-basics.
  • README.md, docs/github-action.md and docs/local-install-docker.md now name the specific scopes. The README keeps a short version that links to the new subsection.
  • Organization discovery is described the same way everywhere: the organization is discovered from the key, and only on an Enterprise organization does that also need socket-basics:read.
  • Things worth knowing that weren't documented:
    • On an Enterprise org, a key without socket-basics:read makes the dashboard-config step fail. That step also throws away the org it discovered, so results don't upload unless SOCKET_ORG is set.
    • The dashboard-config step reads only SOCKET_SECURITY_API_KEY, SOCKET_SECURITY_API_TOKEN and INPUT_SOCKET_SECURITY_API_KEY. A key set only as SOCKET_API_KEY skips it.
    • Tier 1 passes the key to the Socket npm CLI as SOCKET_SECURITY_API_KEY, but that CLI prefers SOCKET_CLI_API_TOKEN, SOCKET_CLI_API_KEY or SOCKET_SECURITY_API_TOKEN when one is set. If several are set to different tokens, Tier 1 can use a different token from the rest of the run.
    • The upload creates a missing repository, and an organization API token needs only full-scans:create for that.
    • A token created for the Socket CLIs may lack socket-basics:read, so check for it before relying on dashboard configuration.
  • For the heavy image's bundled 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:

  • Bundled Socket Python CLI 2.12.0 → 2.13.1, in Dockerfile.heavy and app_tests/Dockerfile. Socket Basics does not run socketcli itself, but heavy-image users who do get the CLI's 2.13.0 changes: new exit codes (2 for invalid flags, 130 for Ctrl+C, setup failures now follow the exit-code flags) and --strict-blocking failing 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.
  • Socket Python SDK (socketdev) 3.6.2 → 3.6.3, in uv.lock, with the pyproject.toml floor 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 fixes settings.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

  • Does Socket Basics need security-policy:read or the triage:* scopes? No. It makes no triage or security-policy calls, and neither does socketcli. So those three scopes on the CI/CD key guide aren't there for either Python tool. The npm CLI's socket ci used security-policy:read before version 1.15.0.
  • Does it share the CLI's silent diff-scans fallback? No. Socket Basics never creates diff scans. It uploads a full scan, and Tier 1 runs socket scan reach, neither of which calls the diff-scans endpoints.
  • Where should the docs live? Socket Basics has no page on docs.socket.dev, so this PR puts the scope docs in the repo (docs/parameters.md, with a short version in the README). A docs-site page would be a separate change.

Related PRs

Testing

uv lock --locked, python3 scripts/check_release_docs.py --check and python3 scripts/sync_release_version.py --check pass, and the test suite passes on socketdev 3.6.3 (508 passed, 1 skipped). scripts/check_core_tools.py --mode watch reads both Dockerfile pins as 2.13.1 and reports the Python CLI as current. Socket Basics and socketsecurity==2.13.1 resolve together with socketdev 3.6.3. The rest of the PR is docs. Each call was traced in the source: the direct socketdev SDK calls, and the published Socket npm CLI that runs socket scan reach for Tier 1. Options passed through socket_additional_params can make more calls, and the docs say those aren't covered.

Fixes: CE-463
Refs: CE-384

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
@lelia
lelia marked this pull request as ready for review November 14, 2026 02:45
@lelia
lelia requested a review from a team as a code owner November 14, 2026 02:45
@cursor

cursor Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

PR Summary

Low Risk
Changes are mostly documentation; the CLI/SDK pin bumps only affect heavy-image consumers who invoke socketcli directly or rely on its new exit codes.

Overview
Documentation now uses the least-privilege scopes full-scans:create and socket-basics:read instead of the broader full-scans / socket-basics group names. A new API token scopes section in docs/parameters.md maps each Socket API call (dashboard config, upload, Tier 1) to its required scope, notes that missing scopes only log (they do not fail the run), and explains Enterprise org discovery when socket-basics:read is absent. README.md, docs/github-action.md, and docs/local-install-docker.md are aligned with that guidance.

Bundled dependency updates (recorded in CHANGELOG.md): Socket Python CLI 2.12.0 → 2.13.1 in Dockerfile.heavy and app_tests/Dockerfile (with an upgrade note on socketcli exit-code changes for heavy-image users), and socketdev 3.6.2 → 3.6.3 via pyproject.toml and uv.lock.

Reviewed by Cursor Bugbot for commit 2369579. Configure here.

@lelia

lelia commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@lelia lelia added the documentation Improvements or additions to documentation label Nov 14, 2026

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@flowstate Eric Hibbs (flowstate) left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/github-action.md Resolved
Comment thread docs/parameters.md Resolved
Comment thread docs/parameters.md Resolved
…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.
@lelia

lelia commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, the three inline notes are fixed in be47b1e, with replies on each thread.

On the description: you are right, full-scans and socket-basics are the groups and they work. The description and the docs now say that instead of calling them invalid. The docs still recommend the specific scopes, because full-scans also grants full-scans:list and full-scans:delete.

On the dashboard question: a token created with socket-basics:read is stored as socket-basics, since normalizeScopes runs on create. In the token dialog the socket-basics group shows as checked with socket-basics:read checked under it, so the name is still there to find, and the tokens table has no scopes column. The API tokens list returns socket-basics. docs/parameters.md now says selecting either one is the same token.

@lelia

lelia commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous 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.
@lelia
lelia deployed to socket-firewall November 20, 2026 22:18 — with GitHub Actions Active
@lelia
lelia deployed to socket-firewall November 20, 2026 22:18 — with GitHub Actions Active
@socket-security

socket-security Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Updatedpypi/​socketdev@​3.6.2 ⏵ 3.6.398 +1100100100100

View full report

@socket-security-staging

socket-security-staging Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Updatedpypi/​socketdev@​3.6.2 ⏵ 3.6.398100100100100

View full report

@lelia

lelia commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous 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.
@lelia
lelia deployed to socket-firewall November 20, 2026 22:26 — with GitHub Actions Active
@lelia
lelia deployed to socket-firewall November 20, 2026 22:27 — with GitHub Actions Active
@lelia

lelia commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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.

@lelia
lelia merged commit 90d2a40 into main Nov 20, 2026
29 checks passed

This branch was successfully deployed

1 active deployment
socket-firewall — 23695794 Deployed Nov 20, 2026 by lelia via python-sfw-smoke-enterprise #218
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants