controlzero 1.9.0__tar.gz → 1.9.1__tar.gz

{controlzero-1.9.0 → controlzero-1.9.1}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.9.1 -- 2026-06-16 (hosted-mode local audit log P0, epic gh#1247)
+
+### Fixed
+
+- **(P0) Hosted mode never wrote the local `~/.controlzero/audit.log`.** After
+  `controlzero install claude-code --api-key cz_live_...` (hosted mode), tool
+  calls reached the dashboard (remote audit) but the local audit log stayed
+  frozen indefinitely -- even though the claude-code template and the install
+  success message both promise that every tool call is logged to
+  `~/.controlzero/audit.log`. Root cause: `Client.__init__` constructed the
+  `LocalAuditLogger` ONLY when no API key was set, so hosted mode left the
+  local sink `None` and `_audit_decision()` skipped the local write (allow AND
+  deny). The local log is now written in EVERY mode; the remote sink is layered
+  on top, not instead. A blocked (deny) call is now locally recorded too -- the
+  exact case a customer hit (Claude Code `Bash` calls denied by no-rule-match).
+  This also restores `cz debug-bundle` and the tamper hash-chain, which read
+  the local log. Regression test: `tests/test_hosted_local_audit_1247.py`.
+
+### Security
+
+- **Local audit log redacts PII/financial DLP plaintext.** Now that hosted mode
+  writes the local plaintext audit log, a DLP finding's raw `matched_text` (which
+  is plaintext for the pii/financial categories; the secret category is already
+  SHA-256 hashed) is stripped from the LOCAL row -- it would otherwise expose
+  PII/financial data to anyone who can read the file, content hosted mode kept
+  server-side only. The finding metadata (rule_id/category/location) is
+  preserved so the local log still records THAT a rule fired, and the remote
+  sink keeps full fidelity.
+
 ## 1.9.0 -- 2026-06-15 (Antigravity install CLI, epic gh#925)
 
 ### Added

{controlzero-1.9.0 → controlzero-1.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.0
+Version: 1.9.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.9.0 → controlzero-1.9.1}/controlzero/__init__.py

@@ -40,7 +40,7 @@ from controlzero.hitl.grant_protocol import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.9.0"
+__version__ = "1.9.1"
 
 __all__ = [
     "Client",

{controlzero-1.9.0 → controlzero-1.9.1}/controlzero/client.py

@@ -36,7 +36,6 @@ import sys
 import threading
 import time
 import uuid
-import warnings
 import asyncio
 from datetime import datetime, timezone
 from pathlib import Path
@@ -120,6 +119,53 @@ def _mask_api_key(api_key: Optional[str]) -> str:
     return "***"
 
 
+# DLP categories whose ``matched_text`` is PLAINTEXT in a finding (the secret
+# category is already SHA-256 hashed by the scanner, so it is safe to persist
+# locally). Anything in this set must have its raw matched value stripped
+# before the finding is written to the local plaintext audit log. See
+# ``_redact_local_dlp`` and the #1247 review note in ``_audit_decision``.
+_DLP_PLAINTEXT_CATEGORIES = ("pii", "financial")
+
+
+def _redact_local_dlp(entry: dict) -> dict:
+    """Return a copy of an audit entry safe to write to the LOCAL plaintext log.
+
+    The only field that carries raw argument-derived sensitive content is
+    ``dlp_findings[*].matched_text`` for pii/financial categories. We strip the
+    raw value (replacing it with a redaction marker) while preserving every
+    other field of the finding -- rule_id, category, location, count, etc. --
+    so the local log still records THAT a DLP rule fired, just not the matched
+    value. Entries without DLP findings are returned unchanged (a cheap
+    identity for the overwhelmingly common case).
+    """
+    findings = entry.get("dlp_findings")
+    if not findings:
+        return entry
+    needs_redaction = any(
+        isinstance(f, dict)
+        and f.get("category") in _DLP_PLAINTEXT_CATEGORIES
+        and "matched_text" in f
+        for f in findings
+    )
+    if not needs_redaction:
+        return entry
+    safe = dict(entry)
+    redacted_findings = []
+    for f in findings:
+        if (
+            isinstance(f, dict)
+            and f.get("category") in _DLP_PLAINTEXT_CATEGORIES
+            and "matched_text" in f
+        ):
+            rf = dict(f)
+            rf["matched_text"] = "[redacted-local]"
+            redacted_findings.append(rf)
+        else:
+            redacted_findings.append(f)
+    safe["dlp_findings"] = redacted_findings
+    return safe
+
+
 class Client:
     """The ControlZero policy client.
 
@@ -302,35 +348,60 @@ class Client:
 
         self._tamper_state_dir = Path.home() / ".controlzero"
 
-        # Set up local audit logger ONLY in pure-local mode.
-        # When hosted, audit goes through the remote forwarder (not implemented in
-        # this skinny client; see hosted SDK in the legacy package for now).
+        # Set up the local audit logger in EVERY mode.
+        #
+        # P0 regression (epic #1247, 2026-06-15): a customer who ran
+        # `controlzero install claude-code --api-key cz_live_...` saw audit
+        # rows reach the dashboard (remote bearer sink) but their local
+        # ~/.controlzero/audit.log stayed frozen -- it was last appended weeks
+        # earlier. Root cause: this block used to create the LocalAuditLogger
+        # ONLY when `not self._has_api_key`, so hosted mode left ``self._audit``
+        # None and ``_audit_decision`` skipped the local write entirely.
+        #
+        # That silently broke the day-one value prop the claude-code template
+        # AND the install command both promise verbatim:
+        #   "every Claude Code tool call is logged to ~/.controlzero/audit.log"
+        #   "Audit log:        ~/.controlzero/audit.log"
+        # The promise is mode-independent, so the local sink must be too. Local
+        # audit is now ALWAYS on (allow AND deny, local AND hosted); the remote
+        # bearer/enrolled sink is layered ON TOP in hosted mode, not instead of
+        # the local file. The local log is also what `cz debug-bundle` and the
+        # tamper hash-chain depend on, so a frozen file degraded those too.
         self._audit: Optional[LocalAuditLogger] = None
-        if not self._has_api_key:
-            # log_* options are honored
+        # In hosted mode the caller (e.g. the hook-check CLI) may not pass a
+        # log_path; default it to the canonical global audit log so a hosted
+        # install still writes the file the template/install message advertise.
+        effective_log_path = log_path
+        if self._has_api_key and log_path == "./controlzero.log":
+            effective_log_path = str(Path.home() / ".controlzero" / "audit.log")
+        try:
             self._audit = LocalAuditLogger(
-                log_path=log_path,
+                log_path=effective_log_path,
                 rotation=log_rotation,
                 retention=log_retention,
                 compression=log_compression,
                 log_format=log_format,
             )
-        else:
-            # Hosted: log_* options are ignored. Warn if user tried to set them.
-            user_set_log_opts = (
-                log_path != "./controlzero.log"
-                or log_rotation != "daily"
-                or log_retention != "30 days"
-                or log_compression is not None
-                or log_format != "json"
+        except (OSError, PermissionError) as exc:
+            # The local audit log must never crash the client when the FAILURE
+            # IS ENVIRONMENTAL: an unwritable log path (read-only HOME, sandbox,
+            # full disk) falls back to no local sink. In hosted mode the remote
+            # sink still carries the trail; in pure-local mode there may be no
+            # remote sink, but the alternative -- crashing every guard() call --
+            # is worse, and the warning surfaces the cause.
+            #
+            # #1247 review (codex): this catch is deliberately NARROW. A broad
+            # ``except Exception`` here would also swallow a genuine logger bug
+            # or bad config and silently set _audit=None, which in pure-local
+            # mode would make audit vanish with no signal. Programming errors
+            # must propagate so they are caught in tests/CI, not in production.
+            self._audit = None
+            import logging as _logging
+            _logging.getLogger("controlzero.client").warning(
+                "controlzero: local audit log path unavailable (%s); "
+                "audit will be recorded remotely only",
+                exc,
             )
-            if user_set_log_opts:
-                warnings.warn(
-                    "controlzero: log_* options are ignored when an API key is set "
-                    "(audit is managed server-side).",
-                    UserWarning,
-                    stacklevel=2,
-                )
 
         # --- Hosted policy periodic refresh state --------------------------
         #
@@ -1746,9 +1817,22 @@ class Client:
             if "host_tool_name" in context:
                 entry["host_tool_name"] = context["host_tool_name"]
 
-        # Local file first (when local audit is enabled)
+        # Local file first (when local audit is enabled).
+        #
+        # #1247 review (codex): now that the local audit log is written in
+        # hosted mode too, we must NOT regress the data-exposure posture.
+        # ``dlp_findings[*].matched_text`` is PLAINTEXT for pii/financial
+        # categories (only the secret category is already SHA-256 hashed --
+        # see dlp_scanner). Previously hosted mode kept that argument-derived
+        # sensitive content server-side only; persisting it to the local
+        # plaintext ~/.controlzero/audit.log would leak PII/financial data to
+        # anyone who can read the file. So the LOCAL row carries DLP findings
+        # with the raw plaintext stripped (rule_id / category / location /
+        # count are preserved so the local log still shows THAT a match fired,
+        # just not the matched value). The REMOTE sinks keep full fidelity --
+        # they ship over TLS to server-side storage exactly as before.
         if self._audit is not None:
-            self._audit.log(entry)
+            self._audit.log(_redact_local_dlp(entry))
 
         # Remote sink (enrolled machines: signed-request auth).
         if self._remote_sink is not None:

{controlzero-1.9.0 → controlzero-1.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.9.0"
+version = "1.9.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.9.1/tests/test_hosted_local_audit_1247.py

@@ -0,0 +1,217 @@
+"""Regression guard for epic #1247: hosted mode MUST write the local audit log.
+
+P0 customer regression (2026-06-15): after
+``controlzero install claude-code --api-key cz_live_...`` (hosted mode), a
+customer's Claude Code tool calls reached the dashboard (remote bearer sink)
+but their local ``~/.controlzero/audit.log`` stayed frozen for weeks. Root
+cause: ``Client.__init__`` only constructed the ``LocalAuditLogger`` when NO
+API key was set, so hosted mode left ``self._audit`` ``None`` and
+``_audit_decision`` skipped the local write entirely.
+
+That silently broke the day-one value prop the claude-code template AND the
+``controlzero install`` message both promise verbatim: every tool call is
+logged to ``~/.controlzero/audit.log``. The promise is mode-independent, so the
+local sink must be too.
+
+These tests pin the contract so the core audit path cannot silently regress
+again:
+
+  * Hosted mode (api_key set) writes a LOCAL audit row for an ALLOW decision.
+  * Hosted mode writes a LOCAL audit row for a DENY decision (a blocked call
+    MUST be locally recorded -- this is the exact shape the customer hit:
+    Claude Code Bash calls denied by the policy engine).
+  * Hosted mode still ALSO ships the row remotely (bearer sink), i.e. the fix
+    layers local audit ON TOP of remote, it does not trade one for the other.
+  * Both rows carry ``client_name == "claude_code"`` so the dashboard + local
+    log attribute the call to the right host adapter.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+
+from controlzero import Client
+
+
+def _make_fake_bearer_sink():
+    """A BearerAuditSink stand-in that records every entry instead of POSTing."""
+    sink = MagicMock()
+    sink.logged = []
+    sink.log.side_effect = lambda entry: sink.logged.append(entry)
+    sink.close = MagicMock()
+    return sink
+
+
+def _read_local_audit_rows(log_path):
+    """Parse the local audit log into a list of decoded JSON rows.
+
+    The LocalAuditLogger writes one JSON object per line (loguru ``{message}``
+    sink). Lines that are not pure JSON (loguru may not be installed, in which
+    case it falls back to a formatted stderr line) are skipped.
+    """
+    rows = []
+    if not log_path.exists():
+        return rows
+    for line in log_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+def _hosted_client(monkeypatch, tmp_path, *, allow: bool, fake_sink):
+    """Build a hosted-mode Client whose evaluator returns a fixed allow/deny.
+
+    Patches the hosted bundle load + the bearer sink so no network is touched.
+    The evaluator is stubbed to return the requested effect deterministically,
+    independent of whatever the (mocked) bundle contains.
+    """
+    monkeypatch.setenv("CONTROLZERO_API_KEY", "cz_live_1247_regression")
+    monkeypatch.delenv("CONTROLZERO_LOCAL_OVERRIDE", raising=False)
+
+    fake_parsed = MagicMock()
+    fake_parsed.payload = {"project_id": "proj-1247"}
+
+    log_path = tmp_path / "audit.log"
+
+    with patch(
+        "controlzero.audit_remote.BearerAuditSink", return_value=fake_sink
+    ), patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        return_value=({"version": "1", "rules": [{"allow": "*"}]}, fake_parsed),
+    ), patch(
+        "controlzero.hosted_policy.load_cached_bundle",
+        return_value=None,
+    ), patch(
+        "controlzero.client.load_policy",
+        return_value=MagicMock(rules=[], settings=MagicMock()),
+    ):
+        cz = Client(log_path=str(log_path))
+
+    # Stub the evaluator so the decision is deterministic regardless of bundle.
+    from controlzero._internal.enforcer import PolicyDecision
+
+    effect = "allow" if allow else "deny"
+    decision = PolicyDecision(
+        effect=effect,
+        reason="ok" if allow else "blocked by policy (no rule match)",
+        policy_id="rule-1" if allow else "synthetic:NO_RULE_MATCH",
+    )
+    cz._evaluator = MagicMock()
+    cz._evaluator.evaluate.return_value = decision
+    return cz, log_path
+
+
+def test_hosted_mode_writes_local_audit_on_allow(monkeypatch, tmp_path):
+    fake_sink = _make_fake_bearer_sink()
+    cz, log_path = _hosted_client(
+        monkeypatch, tmp_path, allow=True, fake_sink=fake_sink
+    )
+    try:
+        # Hosted Client MUST have a live local audit sink (the regression was
+        # this being None whenever an API key was set).
+        assert cz._audit is not None, (
+            "hosted-mode Client must construct a local audit logger "
+            "(#1247: it used to be None when api_key was set)"
+        )
+        cz.guard(
+            "Bash",
+            args={"command": "echo hi"},
+            method="echo",
+            context={"client_name": "claude_code"},
+        )
+    finally:
+        cz.close()
+
+    rows = _read_local_audit_rows(log_path)
+    allow_rows = [r for r in rows if r.get("decision") == "allow"]
+    assert allow_rows, f"expected a local ALLOW audit row, got rows: {rows}"
+    row = allow_rows[-1]
+    assert row["tool"] == "Bash", row
+    assert row["client_name"] == "claude_code", row
+    assert row["policy_source"] == "hosted", row
+
+    # The fix layers local ON TOP of remote: the bearer sink still got the row.
+    remote_rows = [e for e in fake_sink.logged if e.get("mode") != "lifecycle"]
+    assert remote_rows, "hosted mode must still ship the row to the remote sink"
+
+
+def test_hosted_mode_writes_local_audit_on_deny(monkeypatch, tmp_path):
+    """The exact customer shape: a Claude Code call DENIED in hosted mode must
+    still produce a local audit row. A blocked call that leaves no local trace
+    is the worst case -- it is precisely the action an auditor needs to see."""
+    fake_sink = _make_fake_bearer_sink()
+    cz, log_path = _hosted_client(
+        monkeypatch, tmp_path, allow=False, fake_sink=fake_sink
+    )
+    try:
+        assert cz._audit is not None, "hosted-mode Client must have a local audit logger"
+        decision = cz.guard(
+            "Bash",
+            args={"command": "rm -rf /tmp/x"},
+            method="rm",
+            context={"client_name": "claude_code"},
+        )
+        assert decision.denied, "test setup expected a deny decision"
+    finally:
+        cz.close()
+
+    rows = _read_local_audit_rows(log_path)
+    deny_rows = [r for r in rows if r.get("decision") == "deny"]
+    assert deny_rows, f"expected a local DENY audit row, got rows: {rows}"
+    row = deny_rows[-1]
+    assert row["tool"] == "Bash", row
+    assert row["client_name"] == "claude_code", row
+    assert row["policy_source"] == "hosted", row
+
+    remote_rows = [e for e in fake_sink.logged if e.get("mode") != "lifecycle"]
+    assert remote_rows, "hosted mode must still ship the deny row to the remote sink"
+
+
+def test_local_dlp_redaction_strips_plaintext_but_remote_keeps_it():
+    """#1247 review (codex): the local plaintext audit row must NOT carry raw
+    pii/financial ``matched_text``. The remote sink keeps full fidelity.
+
+    Now that hosted mode writes the local audit.log, persisting a DLP match's
+    raw plaintext value to ~/.controlzero/audit.log would leak PII/financial
+    data to anyone who can read the file -- content hosted mode previously
+    kept server-side only. The redaction preserves the finding's metadata
+    (rule_id/category/location) so the local log still shows a match fired.
+    """
+    from controlzero.client import _redact_local_dlp
+
+    entry = {
+        "decision": "deny",
+        "tool": "Bash",
+        "dlp_findings": [
+            {"rule_id": "ssn", "category": "pii", "matched_text": "123-45-6789", "location": "command"},
+            {"rule_id": "ccn", "category": "financial", "matched_text": "4111111111111111"},
+            # secret category is ALREADY hashed by the scanner -> safe, keep as-is.
+            {"rule_id": "aws", "category": "secret", "matched_text": "sha256:deadbeef"},
+        ],
+    }
+
+    safe = _redact_local_dlp(entry)
+
+    # Local copy: pii/financial plaintext stripped, secret hash preserved.
+    by_rule = {f["rule_id"]: f for f in safe["dlp_findings"]}
+    assert by_rule["ssn"]["matched_text"] == "[redacted-local]"
+    assert by_rule["ccn"]["matched_text"] == "[redacted-local]"
+    assert by_rule["aws"]["matched_text"] == "sha256:deadbeef"
+    # Metadata preserved so the local log still records THAT a rule fired.
+    assert by_rule["ssn"]["category"] == "pii"
+    assert by_rule["ssn"]["location"] == "command"
+
+    # The ORIGINAL entry (which the remote sinks consume) is untouched: full
+    # fidelity ships to server-side storage exactly as before.
+    assert entry["dlp_findings"][0]["matched_text"] == "123-45-6789"
+    assert entry["dlp_findings"][1]["matched_text"] == "4111111111111111"
+
+    # No DLP findings -> identity (cheap common path).
+    plain = {"decision": "allow", "tool": "Read"}
+    assert _redact_local_dlp(plain) is plain

controlzero-1.9.1/tests/test_log_options_ignored_hosted.py

@@ -0,0 +1,50 @@
+"""Audit-log option behavior across hosted + pure-local modes.
+
+History: before epic #1247 (2026-06-15), hosted mode (API key set) DISABLED the
+local audit log entirely and warned that ``log_*`` options were ignored. That
+was the regression -- a customer's ``~/.controlzero/audit.log`` froze while the
+dashboard kept receiving rows. The fix makes the local audit log ALWAYS active
+(see ``Client.__init__`` and ``tests/test_hosted_local_audit_1247.py``), so the
+``log_*`` options are now HONORED in hosted mode and the old "ignored" warning
+no longer fires.
+"""
+
+import warnings
+
+from controlzero import Client
+
+
+def test_log_options_honored_in_hosted_mode(monkeypatch, tmp_path):
+    """Hosted mode (api key set) now WRITES the local audit log, so the
+    log_* options take effect and the legacy 'ignored' warning is gone."""
+    monkeypatch.setenv("CONTROLZERO_API_KEY", "cz_test_fakekey")
+    custom_log = tmp_path / "custom.log"
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        cz = Client(
+            policy={"rules": [{"allow": "*"}]},
+            log_path=str(custom_log),
+            log_rotation="1 MB",
+        )
+        log_warnings = [x for x in w if "log_*" in str(x.message)]
+        assert not log_warnings, (
+            "#1247: hosted mode now honors log_* options (local audit always "
+            f"on); no 'ignored' warning expected, got: {[str(x.message) for x in log_warnings]}"
+        )
+    # A local audit sink must exist in hosted mode now.
+    assert cz._audit is not None
+    cz.close()
+
+
+def test_log_options_silent_in_pure_local(tmp_log):
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        cz = Client(
+            policy={"rules": [{"allow": "*"}]},
+            log_path=str(tmp_log),
+            log_rotation="1 MB",
+        )
+        # No warning expected
+        log_warnings = [x for x in w if "log_*" in str(x.message)]
+        assert not log_warnings
+        cz.close()

controlzero-1.9.0/tests/test_log_options_ignored_hosted.py

@@ -1,35 +0,0 @@
-"""When API key is set (hybrid mode), log_* options are ignored with a warning."""
-
-import warnings
-
-from controlzero import Client
-
-
-def test_log_options_warn_in_hybrid_mode(monkeypatch):
-    """Hybrid mode (api key + local policy): log_* options have no effect
-    because audit ships to remote, so we warn the user."""
-    monkeypatch.setenv("CONTROLZERO_API_KEY", "cz_test_fakekey")
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        Client(
-            policy={"rules": [{"allow": "*"}]},
-            log_path="/tmp/custom.log",
-            log_rotation="1 MB",
-        )
-        assert any(
-            "log_*" in str(warning.message) for warning in w
-        ), f"expected log_* warning, got: {[str(x.message) for x in w]}"
-
-
-def test_log_options_silent_in_pure_local(tmp_log):
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        cz = Client(
-            policy={"rules": [{"allow": "*"}]},
-            log_path=str(tmp_log),
-            log_rotation="1 MB",
-        )
-        # No warning expected
-        log_warnings = [x for x in w if "log_*" in str(x.message)]
-        assert not log_warnings
-        cz.close()