feat: differentiated exit code 3 for infrastructure errors

Adds explicit handling and structured logging for API/infrastructure failures
so they are distinguishable from real blocking security findings in CI.

Exit code semantics (NEW for 2.3.0):
  0 - Clean scan, no blocking issues (or --disable-blocking)
  1 - Blocking security finding(s) detected
  2 - Process interrupted (SIGINT) -- already in place
  3 - Infrastructure / API error -- NEW
  5 - Warning-level alerts only -- preserved

This is a BREAKING change for any pipeline that previously caught exit 1 to
mean "anything went wrong." Such pipelines now need to handle 3 separately
for infrastructure failures, or use --exit-code-on-api-error to remap.

Changes:

- socketsecurity/core/__init__.py
  * Import RequestTimeoutExceeded and `requests`
  * Wrap fullscans.stream_diff with requests.exceptions.Timeout ->
    RequestTimeoutExceeded
  * Wrap fullscans.post (create_full_scan) with the same pattern

- socketsecurity/socketcli.py
  * Import RequestTimeoutExceeded + APIFailure
  * IS_BUILDKITE constant (gates BK-specific markers per spec §3)
  * New _emit_infrastructure_error helper emits Buildkite log section
    markers (^^^ +++ and ---) when BUILDKITE=true, plus a soft_fail hint;
    bare log.error otherwise. Markers go to stdout via print() so they
    aren't prefixed with log formatting; markers are literal strings on
    other CI platforms so the gate is required.
  * Explicit RequestTimeoutExceeded and APIFailure handlers added before
    the generic Exception handler, all using config.exit_code_on_api_error

- socketsecurity/config.py
  * New CliConfig field: exit_code_on_api_error (default 3)
  * New flag: --exit-code-on-api-error <int>
    Customers can remap to 0 (swallow), 100 (Buildkite soft_fail), etc.

Note: --disable-blocking now only zeroes out exit 1 (security findings),
not exit 3 (infrastructure). This separation is the whole point of the
new code -- callers who want to also swallow infra errors should use
--exit-code-on-api-error 0.

Motivated by customer incidents (Plaid 413s and timeouts; Anthropic
'other' SocketCategory crash).

Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

Author: lelia

socketsecurity/config.py

@@ -98,6 +98,7 @@ class CliConfig:
     pending_head: bool = False
     enable_diff: bool = False
     timeout: Optional[int] = 1200
+    exit_code_on_api_error: int = 3
     exclude_license_details: bool = False
     include_module_folders: bool = False
     repo_is_public: bool = False
@@ -224,6 +225,7 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
             'integration_type': args.integration,
             'pending_head': args.pending_head,
             'timeout': args.timeout,
+            'exit_code_on_api_error': args.exit_code_on_api_error,
             'exclude_license_details': args.exclude_license_details,
             'include_module_folders': args.include_module_folders,
             'repo_is_public': args.repo_is_public,
@@ -754,6 +756,20 @@ def create_argument_parser() -> argparse.ArgumentParser:
         help="Timeout in seconds for API requests",
         required=False
     )
+    advanced_group.add_argument(
+        "--exit-code-on-api-error",
+        dest="exit_code_on_api_error",
+        type=int,
+        default=3,
+        metavar="<int>",
+        help=(
+            "Exit code to use when the CLI encounters an API or infrastructure "
+            "error (timeout, network failure, unexpected exception). Default: 3. "
+            "Use this to distinguish infrastructure failures from security findings "
+            "in your CI pipeline. Example for Buildkite soft_fail: set to 100. "
+            "Set to 0 to swallow infrastructure errors entirely."
+        )
+    )
     advanced_group.add_argument(
         "--allow-unverified",
         action="store_true",

socketsecurity/core/__init__.py

@@ -11,6 +11,7 @@
 
 if TYPE_CHECKING:
     from socketsecurity.config import CliConfig
+import requests
 from socketdev import socketdev
 from socketdev.exceptions import APIFailure
 from socketdev.fullscans import FullScanParams, SocketArtifact
@@ -26,7 +27,7 @@
     Package,
     Purl
 )
-from socketsecurity.core.exceptions import APIResourceNotFound
+from socketsecurity.core.exceptions import APIResourceNotFound, RequestTimeoutExceeded
 from .socket_config import SocketConfig
 from .utils import socket_globs
 from .resource_utils import check_file_count_against_ulimit
@@ -538,7 +539,13 @@ def create_full_scan(self, files: List[str], params: FullScanParams, base_paths:
         log.info("Creating new full scan")
         create_full_start = time.time()
 
-        res = self.sdk.fullscans.post(files, params, use_types=True, use_lazy_loading=True, max_open_files=50, base_paths=base_paths)
+        try:
+            res = self.sdk.fullscans.post(files, params, use_types=True, use_lazy_loading=True, max_open_files=50, base_paths=base_paths)
+        except requests.exceptions.Timeout as e:
+            raise RequestTimeoutExceeded(
+                f"Request timed out while creating full scan for org "
+                f"'{self.config.org_slug}': {e}"
+            )
         if not res.success:
             log.error(f"Error creating full scan: {res.message}, status: {res.status}")
             raise Exception(f"Error creating full scan: {res.message}, status: {res.status}")
@@ -945,6 +952,11 @@ def get_added_and_removed_packages(
                     include_license_details=str(include_license_details).lower()
                 ).data
             )
+        except requests.exceptions.Timeout as e:
+            raise RequestTimeoutExceeded(
+                f"Request timed out while comparing scans "
+                f"(head: {head_full_scan_id}, new: {new_full_scan_id}): {e}"
+            )
         except APIFailure as e:
             log.error(f"API Error: {e}")
             raise

socketsecurity/socketcli.py

@@ -10,11 +10,13 @@
 from dotenv import load_dotenv
 from git import InvalidGitRepositoryError, NoSuchPathError
 from socketdev import socketdev
+from socketdev.exceptions import APIFailure
 from socketdev.fullscans import FullScanParams
 from socketsecurity.config import CliConfig
 from socketsecurity.core import Core
 from socketsecurity.core.classes import Diff
 from socketsecurity.core.cli_client import CliClient
+from socketsecurity.core.exceptions import RequestTimeoutExceeded
 from socketsecurity.core.git_interface import Git
 from socketsecurity.core.logging import initialize_logging, set_debug_mode
 from socketsecurity.core.messages import Messages
@@ -28,6 +30,11 @@
 
 DEFAULT_API_TIMEOUT = 1200
 
+# Buildkite sets BUILDKITE=true in every job environment. Used to gate
+# log section markers (^^^ +++, ---) that render as literal strings in
+# GitHub Actions / GitLab CI / other platforms.
+IS_BUILDKITE = os.getenv("BUILDKITE") == "true"
+
 
 def get_api_request_timeout(config: CliConfig) -> int:
     return config.timeout if config.timeout is not None else DEFAULT_API_TIMEOUT
@@ -43,6 +50,39 @@ def build_socket_sdk(config: CliConfig) -> socketdev:
     )
 
 
+def _emit_infrastructure_error(
+    message: str,
+    hint: str = None,
+    include_traceback: bool = False,
+) -> None:
+    """Emit a structured error for infrastructure failures.
+
+    Uses Buildkite log section markers when running in Buildkite so the
+    error auto-expands in the BK UI. Markers go to stdout via print()
+    (not log.error) so they're not prefixed with log formatting.
+    """
+    if IS_BUILDKITE:
+        # ^^^ +++ retroactively opens the current log section so the error
+        # is visible immediately without manual expansion.
+        print("^^^ +++", flush=True)
+        print("--- :warning: Socket Infrastructure Error", flush=True)
+
+    log.error(message)
+
+    if hint:
+        log.error(hint)
+
+    if IS_BUILDKITE:
+        log.error(
+            "Tip: to prevent this from blocking your pipeline, add "
+            "`soft_fail: [{exit_status: 3}]` to this step, or use "
+            "`--exit-code-on-api-error` to set a custom exit code."
+        )
+
+    if include_traceback:
+        traceback.print_exc()
+
+
 def cli():
     try:
         main_code()
@@ -53,15 +93,27 @@ def cli():
             sys.exit(2)
         else:
             sys.exit(0)
+    except RequestTimeoutExceeded as error:
+        config = CliConfig.from_args()
+        _emit_infrastructure_error(
+            f"Request timed out: {error}",
+            hint="This is an infrastructure issue, not a security finding.",
+        )
+        sys.exit(config.exit_code_on_api_error)
+    except APIFailure as error:
+        config = CliConfig.from_args()
+        _emit_infrastructure_error(
+            f"API error: {error}",
+            hint="This is an infrastructure issue, not a security finding.",
+        )
+        sys.exit(config.exit_code_on_api_error)
     except Exception as error:
-        log.error("Unexpected error when running the cli")
-        log.error(error)
-        traceback.print_exc()
-        config = CliConfig.from_args()  # Get current config
-        if not config.disable_blocking:
-            sys.exit(3)
-        else:
-            sys.exit(0)
+        config = CliConfig.from_args()
+        _emit_infrastructure_error(
+            f"Unexpected error when running the CLI: {error}",
+            include_traceback=True,
+        )
+        sys.exit(config.exit_code_on_api_error)
 
 
 def main_code():