feat(reach): add unified --exclude-paths, deprecate --reach-exclude-paths (#227)

Add a single --exclude-paths flag (Node CLI parity) that filters BOTH SCA manifest
discovery and reachability analysis:

- New Core matcher: anchored micromatch-style globs compiled to regex (no new deps).
  Scan-root-relative POSIX paths, '*' does not cross '/', '**' does, each pattern P
  expanded to [P, P/**]. Threaded into find_files via cli_config; no-op when unset.
- Reach side unions --exclude-paths with the now-deprecated --reach-exclude-paths and
  forwards to coana --exclude-dirs.
- Validation mirrors Node's assertValidExcludePaths (rejects negation, absolute paths,
  '..' traversal, degenerate match-everything; trailing slash stripped so '**/' is rejected).
  Accepts comma-strings and config-file lists.
- --reach-exclude-paths soft-deprecated: still works, [DEPRECATED] in help, warns at runtime.

Docs: document --exclude-paths under 'Path and File' (it affects every scan, not just
reach), mark --reach-exclude-paths deprecated, and refresh the reachability flag table
(--reach-analysis-timeout/-memory-limit primary names, --reach-debug,
--reach-disable-external-tool-checks, defaults delegated to coana).

Adds a CHANGELOG 2.4.3 entry and tests incl. the Node parity cases, validation, and config-file paths.

Author: mtorp

CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

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:**

pyproject.toml

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

socketsecurity/__init__.py

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

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)
@@ -167,6 +212,12 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> '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
@@ -258,6 +309,7 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> '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,
@@ -361,6 +413,10 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> '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")
@@ -570,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(
@@ -919,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",

socketsecurity/core/__init__.py

@@ -213,6 +213,67 @@ def is_excluded(file_path: str, excluded_dirs: Set[str]) -> bool:
                 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.
@@ -336,6 +397,17 @@ def find_files(self, path: str, ecosystems: Optional[List[str]] = None) -> List[
         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()
 
@@ -365,8 +437,15 @@ def find_files(self, path: str, ecosystems: Optional[List[str]] = None) -> List[
 
                     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")