From d9c5dce89c1a46192204ab40eee91c7bcf01d1a2 Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Thu, 5 Nov 2026 13:58:45 -0600 Subject: [PATCH 1/2] docs(reach): document the network access reachability needs `--reach` downloads the analysis engine from storage.googleapis.com through a signed URL from api.socket.dev, then installs the project's dependencies from each ecosystem's registry. None of that was documented, and the registry case fails quietly: the scan completes but reports every affected vulnerability as INSTALL ERROR. Add a "Reachability network access" section to the CLI reference with the hosts, what fails when each is blocked, and proxy behavior, plus a troubleshooting entry for the two failure signatures. Note that 2.11.0 was never published. Bump to 2.11.12 for the version check. --- CHANGELOG.md | 15 +++++++++++++++ docs/cli-reference.md | 14 ++++++++++++++ docs/troubleshooting.md | 6 ++++++ pyproject.toml | 2 +- socketsecurity/__init__.py | 2 +- uv.lock | 2 +- 6 files changed, 38 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfe78cc5..ac0735bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 2.11.12 + +### Docs: reachability network access + +- Documented the hosts `--reach` needs: `api.socket.dev`, + `storage.googleapis.com` for the analysis engine download, and each scanned + ecosystem's package registry for dependency installs. Covers what fails when + each is blocked, including dependencies reported as `INSTALL ERROR` while the + scan still completes, and that the CLI and engine honor `HTTPS_PROXY`. +- Noted under 2.11.1 that 2.11.0 was never published. +- Documentation-only; no functional code changes. + ## 2.11.11 ### Changed: use lowercase Python CLI User-Agent @@ -123,6 +135,9 @@ their changes ship here. ## 2.11.1 +Version 2.11.0 was never published to PyPI or Docker Hub; its changes ship +here. + ### Changed: bump pinned Coana CLI to 15.12.10 - Bumped the pinned reachability engine (the Coana CLI) from `15.12.8` to diff --git a/docs/cli-reference.md b/docs/cli-reference.md index eeb2e3df..a0780d45 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -366,6 +366,20 @@ The Python CLI verifies the following **up front** (before invoking the analysis Separately, the analysis engine (coana) needs the **per-ecosystem build toolchain** for whatever languages your project uses — e.g. a compatible Python interpreter (3.11+, or PyPy) for Python, a JDK for Java/Kotlin/Scala, .NET 6+ for C#, the matching Go toolchain for Go, etc. These are validated by the engine **at analysis time** (the CLI does not pre-check them) and that validation can be skipped with `--reach-disable-external-tool-checks`. +**Reachability network access:** + +`--reach` downloads the analysis engine on first use and installs your project's dependencies to analyze them. On a restricted network, allow: + +| Host | Used for | If blocked | +|---|---|---| +| `api.socket.dev` | Socket API calls, and a signed URL for the engine download | The CLI fails | +| `storage.googleapis.com` | Downloading the engine and its analyzers (about 120 MB) | The CLI exits with code **3**: `Failed to run reachability analysis: HTTPSConnectionPool(host='storage.googleapis.com', ...)` | +| The package registry of each scanned ecosystem, for example `registry.npmjs.org` | Installing your project's dependencies for analysis | The scan still completes, but the affected vulnerabilities are reported as `INSTALL ERROR` with no reachability result | + +The engine comes from Socket, not npm, so an npm mirror or registry proxy does not cover the engine download. The registry row does not apply when your dependencies are already installed in the target path, for example a `node_modules` directory from an earlier `npm ci`. The engine is cached as described below; with a warm cache, `storage.googleapis.com` is not contacted. + +Behind an HTTP(S) proxy, set `HTTPS_PROXY`. The CLI, the engine download and the engine itself all send their requests through it. + **Reachability analysis types:** Socket's reachability analysis comes in three forms, referred to by their full names rather than the older "Tier" numbering: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 9d6d06df..4161dc3f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -36,6 +36,12 @@ total before assuming either path is at fault. - In `--sarif-scope full` with `--sarif-file`, SARIF JSON is written to file and stdout JSON is suppressed. - `--sarif-grouping alert` currently applies to `--sarif-scope full`. +## Reachability on a restricted network + +- `Failed to run reachability analysis: HTTPSConnectionPool(host='storage.googleapis.com', ...)`: the engine download is blocked. Allow `storage.googleapis.com`, or set `HTTPS_PROXY`. An npm mirror does not cover it. +- Every vulnerability reported as `INSTALL ERROR`: the engine could not install your dependencies. Allow the ecosystem's package registry, or install dependencies in the target path before running `--reach`. +- See **Reachability network access** in the [CLI reference](cli-reference.md) for the full list of hosts. + ## Dashboard vs CLI result counts Differences in result counts can be valid, even when filtering appears similar. diff --git a/pyproject.toml b/pyproject.toml index 966fee16..183008bf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" [project] name = "socketsecurity" -version = "2.11.11" +version = "2.11.12" requires-python = ">= 3.11" license = {"file" = "LICENSE"} dependencies = [ diff --git a/socketsecurity/__init__.py b/socketsecurity/__init__.py index 4a07834f..590de206 100644 --- a/socketsecurity/__init__.py +++ b/socketsecurity/__init__.py @@ -1,4 +1,4 @@ __author__ = 'socket.dev' -__version__ = '2.11.11' +__version__ = '2.11.12' USER_AGENT_NAME = 'socket-python-cli' USER_AGENT = f'{USER_AGENT_NAME}/{__version__}' diff --git a/uv.lock b/uv.lock index 0a14aad8..f9e7a033 100644 --- a/uv.lock +++ b/uv.lock @@ -1332,7 +1332,7 @@ wheels = [ [[package]] name = "socketsecurity" -version = "2.11.11" +version = "2.11.12" source = { editable = "." } dependencies = [ { name = "beautifulsoup4" }, From d9f55ffc551a232a00e4e538a63f80e360f30a2d Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Thu, 5 Nov 2026 14:15:08 -0600 Subject: [PATCH 2/2] docs(changelog): keep the 2.11.12 entry to what users see The entry only needs the documented network requirements. The note about the 2.11.1 heading and the documentation-only remark describe the PR, not the release. --- CHANGELOG.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ac0735bb..eade678a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,6 @@ ecosystem's package registry for dependency installs. Covers what fails when each is blocked, including dependencies reported as `INSTALL ERROR` while the scan still completes, and that the CLI and engine honor `HTTPS_PROXY`. -- Noted under 2.11.1 that 2.11.0 was never published. -- Documentation-only; no functional code changes. ## 2.11.11