From 66eba3564e71c28090ef50f89a7c9f223f3adcaa Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Fri, 13 Nov 2026 21:00:41 -0500 Subject: [PATCH] docs: List the API token scopes Socket Basics needs 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 --- README.md | 14 +++-- docs/github-action.md | 15 ++--- docs/local-install-docker.md | 7 ++- docs/parameters.md | 108 +++++++++++++++++++++++++++++++++-- 4 files changed, 123 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 8a3cffa..041c403 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ Socket Enterprise customers can configure Socket Basics directly from the [Socke ![Socket Basics Settings](docs/screenshots/socket_basics_settings.png) -Configure scanning policies, notification channels, and rule sets for your entire organization in one place. Socket Basics loads these settings on every run when its API key has the `socket-basics` scope, and they take precedence over the matching workflow inputs, including fields you leave blank. See [Dashboard Settings and Workflow Inputs](docs/github-action.md#dashboard-settings-and-workflow-inputs) for the exceptions and for setting values per repository. +Configure scanning policies, notification channels, and rule sets for your entire organization in one place. Socket Basics loads these settings on every run when its API key has the `socket-basics:read` scope, and they take precedence over the matching workflow inputs, including fields you leave blank. See [Dashboard Settings and Workflow Inputs](docs/github-action.md#dashboard-settings-and-workflow-inputs) for the exceptions and for setting values per repository. ![Socket Basics Section Config](docs/screenshots/socket_basics_section_config.png) @@ -164,12 +164,14 @@ Create your `SOCKET_SECURITY_API_KEY` in the [Socket Dashboard](https://socket.d | Scope | Required for | |-------|--------------| -| `full-scans` | Submitting scan results to your organization | -| `socket-basics` | Loading scanner configuration from the Socket Dashboard | +| `full-scans:create` | Submitting scan results to your organization, and running Socket Tier 1 reachability | +| `socket-basics:read` | Loading scanner configuration from the Socket Dashboard (Enterprise organizations) | -If Socket Basics is configured from the Socket Dashboard, the `socket-basics` scope is required. If it is missing, you will see `Insufficient permissions` when Socket Basics loads dashboard configuration. +If Socket Basics is configured from the Socket Dashboard, `socket-basics:read` is required. If it is missing, the log shows `Insufficient permissions` and `Error loading Socket Basics config`, and the scan runs with the workflow inputs alone. On an Enterprise organization the organization is then not discovered from the key either, so results are not uploaded unless `SOCKET_ORG` is set. -If Socket Basics is configured with CLI arguments, environment variables, or a JSON config file, only `full-scans` permissions are required for result submission. Set `SOCKET_ORG` explicitly in your workflow when using this mode. +If Socket Basics is configured with CLI arguments, environment variables, or a JSON config file, only `full-scans:create` is required. Set `SOCKET_ORG` explicitly in your workflow when using this mode. + +A missing scope does not change the exit code. See [API token scopes](docs/parameters.md#api-token-scopes) for every Socket API call Socket Basics makes and the scope each one checks. ## 💻 Other Usage Methods @@ -270,7 +272,7 @@ Add new connectors by: **Socket API errors / results missing from the dashboard:** - Ensure `SOCKET_SECURITY_API_KEY` and `SOCKET_ORG` are set correctly -- `No Socket organization configured` in the log means nothing was uploaded: set `SOCKET_ORG`, or use a key with the `socket-basics` scope so the organization can be discovered +- `No Socket organization configured` in the log means nothing was uploaded: set `SOCKET_ORG`, or use a key with the `socket-basics:read` scope so the organization can be discovered - `Need at least one file to be uploaded` means the facts file was written outside the scanned workspace; keep `--output` inside it (see [Save Results to File](docs/local-install-docker.md#save-results-to-file)) - Verify your Socket Enterprise subscription is active - If you see `Insufficient permissions`, confirm your API token has the scopes required for your configuration mode (see [Required API Token Scopes](#required-api-token-scopes)) diff --git a/docs/github-action.md b/docs/github-action.md index 64f7bc5..1409ae8 100644 --- a/docs/github-action.md +++ b/docs/github-action.md @@ -210,7 +210,7 @@ Include these in your workflow's `jobs..permissions` section. - Without it the scan still runs and comments on the PR, but nothing reaches the Socket dashboard. **`socket_org`** (optional) -- Discovered from the API key when the key has the `socket-basics` scope. Set it +- Discovered from the API key when the key has the `socket-basics:read` scope. Set it explicitly when configuring the scan from `with:` inputs instead of the dashboard. - Outside the action the same value is `SOCKET_ORG` or `--socket-org`. See the [name mapping](parameters.md#name-mapping) for the equivalents of every input. @@ -498,7 +498,7 @@ The dashboard configuration loads when all three of these are true: - The organization is on a Socket Enterprise plan. - Socket Basics is enabled for the organization. -- The API key has the `socket-basics` scope. +- The API key has the `socket-basics:read` scope. Fields you leave blank in the dashboard still count. The dashboard sends a blank field as an empty value and a switched-off toggle as `false`, and either one @@ -1112,11 +1112,12 @@ env: **Solutions:** 1. Provide `socket_security_api_key`. Without it the scan runs locally only. 2. Check the log for `No Socket organization configured`. Either set `socket_org` - or use an API key with the `socket-basics` scope so the organization can be - discovered from the key. -3. Check the token scopes: `full-scans` is required to upload; - `socket-basics` is required to load dashboard configuration. `Insufficient - permissions` in the log means a scope is missing. + or use an API key with the `socket-basics:read` scope so the organization can + be discovered from the key. +3. Check the token scopes: `full-scans:create` is required to upload; + `socket-basics:read` is required to load dashboard configuration. + `Insufficient permissions` in the log means a scope is missing. See + [API token scopes](parameters.md#api-token-scopes). 4. `pr_comment_enabled: 'false'` does **not** affect the upload; results still reach the dashboard. diff --git a/docs/local-install-docker.md b/docs/local-install-docker.md index 8ffc93c..f90375b 100644 --- a/docs/local-install-docker.md +++ b/docs/local-install-docker.md @@ -785,12 +785,13 @@ security-scan: 1. `Need at least one file to be uploaded` in the log: the facts file was written outside the workspace. Use a path under `/workspace` for `--output`. 2. `No Socket organization configured` in the log: set `SOCKET_ORG`, or use an - API key with the `socket-basics` scope so the organization can be discovered. + API key with the `socket-basics:read` scope so the organization can be discovered. 3. `Socket API key not detected - running in free plan mode`: the key did not reach the container. Check the `.env` file or `-e` flags and the variable name (`SOCKET_SECURITY_API_KEY`). -4. `Insufficient permissions`: the key is missing the `full-scans` scope (upload) - or the `socket-basics` scope (dashboard configuration). +4. `Insufficient permissions`: the key is missing the `full-scans:create` scope + (upload) or the `socket-basics:read` scope (dashboard configuration). See + [API token scopes](parameters.md#api-token-scopes). ### PR Comment Not Posted diff --git a/docs/parameters.md b/docs/parameters.md index 86b4794..5c77d80 100644 --- a/docs/parameters.md +++ b/docs/parameters.md @@ -37,7 +37,7 @@ GitHub Action input is delivered to the container as the environment variable | `--console-tabular-enabled` | `console_tabular_enabled` | `INPUT_CONSOLE_TABULAR_ENABLED` | `console_tabular_enabled` | Print consolidated findings as tables. | | `--console-json-enabled` | `console_json_enabled` | `INPUT_CONSOLE_JSON_ENABLED` | `console_json_enabled` | Print consolidated findings as JSON. | | `--socket-org` | `socket_org` | `SOCKET_ORG` (also `SOCKET_ORG_SLUG`, `INPUT_SOCKET_ORG`) | `socket_org` | Socket organization slug. Not the same thing as `--repo`. | -| —2 | `socket_security_api_key` | `SOCKET_SECURITY_API_KEY` (also `SOCKET_SECURITY_API_TOKEN`, `SOCKET_API_KEY`, `INPUT_SOCKET_SECURITY_API_KEY`) | `socket_api_key`3 | Socket API key (`full-scans` scope to upload, `socket-basics` scope to load dashboard config). | +| —2 | `socket_security_api_key` | `SOCKET_SECURITY_API_KEY` (also `SOCKET_SECURITY_API_TOKEN`, `SOCKET_API_KEY`, `INPUT_SOCKET_SECURITY_API_KEY`) | `socket_api_key`3 | Socket API key (`full-scans:create` scope to upload, `socket-basics:read` scope to load dashboard config; see [API token scopes](#api-token-scopes)). | | `--repo` | — | `GITHUB_REPOSITORY` | `repo` | `owner/repo` recorded on the scan and used to find the PR. Discovered from git when omitted. | | `--branch` | — | `GITHUB_HEAD_REF`, `GITHUB_REF_NAME` | `branch` | Branch recorded on the scan. Discovered from git when omitted. | | `--pull-request` | — | `GITHUB_PR_NUMBER` (also `INPUT_PR_NUMBER`) | — | PR number. The PR notifier reads the environment variable. | @@ -701,12 +701,110 @@ export SOCKET_SECURITY_API_KEY="scrt_..." socket-basics --socket-org your-org-slug --python --secrets ``` -The key needs the `full-scans` scope to upload results and the `socket-basics` -scope to load dashboard configuration. With the latter the organization is -discovered from the key; otherwise set `SOCKET_ORG` explicitly or the run logs +The key needs `full-scans:create` to upload results and `socket-basics:read` +to load dashboard configuration; see [API token scopes](#api-token-scopes). +When `SOCKET_ORG` is not set, the organization is discovered from the key. On +an Enterprise organization that discovery is lost if the key lacks +`socket-basics:read`, so set `SOCKET_ORG` explicitly or the run logs `No Socket organization configured` and uploads nothing. `--repo` names the repository, not the organization. +### API token scopes + +Socket Basics authenticates with a single Socket organization API token. A +token missing a scope does **not** fail the run. Each Socket API call that is +denied logs an error or a warning and the scan continues, so check the log +rather than the exit code. + +#### Scopes to grant + +For a least-privilege token, grant these: + +| Scope | Needed for | +|:---|:---| +| `full-scans:create` | Uploading results to the Socket dashboard. Socket Tier 1 also needs it to upload manifests and record the reachability scan | +| `socket-basics:read` | Loading scanner configuration from the Socket dashboard, on Enterprise organizations. Without it on an Enterprise organization, the organization is also not discovered from the key | + +The scopes each endpoint checks are listed in the +[API reference](https://docs.socket.dev/reference). A few calls check no scope +and work with any valid token for the organization: `GET organizations` and +`GET orgs/{org}/supported-files`. + +Socket Basics does not use the `repo:*`, `full-scans:list`, `diff-scans:*`, +`packages:list`, `security-policy:read` or `triage:*` scopes. It never looks up +or creates the repository with a separate call. The repository name travels as +a parameter of the scan upload. + +The [CI/CD token setup guide](https://docs.socket.dev/docs/create-socket-api-key-for-cicd) +is written for the Socket CLIs. Its list includes `full-scans:create`, so a +token made from it can upload results, but it does not include +`socket-basics:read`. Add that scope to load dashboard configuration. + +#### API calls by run type + +**Dashboard configuration**, at startup on every run where the key is set and +no `--config` file is given: + +| API call | Scope | Purpose | +|:---|:---|:---| +| `GET organizations` | none | Find the organization (the one named by `SOCKET_ORG`, or the first one the key belongs to) and its plan | +| `GET orgs/{org}/settings/socket-basics` | `socket-basics:read` | Load the dashboard configuration. **Only called when the plan is Enterprise** | + +This step reads the key from `SOCKET_SECURITY_API_KEY`, +`SOCKET_SECURITY_API_TOKEN` or `INPUT_SOCKET_SECURITY_API_KEY` only. A key set +only as `SOCKET_API_KEY` or `INPUT_SOCKET_API_KEY` is used for uploads and +Tier 1 but skips this step. + +If either call fails, the log shows `Error loading Socket Basics config` and +the run continues with the environment and workflow inputs alone. Nothing from +this step is kept, including the discovered organization, so set `SOCKET_ORG` +when the key lacks `socket-basics:read`. When the settings call is denied for a +missing scope, the error logged just before it starts with +`Insufficient permissions`. + +**Result upload**, after the scanners finish: + +| API call | Scope | Purpose | +|:---|:---|:---| +| `POST orgs/{org}/full-scans` | `full-scans:create` | Upload `.socket.facts.json` as a full scan | + +The upload is skipped, without calling the API, when the facts file has no +components, when no key or organization is configured, or when +`SKIP_SOCKET_SUBMISSION=1`. If the repository does not exist in Socket yet, the +upload creates it, and an organization API token needs no scope beyond +`full-scans:create` for that. A denied upload logs +`Failed to submit socket facts file` and does not change the exit code. + +**Socket Tier 1** (`--socket-tier1`), unless `SKIP_SOCKET_REACH=1`. Socket +Basics runs the Socket npm CLI (`socket scan reach --org `), which makes +these calls with the same token: + +| API call | Scope | Purpose | +|:---|:---|:---| +| `GET organizations` | none | Check that the organization is on an Enterprise plan | +| `GET orgs/{org}/supported-files` | none | Fetch the supported manifest file patterns | +| `POST orgs/{org}/coana-cli/artifacts` | none | Find the reachability engine download. Only called when the engine is not cached, which is every run in a fresh container (see [Network access for Tier 1](#network-access-for-tier-1)) | +| `POST orgs/{org}/upload-manifest-files` | `full-scans:create` | Upload the manifests for analysis | +| `POST tier1-reachability-scan/finalize` | `full-scans:create` | Mark the reachability scan done. A failure here only logs a warning | + +The reachability engine (Coana) runs with the same token, and its calls check +`full-scans:create`. The `coana-cli/artifacts`, `upload-manifest-files` and +`tier1-reachability-scan/finalize` endpoints are not in the public API +reference. Options passed through +`socket_additional_params` can make further calls that this table does not +cover. + +A Tier 1 failure logs `Error running connector socket_tier1` and does not +change the exit code. 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 of them is set in +the environment. If you set more than one of these, give them the same token. + +The heavy image's Python CLI (`socketcli`) is a separate tool that Socket +Basics does not run. For the scopes it needs, see +[API token permissions](https://github.com/SocketDev/socket-python-cli/blob/main/docs/troubleshooting.md#api-token-permissions) +in its documentation. + ### `--socket-tier1` Enable Socket Tier 1 reachability analysis for dependency scanning. @@ -1021,7 +1119,7 @@ Configuration is merged in the following order (later sources override earlier o 1. Default values 2. Environment variables, including GitHub Action inputs (the action passes each `with:` input as an `INPUT_*` variable) -3. Socket Basics dashboard configuration (when the organization is on an Enterprise plan with Socket Basics enabled, the API key has the `socket-basics` scope, and no `--config` file is used) +3. Socket Basics dashboard configuration (when the organization is on an Enterprise plan with Socket Basics enabled, the API key has the `socket-basics:read` scope, and no `--config` file is used) 4. JSON configuration file (via `--config`) 5. Command-line arguments