socketsecurity 2.4.1__tar.gz → 2.4.3__tar.gz

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2.4.3
+
+### Added: unified `--exclude-paths` for manifest discovery and reachability
+
+- New `--exclude-paths` flag (comma-separated globs) that excludes matching paths from
+  BOTH SCA manifest discovery and reachability analysis. Patterns are scan-root-relative
+  anchored globs (`*` does not cross `/`, `**` does), matching the Node CLI's behavior.
+- Pattern validation rejects unsupported forms (negation, absolute paths, `..` traversal,
+  and match-everything patterns). Patterns may be supplied on the CLI as a comma-separated
+  string or via a `--config` file list.
+- `--reach-exclude-paths` is now deprecated in favor of `--exclude-paths`. It still works
+  (and is unioned into the Coana `--exclude-dirs` argument) but is marked deprecated in
+  `--help` and warns at runtime.
+
+## 2.4.2
+
+### Added: reachability flag and Coana environment alignment with the Node CLI
+
+- New `--reach-disable-external-tool-checks` flag (passes `--disable-external-tool-checks`
+  to the Coana CLI).
+- New `--reach-debug` flag to enable Coana debug output (`--debug`) independently of the
+  global `--enable-debug`.
+- Node-style `--reach-analysis-timeout` and `--reach-analysis-memory-limit` are now the
+  primary flag names; the previous `--reach-timeout` / `--reach-memory-limit` continue to
+  work as hidden aliases.
+- The Coana subprocess now receives `SOCKET_CLI_VERSION` and `SOCKET_CALLER_USER_AGENT` so
+  calls are attributed to the Python CLI. Proxies continue to work via the inherited
+  `HTTPS_PROXY` / `HTTP_PROXY` environment variables, which Coana reads itself.
+- `SOCKET_REPO_NAME` / `SOCKET_BRANCH_NAME` are no longer forwarded to Coana when the repo
+  and branch are the default sentinels, avoiding cross-run reachability cache-bucket
+  collisions.
+- Tier 1 reachability finalize now retries with exponential backoff instead of giving up on
+  the first transient error.
+
 ## 2.4.1
 
 ### Added: pyenv in the Docker image

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/PKG-INFO

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

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/docs/cli-reference.md

@@ -148,14 +148,14 @@ socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--workspace WORKSPACE] [--
           [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]]
           [--target-path TARGET_PATH] [--sbom-file SBOM_FILE] [--license-file-name LICENSE_FILE_NAME] [--save-submitted-files-list SAVE_SUBMITTED_FILES_LIST]
           [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME]
-          [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug]
+          [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--exclude-paths EXCLUDE_PATHS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug]
           [--enable-json] [--enable-sarif] [--sarif-file <path>] [--sarif-scope {diff,full}] [--sarif-grouping {instance,alert}] [--sarif-reachability {all,reachable,potentially,reachable-or-potentially}] [--enable-gitlab-security] [--gitlab-security-file <path>]
           [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue]
           [--ignore-commit-files] [--disable-blocking] [--disable-ignore] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders]
-          [--reach] [--reach-version REACH_VERSION] [--reach-timeout REACH_ANALYSIS_TIMEOUT]
-          [--reach-memory-limit REACH_ANALYSIS_MEMORY_LIMIT] [--reach-ecosystems REACH_ECOSYSTEMS] [--reach-exclude-paths REACH_EXCLUDE_PATHS]
-          [--reach-min-severity {low,medium,high,critical}] [--reach-skip-cache] [--reach-disable-analytics] [--reach-output-file REACH_OUTPUT_FILE]
-          [--only-facts-file] [--version]
+          [--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-output-file REACH_OUTPUT_FILE] [--only-facts-file] [--version]
 ````
 
 If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_TOKEN`
@@ -203,6 +203,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 | `--sub-path`                  | False    |                       | Sub-path within target-path for manifest file scanning (can be specified multiple times). All sub-paths are combined into a single workspace scan while preserving git context from target-path. Must be used with `--workspace-name` |
 | `--workspace-name`            | False    |                       | Workspace name suffix to append to repository name (repo-name-workspace_name). Must be used with `--sub-path`                                                                     |
 | `--excluded-ecosystems`       | False    | []                    | List of ecosystems to exclude from analysis (JSON array string). You can get supported files from the [Supported Files API](https://docs.socket.dev/reference/getsupportedfiles) |
+| `--exclude-paths`             | False    |                       | Comma-separated paths/globs to exclude from **both** manifest discovery (every scan) **and** reachability analysis (e.g. `tests/**,packages/legacy,*.spec.ts`). Patterns are scan-root-relative, case-sensitive globs where `*` does not cross `/` and `**` does. Supersedes `--reach-exclude-paths`. |
 
 #### Branch and Scan Configuration
 | Parameter                | Required | Default | Description                                                                                           |
@@ -239,16 +240,18 @@ If you don't want to provide the Socket API Token every time then you can use th
 |:---------------------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------|
 | `--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-timeout`                  | False    | 1200    | Timeout in seconds for the reachability analysis (default: 1200 seconds / 20 minutes)                                      |
-| `--reach-memory-limit`             | False    | 4096    | Memory limit in MB for the reachability analysis (default: 4096 MB / 4 GB)                                                 |
-| `--reach-concurrency`              | False    |         | Control parallel analysis execution (must be >= 1)                                                                         |
+| `--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-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-exclude-paths`            | False    |         | Comma-separated list of file paths or patterns to exclude from reachability analysis                                       |
 | `--reach-min-severity`             | False    |         | Minimum severity level for reporting reachability results (low, medium, high, critical)                                    |
 | `--reach-skip-cache`               | False    | False   | Skip cache and force fresh reachability analysis                                                                           |
 | `--reach-disable-analytics`        | False    | False   | Disable analytics collection during reachability analysis                                                                  |
+| `--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)                            |
 
 **Reachability Analysis Requirements:**

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/pyproject.toml

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

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/socketsecurity/__init__.py

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

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/socketsecurity/config.py

@@ -55,6 +55,50 @@ def load_cli_config_file(config_path: str) -> dict:
         return scoped
     return data
 
+def normalize_exclude_paths(value) -> Optional[List[str]]:
+    """Normalize a --exclude-paths value into a clean list of patterns.
+
+    Accepts a comma-separated string (CLI) or a list/tuple (e.g. a JSON/TOML --config file
+    value), so config-file-supplied patterns flow through the same validation as CLI ones.
+    """
+    if not value:
+        return None
+    if isinstance(value, str):
+        items = value.split(",")
+    elif isinstance(value, (list, tuple)):
+        items = value
+    else:
+        return None
+    cleaned = [str(p).strip() for p in items if str(p).strip()]
+    return cleaned or None
+
+
+def validate_exclude_paths(patterns: List[str]) -> None:
+    """Validate --exclude-paths patterns (mirrors Node's assertValidExcludePaths).
+
+    Patterns are scan-root-relative globs. Reject the cases coana's --exclude-dirs / fast-glob
+    cannot honor: negation, absolute paths, ``..`` traversal, and degenerate match-everything.
+    Exits with code 1 on the first invalid pattern.
+    """
+    # Degenerate match-everything forms, compared against the trailing-slash-stripped pattern
+    # (so "**/" reduces to "**" and is rejected, matching Node's stripTrailingSlash + check).
+    degenerate = {"", ".", "**", "./**", "/**"}
+    for p in patterns:
+        norm = (p or "").strip().replace("\\", "/")
+        if norm.startswith("!"):
+            logging.error(f"--exclude-paths: negation patterns are not supported: {p!r}")
+            exit(1)
+        if norm.startswith("/"):
+            logging.error(f"--exclude-paths: patterns must be scan-root relative (no leading '/'): {p!r}")
+            exit(1)
+        if norm == ".." or norm.startswith("../") or "/../" in norm or norm.endswith("/.."):
+            logging.error(f"--exclude-paths: '..' path traversal is not allowed: {p!r}")
+            exit(1)
+        if norm.rstrip("/") in degenerate:
+            logging.error(f"--exclude-paths: pattern would exclude everything: {p!r}")
+            exit(1)
+
+
 @dataclass
 class PluginConfig:
     enabled: bool = False
@@ -106,6 +150,7 @@ class CliConfig:
     include_module_folders: bool = False
     repo_is_public: bool = False
     excluded_ecosystems: list[str] = field(default_factory=lambda: [])
+    exclude_paths: Optional[List[str]] = None
     version: str = __version__
     jira_plugin: PluginConfig = field(default_factory=PluginConfig)
     slack_plugin: PluginConfig = field(default_factory=PluginConfig)
@@ -139,6 +184,8 @@ class CliConfig:
     reach_continue_on_install_errors: bool = False
     reach_continue_on_missing_lock_files: bool = False
     reach_continue_on_no_source_files: bool = False
+    reach_debug: bool = False
+    reach_disable_external_tool_checks: bool = False
     max_purl_batch_size: int = 5000
     enable_commit_status: bool = False
     legal: bool = False
@@ -165,6 +212,12 @@ class CliConfig:
 
         args = parser.parse_args(args_list)
 
+        if args.reach_exclude_paths:
+            logging.warning(
+                "--reach-exclude-paths is deprecated; use --exclude-paths instead. "
+                "It is still honored and unioned with --exclude-paths."
+            )
+
         # Get API token from env or args (check multiple env var names)
         api_token = (
             os.getenv("SOCKET_SECURITY_API_KEY") or
@@ -256,6 +309,7 @@ class CliConfig:
             'reach_lazy_mode': args.reach_lazy_mode,
             'reach_ecosystems': args.reach_ecosystems.split(',') if args.reach_ecosystems else None,
             'reach_exclude_paths': args.reach_exclude_paths.split(',') if args.reach_exclude_paths else None,
+            'exclude_paths': normalize_exclude_paths(args.exclude_paths),
             'reach_skip_cache': args.reach_skip_cache,
             'reach_min_severity': args.reach_min_severity,
             'reach_output_file': args.reach_output_file,
@@ -267,6 +321,8 @@ class CliConfig:
             'reach_continue_on_install_errors': args.reach_continue_on_install_errors,
             'reach_continue_on_missing_lock_files': args.reach_continue_on_missing_lock_files,
             'reach_continue_on_no_source_files': args.reach_continue_on_no_source_files,
+            'reach_debug': args.reach_debug,
+            'reach_disable_external_tool_checks': args.reach_disable_external_tool_checks,
             'max_purl_batch_size': args.max_purl_batch_size,
             'enable_commit_status': args.enable_commit_status,
             'legal': args.legal or args.legal_format == "fossa",
@@ -357,6 +413,10 @@ class CliConfig:
             logging.error("--sarif-reachability potentially/reachable-or-potentially requires --sarif-scope full")
             exit(1)
 
+        # Validate --exclude-paths patterns up front (mirrors Node's assertValidExcludePaths).
+        if config_args.get("exclude_paths"):
+            validate_exclude_paths(config_args["exclude_paths"])
+
         # Validate that only_facts_file requires reach
         if args.only_facts_file and not args.reach:
             logging.error("--only-facts-file requires --reach to be specified")
@@ -566,6 +626,15 @@ def create_argument_parser() -> argparse.ArgumentParser:
         help="List of ecosystems to exclude from analysis (JSON array string)"
     )
 
+    path_group.add_argument(
+        "--exclude-paths",
+        dest="exclude_paths",
+        metavar="<list>",
+        help="Comma-separated paths/globs to exclude from BOTH manifest discovery and "
+             "reachability analysis (e.g. 'tests/**,packages/legacy,*.spec.ts'). "
+             "Supersedes --reach-exclude-paths."
+    )
+
     # Branch and Scan Configuration
     config_group = parser.add_argument_group('Branch and Scan Configuration')
     config_group.add_argument(
@@ -878,18 +947,32 @@ def create_argument_parser() -> argparse.ArgumentParser:
         help="Specific version of @coana-tech/cli to use (e.g., '1.2.3')"
     )
     reachability_group.add_argument(
-        "--reach-timeout",
+        "--reach-analysis-timeout",
         dest="reach_analysis_timeout",
         type=int,
         metavar="<seconds>",
         help="Timeout for reachability analysis in seconds"
     )
+    # Backwards-compatible alias for the pre-alignment name. Kept working, hidden from help.
     reachability_group.add_argument(
-        "--reach-memory-limit",
+        "--reach-timeout",
+        dest="reach_analysis_timeout",
+        type=int,
+        help=argparse.SUPPRESS
+    )
+    reachability_group.add_argument(
+        "--reach-analysis-memory-limit",
         dest="reach_analysis_memory_limit",
         type=int,
         metavar="<mb>",
-        help="Memory limit for reachability analysis in MB"
+        help="Memory limit for reachability analysis in MB (defaults to the coana CLI's own default, currently 8192)"
+    )
+    # Backwards-compatible alias for the pre-alignment name. Kept working, hidden from help.
+    reachability_group.add_argument(
+        "--reach-memory-limit",
+        dest="reach_analysis_memory_limit",
+        type=int,
+        help=argparse.SUPPRESS
     )
     reachability_group.add_argument(
         "--reach-ecosystems",
@@ -901,7 +984,8 @@ def create_argument_parser() -> argparse.ArgumentParser:
         "--reach-exclude-paths",
         dest="reach_exclude_paths",
         metavar="<list>",
-        help="Paths to exclude from reachability analysis (comma-separated)"
+        help="[DEPRECATED: use --exclude-paths] Paths to exclude from reachability analysis "
+             "(comma-separated). Still honored and unioned with --exclude-paths."
     )
     reachability_group.add_argument(
         "--reach-min-severity",
@@ -957,7 +1041,7 @@ def create_argument_parser() -> argparse.ArgumentParser:
         dest="reach_concurrency",
         type=int,
         metavar="<number>",
-        help="Concurrency level for reachability analysis (must be >= 1)"
+        help="Concurrency level for reachability analysis (must be >= 1; defaults to the coana CLI's own default, currently 1)"
     )
     reachability_group.add_argument(
         "--reach-additional-params",
@@ -1002,6 +1086,20 @@ def create_argument_parser() -> argparse.ArgumentParser:
         action="store_true",
         help=argparse.SUPPRESS
     )
+    reachability_group.add_argument(
+        "--reach-debug",
+        dest="reach_debug",
+        action="store_true",
+        help="Enable debug output for the reachability analysis (passes --debug to the coana CLI). "
+             "Independent of the global --enable-debug flag."
+    )
+    reachability_group.add_argument(
+        "--reach-disable-external-tool-checks",
+        dest="reach_disable_external_tool_checks",
+        action="store_true",
+        help="Disable coana's external tool availability checks during reachability analysis "
+             "(passes --disable-external-tool-checks to the coana CLI)."
+    )
 
     parser.add_argument(
         '--version',

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/socketsecurity/core/__init__.py

@@ -71,6 +71,11 @@ 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.
+TIER1_FINALIZE_MAX_ATTEMPTS = 3
+TIER1_FINALIZE_BACKOFF_SECONDS = 1.0
+
 
 def _humanize_alert_type(alert_type: str) -> str:
     """Convert a camelCase/PascalCase alert type into a Title-Cased label.
@@ -208,6 +213,67 @@ class Core:
                 return True
         return False
 
+    @staticmethod
+    def _exclude_glob_to_regex(pattern: str) -> str:
+        """Translate a micromatch-style glob into an anchored regex string.
+
+        Mirrors the Node CLI's --exclude-paths matcher (src/commands/scan/exclude-paths.mts):
+        patterns are matched against scan-root-relative POSIX paths, case-sensitively, where
+        ``*`` does NOT cross ``/`` and ``**`` DOES. Patterns are anchored at the scan root, so
+        ``tests`` matches ``tests`` (not ``src/tests``); use ``**/tests`` to match at any depth.
+        """
+        i, n = 0, len(pattern)
+        out = ["^"]
+        while i < n:
+            c = pattern[i]
+            if c == "*":
+                if i + 1 < n and pattern[i + 1] == "*":
+                    if i + 2 < n and pattern[i + 2] == "/":
+                        out.append("(?:[^/]+/)*")  # '**/' -> zero or more path segments
+                        i += 3
+                    else:
+                        out.append(".*")           # '**' at end / before non-slash -> any, incl '/'
+                        i += 2
+                else:
+                    out.append("[^/]*")            # '*' -> within a single path segment
+                    i += 1
+            elif c == "?":
+                out.append("[^/]")
+                i += 1
+            else:
+                out.append(re.escape(c))
+                i += 1
+        out.append("$")
+        return "".join(out)
+
+    @staticmethod
+    def compile_exclude_paths(patterns: Optional[List[str]]) -> List["re.Pattern"]:
+        """Compile --exclude-paths globs into anchored regexes (compiled once per scan).
+
+        Each pattern ``P`` is expanded the way Node feeds fast-glob's ``ignore``: ``P`` (a file-
+        or dir-shaped exact match) plus ``P/**`` (its subtree), unless ``P`` already ends with
+        ``/**``. Validation of the patterns happens earlier, in CliConfig.from_args.
+        """
+        compiled: List["re.Pattern"] = []
+        for raw in patterns or []:
+            p = (raw or "").strip().replace("\\", "/").rstrip("/")
+            if not p:
+                continue
+            globs = [p] if p.endswith("/**") else [p, f"{p}/**"]
+            compiled.extend(re.compile(Core._exclude_glob_to_regex(g)) for g in globs)
+        return compiled
+
+    @staticmethod
+    def path_matches_exclude_regexes(rel_path: str, regexes: List["re.Pattern"]) -> bool:
+        rp = rel_path.replace(os.sep, "/").replace("\\", "/")
+        return any(r.match(rp) for r in regexes)
+
+    @staticmethod
+    def matches_exclude_paths(file_path: str, base_path: str, patterns: List[str]) -> bool:
+        """Convenience matcher (compiles patterns per call); used in tests/ad-hoc checks."""
+        rel_path = os.path.relpath(file_path, base_path).replace(os.sep, "/")
+        return Core.path_matches_exclude_regexes(rel_path, Core.compile_exclude_paths(patterns))
+
     def save_submitted_files_list(self, files: List[str], output_path: str) -> None:
         """
         Save the list of submitted file names to a JSON file for debugging.
@@ -331,6 +397,17 @@ class Core:
         start_time = time.time()
         files: Set[str] = set()
 
+        # Unified --exclude-paths: filter discovered manifests by the same paths/globs that are
+        # forwarded to coana's --exclude-dirs. Only consulted when the user supplied the flag.
+        # Patterns are anchored to `path` (the scan root this pass walks), matching coana's
+        # target and the Node CLI's fast-glob cwd. NOTE: when scanning multiple --sub-path
+        # targets, find_files runs once per sub-path, so a pattern like `tests` anchors to each
+        # sub-path independently (Node anchors all patterns to a single scan-root cwd). This only
+        # differs for the multi-target full-scan + --exclude-paths combo; the reach flow is
+        # single-target, so it matches Node there.
+        exclude_paths = getattr(self.cli_config, "exclude_paths", None) if self.cli_config else None
+        exclude_regexes = Core.compile_exclude_paths(exclude_paths) if exclude_paths else []
+
         # Get supported patterns from the API
         patterns = self.get_supported_patterns()
 
@@ -360,8 +437,15 @@ class Core:
 
                     for glob_file in glob_files:
                         glob_file_str = str(glob_file)
-                        if os.path.isfile(glob_file_str) and not Core.is_excluded(glob_file_str, self.config.excluded_dirs):
-                            files.add(glob_file_str.replace("\\", "/"))
+                        if not os.path.isfile(glob_file_str):
+                            continue
+                        if Core.is_excluded(glob_file_str, self.config.excluded_dirs):
+                            continue
+                        if exclude_regexes:
+                            rel = os.path.relpath(glob_file_str, path)
+                            if Core.path_matches_exclude_regexes(rel, exclude_regexes):
+                                continue
+                        files.add(glob_file_str.replace("\\", "/"))
 
                     glob_end = time.time()
                     log.debug(f"Globbing took {glob_end - glob_start:.4f} seconds")
@@ -549,20 +633,43 @@ 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
-        try:
-            success = self.sdk.fullscans.finalize_tier1(
-                full_scan_id=full_scan_id,
-                tier1_reachability_scan_id=tier1_scan_id,
-            )
+        # Call the SDK to finalize the tier 1 scan, retrying transient failures with backoff.
+        last_error: Optional[Exception] = None
+        for attempt in range(1, TIER1_FINALIZE_MAX_ATTEMPTS + 1):
+            try:
+                success = self.sdk.fullscans.finalize_tier1(
+                    full_scan_id=full_scan_id,
+                    tier1_reachability_scan_id=tier1_scan_id,
+                )
 
-            if success:
-                log.debug(f"Successfully finalized tier 1 scan {tier1_scan_id} for full scan {full_scan_id}")
-            return success
+                if success:
+                    log.debug(f"Successfully finalized tier 1 scan {tier1_scan_id} for full scan {full_scan_id}")
+                    return True
 
-        except Exception as e:
-            log.debug(f"Unable to finalize tier 1 scan: {e}")
-            return False
+                log.debug(
+                    f"finalize_tier1 returned a falsy result for scan {tier1_scan_id} "
+                    f"(attempt {attempt}/{TIER1_FINALIZE_MAX_ATTEMPTS})"
+                )
+            except Exception as e:
+                last_error = e
+                log.debug(
+                    f"Unable to finalize tier 1 scan (attempt {attempt}/{TIER1_FINALIZE_MAX_ATTEMPTS}): {e}"
+                )
+
+            if attempt < TIER1_FINALIZE_MAX_ATTEMPTS:
+                time.sleep(TIER1_FINALIZE_BACKOFF_SECONDS * (2 ** (attempt - 1)))
+
+        if last_error is not None:
+            log.debug(
+                f"Giving up finalizing tier 1 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"{TIER1_FINALIZE_MAX_ATTEMPTS} attempts"
+            )
+        return False
 
     @staticmethod
     def _compress_facts_file(source_path: str) -> str:

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/socketsecurity/core/tools/reachability.py

@@ -1,15 +1,31 @@
 from socketdev import socketdev
 from typing import List, Optional, Dict, Any
 import os
+import platform
 import subprocess
 import json
 import pathlib
 import logging
 import sys
 
+from socketsecurity import __version__
+
 log = logging.getLogger(__name__)
 
 
+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
@@ -108,6 +124,8 @@ class ReachabilityAnalyzer:
         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.
@@ -147,8 +165,7 @@ class ReachabilityAnalyzer:
         
         # Add required arguments
         output_dir = str(pathlib.Path(output_path).parent)
-        log.warning(f"output_dir: {output_dir}")
-        log.warning(f"output_path: {output_path}")
+        log.debug(f"output_dir: {output_dir}, output_path: {output_path}")
         cmd.extend([
             "--output-dir", output_dir,
             "--socket-mode", output_path,
@@ -197,6 +214,12 @@ class ReachabilityAnalyzer:
         if enable_debug:
             cmd.append("-d")
 
+        if reach_debug:
+            cmd.append("--debug")
+
+        if disable_external_tool_checks:
+            cmd.append("--disable-external-tool-checks")
+
         if use_only_pregenerated_sboms:
             cmd.append("--use-only-pregenerated-sboms")
 
@@ -222,14 +245,25 @@ class ReachabilityAnalyzer:
         # Required environment variables for Coana CLI
         env["SOCKET_ORG_SLUG"] = org_slug
         env["SOCKET_CLI_API_TOKEN"] = self.api_token
-        
-        # Optional environment variables
+
+        # 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"

{socketsecurity-2.4.1 → socketsecurity-2.4.3}/socketsecurity/socketcli.py

@@ -95,6 +95,12 @@ def _write_attribution_file(config, payload: dict) -> None:
 
 DEFAULT_API_TIMEOUT = 1200
 
+# Sentinel repo/branch names used when none can be detected from git or supplied via flags.
+# When the repo/branch are these defaults we skip forwarding SOCKET_REPO_NAME/SOCKET_BRANCH_NAME
+# to the coana CLI so unrelated default-named runs don't share reachability cache buckets.
+DEFAULT_REPO_NAME = "socket-default-repo"
+DEFAULT_BRANCH_NAME = "socket-default-branch"
+
 
 def get_api_request_timeout(config: CliConfig) -> int:
     return config.timeout if config.timeout is not None else DEFAULT_API_TIMEOUT
@@ -288,16 +294,21 @@ def main_code():
     except NoSuchPathError:
         raise Exception(f"Unable to find path {config.target_path}")
 
+    # Track whether repo/branch fell back to the default sentinels so reachability can skip
+    # forwarding them as coana cache-bucket keys (computed before any workspace suffixing).
+    repo_defaulted = not config.repo
+    branch_defaulted = not config.branch
+
     if not config.repo:
-        base_repo_name = "socket-default-repo"
+        base_repo_name = DEFAULT_REPO_NAME
         if config.workspace_name:
             config.repo = f"{base_repo_name}-{config.workspace_name}"
         else:
             config.repo = base_repo_name
         log.debug(f"Using default repository name: {config.repo}")
-        
+
     if not config.branch:
-        config.branch = "socket-default-branch"
+        config.branch = DEFAULT_BRANCH_NAME
         log.debug(f"Using default branch name: {config.branch}")
 
     # Calculate the scan paths - combine target_path with sub_paths if provided
@@ -377,15 +388,23 @@ def main_code():
                     timeout=config.reach_analysis_timeout,
                     memory_limit=config.reach_analysis_memory_limit,
                     ecosystems=config.reach_ecosystems,
-                    exclude_paths=config.reach_exclude_paths,
+                    # Union the deprecated --reach-exclude-paths with the unified --exclude-paths
+                    # and forward verbatim to coana's --exclude-dirs. Patterns are scan-root
+                    # relative; coana resolves --exclude-dirs relative to its `run` target, which
+                    # here is `.` == cwd == scan root, so passthrough is correct. If a nested
+                    # target is ever supported, re-anchor patterns to the target first (see Node's
+                    # pathRelativeToTarget in exclude-paths.mts).
+                    exclude_paths=(
+                        (config.reach_exclude_paths or []) + (config.exclude_paths or [])
+                    ) or None,
                     min_severity=config.reach_min_severity,
                     skip_cache=config.reach_skip_cache or False,
                     disable_analytics=config.reach_disable_analytics or False,
                     enable_analysis_splitting=config.reach_enable_analysis_splitting or False,
                     detailed_analysis_log_file=config.reach_detailed_analysis_log_file or False,
                     lazy_mode=config.reach_lazy_mode or False,
-                    repo_name=config.repo,
-                    branch_name=config.branch,
+                    repo_name=None if repo_defaulted else config.repo,
+                    branch_name=None if branch_defaulted else config.branch,
                     version=config.reach_version,
                     concurrency=config.reach_concurrency,
                     additional_params=config.reach_additional_params,
@@ -396,6 +415,8 @@ def main_code():
                     continue_on_install_errors=config.reach_continue_on_install_errors,
                     continue_on_missing_lock_files=config.reach_continue_on_missing_lock_files,
                     continue_on_no_source_files=config.reach_continue_on_no_source_files,
+                    reach_debug=config.reach_debug,
+                    disable_external_tool_checks=config.reach_disable_external_tool_checks,
                 )
                 
                 log.info("Reachability analysis completed successfully")