Skip to content

Improve documentation for requisite API token permissions - #353

Merged
lelia merged 12 commits into
mainfrom
lelia/api-scope-docs-audit
Nov 20, 2026
Merged

lelia merged 12 commits into
mainfrom
lelia/api-scope-docs-audit

Conversation

@lelia

@lelia lelia commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

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 never listed the scopes a run needs, or what happens without each one, so a token couldn't be provisioned from the docs.

Tokens made from the setup guide's nine-scope list

The CI/CD token setup guide lists nine scopes. It leaves out diff-scans:create and diff-scans:list. Every run that compares scans calls the diff-scans endpoints first, so a token with only those nine scopes gets APIAccessDenied there and falls back to the streaming comparison. The only sign is a warning in the log.

The list also has four scopes socketcli never uses: repo:update, security-policy:read, triage:alerts-list and triage:alerts-update.

This PR documents the gap for CLI users. SocketDev/docs#195 fixes the guide itself. The docs here describe tokens made from that list instead of the guide's current contents, so they stay true once the guide changes.

What changed

docs/troubleshooting.md carries the substance:

  • Scopes to grant. The least-privilege set, what each scope is for, and what happens without it. Only the two diff-scans scopes degrade to a warning. A missing full-scans:create, full-scans:list, repo:list, repo:create or packages:list fails the run that needs it, with the API-error exit code.
  • API calls by run type. Every run, runs that compare scans, and per flag, each with the scope its endpoint checks.
  • The APIAccessDenied fallback. Which runs compare, and how to tell which scope is missing.
  • Repository lookup failures. Already on main from Fail on existing alerts under --strict-blocking, streamline exit code behavior #453, which this PR's scope table links to: the two messages, the scope each points at, and the pre-2.13.0 behavior.
  • How the baseline is chosen. The newest scan of the same type on the default branch, and when an empty baseline is created instead.
  • Scope groups and repository-restricted tokens. A group such as full-scans covers its scopes. A token restricted to specific repositories can't set up a new repository or use --generate-license.

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.

One dependency change rides along: the pinned Socket Python SDK moves from socketdev==3.6.2 to 3.6.3. That release fixes settings.integration_events(), which the CLI does not call, so CLI behavior is unchanged. The lockfile diff is limited to socketdev, and the full test suite passes on it (992 passed).

How the mapping was verified

Each scope is the one the API's route handler checks, read from the handlers and not only from the API reference. That matters for routes that authenticate at the route and check scopes inside the handler: POST orgs/{org}/coana-cli/artifacts accepts full-scans:create or fixes:list. The calls were traced through socketsecurity/ and re-checked against 2.13.0 after merging main, covering the SDK calls, the direct CliClient requests (python-cli-runs, coana-cli/artifacts, telemetry), and the flow that decides between a comparison and a full scan.

Points worth a reviewer's eye, because they differ from what the names suggest:

  • repo:update is never used. POST full-scans checks only full-scans:create, even when it sets the repository head.
  • The baseline is not the repository's head-scan pointer. scan_type is always set, so the CLI lists full scans on the default branch and takes the newest match. That listing needs full-scans:list, and a denied listing exits with the API-error code before any comparison.
  • --sbom-file makes no API call. The CycloneDX export it was once mapped to has no caller.
  • --strict-blocking, --enable-gitlab-security and --legal-format fossa read the new full scan on a run that compares scans, to get alerts on unchanged packages. That call is in the flags table under full-scans:list.
  • GET organizations and the ignore-comment telemetry post check no scope. GET report/supported needs no token.

Notes for the reviewer

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.

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

@lelia lelia changed the title Document the API token permissions a run actually needs Improve documentation for requisite API token permissions Sep 11, 2026
@lelia

lelia commented Sep 11, 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.

@lelia
lelia force-pushed the lelia/api-scope-docs-audit branch from 72c2f29 to 69f8871 Compare September 23, 2026 21:51
@lelia
lelia temporarily deployed to socket-firewall September 23, 2026 21:53 — with GitHub Actions Inactive
@lelia
lelia force-pushed the lelia/api-scope-docs-audit branch from c7b9938 to a1c1ae4 Compare November 14, 2026 01:53
@lelia
lelia temporarily deployed to socket-firewall November 14, 2026 01:53 — with GitHub Actions Inactive
@lelia
lelia marked this pull request as ready for review November 14, 2026 02:39
@lelia
lelia requested a review from a team as a code owner November 14, 2026 02:39
@lelia
lelia temporarily deployed to socket-firewall November 14, 2026 02:39 — with GitHub Actions Inactive
@lelia

lelia commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor

cursor Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

PR Summary

Low Risk
Documentation and a patch SDK bump only; no CLI logic changes beyond version pins.

Overview
Release 2.13.1 is mostly documentation: a new API token permissions guide that maps least-privilege scopes, failure modes, and API calls by run type and flag. It calls out that the common nine-scope CI/CD token list is missing diff-scans:create and diff-scans:list, so comparison runs degrade to the streaming path with only a warning, and it adds sections on comparison fallback behavior, baseline scan selection, and reachability scan IDs versus full-scan IDs.

README, cli-reference, and ci-cd now point at that guide, document the four accepted token env vars and their priority (SOCKET_SECURITY_API_KEY first), and fix the GitLab requirements example to use SOCKET_SECURITY_API_TOKEN.

The pinned socketdev dependency moves from 3.6.2 to 3.6.3 (lockfile + pyproject.toml); the changelog notes this does not affect CLI behavior because the fixed SDK method is unused here.

Reviewed by Cursor Bugbot for commit a94259c. Configure here.

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

Comment thread CHANGELOG.md Resolved
@lelia
lelia temporarily deployed to socket-firewall November 14, 2026 03:31 — with GitHub Actions Inactive
@lelia
lelia temporarily deployed to socket-firewall November 14, 2026 03:43 — with GitHub Actions Inactive
@lelia
lelia temporarily deployed to socket-firewall November 14, 2026 03:52 — with GitHub Actions Inactive
@lelia

lelia commented Nov 14, 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.

lelia and others added 8 commits November 17, 2026 16:24
The only scope guidance in the repo covered the diff-scans comparison path,
described it as PR/MR-only, and listed `full-scans:list` alongside the two
`diff-scans:*` scopes. The comparison also runs on plain pushes, and the
streaming fallback is itself a full-scans read, so a reader hitting the
`APIAccessDenied` warning was pointed at the wrong permission and told the
condition did not apply to them.

Replace it with the full picture: what every run calls, what diff-producing
runs add, and what each flag adds. Scope names are only published for the
diff-scans path, so the rest are described by endpoint rather than guessed at.

Also document three outcomes that look like failures and are not: the
temporary empty baseline on a first scan, the reachability scan ID being a
`tier1ReachabilityScanId` rather than a full scan ID, and a repository
permission gap exiting 2 — a code the exit table documents as a keyboard
interrupt, and which bypasses `--disable-blocking` and
`--exit-code-on-api-error`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The permission tables described endpoints but deferred on scope names, since
nothing in this repo or the SDK publishes them. The public CI/CD token setup
guide does: nine scopes, which the docs now name and map to the calls they
cover.

That guide omits `diff-scans:create` and `diff-scans:list`. Every
diff-producing run tries the diff-scans endpoints first, so a token
provisioned exactly as documented always fails that call and falls back to the
legacy streaming comparison, with a warning as the only signal. Anyone
following the documented setup hits this.

The converse is also worth stating: `socketcli` makes no triage or
security-policy calls, so three of the nine scopes the guide lists are not
exercised by this CLI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
now sends only a "diff" event type to create_new_diff and everything else,
default-branch pushes included, to create_full_scan_with_report_url.

The permission docs asserted the opposite -- that plain pushes also reach the
diff-scans path -- which was true when they were written against 2.8.1 and is
not true now. Replace the claim with a table of which runs compare, and keep
the old behavior as a note, since the warning still shows up in logs from
pre-2.9.0 runs with no pull request in sight.

Re-verified the rest against 2.9.7: SDK call surface, the four sys.exit(2)
sites, the temporary empty baseline, and the reachability scan ID are all
unchanged.
The scope tables were inferred from scope names. The API reference
publishes the scope each endpoint checks, so the tables now use those and
the open question about unpublished scopes is resolved: GET organizations,
GET report/supported and the ignore-comment telemetry post check none.

Rechecking the call surface against 2.12.0 also changed the guidance:
- repo:update is never exercised. POST full-scans checks only
  full-scans:create, including when it sets the repository head.
- --sbom-file makes no API call; the CycloneDX export it was mapped to
  has no caller. License-metadata and full-scan metadata reads are
  likewise unreached outside tests.
- diff-scans/from-ids checks full-scans:list as well as
  diff-scans:create.
- --reach's manifest upload and tier-1 finalize check
  full-scans:create, as do the Coana CLI's reachability calls.
- The exit-2 section now quotes the repo:create hint the CLI logs on a
  403.
Only a diff-producing run that takes its baseline from the repository's
head scan looks the repository up, and so only that run can create it
or exit 2. A full-scan run uploads straight to full-scans, which creates
a missing repository for an organization-wide token. A failed streaming
fallback also only points at full-scans:list when it fails with
Insufficient permissions.
A failed GET report/supported raises from the SDK and stops the run; the
bundled pattern list only covers a non-error response with no body. An
empty baseline is created when the repository has no head scan, not on
every new branch, since a branch compares against the repository's head
scan.
@lelia
lelia force-pushed the lelia/api-scope-docs-audit branch from 5fc3b67 to 70d1e35 Compare November 17, 2026 21:25
@lelia
lelia temporarily deployed to socket-firewall November 17, 2026 21:25 — with GitHub Actions Inactive

@flowstate Eric Hibbs (flowstate) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Checked the scope list and call tables against socketsecurity/ at this head and the api-v0 handlers. The scope set is right, and a token built from it works. The notes inline are about how the CLI behaves when a scope is missing, plus the overlap with #453.

One general question: repository-scoped tokens. The API rejects them on POST orgs/{org}/repos (no supportsGrantBasedTokens), on POST full-scans for a repository that doesn't exist yet, and on POST orgs/{org}/purl. So a repository-scoped token can't onboard a new repository, whatever scopes it has. Worth a sentence?

Comment thread docs/troubleshooting.md Resolved
Comment thread docs/troubleshooting.md Resolved
Comment thread docs/troubleshooting.md Resolved
Comment thread docs/troubleshooting.md Resolved
Comment thread docs/troubleshooting.md Resolved
A missing scope was described as mostly degrading with a warning. Only
the two diff-scans scopes do that. The others fail the run:

- full-scans:list is needed before any comparison. scan_type is always
  set, so the baseline is the newest matching scan listed from the
  default branch, not the repository's head-scan pointer, and a denied
  listing exits with the API-error code. The same listing explains when
  an empty baseline is created.
- The scope table now says what happens without each scope.

Calls the tables missed: POST python-cli-runs (and its logs and
finalize calls) on every run, and POST coana-cli/artifacts under
--reach, which accepts full-scans:create or fixes:list. GET
report/supported needs no token, and the streaming fallback endpoint is
deprecated in the API.

Also covered: scope groups, tokens restricted to specific repositories,
comment events, and the flags that force a comparison.

The README exit-code table is left alone. The repository-failure section
keeps the exit-2 details under "2.12.x and earlier", so it stays true
when the exit-code contract changes. The setup-guide paragraphs describe
tokens made from its nine-scope list instead of the guide's current
contents, which are about to change.
@lelia
lelia temporarily deployed to socket-firewall November 18, 2026 19:53 — with GitHub Actions Inactive
@lelia

lelia commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the careful pass. Every inline note checked out against socketsecurity/ and the API handlers, and they are all addressed in 423672c, with replies on each thread.

On repository-scoped tokens: yes, worth a sentence. There is now a short paragraph under the scope table. A token restricted to specific repositories cannot set up a new repository (POST orgs/{org}/repos rejects it, and POST orgs/{org}/full-scans will not create a missing repository for it), and it cannot use --generate-license, because POST orgs/{org}/purl rejects it too.

Two things changed beyond the inline notes, both from the same root cause of describing missing scopes as mostly degrading:

  • The intro and the pointers in README.md, docs/cli-reference.md and docs/ci-cd.md now say that most missing scopes fail the run and only the diff-scans pair falls back.
  • The setup-guide paragraphs describe tokens made from its nine-scope list, not the guide as it reads today, so they stay accurate once SocketDev/docs#195 changes the guide.

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

main released 2.12.2 and 2.13.0. The docs ship as 2.13.1, with their
changelog entry above 2.13.0.

2.13.0 changed the behavior these docs described for 2.12.x:

- The repository lookup section on main, which covers the 2.13.0
  messages and exit code, replaces this branch's 2.12.x section.
- A failed repository lookup is no longer an exception to the
  API-error exit code, and creation is attempted only when the lookup
  finds no repository.
- --strict-blocking, --enable-gitlab-security and --legal-format fossa
  read the new full scan on a comparing run, so the flags table lists
  that call under full-scans:list.
@lelia
lelia temporarily deployed to socket-firewall November 19, 2026 20:52 — with GitHub Actions Inactive
@lelia

lelia commented Nov 19, 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.

@flowstate Eric Hibbs (flowstate) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Re-checked 423672c against socketsecurity/ and the api-v0 handlers. The scope table, baseline and fallback sections now match the code.

@lelia
lelia deployed to socket-firewall November 20, 2026 21:43 — with GitHub Actions Active
socketdev 3.6.3 fixes settings.integration_events(), which requested a
path the API does not route. The CLI does not call it, so nothing
changes at runtime; the pin moves so the CLI ships the current SDK.
@lelia
lelia deployed to socket-firewall November 20, 2026 22:16 — with GitHub Actions Active
@socket-security

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

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.

✅ 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 a94259c. Configure here.

This branch was successfully deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants