socketsecurity 2.4.11__tar.gz → 2.4.13__tar.gz

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2.4.13
+
+### Changed: reachability analysis types now use full names instead of "Tier 1/2/3"
+
+- Reachability analysis types are referred to by their full names instead of the
+  "Tier 1/2/3" numbering: **Full application reachability** (formerly Tier 1),
+  **Precomputed reachability** (formerly Tier 2), and **Dependency reachability**
+  (formerly Tier 3). This updates `--help` text, command output, log messages, and docs
+  only — wire-format values such as the `socket_tier1` scan type are unchanged for
+  backward compatibility. See the reachability section in `docs/cli-reference.md` for the
+  old→new name mapping.
+- Bumped the pinned `@coana-tech/cli` version to `15.5.7`.
+
+## 2.4.12
+
+### Changed: consolidated coana launcher env vars into `SOCKET_CLI_COANA_LAUNCHER`
+
+- The reachability launcher is now tuned via a single `SOCKET_CLI_COANA_LAUNCHER`
+  environment variable (mirroring the Socket Node CLI): `auto` (default when unset; try
+  `npx` first, fall back to `npm install` + `node` on launcher-level failures),
+  `npm-install` (skip `npx` entirely), or `npx` (never fall back). An unrecognized value
+  logs a warning and behaves as `auto`.
+- The legacy `SOCKET_CLI_COANA_FORCE_NPM_INSTALL` and `SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK`
+  variables remain supported for back-compat when `SOCKET_CLI_COANA_LAUNCHER` is unset, but
+  are deprecated and no longer documented.
+
 ## 2.4.11
 
 ### Changed: units for `--reach-analysis-timeout` and `--reach-analysis-memory-limit`

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/PKG-INFO

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

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/docs/cli-reference.md

@@ -240,8 +240,8 @@ 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. Creates a tier-1 full-application reachability scan (`scan_type=socket_tier1`). |
-| `--reach-version`                  | False    | 15.5.0  | 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`                          | False    | False   | Enable reachability analysis to identify which vulnerable functions are actually called by your code. Creates a full application reachability scan (`scan_type=socket_tier1`). |
+| `--reach-version`                  | False    | 15.5.7  | 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    | 10m     | Timeout for each reachability analysis run, e.g. `90s`, `10m` or `1h`. Omitted by default, so coana applies its own default (`10m`). Alias: `--reach-timeout` |
 | `--reach-analysis-memory-limit`    | False    | 8GB     | Memory limit for each reachability analysis run, e.g. `512MB` or `8GB`. Omitted by default, so coana applies its own default (`8GB`). Alias: `--reach-memory-limit` |
 | `--reach-concurrency`              | False    | 1       | Control parallel analysis execution (must be >= 1). Omitted by default, so coana applies its own default.                  |
@@ -271,6 +271,14 @@ 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 analysis types:**
+
+Socket's reachability analysis comes in three forms, referred to by their full names rather than the older "Tier" numbering:
+
+- **Full application reachability** (formerly *Tier 1*) — the full-application analysis enabled by `--reach`.
+- **Precomputed reachability** (formerly *Tier 2*).
+- **Dependency reachability** (formerly *Tier 3*).
+
 ## Config file support
 
 Use `--config <path>` to load defaults from a `.toml` or `.json` file.
@@ -317,9 +325,10 @@ For CI-specific examples and guidance, see [`ci-cd.md`](ci-cd.md).
 
 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.
+The launcher can be tuned via the `SOCKET_CLI_COANA_LAUNCHER` environment variable:
+- `auto` (default when unset) — try `npx` first; fall back to `npm install` + `node` if the launcher fails before the engine starts.
+- `npm-install` — skip `npx` entirely and always use the `npm install` + `node` path (useful where `npx` is known-broken).
+- `npx` — never fall back; surface the `npx` failure directly.
 
 #### Advanced Configuration
 | Parameter                | Required | Default | Description                                                           |

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/docs/troubleshooting.md

@@ -22,7 +22,7 @@ Common reasons:
 - Policy vs dataset:
   - `--strict-blocking` only affects diff-scope behavior and does not make diff output equivalent to full dashboard data.
 - Reachability data availability:
-  - If reachability analysis partially fails and falls back to precomputed tiers, counts can shift.
+  - If reachability analysis partially fails and falls back to precomputed reachability, counts can shift.
 
 Recommended comparison path:
 

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/pyproject.toml

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

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/socketsecurity/__init__.py

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

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/socketsecurity/core/__init__.py

@@ -58,7 +58,7 @@ _HUMANIZE_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z]
 # whose basename is exactly ``.socket.facts.json.br`` and stores it as plain
 # ``.socket.facts.json``. Compressing the facts file on upload keeps it well under the
 # server's per-file size cap (a ~262 MB facts file compresses to roughly 15-30 MB),
-# which is required for large reachability (tier 1) scans to succeed.
+# which is required for large full application reachability scans to succeed.
 #
 # The server matches the *exact* name ``.socket.facts.json.br``, so we only compress
 # files whose basename is exactly ``.socket.facts.json`` (a custom ``--reach-output-file``
@@ -72,8 +72,8 @@ SOCKET_FACTS_BROTLI_LGWIN = 24
 # Stream the facts file in 1 MiB chunks so large files aren't held fully in memory.
 SOCKET_FACTS_BROTLI_CHUNK_SIZE = 1024 * 1024
 
-# Tier 1 reachability finalize retry policy. The finalize call links the tier1 scan to the
-# full scan and can fail transiently (network/API blips); a few backoff retries make it robust.
+# Full application reachability finalize retry policy. The finalize call links the reachability
+# scan to the full scan and can fail transiently (network/API blips); a few backoff retries make it robust.
 TIER1_FINALIZE_MAX_ATTEMPTS = 3
 TIER1_FINALIZE_BACKOFF_SECONDS = 1.0
 
@@ -612,21 +612,21 @@ class Core:
 
     def finalize_tier1_scan(self, full_scan_id: str, facts_file_path: str) -> bool:
         """
-        Finalize a tier 1 reachability scan by associating it with a full scan.
+        Finalize a full application reachability scan by associating it with a full scan.
 
         This function reads the tier1ReachabilityScanId from the facts file and
         calls the SDK to link it with the specified full scan.
 
-        Linking the tier 1 scan to the full scan helps the Socket team debug potential issues.
+        Linking the reachability scan to the full scan helps the Socket team debug potential issues.
 
         Args:
-            full_scan_id: The ID of the full scan to associate with the tier 1 scan
+            full_scan_id: The ID of the full scan to associate with the reachability scan
             facts_file_path: Path to the .socket.facts.json file containing the tier1ReachabilityScanId
 
         Returns:
             True if successful, False otherwise
         """
-        log.debug(f"Finalizing tier 1 scan for full scan {full_scan_id}")
+        log.debug(f"Finalizing full application reachability scan for full scan {full_scan_id}")
 
         # Read the tier1ReachabilityScanId from the facts file
         try:
@@ -649,7 +649,7 @@ class Core:
             log.debug(f"Failed to read tier1ReachabilityScanId from {facts_file_path}: {e}")
             return False
 
-        # Call the SDK to finalize the tier 1 scan, retrying transient failures with backoff.
+        # Call the SDK to finalize the full application reachability scan, retrying transient failures with backoff.
         last_error: Optional[Exception] = None
         for attempt in range(1, TIER1_FINALIZE_MAX_ATTEMPTS + 1):
             try:
@@ -659,7 +659,7 @@ class Core:
                 )
 
                 if success:
-                    log.debug(f"Successfully finalized tier 1 scan {tier1_scan_id} for full scan {full_scan_id}")
+                    log.debug(f"Successfully finalized full application reachability scan {tier1_scan_id} for full scan {full_scan_id}")
                     return True
 
                 log.debug(
@@ -669,7 +669,7 @@ class Core:
             except Exception as e:
                 last_error = e
                 log.debug(
-                    f"Unable to finalize tier 1 scan (attempt {attempt}/{TIER1_FINALIZE_MAX_ATTEMPTS}): {e}"
+                    f"Unable to finalize full application reachability scan (attempt {attempt}/{TIER1_FINALIZE_MAX_ATTEMPTS}): {e}"
                 )
 
             if attempt < TIER1_FINALIZE_MAX_ATTEMPTS:
@@ -677,12 +677,12 @@ class Core:
 
         if last_error is not None:
             log.debug(
-                f"Giving up finalizing tier 1 scan {tier1_scan_id} after "
+                f"Giving up finalizing full application reachability scan {tier1_scan_id} after "
                 f"{TIER1_FINALIZE_MAX_ATTEMPTS} attempts: {last_error}"
             )
         else:
             log.debug(
-                f"Giving up finalizing tier 1 scan {tier1_scan_id} after "
+                f"Giving up finalizing full application reachability scan {tier1_scan_id} after "
                 f"{TIER1_FINALIZE_MAX_ATTEMPTS} attempts"
             )
         return False
@@ -846,21 +846,21 @@ class Core:
         total_time = create_full_end - create_full_start
         log.debug(f"New Full Scan created in {total_time:.2f} seconds")
 
-        # Finalize tier1 scan if reachability analysis was enabled
+        # Finalize full application reachability scan if reachability analysis was enabled
         if self.cli_config and self.cli_config.reach:
             facts_file_path = os.path.join(
-                self.cli_config.target_path or ".", 
+                self.cli_config.target_path or ".",
                 self.cli_config.reach_output_file
             )
-            log.debug(f"Reachability analysis enabled, finalizing tier1 scan for full scan {full_scan.id}")
+            log.debug(f"Reachability analysis enabled, finalizing full application reachability scan for full scan {full_scan.id}")
             try:
                 success = self.finalize_tier1_scan(full_scan.id, facts_file_path)
                 if success:
-                    log.debug(f"Successfully finalized tier1 scan for full scan {full_scan.id}")
+                    log.debug(f"Successfully finalized full application reachability scan for full scan {full_scan.id}")
                 else:
-                    log.debug(f"Failed to finalize tier1 scan for full scan {full_scan.id}")
+                    log.debug(f"Failed to finalize full application reachability scan for full scan {full_scan.id}")
             except Exception as e:
-                log.warning(f"Error finalizing tier1 scan for full scan {full_scan.id}: {e}")
+                log.warning(f"Error finalizing full application reachability scan for full scan {full_scan.id}: {e}")
 
         return full_scan
 

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/socketsecurity/core/tools/reachability.py

@@ -18,7 +18,7 @@ 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.5.0"
+DEFAULT_COANA_CLI_VERSION: Final = "15.5.7"
 
 # 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
@@ -55,7 +55,7 @@ class ReachabilityAnalyzer:
     
     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.5.0').
+        Resolve the @coana-tech/cli package spec to run (e.g. '@coana-tech/cli@15.5.7').
 
         Args:
             version: Coana CLI version to use.
@@ -64,7 +64,7 @@ class ReachabilityAnalyzer:
                 - '<semver>': that exact version.
 
         Returns:
-            str: The package specifier to use with npx (e.g. '@coana-tech/cli@15.5.0').
+            str: The package specifier to use with npx (e.g. '@coana-tech/cli@15.5.7').
         """
         return f"@coana-tech/cli@{self._resolve_coana_version(version)}"
 
@@ -304,6 +304,31 @@ class ReachabilityAnalyzer:
         """
         return returncode < 0 or returncode >= 128
 
+    @staticmethod
+    def _resolve_coana_launcher_mode() -> str:
+        """Resolve the coana launcher mode: ``auto``, ``npx``, or ``npm-install``.
+
+        ``SOCKET_CLI_COANA_LAUNCHER`` wins when set to a recognized value; an unrecognized
+        value warns and behaves as ``auto``. Only when it is unset/empty do the legacy vars
+        apply: ``SOCKET_CLI_COANA_FORCE_NPM_INSTALL`` -> ``npm-install``, else
+        ``SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK`` -> ``npx``. Mirrors the Node CLI.
+        """
+        raw = os.environ.get("SOCKET_CLI_COANA_LAUNCHER", "")
+        mode = raw.strip().lower()
+        if mode in ("auto", "npx", "npm-install"):
+            return mode
+        if mode:
+            log.warning(
+                f'Ignoring unrecognized SOCKET_CLI_COANA_LAUNCHER value "{raw}"; '
+                'expected "auto", "npm-install", or "npx".'
+            )
+            return "auto"
+        if os.environ.get("SOCKET_CLI_COANA_FORCE_NPM_INSTALL"):
+            return "npm-install"
+        if os.environ.get("SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK"):
+            return "npx"
+        return "auto"
+
     def _spawn_coana(
         self,
         coana_args: List[str],
@@ -324,14 +349,15 @@ class ReachabilityAnalyzer:
 
         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).
+        Tune with ``SOCKET_CLI_COANA_LAUNCHER``: ``auto`` (default; npx with the npm-install
+        fallback), ``npm-install`` (skip npx, always use the fallback path), or ``npx``
+        (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"))
+        launcher_mode = self._resolve_coana_launcher_mode()
 
-        if os.environ.get("SOCKET_CLI_COANA_FORCE_NPM_INSTALL"):
+        if launcher_mode == "npm-install":
             return self._spawn_coana_via_npm_install(coana_args, effective_version, coana_env, cwd)
 
         package_spec = f"@coana-tech/cli@{effective_version}"
@@ -347,7 +373,7 @@ class ReachabilityAnalyzer:
             )
         except FileNotFoundError:
             # npx is not on PATH: the launcher provably never started coana.
-            if disable_fallback:
+            if launcher_mode == "npx":
                 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)
@@ -355,7 +381,7 @@ class ReachabilityAnalyzer:
         if result.returncode == 0:
             return 0
 
-        if not disable_fallback and self._npx_launcher_failed_before_coana(result.returncode):
+        if launcher_mode != "npx" 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`."

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/tests/unit/test_reachability.py

@@ -317,6 +317,54 @@ def test_disable_fallback_propagates_npx_failure(analyzer, mocker, monkeypatch):
     assert all(c[:2] != ["npm", "install"] for c in calls)
 
 
+def test_launcher_npm_install_skips_npx(analyzer, mocker, monkeypatch):
+    """SOCKET_CLI_COANA_LAUNCHER=npm-install routes straight to npm install + node."""
+    monkeypatch.setenv("SOCKET_CLI_COANA_LAUNCHER", "npm-install")
+    calls = _capture_spawns(analyzer, mocker, npx_behavior=0)
+    assert all(c[0] != "npx" for c in calls)
+    assert calls[0][:2] == ["npm", "install"]
+    assert calls[1][0] == "node"
+
+
+def test_launcher_npx_propagates_npx_failure(analyzer, mocker, monkeypatch):
+    """SOCKET_CLI_COANA_LAUNCHER=npx: a launcher failure is NOT retried via npm."""
+    monkeypatch.setenv("SOCKET_CLI_COANA_LAUNCHER", "npx")
+    mocker.patch.object(analyzer, "_extract_scan_id", return_value=None)
+    calls = []
+
+    def fake_run(argv, **_kw):
+        calls.append(argv)
+        m = MagicMock()
+        m.returncode = 137
+        return m
+
+    mocker.patch.object(reachability.subprocess, "run", side_effect=fake_run)
+    with pytest.raises(Exception):
+        analyzer.run_reachability_analysis(org_slug="my-org", target_directory=".")
+    assert calls[0][0] == "npx"
+    assert all(c[:2] != ["npm", "install"] for c in calls)
+
+
+def test_launcher_overrides_legacy_vars(analyzer, mocker, monkeypatch):
+    """A recognized SOCKET_CLI_COANA_LAUNCHER wins; legacy vars are ignored entirely."""
+    monkeypatch.setenv("SOCKET_CLI_COANA_LAUNCHER", "auto")
+    monkeypatch.setenv("SOCKET_CLI_COANA_FORCE_NPM_INSTALL", "1")
+    monkeypatch.setenv("SOCKET_CLI_COANA_DISABLE_NPM_FALLBACK", "1")
+    calls = _capture_spawns(analyzer, mocker, npx_behavior=137)
+    assert calls[0][0] == "npx"  # force-npm-install ignored: npx still attempted
+    assert calls[1][:2] == ["npm", "install"]  # disable-fallback ignored: fallback runs
+    assert calls[2][0] == "node"
+
+
+def test_launcher_unrecognized_value_behaves_as_auto(analyzer, mocker, monkeypatch):
+    """An unrecognized SOCKET_CLI_COANA_LAUNCHER value warns and behaves as auto."""
+    monkeypatch.setenv("SOCKET_CLI_COANA_LAUNCHER", "bogus")
+    calls = _capture_spawns(analyzer, mocker, npx_behavior=137)
+    assert calls[0][0] == "npx"
+    assert calls[1][:2] == ["npm", "install"]
+    assert calls[2][0] == "node"
+
+
 def test_fallback_installs_once_per_version(analyzer, mocker):
     """A second in-process fallback for the same version reuses the install (no re-install)."""
     mocker.patch.object(analyzer, "_extract_scan_id", return_value="scan-123")

{socketsecurity-2.4.11 → socketsecurity-2.4.13}/uv.lock

@@ -1283,7 +1283,7 @@ wheels = [
 
 [[package]]
 name = "socketsecurity"
-version = "2.4.11"
+version = "2.4.13"
 source = { editable = "." }
 dependencies = [
     { name = "brotli", marker = "platform_python_implementation == 'CPython'" },