feat: add SKIP_SOCKET_SUBMISSION and SKIP_SOCKET_REACH environment variables for CLI integration (#29)

Add support for environment variables to allow external tools (like the Node.js Socket CLI)
to skip specific operations and collect data for unified API submission.

SKIP_SOCKET_SUBMISSION:
- Skip Socket API submission while still generating .socket.facts.json
- Socket Basics completes all scanning and generates the facts file
- Allows external tools to collect and submit in a unified API call

SKIP_SOCKET_REACH:
- Skip Socket Tier 1 reachability analysis
- Allows external tools to skip redundant reachability scans
- Useful when reachability analysis is performed separately

Benefits:
- Single scan ID for all findings (supply chain + SAST + secrets + containers + reachability)
- Unified dashboard view
- Better performance via parallel execution
- No duplicate API submissions
- Flexible workflow integration

Implementation:
- Added SKIP_SOCKET_SUBMISSION check in submit_socket_facts()
- Added SKIP_SOCKET_REACH check in SocketTier1Scanner.scan()
- Returns early when environment variables are set
- Documented in README under Integration Environment Variables

Author: jdalton

README.md

@@ -89,6 +89,14 @@ All configuration can be managed through:
 
 See [Configuration Documentation](docs/configuration.md) for details on all available options.
 
+#### Integration Environment Variables
+
+Socket Basics supports special environment variables for integration with other tools:
+
+- **`SKIP_SOCKET_REACH=1`** — Skip Socket Tier 1 reachability analysis. This allows external tools (like the Node.js Socket CLI) to skip redundant reachability scans when the analysis will be performed separately or is not needed for a particular workflow.
+
+- **`SKIP_SOCKET_SUBMISSION=1`** — Skip submission to Socket API while still generating `.socket.facts.json`. This allows external tools (like the Node.js Socket CLI) to collect the facts file and submit it along with other data in a unified API call. When this is set, Socket Basics will complete all scanning and generate the facts file, but will not make the API submission call.
+
 ## 🎯 What Socket Basics Does
 
 1. **Scans** your codebase using multiple security tools in parallel

socket_basics/core/connector/socket_tier1/scanner.py

@@ -100,6 +100,13 @@ def _parse_additional_params(self) -> List[str]:
         return shlex.split(raw)
 
     def scan(self) -> Dict[str, Any]:
+        # Check if Socket Tier 1 reachability scan should be skipped (for Node.js Socket CLI integration).
+        # When SKIP_SOCKET_REACH=1, Socket Basics skips the reachability analysis. This allows the Node.js
+        # Socket CLI to skip redundant scans when reachability analysis will be performed separately.
+        if os.getenv('SKIP_SOCKET_REACH') == '1':
+            logger.info("Skipping Socket Tier 1 reachability scan (SKIP_SOCKET_REACH=1)")
+            return {}
+
         # Verify auth
         auth_env = self._get_auth_env()
         if not auth_env.get('SOCKET_ORG') or not auth_env.get('SOCKET_SECURITY_API_KEY'):

socket_basics/socket_basics.py

@@ -199,14 +199,25 @@ def load_notification_manager(self, notifications_cfg: Dict[str, Any] | None = N
 
     def submit_socket_facts(self, socket_facts_path: Path, results: Dict[str, Any]) -> Dict[str, Any]:
         """Submit the socket facts file to Socket API and return full scan results.
-        
+
         Args:
             socket_facts_path: Path to the .socket.facts.json file
             results: Current scan results dict to update with full scan info
-            
+
         Returns:
             Updated results dict with full scan information (id, html_url)
         """
+        # Check if Socket submission should be skipped (for Node.js Socket CLI integration).
+        # When SKIP_SOCKET_SUBMISSION=1, socket-basics generates the .socket.facts.json
+        # file but does not submit it to the Socket API. This allows the Node.js Socket CLI to
+        # collect the facts and submit them in a unified API call along with manifest data.
+        if os.getenv('SKIP_SOCKET_SUBMISSION') == '1':
+            logger.info("Skipping Socket API submission (SKIP_SOCKET_SUBMISSION=1)")
+            logger.debug(f"Socket facts file will be available at: {socket_facts_path}")
+            # Include the facts file path in results for downstream tools.
+            results['socket_facts_path'] = str(socket_facts_path)
+            return results
+
         try:
             # Check if socket facts file is empty or has no components
             if not socket_facts_path.exists():