controlzero 1.5.0__tar.gz → 1.5.1__tar.gz

{controlzero-1.5.0 → controlzero-1.5.1}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.5.1 -- 2026-05-12 (SECURITY)
+
+### Fixed
+
+- **API key leak in the active-source stderr notification.** The T103
+  startup line `controlzero: active policy source = hosted (...)`
+  printed the first 14 characters of `CONTROLZERO_API_KEY`, which for
+  a `cz_live_...` or `cz_test_...` key meant 6 characters of the
+  customer secret reached stderr (visible in terminals, screen shares,
+  support transcripts, and CI logs). The hint is now masked to
+  `cz_live_***` or `cz_test_***` so the mode is still observable but
+  no secret bytes are exposed. Upgrade ASAP if you ran 1.5.0 in any
+  environment where stderr is observable. 1.5.0 is yanked on PyPI.
+
 ## 1.5.0 -- 2026-05-12
 
 ### Changed (governance posture; opt-out path documented)

{controlzero-1.5.0 → controlzero-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.0
+Version: 1.5.1
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai

{controlzero-1.5.0 → controlzero-1.5.1}/controlzero/__init__.py

@@ -28,7 +28,7 @@ from controlzero.errors import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.5.0"
+__version__ = "1.5.1"
 
 __all__ = [
     "Client",

{controlzero-1.5.0 → controlzero-1.5.1}/controlzero/client.py

@@ -73,6 +73,19 @@ _DEFAULT_REFRESH_INTERVAL_SECONDS = 60
 _refresh_logger = logging.getLogger("controlzero.client.refresh")
 
 
+def _mask_api_key(api_key: Optional[str]) -> str:
+    # Reveal only the public, non-secret prefix (cz_live_ / cz_test_) and mask
+    # the rest. Anything past the prefix is entropy from the customer's secret
+    # and must never appear on stderr, in logs, or in support transcripts.
+    if not api_key:
+        return "***"
+    if api_key.startswith("cz_live_"):
+        return "cz_live_***"
+    if api_key.startswith("cz_test_"):
+        return "cz_test_***"
+    return "***"
+
+
 class Client:
     """The ControlZero policy client.
 
@@ -174,7 +187,7 @@ class Client:
                     self._hosted_etag = cb.etag
             except Exception:  # noqa: BLE001
                 self._hosted_etag = None
-            self._notify_active_source("hosted", source_hint=self._api_key[:14])
+            self._notify_active_source("hosted", source_hint=_mask_api_key(self._api_key))
         else:
             # Either no api_key, or api_key + LOCAL_OVERRIDE escape hatch.
             local_source = self._resolve_local_source(None, None)

{controlzero-1.5.0 → controlzero-1.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.5.0"
+version = "1.5.1"
 description = "AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup."
 readme = "README.md"
 license = {text = "Apache-2.0"}

controlzero-1.5.1/tests/test_api_key_mask.py

@@ -0,0 +1,59 @@
+"""Regression tests for the masked API-key hint shown in the active-source
+stderr notification (T103 follow-up, 1.5.1 security fix).
+
+Before 1.5.1 the SDK printed ``self._api_key[:14]`` to stderr on every
+Client construction in hosted mode. For a ``cz_live_abcdef123456...``
+key that meant 6 characters of the customer secret leaked to terminals,
+screen shares, support transcripts, and CI logs.
+
+The mask MUST:
+
+* preserve the public ``cz_live_`` / ``cz_test_`` prefix as a mode signal
+* NEVER emit any character beyond that prefix from the input key
+
+These tests verify both invariants with a brute-force substring scan so a
+future regression that switches back to a length-prefix slice fails loud.
+"""
+
+from controlzero.client import _mask_api_key
+
+
+def test_mask_live_key_emits_only_public_prefix():
+    masked = _mask_api_key("cz_live_7ebef6b600015e3eaeda9149bf6d9c29a")
+    assert masked == "cz_live_***"
+
+
+def test_mask_test_key_emits_only_public_prefix():
+    masked = _mask_api_key("cz_test_abcdef0123456789abcdef0123456789")
+    assert masked == "cz_test_***"
+
+
+def test_mask_unknown_prefix_falls_through_to_triple_star():
+    masked = _mask_api_key("plain-token-1234567890")
+    assert masked == "***"
+
+
+def test_mask_none_returns_triple_star():
+    assert _mask_api_key(None) == "***"
+
+
+def test_mask_empty_string_returns_triple_star():
+    assert _mask_api_key("") == "***"
+
+
+def test_mask_never_leaks_secret_bytes_brute_force():
+    # The secret portion of a real CloudShift production key (anonymised:
+    # do not use this value as-is, the customer rotated it after the
+    # 1.5.0 -> 1.5.1 incident on 2026-05-12).
+    secret_tail = "7ebef6b600015e3eaeda9149bf6d9c29a3a2a7a3075209112afde20888280de0"
+    for prefix in ("cz_live_", "cz_test_"):
+        key = prefix + secret_tail
+        masked = _mask_api_key(key)
+        # Scan every 4-char substring of the secret and assert NONE
+        # appears in the masked output. 4 chars is enough entropy that
+        # an accidental match is vanishingly unlikely.
+        for i in range(len(secret_tail) - 3):
+            window = secret_tail[i : i + 4]
+            assert window not in masked, (
+                f"secret bytes {window!r} leaked into masked output {masked!r}"
+            )