Pin @coana-tech/cli version; make reachability auto-update opt-in

The Python CLI auto-updated the reachability (Coana) engine to the latest
published version on every --reach run via `npm install -g @coana-tech/cli`.
Automatically pulling a brand-new engine version without opting in is
undesirable for environments that need to review/approve dependency updates
before adopting them.

Run a fixed, pinned version (DEFAULT_COANA_CLI_VERSION = 15.3.22) via
`npx @coana-tech/cli@<pinned>` instead, so the engine version only changes
through a standard pip upgrade of this CLI. Opt into newest with
`--reach-version latest`; pin an explicit version with `--reach-version <semver>`.
The global `npm install -g` step is dropped entirely, so an existing global
install is never auto-updated or downgraded.

Author: mtorp

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.4.7
+
+### Changed: pin @coana-tech/cli version; auto-update is now opt-in
+
+- Reachability analysis now runs a fixed `@coana-tech/cli` version pinned to this CLI release
+  (`15.3.22`) via `npx`, instead of silently pulling the latest published version on every run.
+  Engine version changes now ride with the Socket Python CLI release (standard `pip` upgrade),
+  giving advance notice of analysis-engine changes.
+- The CLI no longer runs `npm install -g @coana-tech/cli`; an existing global install is left
+  untouched (never auto-updated or downgraded).
+- Opt into always-newest with `--reach-version latest`; pin an explicit version with
+  `--reach-version <semver>` (unchanged).
+
 ## 2.4.6
 
 ### Docs: reachability reference corrections

docs/cli-reference.md

@@ -240,7 +240,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 | Parameter                        | Required | Default | Description                                                                                                                |
 |:---------------------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------|
 | `--reach`                          | False    | False   | Enable reachability analysis to identify which vulnerable functions are actually called by your code. Creates a tier-1 full-application reachability scan (`scan_type=socket_tier1`). |
-| `--reach-version`                  | False    | latest  | Version of @coana-tech/cli to use for analysis                                                                             |
+| `--reach-version`                  | False    | *pinned* | Version of @coana-tech/cli to use. Defaults to the version pinned to this CLI release (currently `15.3.22`), so the engine only changes when you upgrade the Socket CLI. Pass `latest` to always use the newest published version (opt-in auto-update), or an explicit version (e.g. `1.2.3`) to pin it. |
 | `--reach-analysis-timeout`         | False    | *coana* | Timeout in seconds for the reachability analysis. Omitted by default, so coana applies its own (currently 600s). Alias: `--reach-timeout` |
 | `--reach-analysis-memory-limit`    | False    | *coana* | Memory limit in MB for the reachability analysis. Omitted by default, so coana applies its own (currently 8192). Alias: `--reach-memory-limit` |
 | `--reach-concurrency`              | False    | *coana* | Control parallel analysis execution (must be >= 1). Omitted by default, so coana applies its own (currently 1)             |
@@ -262,8 +262,8 @@ If you don't want to provide the Socket API Token every time then you can use th
 **Reachability Analysis Requirements:**
 
 The Python CLI verifies the following **up front** (before invoking the analysis engine) and exits with code **3** if any are unmet:
-- `npm` - Required to install and run `@coana-tech/cli` (the analysis engine)
-- `npx` - Required to execute `@coana-tech/cli`
+- `npm` - Required (verified up front; ships alongside `npx`)
+- `npx` - Required to fetch (on first use) and run `@coana-tech/cli` (the analysis engine)
 - `uv` - Required by the analysis engine
 - An **Enterprise** Socket organization plan (any `enterprise*` plan, including Enterprise trials)
 
@@ -313,7 +313,7 @@ Sample config files:
 
 For CI-specific examples and guidance, see [`ci-cd.md`](ci-cd.md).
 
-The CLI will automatically install `@coana-tech/cli` if not present. Use `--reach` to enable reachability analysis during a full scan, or add `--only-facts-file` (with `--reach`) to submit only the reachability facts file (`.socket.facts.json`) when creating the full scan.
+The CLI runs a pinned `@coana-tech/cli` version via `npx` (fetched on first use, then cached); it does **not** auto-update the engine or install it globally. Pass `--reach-version latest` to opt into the newest published version. Use `--reach` to enable reachability analysis during a full scan, or add `--only-facts-file` (with `--reach`) to submit only the reachability facts file (`.socket.facts.json`) when creating the full scan.
 
 #### Advanced Configuration
 | Parameter                | Required | Default | Description                                                           |

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.4.6"
+version = "2.4.7"
 requires-python = ">= 3.11"
 license = {"file" = "LICENSE"}
 dependencies = [

socketsecurity/__init__.py

@@ -1,3 +1,3 @@
 __author__ = 'socket.dev'
-__version__ = '2.4.6'
+__version__ = '2.4.7'
 USER_AGENT = f'SocketPythonCLI/{__version__}'

socketsecurity/config.py

@@ -943,8 +943,10 @@ def create_argument_parser() -> argparse.ArgumentParser:
     reachability_group.add_argument(
         "--reach-version",
         dest="reach_version",
-        metavar="<version>",
-        help="Specific version of @coana-tech/cli to use (e.g., '1.2.3')"
+        metavar="<version|latest>",
+        help="Version of @coana-tech/cli to use. Defaults to the version pinned to this CLI "
+             "release; pass 'latest' to always use the newest published version (opt-in "
+             "auto-update), or an explicit version (e.g. '1.2.3') to pin it."
     )
     reachability_group.add_argument(
         "--reach-analysis-timeout",

socketsecurity/core/tools/reachability.py

@@ -12,6 +12,11 @@
 
 log = logging.getLogger(__name__)
 
+# Pinned @coana-tech/cli version. Bumped deliberately per Python CLI release so the
+# reachability engine version only changes through a standard pip upgrade (advance notice).
+# Pass --reach-version latest to opt into the newest published version instead.
+DEFAULT_COANA_CLI_VERSION = "15.3.22"
+
 
 def _build_caller_user_agent() -> str:
     """Build the SOCKET_CALLER_USER_AGENT string forwarded to the coana CLI.
@@ -31,70 +36,28 @@ def __init__(self, sdk: socketdev, api_token: str):
         self.sdk = sdk
         self.api_token = api_token
 
-    def _ensure_coana_cli_installed(self, version: Optional[str] = None) -> str:
+    def _resolve_coana_package_spec(self, version: Optional[str] = None) -> str:
         """
-        Check if @coana-tech/cli is installed, and install/update it if needed.
-        
+        Resolve the @coana-tech/cli package spec to run with npx.
+
+        We pass an exact, versioned spec to npx so it runs a deterministic version from its
+        own cache (fetching once if absent). We intentionally do NOT ``npm install -g`` here:
+        that would silently auto-update the engine on every run and mutate the user's global
+        install. The pinned version rides with the Python CLI release instead, so engine
+        changes only happen through a standard pip upgrade (advance notice).
+
         Args:
-            version: Specific version to install (e.g., '1.2.3'). If None, always updates to latest.
-            
+            version: Coana CLI version to use.
+                - None: the pinned ``DEFAULT_COANA_CLI_VERSION`` (no auto-update).
+                - 'latest': always the newest published version (opt-in to auto-update).
+                - '<semver>': that exact version.
+
         Returns:
-            str: The package specifier to use with npx
+            str: The package specifier to use with npx (e.g. '@coana-tech/cli@15.3.22').
         """
-        # Determine the package specifier
-        package_spec = f"@coana-tech/cli@{version}" if version else "@coana-tech/cli"
-        
-        # If a specific version is requested, check if it's already installed
-        if version:
-            try:
-                check_cmd = ["npm", "list", "-g", "@coana-tech/cli", "--depth=0"]
-                result = subprocess.run(
-                    check_cmd,
-                    capture_output=True,
-                    text=True,
-                    timeout=10
-                )
-                
-                # If npm list succeeds and mentions the specific version, it's installed
-                if result.returncode == 0 and f"@coana-tech/cli@{version}" in result.stdout:
-                    log.debug(f"@coana-tech/cli@{version} is already installed globally")
-                    return package_spec
-                    
-            except Exception as e:
-                log.debug(f"Could not check for existing @coana-tech/cli installation: {e}")
-        
-        # Install or update the package
-        # When no version is specified, always try to update to latest
-        if version:
-            log.info(f"Installing reachability analysis plugin (@coana-tech/cli@{version})...")
-        else:
-            log.info("Updating reachability analysis plugin (@coana-tech/cli) to latest version...")
-        log.info("This may take a moment...")
-        
-        try:
-            install_cmd = ["npm", "install", "-g", package_spec]
-            log.debug(f"Installing with command: {' '.join(install_cmd)}")
-            
-            result = subprocess.run(
-                install_cmd,
-                capture_output=True,
-                text=True,
-                timeout=300  # 5 minute timeout for installation
-            )
-            
-            if result.returncode != 0:
-                log.warning(f"Global installation failed, npx will download on demand")
-                log.debug(f"Install stderr: {result.stderr}")
-            else:
-                log.info("Reachability analysis plugin installed successfully")
-                
-        except subprocess.TimeoutExpired:
-            log.warning("Installation timed out, npx will download on demand")
-        except Exception as e:
-            log.warning(f"Could not install globally: {e}, npx will download on demand")
-        
-        return package_spec
-    
+        effective = (version or DEFAULT_COANA_CLI_VERSION).strip()
+        return f"@coana-tech/cli@{effective}"
+
 
     def run_reachability_analysis(
         self,
@@ -147,7 +110,9 @@ def run_reachability_analysis(
             lazy_mode: Enable lazy mode for analysis
             repo_name: Repository name
             branch_name: Branch name
-            version: Specific version of @coana-tech/cli to use
+            version: @coana-tech/cli version to use. None uses the pinned
+                DEFAULT_COANA_CLI_VERSION (no auto-update); 'latest' opts into the newest
+                published version; '<semver>' pins an explicit version.
             concurrency: Concurrency level for analysis (must be >= 1)
             additional_params: Additional parameters to pass to coana CLI
             allow_unverified: Disable SSL certificate verification (sets NODE_TLS_REJECT_UNAUTHORIZED=0)
@@ -157,8 +122,8 @@ def run_reachability_analysis(
         Returns:
             Dict containing scan_id and report_path
         """
-        # Ensure @coana-tech/cli is installed
-        cli_package = self._ensure_coana_cli_installed(version)
+        # Resolve the pinned (or explicitly requested) @coana-tech/cli version for npx
+        cli_package = self._resolve_coana_package_spec(version)
 
         # Build CLI command arguments
         cmd = ["npx", cli_package, "run", "."]

tests/unit/test_reachability.py

@@ -2,7 +2,7 @@
 
 These cover the arg-builder and environment wiring in
 ``socketsecurity.core.tools.reachability.ReachabilityAnalyzer`` without actually
-invoking npm/npx/coana: ``_ensure_coana_cli_installed`` and ``subprocess.run`` are mocked.
+invoking npx/coana: ``_resolve_coana_package_spec`` and ``subprocess.run`` are mocked.
 """
 from unittest.mock import MagicMock
 
@@ -11,6 +11,7 @@
 from socketsecurity import __version__
 from socketsecurity.core.tools import reachability
 from socketsecurity.core.tools.reachability import (
+    DEFAULT_COANA_CLI_VERSION,
     ReachabilityAnalyzer,
     _build_caller_user_agent,
 )
@@ -22,8 +23,12 @@ def analyzer():
 
 
 def _run(analyzer, mocker, **kwargs):
-    """Invoke run_reachability_analysis with npm/npx/coana mocked; return (cmd, env)."""
-    mocker.patch.object(analyzer, "_ensure_coana_cli_installed", return_value="@coana-tech/cli")
+    """Invoke run_reachability_analysis with the spec resolver/coana mocked; return (cmd, env)."""
+    mocker.patch.object(
+        analyzer,
+        "_resolve_coana_package_spec",
+        return_value=f"@coana-tech/cli@{DEFAULT_COANA_CLI_VERSION}",
+    )
     mocker.patch.object(analyzer, "_extract_scan_id", return_value="scan-123")
     completed = MagicMock()
     completed.returncode = 0
@@ -104,3 +109,64 @@ def test_repo_branch_env_absent_when_none(analyzer, mocker):
     _, env = _run(analyzer, mocker, repo_name=None, branch_name=None)
     assert "SOCKET_REPO_NAME" not in env
     assert "SOCKET_BRANCH_NAME" not in env
+
+
+# --- Coana package-spec resolution (pinned by default, latest is opt-in) ---
+
+
+def test_resolve_spec_defaults_to_pinned_version(analyzer):
+    """No --reach-version -> pinned DEFAULT_COANA_CLI_VERSION (no auto-update)."""
+    assert (
+        analyzer._resolve_coana_package_spec(None)
+        == f"@coana-tech/cli@{DEFAULT_COANA_CLI_VERSION}"
+    )
+
+
+def test_resolve_spec_pins_explicit_version(analyzer):
+    assert analyzer._resolve_coana_package_spec("1.2.3") == "@coana-tech/cli@1.2.3"
+
+
+def test_resolve_spec_latest_opt_in(analyzer):
+    """'latest' opts into the newest published version."""
+    assert analyzer._resolve_coana_package_spec("latest") == "@coana-tech/cli@latest"
+
+
+def test_resolve_spec_is_always_versioned(analyzer):
+    """Never the bare '@coana-tech/cli' (which would let npx pick a stray global version)."""
+    for version in (None, "latest", "1.2.3", " 1.2.3 "):
+        assert analyzer._resolve_coana_package_spec(version).startswith("@coana-tech/cli@")
+
+
+def _run_with_real_resolver(analyzer, mocker, **kwargs):
+    """Like _run but exercises the real _resolve_coana_package_spec; returns the run mock."""
+    mocker.patch.object(analyzer, "_extract_scan_id", return_value="scan-123")
+    completed = MagicMock()
+    completed.returncode = 0
+    run_mock = mocker.patch.object(reachability.subprocess, "run", return_value=completed)
+    analyzer.run_reachability_analysis(org_slug="my-org", target_directory=".", **kwargs)
+    return run_mock
+
+
+def test_npx_runs_pinned_version_by_default(analyzer, mocker):
+    run_mock = _run_with_real_resolver(analyzer, mocker)
+    cmd = run_mock.call_args.args[0]
+    assert cmd[0] == "npx"
+    assert cmd[1] == f"@coana-tech/cli@{DEFAULT_COANA_CLI_VERSION}"
+
+
+def test_npx_runs_explicit_version(analyzer, mocker):
+    run_mock = _run_with_real_resolver(analyzer, mocker, version="9.9.9")
+    assert run_mock.call_args.args[0][1] == "@coana-tech/cli@9.9.9"
+
+
+def test_npx_runs_latest_when_opted_in(analyzer, mocker):
+    run_mock = _run_with_real_resolver(analyzer, mocker, version="latest")
+    assert run_mock.call_args.args[0][1] == "@coana-tech/cli@latest"
+
+
+def test_never_runs_npm_install(analyzer, mocker):
+    """Core guarantee: we never `npm install -g` (no auto-update / global mutation)."""
+    run_mock = _run_with_real_resolver(analyzer, mocker)
+    for call in run_mock.call_args_list:
+        argv = call.args[0]
+        assert argv[:2] != ["npm", "install"]