Repository navigation
Improve documentation for requisite API token permissions - #353
Conversation
|
bugbot run |
72c2f29 to
69f8871
Compare
c7b9938 to
a1c1ae4
Compare
|
bugbot run |
PR SummaryLow Risk Overview README, cli-reference, and ci-cd now point at that guide, document the four accepted token env vars and their priority ( The pinned Reviewed by Cursor Bugbot for commit a94259c. Configure here. |
|
bugbot run |
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.
5fc3b67 to
70d1e35
Compare
Eric Hibbs (flowstate)
left a comment
There was a problem hiding this comment.
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?
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.
|
Thanks for the careful pass. Every inline note checked out against 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 ( Two things changed beyond the inline notes, both from the same root cause of describing missing scopes as mostly degrading:
|
|
bugbot 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.
|
bugbot run |
Eric Hibbs (flowstate)
left a comment
There was a problem hiding this comment.
Re-checked 423672c against socketsecurity/ and the api-v0 handlers. The scope table, baseline and fallback sections now match the code.
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.
|
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 |
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 a94259c. Configure here.
Why
Before this PR, the repo said one thing about token permissions: a troubleshooting note on the diff-scans comparison. That note described the
APIAccessDeniedfallback 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:createanddiff-scans:list. Every run that compares scans calls the diff-scans endpoints first, so a token with only those nine scopes getsAPIAccessDeniedthere and falls back to the streaming comparison. The only sign is a warning in the log.The list also has four scopes
socketclinever uses:repo:update,security-policy:read,triage:alerts-listandtriage: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.mdcarries the substance:diff-scansscopes degrade to a warning. A missingfull-scans:create,full-scans:list,repo:list,repo:createorpackages:listfails the run that needs it, with the API-error exit code.APIAccessDeniedfallback. Which runs compare, and how to tell which scope is missing.mainfrom 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.full-scanscovers its scopes. A token restricted to specific repositories can't set up a new repository or use--generate-license.Supporting changes:
README.md,docs/cli-reference.mdanddocs/ci-cd.md.$SOCKET_API_TOKEN. It now saysSOCKET_SECURITY_API_TOKEN.One dependency change rides along: the pinned Socket Python SDK moves from
socketdev==3.6.2to3.6.3. That release fixessettings.integration_events(), which the CLI does not call, so CLI behavior is unchanged. The lockfile diff is limited tosocketdev, 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/artifactsacceptsfull-scans:createorfixes:list. The calls were traced throughsocketsecurity/and re-checked against 2.13.0 after mergingmain, covering the SDK calls, the directCliClientrequests (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:updateis never used.POST full-scanschecks onlyfull-scans:create, even when it sets the repository head.scan_typeis always set, so the CLI lists full scans on the default branch and takes the newest match. That listing needsfull-scans:list, and a denied listing exits with the API-error code before any comparison.--sbom-filemakes no API call. The CycloneDX export it was once mapped to has no caller.--strict-blocking,--enable-gitlab-securityand--legal-format fossaread the new full scan on a run that compares scans, to get alerts on unchanged packages. That call is in the flags table underfull-scans:list.GET organizationsand the ignore-comment telemetry post check no scope.GET report/supportedneeds no token.Notes for the reviewer
--strict-blocking, streamline exit code behavior #453 landed first, as 2.13.0. This branch hasmainmerged in. The repository lookup section Fail on existing alerts under--strict-blocking, streamline exit code behavior #453 added todocs/troubleshooting.mdreplaces the one this PR had, and the rest of the text describes 2.13.0 behavior: a failed lookup exits with the API-error code like any other failure, and the repository is created only when the lookup finds none. This PR does not touch the README exit-code table.check_versionis a required, unfiltered check that wants a version ahead of PyPI (2.13.0 is published), and the release now also carries the SDK bump. If another release lands first, this needs another bump.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