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

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.

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

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(
@@ -920,7 +985,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")

socketsecurity/socketcli.py

@@ -388,7 +388,15 @@ 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,