feat: add Socket tier 1 reachability analysis support

- Add --reach flag and related CLI arguments for reachability analysis
- Add ReachabilityAnalyzer class to run @coana-tech/cli
- Add dependency checks for java, npm, uv, npx when --reach is enabled
- Add --only-facts-file mode to submit only .socket.facts.json
- Auto-install @coana-tech/cli if not present
- Stream reachability CLI output to stderr for user visibility
- Filter .socket.facts.json from manifest uploads but include in full scans
- Set tmp=False in FullScanParams to fix API 400 errors

Author: dacoburn

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.2.15"
+version = "2.2.16"
 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.16'
 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