controlzero 1.5.0__tar.gz → 1.5.2__tar.gz

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

@@ -1,5 +1,48 @@
 # Changelog
 
+## 1.5.2 -- 2026-05-12
+
+### Fixed
+
+- **Windows Claude Code hook never delivered audit logs.** The
+  installer wrote `CONTROLZERO_API_KEY=cz_live_... controlzero hook-check`
+  into `~/.claude/settings.json`. The `VAR=value command` env-prefix
+  is bash-only and PowerShell / cmd.exe cannot parse it, so the
+  Claude Code hook subprocess failed to spawn on every PreToolUse
+  call. macOS / Linux were unaffected. After 1.5.2 the hook command
+  is plain `controlzero hook-check`; the api key flows through
+  `~/.controlzero/config.yaml` (already written by `install --api-key`)
+  on every supported platform. Side benefit: the cleartext key is
+  no longer embedded in `settings.json` on disk.
+- **Audit-log dashboard SOURCE column rendered `--` for direct-SDK
+  rows.** `detect_client_name()` returned the generic alias `"sdk"`
+  when no agent-runtime env vars were detected; the backend
+  `NormalizeSource` mapped `"sdk"` to `unknown`, and the frontend
+  rendered `unknown` as `--`. The default is now `"python-sdk"`,
+  which the backend maps to the canonical `python_sdk` source value
+  and the frontend renders as `Python SDK`.
+
+### Customer impact
+
+CloudShift / kh.lee reported on 2026-05-12 that Claude Code on
+Windows was not sending any audit logs to the dashboard, while the
+direct Python SDK script was sending logs without a populated
+SOURCE column. Both symptoms collapse to the two fixes above.
+
+## 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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.0
+Version: 1.5.2
 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.2}/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.2"
 
 __all__ = [
     "Client",

{controlzero-1.5.0 → controlzero-1.5.2}/controlzero/cli/main.py

@@ -1517,10 +1517,15 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str], api_k
     hooks = existing.setdefault("hooks", {})
     pre_tool = hooks.setdefault("PreToolUse", [])
 
-    # Idempotency: replace any existing controlzero hook block, preserve others
+    # Idempotency: replace any existing controlzero hook block, preserve others.
+    # The hook subprocess resolves api_key from ~/.controlzero/config.yaml
+    # (written by _write_api_key_config above) and falls back to
+    # CONTROLZERO_API_KEY in the parent shell env. Embedding
+    # `CONTROLZERO_API_KEY=cz_... controlzero hook-check` as a bash-style
+    # env-prefix was a Windows-portability bug (PowerShell / cmd.exe cannot
+    # parse the syntax) AND placed the cleartext key into settings.json on
+    # disk. Both go away here. See 2026-05-12 CloudShift incident.
     hook_command = "controlzero hook-check"
-    if api_key:
-        hook_command = f"CONTROLZERO_API_KEY={api_key} controlzero hook-check"
     new_block = {
         "matcher": "*",
         "hooks": [
@@ -1665,9 +1670,11 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str], api_ke
     hooks_root = existing.setdefault("hooks", {})
     before_tool = hooks_root.setdefault("BeforeTool", [])
 
+    # 1.5.2: api_key flows via ~/.controlzero/config.yaml (see
+    # _write_api_key_config above). The legacy bash-only env-prefix
+    # broke Windows; see the claude-code install path for the full
+    # rationale.
     hook_command = "controlzero hook-check"
-    if api_key:
-        hook_command = f"CONTROLZERO_API_KEY={api_key} controlzero hook-check"
 
     # Gemini CLI expects a nested structure:
     #   { matcher: "regex", hooks: [{ type: "command", command: "...", timeout: N }] }
@@ -1819,9 +1826,11 @@ def install_codex_cli(force: bool, merge: bool, config: Optional[str], api_key:
     codex_dir.mkdir(parents=True, exist_ok=True)
     hooks_json_path = codex_dir / "hooks.json"
 
+    # 1.5.2: api_key flows via ~/.controlzero/config.yaml (see
+    # _write_api_key_config above). The legacy bash-only env-prefix
+    # broke Windows; see the claude-code install path for the full
+    # rationale.
     hook_command = "controlzero hook-check"
-    if api_key:
-        hook_command = f"CONTROLZERO_API_KEY={api_key} controlzero hook-check"
 
     new_hook_entry = {
         "matcher": ".*",

{controlzero-1.5.0 → controlzero-1.5.2}/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.2}/controlzero/device.py

@@ -136,8 +136,14 @@ def detect_client_name() -> str:
         _client_name_cache = "gemini-cli"
         return "gemini-cli"
 
-    _client_name_cache = "sdk"
-    return "sdk"
+    # Direct SDK usage (no agent runtime detected) -- emit the canonical
+    # backend source value so the dashboard renders "Python SDK" instead
+    # of "--". Pre-2026-05-12 we emitted the generic alias "sdk", which
+    # the backend NormalizeSource maps to "unknown" and the audit log
+    # column rendered as "--", confusing customers into thinking their
+    # logs weren't reaching the dashboard.
+    _client_name_cache = "python-sdk"
+    return "python-sdk"
 
 
 def detect_client_version() -> str:

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.5.0"
+version = "1.5.2"
 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.2/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}"
+            )

{controlzero-1.5.0 → controlzero-1.5.2}/tests/test_coding_agent_hooks.py

@@ -709,8 +709,14 @@ class TestApiKeyOption:
         pre_tool = settings["hooks"]["PreToolUse"]
         assert len(pre_tool) == 1
         hook_cmd = pre_tool[0]["hooks"][0]["command"]
-        assert "CONTROLZERO_API_KEY=cz_live_testkey123" in hook_cmd
-        assert "controlzero hook-check" in hook_cmd
+        # 1.5.2 portability fix: the hook command is plain
+        # `controlzero hook-check`. The api key flows through
+        # ~/.controlzero/config.yaml (see _write_api_key_config) so it
+        # is no longer embedded in settings.json (Windows shells could
+        # not parse the bash-only env-prefix syntax).
+        assert hook_cmd == "controlzero hook-check"
+        assert "cz_live_" not in hook_cmd
+        assert "CONTROLZERO_API_KEY=" not in hook_cmd
 
     def test_install_gemini_cli_with_api_key_updates_hook_command(
         self, tmp_path, monkeypatch
@@ -732,7 +738,9 @@ class TestApiKeyOption:
         # Nested format: check inside the hooks array
         inner_hooks = before_tool[0].get("hooks", [])
         assert len(inner_hooks) == 1
-        assert "CONTROLZERO_API_KEY=cz_test_geminikey" in inner_hooks[0]["command"]
+        # 1.5.2: hook command is plain, key flows via config.yaml.
+        assert inner_hooks[0]["command"] == "controlzero hook-check"
+        assert "cz_test_" not in inner_hooks[0]["command"]
 
     def test_install_codex_cli_with_api_key_updates_hooks_json(
         self, tmp_path, monkeypatch
@@ -754,7 +762,9 @@ class TestApiKeyOption:
         assert len(pre_tool) == 1
         inner_hooks = pre_tool[0].get("hooks", [])
         assert len(inner_hooks) == 1
-        assert "CONTROLZERO_API_KEY=cz_live_codexkey" in inner_hooks[0]["command"]
+        # 1.5.2: hook command is plain, key flows via config.yaml.
+        assert inner_hooks[0]["command"] == "controlzero hook-check"
+        assert "cz_live_" not in inner_hooks[0]["command"]
 
     def test_install_with_invalid_api_key_exits_with_error(
         self, tmp_path, monkeypatch

{controlzero-1.5.0 → controlzero-1.5.2}/tests/test_device.py

@@ -141,10 +141,14 @@ def _isolated_env(extras: dict[str, str] | None = None) -> dict[str, str]:
 
 
 class TestDetectClientName:
-    def test_default_is_sdk(self):
+    def test_default_is_python_sdk(self):
+        # 1.5.2: default-emission fix. Previously returned "sdk", which
+        # the backend NormalizeSource mapped to SourceUnknown and the
+        # dashboard rendered as "--". "python-sdk" is the canonical
+        # alias that maps to SourcePythonSDK on the backend.
         with mock.patch.dict(os.environ, _isolated_env(), clear=True):
             _reset_caches()
-            assert detect_client_name() == "sdk"
+            assert detect_client_name() == "python-sdk"
 
     def test_reads_controlzero_client_env(self):
         with mock.patch.dict(os.environ, _isolated_env({"CONTROLZERO_CLIENT": "my-custom-client"}), clear=True):
@@ -195,10 +199,10 @@ class TestDetectClientName:
         # mislabeled SDK-direct users (Bryan deny-deny incident,
         # 2026-05-10) as "gemini-cli". GEMINI_API_KEY is a Google API
         # credential, not a Gemini CLI runtime signal. Must default
-        # back to "sdk".
+        # back to the python-sdk fallback (1.5.2 canonical alias).
         with mock.patch.dict(os.environ, _isolated_env({"GEMINI_API_KEY": "fake-google-key"}), clear=True):
             _reset_caches()
-            assert detect_client_name() == "sdk"
+            assert detect_client_name() == "python-sdk"
 
     def test_cursor_with_gemini_api_key_resolves_to_cursor(self):
         # T92 regression: a Cursor user who also exports GEMINI_API_KEY

controlzero-1.5.2/tests/test_install_hook_command.py

@@ -0,0 +1,139 @@
+"""Regression tests for the Claude Code / Gemini CLI / Codex CLI installer
+hook command (1.5.2 customer fix).
+
+Two invariants the installer MUST satisfy:
+
+1. The `command` field in the agent settings JSON is plain
+   ``controlzero hook-check``. It MUST NOT contain the customer api
+   key. Embedding ``CONTROLZERO_API_KEY=cz_live_... controlzero
+   hook-check`` was a portability bug: bash parses the env-prefix,
+   PowerShell / cmd.exe do not, so the hook subprocess failed to
+   spawn on Windows and CloudShift's Claude Code instance never
+   delivered audit logs (2026-05-12 incident).
+2. The api key is persisted to ``~/.controlzero/config.yaml`` so the
+   hook subprocess can pick it up at runtime via the
+   ``cli/main.py:hook_check`` env-fallback path.
+
+The test runs the installer via the click CLI runner with a synthetic
+HOME directory so the assertions can read both files back.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import yaml
+from click.testing import CliRunner
+
+from controlzero.cli.main import cli
+
+
+LIVE_KEY = "cz_live_7ebef6b600015e3eaeda9149bf6d9c29a3a2a7a3075209112afde20888280de0"
+TEST_KEY = "cz_test_abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567"
+
+
+def _read_pretooluse_command(settings_path: Path) -> str:
+    data = json.loads(settings_path.read_text())
+    blocks = data["hooks"]["PreToolUse"]
+    # Find the controlzero block (idempotent installer keeps a single
+    # block; tests assert the singular contract).
+    cz_blocks = [
+        b
+        for b in blocks
+        if any("controlzero hook-check" in h.get("command", "") for h in b.get("hooks", []))
+    ]
+    assert len(cz_blocks) == 1, f"expected one controlzero hook block, got {cz_blocks}"
+    return cz_blocks[0]["hooks"][0]["command"]
+
+
+@pytest.mark.parametrize("api_key", [LIVE_KEY, TEST_KEY])
+def test_install_claude_code_writes_clean_hook_command(api_key, tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    # Force the controlzero state dir to match the synthetic HOME so
+    # _write_api_key_config and the settings.json patch both land
+    # inside tmp_path.
+    monkeypatch.setattr(
+        "controlzero.cli.main.GLOBAL_POLICY_DIR",
+        tmp_path / ".controlzero",
+    )
+    monkeypatch.setattr(
+        "controlzero.cli.main.GLOBAL_POLICY_PATH",
+        tmp_path / ".controlzero" / "policy.yaml",
+    )
+    monkeypatch.setattr(
+        "controlzero.cli.main.GLOBAL_CONFIG_PATH",
+        tmp_path / ".controlzero" / "config.yaml",
+    )
+    monkeypatch.setattr(
+        "controlzero.cli.main.GLOBAL_AUDIT_PATH",
+        tmp_path / ".controlzero" / "audit.log",
+    )
+
+    settings_path = tmp_path / ".claude" / "settings.json"
+
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "install",
+            "claude-code",
+            "--api-key",
+            api_key,
+            "--settings",
+            str(settings_path),
+            "--force",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+
+    # Invariant 1: hook command MUST NOT embed the api key. Plain
+    # `controlzero hook-check` is the only acceptable shape.
+    command = _read_pretooluse_command(settings_path)
+    assert command == "controlzero hook-check", (
+        f"hook command leaked api_key or shell-only syntax: {command!r}"
+    )
+    assert "cz_live_" not in command
+    assert "cz_test_" not in command
+    assert "CONTROLZERO_API_KEY=" not in command
+
+    # Invariant 2: api key MUST be persisted to config.yaml so the
+    # hook subprocess can resolve it without an env-prefix.
+    config_path = tmp_path / ".controlzero" / "config.yaml"
+    assert config_path.exists(), "_write_api_key_config did not run"
+    cfg = yaml.safe_load(config_path.read_text())
+    assert cfg["api_key"] == api_key, "config.yaml api_key mismatch"
+
+
+def test_detect_client_name_default_is_python_sdk(monkeypatch):
+    # 1.5.2 default-emission fix: when no agent-runtime env vars are
+    # set, detect_client_name() must return the canonical
+    # `python-sdk` alias so the backend NormalizeSource pipeline
+    # resolves it to SourcePythonSDK instead of SourceUnknown (which
+    # the dashboard renders as `--`).
+    for var in (
+        "CONTROLZERO_CLIENT",
+        "CLAUDECODE",
+        "CLAUDE_CODE",
+        "CODEX_HOME",
+        "CODEX_PROFILE",
+        "CODEX_CLI",
+        "CURSOR_TRACE_ID",
+        "CURSOR_AGENT",
+        "CURSOR_USER_AGENT",
+        "TERM_PROGRAM",
+        "WINDSURF_AGENT",
+        "WINDSURF_SESSION_ID",
+        "GEMINI_CLI",
+        "GEMINI_SANDBOX",
+        "GEMINI_SYSTEM_MD",
+    ):
+        monkeypatch.delenv(var, raising=False)
+
+    # Reset the module-level cache so the function actually re-runs.
+    import controlzero.device as device
+
+    monkeypatch.setattr(device, "_client_name_cache", None)
+
+    assert device.detect_client_name() == "python-sdk"