Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ pip install socketsecurity
export SOCKET_SECURITY_API_TOKEN="<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
Expand Down
9 changes: 9 additions & 0 deletions docs/ci-cd.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
18 changes: 17 additions & 1 deletion docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|:-----------------|:---------|:--------|:------------------------------------------------------------------------------------------------------------------|
Expand Down Expand Up @@ -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
Expand Down
200 changes: 179 additions & 21 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,39 +28,197 @@ 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:
Comment thread
lelia marked this conversation as resolved.
Resolved

| 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
streaming comparison requests a lean payload. On a large dependency tree, compare the
`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="<baseline>"
Comparing scans - Head scan ID: <baseline>, New scan ID: <real scan>
```

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: <tier-1 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.
Expand Down
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [
Expand All @@ -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'",
Expand Down
2 changes: 1 addition & 1 deletion socketsecurity/__init__.py
Original file line number Diff line number Diff line change
@@ -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__}'
10 changes: 5 additions & 5 deletions uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.