diff --git a/CHANGELOG.md b/CHANGELOG.md index ff28e72..ca99993 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## 2.13.1 + +### Documentation + +- New [API token permissions](docs/troubleshooting.md#api-token-permissions) guide: + the scopes `socketcli` needs, what happens without each one, and the API calls + behind them. +- Add `diff-scans:create` and `diff-scans:list` to CI tokens. Without them, scan + comparisons fall back to a less resilient path with only a warning. +- Documented how the baseline scan for a comparison is chosen. +- Listed all four accepted token environment variables in priority order. + +### Changed: bump the Socket Python SDK to 3.6.3 + +- Bumped the pinned Socket Python SDK (`socketdev`) from `3.6.2` to `3.6.3`. + The release fixes `settings.integration_events()`, which the CLI does not + call, so CLI behavior is unchanged. + ## 2.13.0 ### Upgrade notes diff --git a/README.md b/README.md index 831c0c0..aa22735 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ pip install socketsecurity export SOCKET_SECURITY_API_TOKEN="" ``` +The token needs more than scan-creation access. Most missing scopes fail the run, and +a token without the `diff-scans` scopes falls back with only a warning. See +[`docs/troubleshooting.md#api-token-permissions`](https://github.com/SocketDev/socket-python-cli/blob/main/docs/troubleshooting.md#api-token-permissions). + ### 3) Run a basic scan ```bash diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 88210ed..3282778 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -661,3 +661,12 @@ Prebuilt examples in this repo: the console table, including native Buildkite job logs, and in GitHub/GitLab security comments when that SCM adapter is configured. Findings without a known patched release leave the console cell blank and omit the comment field. +- A token missing the `diff-scans:create` and `diff-scans:list` scopes does not fail + the build. It logs + `Diff scan comparison failed with APIAccessDenied(Insufficient permissions)` and falls + back to a less resilient comparison path. This affects every run that compares + scans: PR/MR events, and runs without an SCM integration. An SCM-integrated branch + push creates a full scan and never compares. Tokens created from the nine-scope + list in the CI/CD token setup guide lack both scopes; see + [`troubleshooting.md#api-token-permissions`](troubleshooting.md#api-token-permissions) + for the full scope list and what each missing scope does. diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 066820d..3a9ebab 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -232,6 +232,22 @@ If you don't want to provide the Socket API Token every time then you can use th |:------------|:---------|:--------|:----------------------------------------------------------------------------------| | `--api-token` | False | | Socket Security API token (can also be set via SOCKET_SECURITY_API_TOKEN env var) | +The token is read from the first of these that is set, then from `--api-token`: + +1. `SOCKET_SECURITY_API_KEY` +2. `SOCKET_SECURITY_API_TOKEN` +3. `SOCKET_API_KEY` +4. `SOCKET_API_TOKEN` + +This repository's examples use `SOCKET_SECURITY_API_TOKEN`, and the CI/CD guides on +docs.socket.dev use `SOCKET_SECURITY_API_KEY`. Either works. If both are set, +`SOCKET_SECURITY_API_KEY` wins. + +> **Token permissions:** the CLI needs more than scan-creation access. Most missing +> scopes fail the run, and a token without the `diff-scans` scopes falls back with only +> a warning. See [`troubleshooting.md#api-token-permissions`](troubleshooting.md#api-token-permissions) +> for the scopes to grant, the API calls a run makes, and which flags add to them. + #### Repository | Parameter | Required | Default | Description | |:-----------------|:---------|:--------|:------------------------------------------------------------------------------------------------------------------| @@ -930,7 +946,7 @@ When `--enable-gitlab-security` (or `--enable-json` / `--enable-sarif`) is used ### Requirements - **GitLab Version**: GitLab 12.0 or later (for Security Dashboard support) -- **Socket API Token**: Set via `$SOCKET_API_TOKEN` environment variable or `--api-token` parameter +- **Socket API Token**: Set via `SOCKET_SECURITY_API_TOKEN` environment variable or `--api-token` parameter (see [Authentication](#authentication) for the other accepted variable names) - **CI/CD Artifacts**: Reports must be uploaded as `dependency_scanning` artifacts ### Troubleshooting diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c2a1b02..f26b158 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -28,32 +28,151 @@ Both failures follow `--disable-blocking` and `--exit-code-on-api-error`. Before `repo:list` ended in the `repo:create` message, and the run exited `2` whatever either flag said. -## API token scopes for scan comparisons - -PR/MR runs compare the new scan against the repository's head scan. That comparison -first uses the diff-scans endpoints, which require an organization token with these -scopes in addition to whatever the scan itself needs: - -- `diff-scans:create` -- `diff-scans:list` -- `full-scans:list` - -`full-scans:list` also covers the read of the new full scan that `--strict-blocking`, -`--enable-gitlab-security` and `--legal-format fossa` use to get alerts on unchanged -packages. - -If the token is missing them the scan still succeeds, so this is easy to miss. The only -signal is a warning, after which the CLI falls back to the older streaming comparison: +## API token permissions + +The CLI authenticates with a single Socket organization API token. Most missing scopes +fail the run with an API error. The two `diff-scans` scopes are the exception: without +them the run falls back to an older comparison and only logs a warning. + +### Scopes to grant + +For a least-privilege CI token, grant these: + +| Scope | Needed for | Without it | +|:---|:---|:---| +| `full-scans:create` | Creating the scan, on every run. `--reach` also locates the analysis engine, uploads manifests and records the reachability scan under it | The run fails | +| `full-scans:list` | Finding the baseline scan and comparing against it, on every run that compares scans. Also fetching scan contents for `--enable-json`, `--enable-sarif`, `--enable-gitlab-security` and `--generate-license` on a full scan | Those runs fail | +| `diff-scans:create` | Creating the comparison | The run [falls back](#apiaccessdenied-on-the-scan-comparison) with a warning | +| `diff-scans:list` | Polling for the comparison, and finding an existing one | The same fallback | +| `repo:list` | Looking up the repository's default branch, on runs that compare scans without `--base-scan-id` or `--base-commit-sha` | Those runs fail; see [Repository lookup or creation fails](#repository-lookup-or-creation-fails) | +| `repo:create` | Creating the repository when that lookup finds none | The first comparison for a repository Socket has not seen fails | +| `packages:list` | `--generate-license` only | Those runs fail | + +A failed run exits with the API-error code: `3` by default, the value of +`--exit-code-on-api-error` when set, or `0` with `--disable-blocking`. + +Scopes are grouped by their prefix, and granting a group grants every scope in it: +`full-scans` covers `full-scans:create`, `full-scans:list` and `full-scans:delete`. The +dashboard's token dialog lists each scope under its group. A token with the groups +`full-scans`, `diff-scans`, `repo` and `packages` therefore works too; it just holds +more than this CLI uses. + +The scopes each endpoint checks are listed in the +[API reference](https://docs.socket.dev/reference). `GET organizations` and the +telemetry event posted when someone replies to a Socket comment with an ignore command +check no scope, so any valid token for the organization works. `GET report/supported` +needs no token at all. + +**Tokens restricted to specific repositories** can scan those repositories but cannot +set up a new one. The API rejects them on `POST orgs/{org}/repos`, and +`POST orgs/{org}/full-scans` does not create a missing repository for them, whatever +scopes they hold. They are also rejected on `POST orgs/{org}/purl`, so +`--generate-license` needs a token with organization-wide repository access. + +### Tokens with the nine-scope CI/CD list + +The [CI/CD token setup guide](https://docs.socket.dev/docs/create-socket-api-key-for-cicd) +was written before the diff-scans endpoints existed. Tokens created from its +nine-scope list hold exactly these: + +`repo:list`, `repo:create`, `repo:update`, `security-policy:read`, +`triage:alerts-list`, `triage:alerts-update`, `full-scans:list`, `full-scans:create`, +`packages:list` + +**That list has neither `diff-scans:create` nor `diff-scans:list`**, and every run +that compares scans uses both. A token with only those nine scopes always falls back +to the older comparison path; see +[the next section](#apiaccessdenied-on-the-scan-comparison). Add the two scopes. + +The list also has four scopes this CLI never uses: `repo:update`, +`security-policy:read`, `triage:alerts-list` and `triage:alerts-update`. A token used +only by `socketcli` can drop them. + +### API calls by run type + +Every run: + +| API call | Scope | Purpose | +|:---|:---|:---| +| `GET organizations` | none | Resolve the org ID and slug from the token | +| `POST python-cli-runs` | `full-scans:create` | Register the run. When log upload is on (`--upload-logs`, or enabled for the organization), `POST python-cli-runs/{id}/logs` and `POST python-cli-runs/{id}/finalize` follow under the same scope. A failure in any of the three is ignored | +| `GET report/supported` | none | Fetch supported manifest patterns | +| `POST orgs/{org}/full-scans` | `full-scans:create` | Create the new scan. With an organization-wide token, the server creates the repository if it does not exist yet | + +Comment events with `--scm github` or `--scm gitlab` create no scan. + +Runs that compare scans (see [which runs compare](#apiaccessdenied-on-the-scan-comparison)) add: + +| API call | Scope | Purpose | +|:---|:---|:---| +| `GET orgs/{org}/repos/{repo}` | `repo:list` | Look up the repository's default branch. Skipped with `--base-scan-id` or `--base-commit-sha` | +| `POST orgs/{org}/repos` | `repo:create` | Create the repository, **only attempted when the lookup above finds none** | +| `GET orgs/{org}/full-scans` | `full-scans:list` | Find the baseline: the newest matching scan on the default branch, or with `--base-commit-sha` the scan for that commit or a scanned ancestor. Skipped with `--base-scan-id` | +| `POST orgs/{org}/full-scans` | `full-scans:create` | Create a temporary empty baseline when no scan matches | +| `POST orgs/{org}/diff-scans/from-ids` | `diff-scans:create` and `full-scans:list` | Create the comparison (preferred path) | +| `GET orgs/{org}/diff-scans` | `diff-scans:list` | Find the existing comparison when creation returns 409 | +| `GET orgs/{org}/diff-scans/{id}` | `diff-scans:list` | Poll for the computed comparison | +| `GET orgs/{org}/full-scans/diff` | `full-scans:list` | Streaming comparison (fallback path). The API marks this endpoint as deprecated | + +Flags add: + +| Flag | API call | Scope | +|:---|:---|:---| +| `--reach` | `GET organizations` (plan check) | none | +| `--reach` | `POST orgs/{org}/coana-cli/artifacts` (locate the analysis engine download, only when it is not cached) | `full-scans:create` or `fixes:list` | +| `--reach` | `POST orgs/{org}/upload-manifest-files`, `POST tier1-reachability-scan/finalize` | `full-scans:create` | +| `--generate-license` | `POST orgs/{org}/purl` | `packages:list` | +| `--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` | +| `--strict-blocking`, `--enable-gitlab-security` or `--legal-format fossa` on a run that compares scans | `GET orgs/{org}/full-scans/{id}` (alerts on unchanged packages) | `full-scans:list` | + +`--reach` also runs the analysis engine with the same token. The engine reports to the +`tier1-reachability-scan/*` endpoints, which check `full-scans:create`. + +## `APIAccessDenied` on the scan comparison + +Any run that compares scans first tries the diff-scans endpoints. A token without the +`diff-scans:create` and `diff-scans:list` scopes logs a warning and continues on the +older path: ``` Diff scan comparison failed with APIAccessDenied(Insufficient permissions), falling back to the streaming scan comparison ``` -Grant the scopes to use the diff-scans path. It polls with short, bounded requests -rather than holding one connection open while the backend computes, which is what lets -large comparisons survive network idle timeouts — notably Azure NAT gateways, which -reap idle connections after four minutes and surface as an intermittent -`ConnectionResetError`. +The scan still succeeds and the diff results are the same, so this is easy to miss. + +**Which runs compare scans:** + +| Run | Compares? | +|:---|:---| +| Pull request or merge request run with `--scm github` / `--scm gitlab` | Yes | +| Comment event with `--scm github` / `--scm gitlab` | No. It creates no scan | +| Any other event with `--scm github` / `--scm gitlab` (branch and default-branch pushes) | No. It creates a full scan | +| No SCM integration (`--scm api`, the default) | Yes | + +In the rows that compare, the CLI first looks for a supported manifest among the +commit's changed files, or among `--files` when that is given. If it finds none, or +the directory is not a git repository and `--files` is not given, it creates a full +scan instead. `--ignore-commit-files` in a git repository and `--enable-diff` outside +one skip that check, so those runs always compare. + +Before 2.9.0 an SCM-integrated branch push also compared, so a pipeline scanning only +pushes (`--pr-number 0 --default-branch`) hit this too. If you are diagnosing an older +run, that is why the warning can appear in a log with no pull request in sight. + +**Which scope is missing.** The fallback calls `GET orgs/{org}/full-scans/diff`, which +checks `full-scans:list`. When the fallback succeeds, the missing scope is +`diff-scans:create`, `diff-scans:list`, or both. A token without `full-scans:list` +does not get that far: the CLI lists full scans to pick the baseline before it compares +anything, so the run fails first with `Failed to resolve the matching head scan for +repo ...` and the API-error exit code. With `--base-scan-id` that lookup is skipped, +and the run fails at the fallback instead. A fallback that fails another way, such as a +timeout or a dropped connection, says nothing about scopes. + +**Why the diff-scans path is preferred.** It polls with short, bounded requests rather +than holding one connection open while the backend computes, which is what lets large +comparisons survive network idle timeouts — notably Azure NAT gateways, which reap idle +connections after four minutes and surface as an intermittent `ConnectionResetError`. +Falling back costs resilience, not correctness. The two paths can take noticeably different amounts of time on the same repository, because cached diff-scan responses always embed per-package license details while the @@ -61,6 +180,45 @@ streaming comparison requests a lean payload. On a large dependency tree, compar `Diff scan comparison ready in ...` timing against the `Diff Report Gathered in ...` total before assuming either path is at fault. +## Baseline scans that do not appear in the dashboard + +A run that compares scans picks its baseline from the repository's default branch: the +newest scan there with the same scan type (`socket`, or `socket_tier1` with `--reach`) +and, with `--workspace`, the same workspace. `--base-scan-id` and `--base-commit-sha` +override that choice. When no scan matches, the CLI creates a **temporary empty +baseline** and compares to that: + +``` +No previous scan found - creating empty baseline scan +Baseline selected: source=empty scan_id="" +Comparing scans - Head scan ID: , New scan ID: +``` + +The baseline is created as a temporary scan and is deliberately not set as the +repository head or default branch, so it does not show up as a repository scan in the +dashboard. Looking it up by ID will come up empty. This is expected — the scan to look +at is the "New scan ID". + +Because everything is new relative to an empty baseline, that comparison reports +every package as added and zero as unchanged. This happens on a repository's first +comparison, and also the first time it is compared under a different scan type or +workspace, such as the first `--reach` run on a repository that only has regular +scans. A new branch compares against the default branch's newest matching scan, not an +empty baseline. + +## Reachability scan IDs are not full-scan IDs + +With `--reach`, the CLI logs an extra identifier before the normal scan flow starts: + +``` +Reachability scan ID: +``` + +That value is `tier1ReachabilityScanId`, read out of `.socket.facts.json`. It +identifies the reachability analysis run, not a Socket full scan, and will not resolve +in the dashboard's scan views. The full scan to look at is the "New scan ID" reported +by the comparison step that follows. + ## Common gotchas - In diff scope, `--strict-blocking` uses a stricter alert set (`new + unchanged`) for blocking checks and diff-based output selection. diff --git a/pyproject.toml b/pyproject.toml index 3604a71..44589f1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" [project] name = "socketsecurity" -version = "2.13.0" +version = "2.13.1" requires-python = ">= 3.11" license = {"file" = "LICENSE"} dependencies = [ @@ -16,7 +16,7 @@ dependencies = [ "gitpython==3.2.1", "packaging==26.3", "python-dotenv==1.2.4", - "socketdev==3.6.2", + "socketdev==3.6.3", "beautifulsoup4==4.15.0", "markdown==3.11.3", "brotli==1.2.1; platform_python_implementation == 'CPython'", diff --git a/socketsecurity/__init__.py b/socketsecurity/__init__.py index 08835ec..a3c8f69 100644 --- a/socketsecurity/__init__.py +++ b/socketsecurity/__init__.py @@ -1,4 +1,4 @@ __author__ = 'socket.dev' -__version__ = '2.13.0' +__version__ = '2.13.1' USER_AGENT_NAME = 'socket-python-cli' USER_AGENT = f'{USER_AGENT_NAME}/{__version__}' diff --git a/uv.lock b/uv.lock index b96bbc7..09162e4 100644 --- a/uv.lock +++ b/uv.lock @@ -1320,21 +1320,21 @@ wheels = [ [[package]] name = "socketdev" -version = "3.6.2" +version = "3.6.3" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "certifi" }, { name = "requests" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/3a/c2/48db5863e4e1d86f7b92334b91e8f9c59f4e96fc5949f0b594fff86dfeed/socketdev-3.6.2.tar.gz", hash = "sha256:ad51c879cad8d897ed1b949339fb7aded30d0fe25b2a3810c83079887e8610b5", size = 182918, upload-time = "2026-11-03T23:18:52.18Z" } +sdist = { url = "https://files.pythonhosted.org/packages/3b/94/1ac6e7da44a86571b2b91538e750a854d91f8f225da6bc324e433e9df222/socketdev-3.6.3.tar.gz", hash = "sha256:71a6dc6d1e0359f5f215e6da8c63bf479038ae07dd0ce29ec6c9fc8bf88054b0", size = 189957, upload-time = "2026-11-20T22:12:29.769Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/c2/3a/7ed253ade4cd47e6af02bf61668c9c2824a35e617668b6f4f12e41d617a5/socketdev-3.6.2-py3-none-any.whl", hash = "sha256:ea94b2da1bdb89f3b70209b606f3abe5c609f66549c1deb160cf18f58e0c2e48", size = 75559, upload-time = "2026-11-03T23:18:50.423Z" }, + { url = "https://files.pythonhosted.org/packages/da/39/775de959c64847fde70599bc67c4dcf9057ad540657c46157971f564f69c/socketdev-3.6.3-py3-none-any.whl", hash = "sha256:ba5fb7bbce566ddd7c9ecdfbc37389708f5115f9edbb42eeff14ce7dc2278be8", size = 78954, upload-time = "2026-11-20T22:12:28.453Z" }, ] [[package]] name = "socketsecurity" -version = "2.13.0" +version = "2.13.1" source = { editable = "." } dependencies = [ { name = "beautifulsoup4" }, @@ -1393,7 +1393,7 @@ requires-dist = [ { name = "python-dotenv", specifier = "==1.2.4" }, { name = "requests", specifier = "==2.34.2" }, { name = "ruff", marker = "extra == 'dev'", specifier = "==0.17.5" }, - { name = "socketdev", specifier = "==3.6.2" }, + { name = "socketdev", specifier = "==3.6.3" }, { name = "twine", marker = "extra == 'dev'", specifier = "==7.0.0" }, { name = "uv", marker = "extra == 'dev'", specifier = "==0.13.8" }, ]