socketsecurity 2.4.5__tar.gz → 2.4.7__tar.gz

{socketsecurity-2.4.5 → socketsecurity-2.4.7}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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.24`) 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).
+- Runs the engine via `npx --yes --force` (the same flags the Socket Node CLI passes for
+  coana); `--yes` skips npx's interactive install prompt so non-interactive/CI runs don't hang.
+- Added an `npm install` + `node` fallback for when the `npx` launcher is missing or fails
+  before the engine starts. The installed engine is cached per version for the process
+  lifetime (installs once). Tunable via `SOCKET_CLI_COANA_FORCE_NPM_INSTALL` (use the fallback
+  as the primary path) and `SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK` (never fall back). `node` is
+  now part of the up-front prerequisite check. Also strips `npm_package_*` env vars before
+  spawning the engine to avoid `E2BIG` in large monorepos.
+
+## 2.4.6
+
+### Docs: reachability reference corrections
+
+- Documented the `uv` and Enterprise-plan prerequisites the CLI enforces **before** running
+  reachability (exit code 3 if unmet), and clarified that per-ecosystem build toolchains
+  (JDK / .NET / Go / a compatible Python interpreter) are checked by the analysis engine at
+  runtime, not pre-checked by the CLI.
+- Corrected the `--reach-min-severity` values to `info, low, moderate, high, critical`.
+- Documented the previously-undocumented reachability flags: `--reach-enable-analysis-splitting`,
+  `--reach-detailed-analysis-log-file`, `--reach-lazy-mode`, and `--reach-use-only-pregenerated-sboms`.
+- Clarified that `--only-facts-file` submits only the facts file when **creating** the full scan
+  (it does not require a pre-existing scan).
+- Documentation-only; no functional code changes.
+
 ## 2.4.5
 
 ### Changed: Bump required SDK version to `>=3.2.1`

{socketsecurity-2.4.5 → socketsecurity-2.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socketsecurity
-Version: 2.4.5
+Version: 2.4.7
 Summary: Socket Security CLI for CI/CD
 Project-URL: Homepage, https://socket.dev
 Author-email: Douglas Coburn <douglas@socket.dev>

{socketsecurity-2.4.5 → socketsecurity-2.4.7}/docs/cli-reference.md

@@ -154,7 +154,8 @@ socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--workspace WORKSPACE] [--
           [--ignore-commit-files] [--disable-blocking] [--disable-ignore] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders]
           [--reach] [--reach-version REACH_VERSION] [--reach-analysis-timeout REACH_ANALYSIS_TIMEOUT]
           [--reach-analysis-memory-limit REACH_ANALYSIS_MEMORY_LIMIT] [--reach-concurrency REACH_CONCURRENCY] [--reach-ecosystems REACH_ECOSYSTEMS]
-          [--reach-min-severity {low,medium,high,critical}] [--reach-skip-cache] [--reach-disable-analytics] [--reach-debug] [--reach-disable-external-tool-checks]
+          [--reach-min-severity <level>] [--reach-skip-cache] [--reach-disable-analytics] [--reach-enable-analysis-splitting] [--reach-detailed-analysis-log-file]
+          [--reach-lazy-mode] [--reach-use-only-pregenerated-sboms] [--reach-debug] [--reach-disable-external-tool-checks]
           [--reach-output-file REACH_OUTPUT_FILE] [--only-facts-file] [--version]
 ````
 
@@ -238,25 +239,36 @@ If you don't want to provide the Socket API Token every time then you can use th
 #### Reachability Analysis
 | Parameter                        | Required | Default | Description                                                                                                                |
 |:---------------------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------|
-| `--reach`                          | False    | False   | Enable reachability analysis to identify which vulnerable functions are actually called by your code                       |
-| `--reach-version`                  | False    | latest  | Version of @coana-tech/cli to use for analysis                                                                             |
-| `--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)             |
+| `--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    | 15.3.24 | Version of @coana-tech/cli to use. Defaults to the pinned version that ships with this CLI release, 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    | 600     | Timeout in seconds for the reachability analysis. Omitted by default, so coana applies its own default. Alias: `--reach-timeout` |
+| `--reach-analysis-memory-limit`    | False    | 8192    | Memory limit in MB for the reachability analysis. Omitted by default, so coana applies its own default. Alias: `--reach-memory-limit` |
+| `--reach-concurrency`              | False    | 1       | Control parallel analysis execution (must be >= 1). Omitted by default, so coana applies its own default.                  |
 | `--reach-additional-params`        | False    |         | Pass custom parameters to the coana CLI tool                                                                               |
 | `--reach-ecosystems`               | False    |         | Comma-separated list of ecosystems to analyze (e.g., "npm,pypi"). If not specified, all supported ecosystems are analyzed  |
-| `--reach-min-severity`             | False    |         | Minimum severity level for reporting reachability results (low, medium, high, critical)                                    |
+| `--reach-min-severity`             | False    | info    | Minimum severity of vulnerabilities to analyze (info, low, moderate, high, critical). Omitted by default, so coana analyzes all severities — equivalent to `info`, the lowest. |
 | `--reach-skip-cache`               | False    | False   | Skip cache and force fresh reachability analysis                                                                           |
 | `--reach-disable-analytics`        | False    | False   | Disable analytics collection during reachability analysis                                                                  |
+| `--reach-enable-analysis-splitting` | False   | False   | Enable analysis splitting/bucketing (a legacy performance feature). Splitting is disabled by default.                      |
+| `--reach-detailed-analysis-log-file` | False  | False   | Write a detailed analysis log file; its path is printed to stdout                                                          |
+| `--reach-lazy-mode`                | False    | False   | Enable lazy mode (experimental performance feature)                                                                        |
+| `--reach-use-only-pregenerated-sboms` | False | False   | Build the scan only from pre-generated CycloneDX (CDX) and SPDX files in your project (requires --reach)                    |
 | `--reach-debug`                    | False    | False   | Enable coana debug output (`--debug`) for the analysis, independent of the global `--enable-debug`                         |
 | `--reach-disable-external-tool-checks` | False | False | Disable coana's external tool availability checks (passes `--disable-external-tool-checks`)                              |
 | `--reach-output-file`              | False    | .socket.facts.json | Path where reachability analysis results should be saved                                                        |
 | `--reach-exclude-paths`            | False    |         | **[DEPRECATED — use `--exclude-paths`]** Comma-separated paths to exclude from reachability analysis. Still honored (unioned with `--exclude-paths`) but will be hidden in a future release |
-| `--only-facts-file`                | False    | False   | Submit only the .socket.facts.json file to an existing scan (requires --reach and a prior scan)                            |
+| `--only-facts-file`                | False    | False   | Submit only the .socket.facts.json file when creating the full scan (requires --reach)                                     |
 
 **Reachability Analysis Requirements:**
-- `npm` - Required to install and run @coana-tech/cli
-- `npx` - Required to execute @coana-tech/cli
+
+The Python CLI verifies the following **up front** (before invoking the analysis engine) and exits with code **3** if any are unmet:
+- `npm` - Required (verified up front; ships alongside `npx`)
+- `npx` - Required to fetch (on first use) and run `@coana-tech/cli` (the analysis engine)
+- `node` - Required to run the engine (used directly by the `npm install` fallback)
+- `uv` - Required by the analysis engine
+- An **Enterprise** Socket organization plan (any `enterprise*` plan, including Enterprise trials)
+
+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`.
 
 ## Config file support
 
@@ -302,7 +314,11 @@ 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 use `--only-facts-file` with `--reach` to submit reachability results to an existing scan.
+The CLI runs a pinned `@coana-tech/cli` version via `npx --yes --force` (the same flags the Socket Node CLI passes for coana); it does **not** auto-update the engine or install it globally. `--yes` skips npx's interactive install prompt so non-interactive/CI runs don't hang. If the `npx` launcher is unavailable or fails before the engine starts, the CLI falls back to `npm install`-ing the pinned version into a temp directory and running it via `node`. 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.
+
+The launcher fallback can be tuned via environment variables:
+- `SOCKET_CLI_COANA_FORCE_NPM_INSTALL` — skip `npx` entirely and always use the `npm install` + `node` path (useful where `npx` is known-broken).
+- `SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK` — never fall back; surface the `npx` failure directly.
 
 #### Advanced Configuration
 | Parameter                | Required | Default | Description                                                           |

{socketsecurity-2.4.5 → socketsecurity-2.4.7}/pyproject.toml

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

{socketsecurity-2.4.5 → socketsecurity-2.4.7}/socketsecurity/__init__.py

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

{socketsecurity-2.4.5 → socketsecurity-2.4.7}/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-2.4.7/socketsecurity/core/tools/reachability.py

@@ -0,0 +1,469 @@
+from socketdev import socketdev
+from typing import List, Optional, Dict, Any, Final
+import atexit
+import os
+import platform
+import shutil
+import subprocess
+import json
+import pathlib
+import logging
+import sys
+import tempfile
+
+from socketsecurity import __version__
+
+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: Final = "15.3.24"
+
+# Resolved @coana-tech/cli script paths from the npm-install fallback, keyed by version.
+# Lives for the process lifetime so repeated fallback invocations install only once
+# (mirrors the Node CLI's installedCoanaScriptPathsByVersion).
+_INSTALLED_COANA_SCRIPT_PATHS: Dict[str, str] = {}
+
+# Temp dirs created by the npm-install fallback, removed at process exit.
+_COANA_INSTALL_DIRS: List[str] = []
+
+
+@atexit.register
+def _cleanup_coana_install_dirs() -> None:
+    for install_dir in _COANA_INSTALL_DIRS:
+        shutil.rmtree(install_dir, ignore_errors=True)
+
+
+def _build_caller_user_agent() -> str:
+    """Build the SOCKET_CALLER_USER_AGENT string forwarded to the coana CLI.
+
+    Mirrors the Node CLI's ``<product>/<version> <runtime>/<version> <platform>/<arch>``
+    shape so the backend can attribute reachability calls to the Python CLI.
+    """
+    return (
+        f"socket/{__version__} "
+        f"python/{platform.python_version()} "
+        f"{platform.system().lower()}/{platform.machine().lower()}"
+    )
+
+
+class ReachabilityAnalyzer:
+    def __init__(self, sdk: socketdev, api_token: str):
+        self.sdk = sdk
+        self.api_token = api_token
+    
+    def _resolve_coana_package_spec(self, version: Optional[str] = None) -> str:
+        """
+        Resolve the @coana-tech/cli package spec to run (e.g. '@coana-tech/cli@15.3.24').
+
+        Args:
+            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 (e.g. '@coana-tech/cli@15.3.24').
+        """
+        return f"@coana-tech/cli@{self._resolve_coana_version(version)}"
+
+    def _resolve_coana_version(self, version: Optional[str] = None) -> str:
+        """Resolve the effective @coana-tech/cli version string (see _resolve_coana_package_spec)."""
+        return (version or DEFAULT_COANA_CLI_VERSION).strip()
+
+    
+    def run_reachability_analysis(
+        self,
+        org_slug: str,
+        target_directory: str,
+        tar_hash: Optional[str] = None,
+        output_path: str = ".socket.facts.json",
+        timeout: Optional[int] = None,
+        memory_limit: Optional[int] = None,
+        ecosystems: Optional[List[str]] = None,
+        exclude_paths: Optional[List[str]] = None,
+        min_severity: Optional[str] = None,
+        skip_cache: bool = False,
+        disable_analytics: bool = False,
+        enable_analysis_splitting: bool = False,
+        detailed_analysis_log_file: bool = False,
+        lazy_mode: bool = False,
+        repo_name: Optional[str] = None,
+        branch_name: Optional[str] = None,
+        version: Optional[str] = None,
+        concurrency: Optional[int] = None,
+        additional_params: Optional[List[str]] = None,
+        allow_unverified: bool = False,
+        enable_debug: bool = False,
+        use_only_pregenerated_sboms: bool = False,
+        continue_on_analysis_errors: bool = False,
+        continue_on_install_errors: bool = False,
+        continue_on_missing_lock_files: bool = False,
+        continue_on_no_source_files: bool = False,
+        reach_debug: bool = False,
+        disable_external_tool_checks: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Run reachability analysis.
+
+        Args:
+            org_slug: Socket organization slug
+            target_directory: Directory to analyze
+            tar_hash: Tar hash from manifest upload or existing scan (optional)
+            output_path: Output file path for results
+            timeout: Analysis timeout in seconds
+            memory_limit: Memory limit in MB
+            ecosystems: List of ecosystems to analyze (e.g., ['npm', 'pypi'])
+            exclude_paths: Paths to exclude from analysis
+            min_severity: Minimum severity level (info, low, moderate, high, critical)
+            skip_cache: Skip cache usage
+            disable_analytics: Disable analytics sharing
+            enable_analysis_splitting: Enable analysis splitting (disabled by default)
+            detailed_analysis_log_file: Print detailed analysis log file path
+            lazy_mode: Enable lazy mode for analysis
+            repo_name: Repository name
+            branch_name: Branch name
+            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)
+            enable_debug: Enable debug mode (passes -d flag to coana CLI)
+            use_only_pregenerated_sboms: Use only pre-generated CDX and SPDX files for the scan
+
+        Returns:
+            Dict containing scan_id and report_path
+        """
+        # Build the coana CLI arguments (everything after the package spec). The launcher
+        # (npx, or the npm-install + node fallback) is chosen in _spawn_coana() below.
+        coana_args = ["run", "."]
+
+        # Add required arguments
+        output_dir = str(pathlib.Path(output_path).parent)
+        log.debug(f"output_dir: {output_dir}, output_path: {output_path}")
+        coana_args.extend([
+            "--output-dir", output_dir,
+            "--socket-mode", output_path,
+            "--disable-report-submission"
+        ])
+        
+        # Add conditional arguments
+        if timeout:
+            coana_args.extend(["--analysis-timeout", str(timeout)])
+        
+        if memory_limit:
+            coana_args.extend(["--memory-limit", str(memory_limit)])
+        
+        if disable_analytics:
+            coana_args.append("--disable-analytics-sharing")
+
+        # Analysis splitting is disabled by default; only omit the flag if explicitly enabled
+        if not enable_analysis_splitting:
+            coana_args.append("--disable-analysis-splitting")
+
+        if detailed_analysis_log_file:
+            coana_args.append("--print-analysis-log-file")
+
+        if lazy_mode:
+            coana_args.append("--lazy-mode")
+        
+        # KEY POINT: Only add manifest tar hash if we have one
+        if tar_hash:
+            coana_args.extend(["--run-without-docker", "--manifests-tar-hash", tar_hash])
+        
+        if ecosystems:
+            coana_args.extend(["--purl-types"] + ecosystems)
+        
+        if exclude_paths:
+            coana_args.extend(["--exclude-dirs"] + exclude_paths)
+        
+        if min_severity:
+            coana_args.extend(["--min-severity", min_severity])
+        
+        if skip_cache:
+            coana_args.append("--skip-cache-usage")
+        
+        if concurrency:
+            coana_args.extend(["--concurrency", str(concurrency)])
+        
+        if enable_debug:
+            coana_args.append("-d")
+
+        if reach_debug:
+            coana_args.append("--debug")
+
+        if disable_external_tool_checks:
+            coana_args.append("--disable-external-tool-checks")
+
+        if use_only_pregenerated_sboms:
+            coana_args.append("--use-only-pregenerated-sboms")
+
+        if continue_on_analysis_errors:
+            coana_args.append("--reach-continue-on-analysis-errors")
+
+        if continue_on_install_errors:
+            coana_args.append("--reach-continue-on-install-errors")
+
+        if continue_on_missing_lock_files:
+            coana_args.append("--reach-continue-on-missing-lock-files")
+
+        if continue_on_no_source_files:
+            coana_args.append("--reach-continue-on-no-source-files")
+
+        # Add any additional parameters provided by the user
+        if additional_params:
+            coana_args.extend(additional_params)
+        
+        # Set up environment variables
+        env = os.environ.copy()
+        
+        # Required environment variables for Coana CLI
+        env["SOCKET_ORG_SLUG"] = org_slug
+        env["SOCKET_CLI_API_TOKEN"] = self.api_token
+
+        # Identify the calling CLI to the coana tool / backend (parity with the Node CLI).
+        env["SOCKET_CLI_VERSION"] = __version__
+        env["SOCKET_CALLER_USER_AGENT"] = _build_caller_user_agent()
+
+        # NOTE: no proxy env is set here. coana already reads HTTPS_PROXY/HTTP_PROXY itself, and
+        # we pass the full parent env above, so it inherits them. A SOCKET_CLI_API_PROXY override
+        # should only be set from an explicit --proxy flag (not yet implemented), since seeding it
+        # from HTTPS_PROXY would be a no-op (it's the same value coana already resolves).
+
+        # Optional environment variables.
+        # NOTE: repo/branch are intentionally omitted by the caller (passed as None) when they
+        # are the default sentinels, to avoid polluting coana's per-repo/branch cache buckets.
+        if repo_name:
+            env["SOCKET_REPO_NAME"] = repo_name
+
+        if branch_name:
+            env["SOCKET_BRANCH_NAME"] = branch_name
+
+        # Set NODE_TLS_REJECT_UNAUTHORIZED=0 if allow_unverified is True
+        if allow_unverified:
+            env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0"
+        
+        # Execute coana
+        log.info("Running reachability analysis...")
+        log.debug(f"Environment: SOCKET_ORG_SLUG={org_slug}, SOCKET_REPO_NAME={repo_name or 'not set'}, SOCKET_BRANCH_NAME={branch_name or 'not set'}")
+
+        try:
+            # Prefer npx (with caching disabled); fall back to `npm install` + `node`
+            # if the npx launcher fails before coana starts (parity with the Node CLI).
+            returncode = self._spawn_coana(coana_args, version, env, target_directory)
+
+            if returncode != 0:
+                log.error(f"Reachability analysis failed with exit code {returncode}")
+                raise Exception(f"Reachability analysis failed with exit code {returncode}")
+            
+            # Extract scan ID from output file
+            scan_id = self._extract_scan_id(output_path)
+            
+            log.info(f"Reachability analysis completed successfully")
+            if scan_id:
+                log.info(f"Scan ID: {scan_id}")
+            
+            return {
+                "scan_id": scan_id,
+                "report_path": output_path,
+                "tar_hash_used": tar_hash
+            }
+        
+        except Exception as e:
+            log.error(f"Failed to run reachability analysis: {str(e)}")
+            raise Exception(f"Failed to run reachability analysis: {str(e)}")
+
+    @staticmethod
+    def _sanitize_coana_env(env: Dict[str, str]) -> Dict[str, str]:
+        """Drop npm-injected ``npm_package_*`` vars before spawning coana.
+
+        npm/pnpm/yarn populate one env var per leaf of the cwd's package.json
+        (``npm_package_dependencies_*`` etc.). In large monorepos this can be tens of KB
+        and push argv+env past the OS ARG_MAX, making the spawn fail with E2BIG before
+        coana even starts. coana doesn't read these, so dropping them is safe; we keep
+        ``npm_config_*`` (registry/cache/proxy) untouched. Mirrors the Node CLI.
+        """
+        return {k: v for k, v in env.items() if not k.startswith("npm_package_")}
+
+    @staticmethod
+    def _npx_launcher_failed_before_coana(returncode: int) -> bool:
+        """Heuristic: did npx fail *before* coana started (so retrying is worthwhile)?
+
+        We stream coana's output (no capture), so we classify by exit code alone, like the
+        Node CLI does with inherited stdio: signal kills (negative codes) and codes >= 128
+        are conventionally launcher/signal failures -> retry. Small positive codes (1..127)
+        are ambiguous (coana's own exit codes are small ints), so we do NOT retry.
+        """
+        return returncode < 0 or returncode >= 128
+
+    def _spawn_coana(
+        self,
+        coana_args: List[str],
+        version: Optional[str],
+        env: Dict[str, str],
+        cwd: str,
+    ) -> int:
+        """Run coana for the given args, returning the process exit code.
+
+        We run a pinned, versioned spec via npx and intentionally do NOT ``npm install -g``:
+        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 (see
+        ``DEFAULT_COANA_CLI_VERSION``).
+
+        Primary path: ``npx --yes --force @coana-tech/cli@<version> ...`` — the exact flags the
+        Socket Node CLI passes for coana (``--yes`` skips npx's interactive install prompt so
+        CI runs don't hang).
+
+        Fallback path: if npx is missing, or its launcher dies before coana starts, install
+        @coana-tech/cli into a temp dir via ``npm install`` and run it directly via ``node``.
+        Toggle with ``SOCKET_CLI_COANA_FORCE_NPM_INSTALL`` (use the fallback as the primary
+        path) and ``SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK`` (never fall back).
+        """
+        effective_version = self._resolve_coana_version(version)
+        coana_env = self._sanitize_coana_env(env)
+        disable_fallback = bool(os.environ.get("SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK"))
+
+        if os.environ.get("SOCKET_CLI_COANA_FORCE_NPM_INSTALL"):
+            return self._spawn_coana_via_npm_install(coana_args, effective_version, coana_env, cwd)
+
+        package_spec = f"@coana-tech/cli@{effective_version}"
+        npx_cmd = ["npx", "--yes", "--force", package_spec, *coana_args]
+        log.debug(f"Reachability command: {' '.join(npx_cmd)}")
+        try:
+            result = subprocess.run(
+                npx_cmd,
+                env=coana_env,
+                cwd=cwd,
+                stdout=sys.stderr,  # Send stdout to stderr so the user sees it
+                stderr=sys.stderr,
+            )
+        except FileNotFoundError:
+            # npx is not on PATH: the launcher provably never started coana.
+            if disable_fallback:
+                raise
+            log.warning("npx not found on PATH; retrying reachability analysis via `npm install` + `node`.")
+            return self._spawn_coana_via_npm_install(coana_args, effective_version, coana_env, cwd)
+
+        if result.returncode == 0:
+            return 0
+
+        if not disable_fallback and self._npx_launcher_failed_before_coana(result.returncode):
+            log.warning(
+                f"npx launcher failed (exit {result.returncode}) before coana started; "
+                "retrying reachability analysis via `npm install` + `node`."
+            )
+            return self._spawn_coana_via_npm_install(coana_args, effective_version, coana_env, cwd)
+
+        return result.returncode
+
+    def _spawn_coana_via_npm_install(
+        self,
+        coana_args: List[str],
+        version: str,
+        env: Dict[str, str],
+        cwd: str,
+    ) -> int:
+        """Fallback launcher: ``npm install`` @coana-tech/cli into a temp dir, run via ``node``.
+
+        Used when npx is unavailable or its launcher fails before coana boots. Mirrors the
+        Node CLI's npm-install fallback. Returns coana's exit code; raises if the install
+        itself fails or if ``node`` is unavailable.
+        """
+        script_path = self._install_coana_to_tmpdir(version, env)
+        node_cmd = self._build_coana_node_cmd(script_path, coana_args)
+        log.debug(f"Reachability fallback command: {' '.join(node_cmd)}")
+        try:
+            result = subprocess.run(node_cmd, env=env, cwd=cwd, stdout=sys.stderr, stderr=sys.stderr)
+        except FileNotFoundError as e:
+            # The fallback exists for broken-launcher environments, but it still needs node.
+            raise Exception(
+                "`node` was not found on PATH; it is required to run the reachability engine "
+                "via the npm-install fallback."
+            ) from e
+        return result.returncode
+
+    def _install_coana_to_tmpdir(self, version: str, env: Dict[str, str]) -> str:
+        """``npm install`` @coana-tech/cli@<version> into a temp dir; return its executable JS path.
+
+        Caches the resolved path per version for the process lifetime so repeated fallback
+        invocations install only once (mirrors the Node CLI's installCoanaToTmpdir). Raises if
+        the install fails.
+        """
+        cached = _INSTALLED_COANA_SCRIPT_PATHS.get(version)
+        if cached and os.path.exists(cached):
+            return cached
+
+        install_dir = tempfile.mkdtemp(prefix="socket-coana-")
+        _COANA_INSTALL_DIRS.append(install_dir)
+        npm_cmd = [
+            "npm", "install",
+            "--no-save", "--no-package-lock", "--no-audit", "--no-fund",
+            "--prefix", install_dir,
+            f"@coana-tech/cli@{version}",
+        ]
+        log.info("Installing reachability analysis engine via npm fallback...")
+        log.debug(f"npm install fallback command: {' '.join(npm_cmd)}")
+        install = subprocess.run(npm_cmd, env=env, stdout=sys.stderr, stderr=sys.stderr)
+        if install.returncode != 0:
+            raise Exception(
+                f"npm install fallback for @coana-tech/cli@{version} failed with exit code {install.returncode}"
+            )
+
+        script_path = self._resolve_coana_bin(install_dir)
+        _INSTALLED_COANA_SCRIPT_PATHS[version] = script_path
+        return script_path
+
+    @staticmethod
+    def _resolve_coana_bin(install_dir: str) -> str:
+        """Resolve @coana-tech/cli's executable JS from its installed package.json ``bin`` field."""
+        package_json_path = os.path.join(
+            install_dir, "node_modules", "@coana-tech", "cli", "package.json"
+        )
+        with open(package_json_path, "r") as f:
+            pkg = json.load(f)
+        bin_field = pkg.get("bin")
+        relative_bin = None
+        if isinstance(bin_field, str):
+            relative_bin = bin_field
+        elif isinstance(bin_field, dict):
+            # Prefer an entry named "coana"; otherwise take the first.
+            relative_bin = bin_field.get("coana") or next(iter(bin_field.values()), None)
+        if not relative_bin:
+            raise Exception(
+                f"@coana-tech/cli package.json at {package_json_path} is missing a usable bin entry"
+            )
+        return os.path.abspath(os.path.join(os.path.dirname(package_json_path), relative_bin))
+
+    @staticmethod
+    def _build_coana_node_cmd(script_path: str, coana_args: List[str]) -> List[str]:
+        """Run a .js/.mjs entry via ``node``; invoke a native binary directly (Node CLI parity)."""
+        if script_path.endswith(".js") or script_path.endswith(".mjs"):
+            return ["node", script_path, *coana_args]
+        return [script_path, *coana_args]
+
+    def _extract_scan_id(self, facts_file_path: str) -> Optional[str]:
+        """
+        Extract tier1ReachabilityScanId from the socket facts JSON file.
+        
+        Args:
+            facts_file_path: Path to the .socket.facts.json file
+            
+        Returns:
+            Optional[str]: The scan ID if found, None otherwise
+        """
+        try:
+            if not os.path.exists(facts_file_path):
+                log.warning(f"Facts file not found: {facts_file_path}")
+                return None
+            
+            with open(facts_file_path, 'r') as f:
+                facts = json.load(f)
+            
+            scan_id = facts.get('tier1ReachabilityScanId')
+            return scan_id.strip() if scan_id else None
+        
+        except (json.JSONDecodeError, IOError) as e:
+            log.warning(f"Failed to extract scan ID from {facts_file_path}: {e}")
+            return None

{socketsecurity-2.4.5 → socketsecurity-2.4.7}/socketsecurity/socketcli.py

@@ -189,7 +189,7 @@ def main_code():
     # Check for required dependencies if reachability analysis is enabled
     if config.reach:
         log.info("Reachability analysis enabled, checking for required dependencies...")
-        required_deps = ["npm", "uv", "npx"]
+        required_deps = ["npm", "node", "uv", "npx"]
         missing_deps = []
         found_deps = []