feat: flip streaming logs to opt-in via --upload-logs

The Socket backend changed its register contract so that log streaming
is now opt-in rather than default-on. The CLI always calls register
(cheap, lets the server force-enable for specific orgs) and gates the
downstream upload/finalize lifecycle on the response.

Wire changes:
- POST /v0/python-cli-runs body adds a required `share_logs` field.
- Response: { log_streaming_enabled: bool, run_id: <uuid|null> }.
  When log_streaming_enabled is false, run_id is null and the CLI
  skips the upload + finalize calls entirely.

CLI changes:
- New `--upload-logs` flag (default off). When set, the CLI sends
  share_logs=true on register.
- Removed `--disable-server-log-streaming` — default is off, so an
  opt-out flag no longer makes sense.
- register_cli_run takes a required share_logs arg and returns None
  whenever log_streaming_enabled is false (whatever the reason: client
  opted out, server denied, server unreachable).

Bumps version to 2.2.88 and updates the CHANGELOG entry to reflect
the opt-in shape.

Author: barslev

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Changelog
 
-## 2.2.87
+## 2.2.88
 
-- Added a streaming log channel between the CLI and the Socket backend. Each CLI invocation now reports a per-run status (`in_progress` / `success` / `failure` / `cancelled`) and uploads a transcript of its own log output, visible in the Socket admin views. The transcript is captured regardless of the local `--enable-debug` state; the existing terminal verbosity is unchanged. The feature is best-effort — registration or upload failures silently degrade and never block the scan. Opt out with `--disable-server-log-streaming`.
+- Added an opt-in streaming log channel between the CLI and the Socket backend. When the new `--upload-logs` flag is set, each CLI invocation registers a run, reports a per-run status (`in_progress` / `success` / `failure` / `cancelled`), and uploads a transcript of its own log output to the Socket backend for that run, visible in the Socket admin views. The transcript is captured regardless of the local `--enable-debug` state; the existing terminal verbosity is unchanged. The Socket backend can also force-enable streaming for specific orgs regardless of the flag. The feature is best-effort — registration or upload failures silently degrade and never block the scan.
 
 ## 2.2.83
 

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.2.87"
+version = "2.2.88"
 requires-python = ">= 3.11"
 license = {"file" = "LICENSE"}
 dependencies = [

socketsecurity/__init__.py

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

socketsecurity/config.py

@@ -92,7 +92,7 @@ class CliConfig:
     ignore_commit_files: bool = False
     disable_blocking: bool = False
     disable_ignore: bool = False
-    disable_server_log_streaming: bool = False
+    upload_logs: bool = False
     strict_blocking: bool = False
     integration_type: IntegrationType = "api"
     integration_org_slug: Optional[str] = None
@@ -208,7 +208,7 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
             'ignore_commit_files': args.ignore_commit_files,
             'disable_blocking': args.disable_blocking,
             'disable_ignore': args.disable_ignore,
-            'disable_server_log_streaming': args.disable_server_log_streaming,
+            'upload_logs': args.upload_logs,
             'strict_blocking': args.strict_blocking,
             'integration_type': args.integration,
             'pending_head': args.pending_head,
@@ -719,14 +719,16 @@ def create_argument_parser() -> argparse.ArgumentParser:
         help=argparse.SUPPRESS
     )
     advanced_group.add_argument(
-        "--disable-server-log-streaming",
-        dest="disable_server_log_streaming",
+        "--upload-logs",
+        dest="upload_logs",
         action="store_true",
-        help="Disable streaming server-side log lines to the terminal during long-running CLI operations."
+        help="Upload the CLI's log output to the Socket backend for this run. "
+             "When set, the CLI registers the run with share_logs=true and streams "
+             "its log records in 5s batches. Default off."
     )
     advanced_group.add_argument(
-        "--disable_server_log_streaming",
-        dest="disable_server_log_streaming",
+        "--upload_logs",
+        dest="upload_logs",
         action="store_true",
         help=argparse.SUPPRESS
     )

socketsecurity/core/cli_run.py

@@ -1,11 +1,16 @@
 """Lifecycle helpers for a CLI run on the Socket backend.
 
 A "run" represents a single CLI invocation. `register_cli_run` opens it and
-returns a server-issued `run_id`; `finalize_cli_run` closes it on exit. The
-run_id keys the rows that `BatchedLogUploader` POSTs to
+returns a server-issued `run_id` when streaming is enabled; `finalize_cli_run`
+closes it on exit. The run_id keys the rows that `BatchedLogUploader` POSTs to
 `/python-cli-runs/<run_id>/logs` during the run so the dashboard can show
 what the user saw in their terminal.
 
+Streaming is opt-in via the `share_logs` field on register. The server may
+also force-enable streaming for an org regardless of the client's request,
+so the CLI always calls register and gates on the response's
+`log_streaming_enabled` flag rather than the client's intent.
+
 Both calls are best-effort: failures fall back to no-streaming and never
 prevent the scan from running.
 """
@@ -23,12 +28,13 @@
 def register_cli_run(
     client: CliClient,
     client_version: str,
+    share_logs: bool,
 ) -> Optional[str]:
     try:
         resp = client.request(
             path="python-cli-runs",
             method="POST",
-            payload=json.dumps({"client_version": client_version}),
+            payload=json.dumps({"client_version": client_version, "share_logs": share_logs}),
         )
     except APIFailure as e:
         log.debug(f"cli-run register failed (streaming disabled): {e}")
@@ -40,9 +46,13 @@ def register_cli_run(
         log.debug(f"cli-run register: bad JSON body: {e}")
         return None
 
+    if not body.get("log_streaming_enabled"):
+        log.debug("cli-run register: log streaming not enabled by server")
+        return None
+
     run_id = body.get("run_id")
     if not isinstance(run_id, str) or not run_id:
-        log.debug(f"cli-run register: missing run_id in response: {body!r}")
+        log.debug(f"cli-run register: enabled but missing run_id in response: {body!r}")
         return None
     return run_id
 

socketsecurity/core/streaming.py

@@ -36,14 +36,16 @@ def setup_streaming(
     cli_logger: logging.Logger,
     sdk_logger: logging.Logger,
     client_version: str,
+    share_logs: bool,
     enable_debug: bool,
 ) -> Optional[Callable[[], None]]:
     run_id = register_cli_run(
         client,
         client_version=client_version,
+        share_logs=share_logs,
     )
     if not run_id:
-        cli_logger.debug("server log streaming disabled (register failed)")
+        cli_logger.debug("server log streaming not active for this run")
         return None
 
     log_uploader = BatchedLogUploader(client, run_id)

socketsecurity/socketcli.py

@@ -98,16 +98,16 @@ def main_code():
     sdk.api.api_url = socket_config.api_url
     log.debug("loaded client")
 
-    if not config.disable_server_log_streaming:
-        teardown = setup_streaming(
-            client=client,
-            cli_logger=log,
-            sdk_logger=socket_logger,
-            client_version=config.version,
-            enable_debug=config.enable_debug,
-        )
-        if teardown:
-            atexit.register(teardown)
+    teardown = setup_streaming(
+        client=client,
+        cli_logger=log,
+        sdk_logger=socket_logger,
+        client_version=config.version,
+        share_logs=config.upload_logs,
+        enable_debug=config.enable_debug,
+    )
+    if teardown:
+        atexit.register(teardown)
 
     core = Core(socket_config, sdk, config)
     log.debug("loaded core")

tests/unit/test_cli_run.py

@@ -12,32 +12,55 @@ def _resp(payload):
     return r
 
 
-def test_register_cli_run_returns_run_id():
+def test_register_cli_run_returns_run_id_when_enabled():
     client = Mock(spec=CliClient)
-    client.request.return_value = _resp({"run_id": "srv-issued-123"})
+    client.request.return_value = _resp({
+        "log_streaming_enabled": True,
+        "run_id": "srv-issued-123",
+    })
 
-    run_id = register_cli_run(client, client_version="1.2.3")
+    run_id = register_cli_run(client, client_version="1.2.3", share_logs=True)
 
     assert run_id == "srv-issued-123"
     args, kwargs = client.request.call_args
     assert kwargs["path"] == "python-cli-runs"
     assert kwargs["method"] == "POST"
     body = json.loads(kwargs["payload"])
-    assert body == {"client_version": "1.2.3"}
+    assert body == {"client_version": "1.2.3", "share_logs": True}
+
+
+def test_register_cli_run_returns_none_when_disabled_by_server():
+    client = Mock(spec=CliClient)
+    client.request.return_value = _resp({
+        "log_streaming_enabled": False,
+        "run_id": None,
+    })
+
+    assert register_cli_run(client, client_version="1.0.0", share_logs=False) is None
+
+
+def test_register_cli_run_sends_share_logs_false_when_not_opted_in():
+    client = Mock(spec=CliClient)
+    client.request.return_value = _resp({"log_streaming_enabled": False, "run_id": None})
+
+    register_cli_run(client, client_version="1.0.0", share_logs=False)
+
+    body = json.loads(client.request.call_args.kwargs["payload"])
+    assert body == {"client_version": "1.0.0", "share_logs": False}
 
 
 def test_register_cli_run_returns_none_on_api_failure():
     client = Mock(spec=CliClient)
     client.request.side_effect = APIFailure("network down")
 
-    assert register_cli_run(client, client_version="1.0.0") is None
+    assert register_cli_run(client, client_version="1.0.0", share_logs=True) is None
 
 
-def test_register_cli_run_returns_none_on_missing_run_id():
+def test_register_cli_run_returns_none_on_missing_run_id_when_enabled():
     client = Mock(spec=CliClient)
-    client.request.return_value = _resp({})
+    client.request.return_value = _resp({"log_streaming_enabled": True})
 
-    assert register_cli_run(client, client_version="1.0.0") is None
+    assert register_cli_run(client, client_version="1.0.0", share_logs=True) is None
 
 
 def test_register_cli_run_returns_none_on_bad_json():
@@ -46,7 +69,7 @@ def test_register_cli_run_returns_none_on_bad_json():
     client = Mock(spec=CliClient)
     client.request.return_value = bad
 
-    assert register_cli_run(client, client_version="1.0.0") is None
+    assert register_cli_run(client, client_version="1.0.0", share_logs=True) is None
 
 
 def test_finalize_cli_run_posts_status_and_null_report_run_id_by_default():

tests/unit/test_streaming.py

@@ -27,6 +27,7 @@ def test_setup_streaming_returns_none_when_register_fails():
             cli_logger=logging.getLogger("t-fail"),
             sdk_logger=logging.getLogger("t-fail-sdk"),
             client_version="1.0",
+            share_logs=True,
             enable_debug=False,
         )
     assert teardown is None
@@ -50,6 +51,7 @@ def fake_finalize(client, run_id, status="success", report_run_id=None):
             cli_logger=cli_logger,
             sdk_logger=sdk_logger,
             client_version="1.0",
+            share_logs=True,
             enable_debug=False,
         )
         assert teardown is not None
@@ -79,6 +81,7 @@ def fake_finalize(client, run_id, status="success", report_run_id=None):
             cli_logger=cli_logger,
             sdk_logger=sdk_logger,
             client_version="1.0",
+            share_logs=True,
             enable_debug=False,
         )
         teardown()
@@ -104,6 +107,7 @@ def test_setup_streaming_restores_logger_state_on_teardown():
             cli_logger=cli_logger,
             sdk_logger=sdk_logger,
             client_version="1.0",
+            share_logs=True,
             enable_debug=False,
         )
         # During streaming: levels and propagate are forced