feat: add --exit-code-on-api-error flag + Buildkite-aware infra error logging

Adds a configurable exit code for API/infrastructure failures so CI pipelines
can distinguish them from blocking security findings (exit 1), without changing
any default behavior.

- New CliConfig field exit_code_on_api_error (default 3) + --exit-code-on-api-error
  flag. The CLI already exited 3 on unexpected errors; this just makes that code
  configurable (e.g. remap to a Buildkite soft_fail code, or 0 to swallow).
- New _emit_infrastructure_error helper + IS_BUILDKITE gate: emits Buildkite log
  section markers (^^^ +++ / --- ⚠️) and a soft_fail hint when running in
  Buildkite; plain log.error elsewhere so markers don't leak as literal text.
- Wire the top-level generic-exception handler in cli() through the helper and
  the configurable code.

Deliberately NON-breaking for 2.3.x:
- --disable-blocking STILL forces exit 0 for all outcomes and takes precedence
  over --exit-code-on-api-error (documented in the flag help so the two aren't
  combined by mistake).
- Default exit codes are unchanged; the exit code only changes when the user
  explicitly passes the flag.

The breaking variant (infra errors bypassing --disable-blocking, distinct
RequestTimeoutExceeded handling, exit 1 -> 3 for diff API failures) is
intentionally deferred to a future 3.0 release.

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

Author: lelia

socketsecurity/config.py

@@ -101,6 +101,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
@@ -219,6 +220,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,
@@ -802,6 +804,21 @@ 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 fails on an API or infrastructure error "
+            "(timeout, network failure, unexpected exception). Default: 3. Useful for "
+            "distinguishing infrastructure failures from security findings (exit 1) in "
+            "CI -- e.g. set to a Buildkite soft_fail code. NOTE: --disable-blocking "
+            "forces exit 0 for ALL outcomes and therefore overrides this flag; do not "
+            "combine the two if you want the custom code to take effect."
+        )
+    )
     advanced_group.add_argument(
         "--allow-unverified",
         action="store_true",

socketsecurity/socketcli.py

@@ -27,6 +27,37 @@
 
 load_dotenv()
 
+# Buildkite sets BUILDKITE=true in every job environment. Used to gate log
+# section markers that would render as literal text on other CI platforms.
+IS_BUILDKITE = os.getenv("BUILDKITE") == "true"
+
+
+def _emit_infrastructure_error(message: str, include_traceback: bool = False) -> None:
+    """Emit a structured error for infrastructure/API failures.
+
+    When running in Buildkite, wraps the error in log-section markers
+    (`^^^ +++` expands the section in the BK UI) and prints a soft_fail hint.
+    On every other platform it's a plain log.error so the markers don't leak
+    as literal text. This is presentation only -- it does not decide the exit
+    code (the caller does that, honoring --disable-blocking and
+    --exit-code-on-api-error).
+    """
+    if IS_BUILDKITE:
+        print("^^^ +++", flush=True)
+        print("--- :warning: Socket infrastructure error", flush=True)
+
+    log.error(message)
+
+    if IS_BUILDKITE:
+        log.error(
+            "Tip: this is an infrastructure error, not a security finding. To keep it "
+            "from blocking the build, add a soft_fail rule for the CLI's API-error exit "
+            "code (default 3, or whatever you pass to --exit-code-on-api-error)."
+        )
+
+    if include_traceback:
+        traceback.print_exc()
+
 
 def build_license_artifact_payload(
     diff: Diff,
@@ -73,12 +104,17 @@ def cli():
         else:
             sys.exit(0)
     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
+        _emit_infrastructure_error(
+            f"Unexpected error when running the CLI: {error}",
+            include_traceback=True,
+        )
+        # --disable-blocking forces a clean exit for ALL outcomes (it takes
+        # precedence over --exit-code-on-api-error); otherwise infra/API errors
+        # exit with the configurable code (default 3), keeping them distinct
+        # from blocking security findings (exit 1).
         if not config.disable_blocking:
-            sys.exit(3)
+            sys.exit(config.exit_code_on_api_error)
         else:
             sys.exit(0)