feat: add Socket tier 1 reachability analysis support

README.md

@@ -94,7 +94,11 @@ socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branc
           [--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] 
           [--enable-json] [--enable-sarif] [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue] 
-          [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders] [--version]
+          [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders] 
+          [--reach] [--reach-version REACH_VERSION] [--reach-analysis-timeout REACH_ANALYSIS_TIMEOUT] 
+          [--reach-analysis-memory-limit REACH_ANALYSIS_MEMORY_LIMIT] [--reach-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]
 ````
 
 If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_KEY`
@@ -160,6 +164,28 @@ If you don't want to provide the Socket API Token every time then you can use th
 | --allow-unverified       | False    | False   | Allow unverified packages     |
 | --disable-security-issue | False    | False   | Disable security issue checks |
 
+#### Reachability Analysis
+| Parameter                        | Required | Default | Description                                                                                                                |
+|:---------------------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------|
+| --reach                          | False    | False   | Enable reachability analysis to identify which vulnerable functions are actually called by your code                       |
+| --reach-version                  | False    | latest  | Version of @coana-tech/cli to use for analysis                                                                             |
+| --reach-analysis-timeout         | False    | 1200    | Timeout in seconds for the reachability analysis (default: 1200 seconds / 20 minutes)                                      |
+| --reach-analysis-memory-limit    | False    | 4096    | Memory limit in MB for the reachability analysis (default: 4096 MB / 4 GB)                                                 |
+| --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-output-file              | False    | .socket.facts.json | Path where reachability analysis results should be saved                                                        |
+| --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:**
+- `npm` - Required to install and run @coana-tech/cli
+- `npx` - Required to execute @coana-tech/cli
+- `uv` - Required for Python environment management
+
+The CLI will automatically install @coana-tech/cli if not present. Use `--reach` to enable reachability analysis during a full scan, or use `--only-facts-file` with `--reach` to submit reachability results to an existing scan.
+
 #### Advanced Configuration
 | Parameter                | Required | Default | Description                                                           |
 |:-------------------------|:---------|:--------|:----------------------------------------------------------------------|

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.2.15"
+version = "2.2.18"
 requires-python = ">= 3.10"
 license = {"file" = "LICENSE"}
 dependencies = [
@@ -16,7 +16,8 @@ dependencies = [
     'GitPython',
     'packaging',
     'python-dotenv',
-    'socketdev>=3.0.6,<4.0.0'
+    'socketdev>=3.0.6,<4.0.0',
+    "bs4>=0.0.2",
 ]
 readme = "README.md"
 description = "Socket Security CLI for CI/CD"
@@ -158,4 +159,4 @@ docstring-code-format = false
 docstring-code-line-length = "dynamic"
 
 [tool.hatch.build.targets.wheel]
-include = ["socketsecurity", "LICENSE"]
+include = ["socketsecurity", "LICENSE"]

socketsecurity/__init__.py

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

socketsecurity/config.py

@@ -62,7 +62,19 @@ class CliConfig:
     save_manifest_tar: Optional[str] = None
     sub_paths: List[str] = field(default_factory=list)
     workspace_name: Optional[str] = None
-
+    # Reachability Flags
+    reach: bool = False
+    reach_version: Optional[str] = None
+    reach_analysis_memory_limit: Optional[int] = None
+    reach_analysis_timeout: Optional[int] = None
+    reach_disable_analytics: bool = False
+    reach_ecosystems: Optional[List[str]] = None
+    reach_exclude_paths: Optional[List[str]] = None
+    reach_skip_cache: bool = False
+    reach_min_severity: Optional[str] = None
+    reach_output_file: Optional[str] = None
+    only_facts_file: bool = False
+
     @classmethod
     def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
         parser = create_argument_parser()
@@ -110,6 +122,17 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
             'save_manifest_tar': args.save_manifest_tar,
             'sub_paths': args.sub_paths or [],
             'workspace_name': args.workspace_name,
+            'reach': args.reach,
+            'reach_version': args.reach_version,
+            'reach_analysis_timeout': args.reach_analysis_timeout,
+            'reach_analysis_memory_limit': args.reach_analysis_memory_limit,
+            'reach_disable_analytics': args.reach_disable_analytics,
+            '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,
+            'reach_skip_cache': args.reach_skip_cache,
+            'reach_min_severity': args.reach_min_severity,
+            'reach_output_file': args.reach_output_file,
+            'only_facts_file': args.only_facts_file,
             'version': __version__
         }
         try:
@@ -141,6 +164,11 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
             logging.error("--workspace-name requires --sub-path to be specified")
             exit(1)
 
+        # 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")
+            exit(1)
+
         return cls(**config_args)
 
     def to_dict(self) -> dict:
@@ -474,6 +502,78 @@ def create_argument_parser() -> argparse.ArgumentParser:
         help="Enabling including module folders like node_modules"
     )
 
+    # Reachability Configuration
+    reachability_group = parser.add_argument_group('Reachability Analysis')
+    reachability_group.add_argument(
+        "--reach",
+        dest="reach",
+        action="store_true",
+        help="Enable reachability analysis"
+    )
+    reachability_group.add_argument(
+        "--reach-version",
+        dest="reach_version",
+        metavar="<version>",
+        help="Specific version of @coana-tech/cli to use (e.g., '1.2.3')"
+    )
+    reachability_group.add_argument(
+        "--reach-timeout",
+        dest="reach_analysis_timeout",
+        type=int,
+        metavar="<seconds>",
+        help="Timeout for reachability analysis in seconds"
+    )
+    reachability_group.add_argument(
+        "--reach-memory-limit",
+        dest="reach_analysis_memory_limit",
+        type=int,
+        metavar="<mb>",
+        help="Memory limit for reachability analysis in MB"
+    )
+    reachability_group.add_argument(
+        "--reach-ecosystems",
+        dest="reach_ecosystems",
+        metavar="<list>",
+        help="Ecosystems to analyze for reachability (comma-separated, e.g., 'npm,pypi')"
+    )
+    reachability_group.add_argument(
+        "--reach-exclude-paths",
+        dest="reach_exclude_paths",
+        metavar="<list>",
+        help="Paths to exclude from reachability analysis (comma-separated)"
+    )
+    reachability_group.add_argument(
+        "--reach-min-severity",
+        dest="reach_min_severity",
+        metavar="<level>",
+        help="Minimum severity level for reachability analysis (info, low, moderate, high, critical)"
+    )
+    reachability_group.add_argument(
+        "--reach-skip-cache",
+        dest="reach_skip_cache",
+        action="store_true",
+        help="Skip cache usage for reachability analysis"
+    )
+    reachability_group.add_argument(
+        "--reach-disable-analytics",
+        dest="reach_disable_analytics",
+        action="store_true",
+        help="Disable analytics sharing for reachability analysis"
+    )
+    reachability_group.add_argument(
+        "--reach-output-file",
+        dest="reach_output_file",
+        metavar="<path>",
+        default=".socket.facts.json",
+        help="Output file path for reachability analysis results (default: .socket.facts.json)"
+    )
+    reachability_group.add_argument(
+        "--only-facts-file",
+        dest="only_facts_file",
+        action="store_true",
+        help="Submit only the .socket.facts.json file when creating full scan (requires --reach)"
+    )
+
     parser.add_argument(
         '--version',
         action='version',

socketsecurity/core/helper/__init__.py

@@ -1,5 +1,6 @@
 import markdown
-from bs4 import BeautifulSoup, NavigableString, Tag
+from bs4 import BeautifulSoup, Tag
+from bs4.element import NavigableString
 import string