You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit db69ae4
Browse filesBrowse the repository at this point in the historyBrowse files
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.
|`GET orgs/{org}/full-scans/{id}`| Resolve a baseline for `--base-scan-id` / `--base-commit-sha`|
30
-
31
-
### Which scopes to grant
15
+
|`repo:list`| Looking up the repository and its head scan, on every run |
16
+
|`repo:create`| Creating the repository on its first scan. Without it, a scan of a repository Socket has not seen yet exits `2`; see [below](#a-missing-repository-permission-can-exit-2)|
17
+
|`full-scans:create`| Creating the scan, on every run. `--reach` also uploads manifests and finalizes the reachability scan under this scope |
18
+
|`full-scans:list`| Every comparison, the `--base-commit-sha` lookup, and fetching scan contents for `--enable-json`, `--enable-sarif`, `--enable-gitlab-security` and `--generate-license` on a full scan |
19
+
|`diff-scans:create`| Creating the comparison on a diff-producing run |
20
+
|`diff-scans:list`| Polling for the comparison, and finding an existing one |
21
+
|`packages:list`|`--generate-license` only |
22
+
23
+
The scopes each endpoint checks are listed in the
24
+
[API reference](https://docs.socket.dev/reference). A few calls check no scope and work
25
+
with any valid token for the organization: `GET organizations`, `GET report/supported`,
26
+
and the telemetry event posted when someone replies to a Socket comment with an ignore
27
+
command.
28
+
29
+
### The CI/CD setup guide's list is incomplete for this CLI
32
30
33
31
The [CI/CD token setup guide](https://docs.socket.dev/docs/create-socket-api-key-for-cicd)
|`--enable-json` / `--enable-sarif` / `--enable-gitlab-security` on a full scan |`GET orgs/{org}/full-scans/{id}` (metadata), full-scan stream, and `POST license-metadata` for every package that carries a license |
75
-
|`--sbom-file`|`GET orgs/{org}/export/cdx/{id}`|
50
+
Every run:
51
+
52
+
| API call | Scope | Purpose |
53
+
|:---|:---|:---|
54
+
|`GET organizations`| none | Resolve the org ID and slug from the token |
55
+
|`GET report/supported`| none | Fetch supported manifest patterns. On failure the CLI uses a bundled list that covers fewer ecosystems |
56
+
|`GET orgs/{org}/repos/{repo}`|`repo:list`| Look up the repository and its head scan |
57
+
|`POST orgs/{org}/repos`|`repo:create`| Create the repository, **only attempted if the lookup above fails**|
58
+
|`POST orgs/{org}/full-scans`|`full-scans:create`| Create the new scan, and the temporary empty baseline on a first scan |
59
+
60
+
Diff-producing runs (see [which runs compare](#apiaccessdenied-on-the-scan-comparison)) add:
61
+
62
+
| API call | Scope | Purpose |
63
+
|:---|:---|:---|
64
+
|`POST orgs/{org}/diff-scans/from-ids`|`diff-scans:create` and `full-scans:list`| Create the comparison (preferred path) |
65
+
|`GET orgs/{org}/diff-scans`|`diff-scans:list`| Find the existing comparison when creation returns 409 |
66
+
|`GET orgs/{org}/diff-scans/{id}`|`diff-scans:list`| Poll for the computed comparison |
|`--enable-json`, `--enable-sarif`, `--enable-gitlab-security` or `--generate-license` on a full scan |`GET orgs/{org}/full-scans/{id}` (scan contents) |`full-scans:list`|
77
+
78
+
`--reach` also runs the Coana CLI with the same token, and its reachability calls
79
+
check `full-scans:create`.
76
80
77
81
## `APIAccessDenied` on the scan comparison
78
82
79
83
Any run that produces a diff first tries the diff-scans endpoints. A token without the
80
-
`diff-scans:*`permissions logs a warning and silently continues on the older path:
84
+
`diff-scans:*`scopes logs a warning and continues on the older path:
81
85
82
86
```
83
87
Diff scan comparison failed with APIAccessDenied(Insufficient permissions), falling back to the streaming scan comparison
@@ -98,10 +102,10 @@ Before 2.9.0 an SCM-integrated branch push also compared, so a pipeline scanning
98
102
pushes (`--pr-number 0 --default-branch`) hit this too. If you are diagnosing an older
99
103
run, that is why the warning can appear in a log with no pull request in sight.
100
104
101
-
**Which permission is missing.** The fallback path is `GET orgs/{org}/full-scans/diff`,
102
-
a full-scans read. If you see the fallback produce results, your token already has
103
-
full-scans read, and the missing grants are the two `diff-scans:*` permissions — not
104
-
`full-scans:list`. If the fallback *also* fails, the gap is broader.
105
+
**Which scope is missing.** The fallback calls `GET orgs/{org}/full-scans/diff`, which
106
+
checks `full-scans:list`. If the fallback produces results, the token already has
107
+
`full-scans:list`, so the missing grant is `diff-scans:create`, `diff-scans:list`, or
108
+
both. If the fallback also fails, `full-scans:list`is missing too.
105
109
106
110
**Why the diff-scans path is preferred.** It polls with short, bounded requests rather
107
111
than holding one connection open while the backend computes, which is what lets large
@@ -124,9 +128,16 @@ interrupt. That exit also bypasses `--disable-blocking` and `--exit-code-on-api-
124
128
so it fails the pipeline even when you have asked for infrastructure errors to be
125
129
non-blocking.
126
130
127
-
If a job dies with exit 2 and `Failed to create repository` or `API failure while
128
-
creating repository` in the log, check the token's repository permissions before
129
-
looking anywhere else.
131
+
This usually happens on the first scan of a repository Socket has not seen, when the
132
+
token lacks `repo:create`. A token without `repo:list` can end up here even for
133
+
a repository that exists, because its lookup fails and the CLI then tries to create it. The log shows `API failure while creating repository`, and on a
134
+
403 adds:
135
+
136
+
```
137
+
A 403 here usually means the API token is missing the repo:create scope.
138
+
```
139
+
140
+
Grant `repo:create`, or create the repository in Socket before the first pipeline run.
130
141
131
142
## Baseline scans that do not appear in the dashboard
132
143
@@ -135,6 +146,7 @@ the CLI creates a **temporary empty baseline** and compares to that:
135
146
136
147
```
137
148
No previous scan found - creating empty baseline scan
0 commit comments