Merge main into the --repo and --pending-head branch

Fold this branch's changelog entries into the existing 2.11.13 section.

Author: lelia

CHANGELOG.md

@@ -19,6 +19,14 @@
 - `--pending-head` has no effect and logs a deprecation warning. Use
   `--default-branch`.
 
+### 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`.
+
 ## 2.11.12
 
 ### Changed: bump pinned Coana CLI to 15.14.2
@@ -151,6 +159,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

docs/cli-reference.md

@@ -365,6 +365,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:

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.