controlzero 1.9.0__tar.gz → 1.9.2__tar.gz

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

@@ -1,5 +1,78 @@
 # 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.2 -- 2026-06-16 (durable-by-default + keychain-DEK audit spool, epic gh#1247)
+
+### Changed
+
+- **Hosted-mode audit is now durable by default.** When a `Client` is
+  constructed with an API key (hosted mode) and `CONTROLZERO_SPOOL` is
+  unset, the audit sink now defaults to the **durable encrypted spool**:
+  every decision is serialized, encrypted, and fsynced to an append-only
+  on-disk WAL **before** any network send, then drained opportunistically
+  in a background thread. Audit is no longer lost on a backend outage. An
+  explicit `CONTROLZERO_SPOOL` value (including `off`) still wins, and the
+  enrolled-machine sink keeps its prior off-by-default. Sink init is
+  fail-soft: any open/IO error degrades to the prior in-memory path,
+  emits `spool_init_degraded_total`, and never crashes or blocks the
+  PreToolUse hook.
+
+### Security
+
+- **Spool encryption key (DEK) defaults to the OS keystore.** The DEK now
+  lives in the macOS Keychain (a `security` generic-password item) or the
+  Linux Secret Service (`secret-tool`/libsecret) by default when one is
+  available; the on-disk `spool.key` then holds only a sentinel, so a
+  file-read of the spool directory can neither **decrypt** nor **forge**
+  spooled audit records (the AES-GCM tag and hash chain are keyed on the
+  DEK). Keystore access is strictly **non-interactive** and
+  hard-timeout-bounded -- a prompt risk, locked keystore, or missing CLI
+  degrades to the legacy 0600 `spool.key` (key hardening never costs audit
+  durability and never blocks the hook). A pre-existing on-disk DEK is
+  migrated into the keystore on first keystore-enabled open. Force the
+  legacy file DEK with `CONTROLZERO_SPOOL_KEYCHAIN=0` or
+  `CONTROLZERO_SPOOL_KEYCHAIN_DISABLE=1`; require the keystore with
+  `CONTROLZERO_SPOOL_KEYCHAIN=1`.
+
+### Tests
+
+- New `tests/spool/test_spool_keychain_dek.py` (keystore round-trip,
+  sentinel-on-disk, prompt-risk fallback, file opt-out, file->keystore
+  migration) and `tests/spool/test_spool_durable_default_tamper.py`
+  (hosted durable default, encrypted-WAL-before-send, **tampered-frame
+  rejection surfaced via `spool_tamper_records_total{gcm_auth}`**,
+  graceful init-failure degrade, WAL append latency budget). Spool
+  isolation is enforced suite-wide so tests never touch the real home dir
+  or OS keychain.
+
 ## 1.9.0 -- 2026-06-15 (Antigravity install CLI, epic gh#925)
 
 ### Added

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

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

{controlzero-1.9.0 → controlzero-1.9.2}/controlzero/audit_remote.py

@@ -261,26 +261,74 @@ class _SpoolWiringMixin:
     _spool = None
     _spool_mode = "off"
 
-    def _init_spool(self, stream_key: str) -> None:
+    def _init_spool(self, stream_key: str, default_mode: str = "off") -> None:
+        """Open the offline audit spool for this sink.
+
+        ``default_mode`` is the mode used when ``CONTROLZERO_SPOOL`` is
+        UNSET. The hosted (API-key) sink passes ``"durable"`` so audit is
+        never lost on a backend outage even when the operator has not set
+        the env knob -- the founder requirement that hosted-mode audit
+        WALs to encrypted disk before send by default. The enrolled sink
+        keeps ``"off"`` (no behavior change). An explicit ``CONTROLZERO_SPOOL``
+        value ALWAYS wins (operators can force ``off``/``spool_only``).
+
+        Non-blocking guarantee (founder constraint): this runs inside the
+        PreToolUse hook hot path. Every failure mode -- spool import
+        error, keystore prompt risk, IO error, ENOSPC -- DEGRADES to the
+        prior in-memory behavior and emits ``spool_init_degraded_total``;
+        it never crashes or blocks the agent. Spool open itself is
+        bounded (one recovery scan + the 200 ms seq.lock budget); it does
+        no network IO.
+        """
         self._drain_state_lock = threading.Lock()
         self._drain_inflight = False
         self._drain_again = False
         self._drain_auth_blocked = False
         self._spool = None
         self._spool_mode = "off"
-        # Fast path: flag off AND no spool directory on disk -- skip the
-        # spool import entirely so the default path stays byte-identical.
-        mode_raw = (os.environ.get("CONTROLZERO_SPOOL") or "").strip().lower()
+        # Fast path: flag off/unset, NO hosted default, AND no spool
+        # directory on disk -- skip the spool import entirely so the
+        # legacy default path stays byte-identical. When default_mode is
+        # durable (hosted), we must NOT take this shortcut: the whole
+        # point is to open a durable spool with no env set.
+        env_present = os.environ.get("CONTROLZERO_SPOOL")
+        mode_raw = (env_present or "").strip().lower()
         spool_dir = os.path.expanduser(
             os.environ.get("CONTROLZERO_SPOOL_DIR") or _SPOOL_DEFAULT_DIR)
-        if mode_raw in ("", "off") and not os.path.isdir(spool_dir):
+        # "Unset" means the env var is absent or an empty/whitespace
+        # string. An EXPLICIT "off" is a deliberate operator choice and
+        # MUST win over the sink default -- it is NOT treated as unset.
+        env_unset = (env_present is None) or (mode_raw == "")
+        env_off = mode_raw == "off"
+        # Effective mode is "off" when: env explicitly off, OR env unset
+        # AND this sink's default is off. In that case, with no spool on
+        # disk, skip the spool import entirely (byte-identical legacy).
+        effective_off = env_off or (env_unset and default_mode in ("", "off"))
+        if effective_off and not os.path.isdir(spool_dir):
             return
         try:
-            from controlzero.spool import Spool, get_mode
-
-            self._spool_mode = get_mode()
-            self._spool = Spool.maybe_open(stream_key)
+            from controlzero.spool import Spool, SpoolConfig, get_mode
+
+            # Resolve the effective mode: an explicit env value (incl.
+            # "off") wins; only a truly UNSET/blank env falls back to
+            # this sink's default_mode.
+            resolved = get_mode()  # "off" when unset/blank or unknown
+            if env_unset and default_mode not in ("", "off"):
+                resolved = default_mode
+            cfg = SpoolConfig.from_env()
+            cfg.mode = resolved
+            self._spool_mode = resolved
+            self._spool = Spool.maybe_open(stream_key, config=cfg)
+            # If the spool opened but immediately degraded to memory-only
+            # (e.g. ENOSPC during the open-time recovery/cleanup), surface
+            # it as a metric. The sink still functions -- WAL just buffers
+            # in memory until disk frees up -- so this is a warning, not a
+            # crash (C15).
+            if (self._spool is not None
+                    and getattr(self._spool, "in_memory_mode", False)):
+                self._spool_init_degraded("memory_mode")
         except Exception as exc:  # noqa: BLE001
+            self._spool_init_degraded("exception")
             logger.warning(
                 "controlzero: audit spool unavailable (%s); "
                 "falling back to in-memory buffering",
@@ -289,6 +337,15 @@ class _SpoolWiringMixin:
             self._spool = None
             self._spool_mode = "off"
 
+    @staticmethod
+    def _spool_init_degraded(reason: str) -> None:
+        """Emit the spool-init degrade metric. Never raises."""
+        try:
+            from controlzero.spool import metrics as _m
+            _m.incr("spool_init_degraded_total", reason)
+        except Exception:  # noqa: BLE001
+            pass
+
     @property
     def _spool_wal(self) -> bool:
         """True when log() must take the spool-first WAL path."""
@@ -660,8 +717,11 @@ class BearerAuditSink(_SpoolWiringMixin):
         self._closed = False
 
         # Offline audit spool (Phase 2): the stream is keyed by the api
-        # key fingerprint, exactly the spec's stream identity.
-        self._init_spool(api_key)
+        # key fingerprint, exactly the spec's stream identity. HOSTED
+        # mode defaults to durable WAL-to-encrypted-disk so audit is
+        # never lost on a backend outage even with no env set (founder
+        # requirement). An explicit CONTROLZERO_SPOOL value still wins.
+        self._init_spool(api_key, default_mode=_SPOOL_MODE_DURABLE)
 
         self._start_flush_timer()
         # Drain-only rule (plan section 10): an existing non-empty spool

{controlzero-1.9.0 → controlzero-1.9.2}/controlzero/cli/spool_cmd.py

@@ -203,9 +203,22 @@ def spool_verify(as_json):
         click.echo("error: spool.key missing; cannot verify", err=True)
         sys.exit(2)
     from controlzero.spool import assess_segment, derive_key
-    from controlzero.spool._state import load_or_create_dek, secure_read
+    from controlzero.spool._state import (
+        SpoolKeyUnavailable,
+        load_or_create_dek,
+        secure_read,
+    )
 
-    dek = load_or_create_dek(root)
+    try:
+        dek = load_or_create_dek(root)
+    except SpoolKeyUnavailable:
+        click.echo(
+            "error: spool DEK lives in the OS keystore but the keystore is "
+            "not readable right now (locked, or run on a different machine). "
+            "Unlock the keystore (or run on the originating host) and retry.",
+            err=True,
+        )
+        sys.exit(2)
 
     def key_provider(header):
         return derive_key(dek, header.device_id, header.stream_fp,

{controlzero-1.9.0 → controlzero-1.9.2}/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: