controlzero 1.4.7__tar.gz → 1.5.1__tar.gz

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

@@ -1,8 +1,66 @@
 # 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)
+
+- **Hosted policy wins by default when `CONTROLZERO_API_KEY` is set.**
+  Before 1.5: a stale local `policy.yaml` silently shadowed the
+  dashboard policy. A paying customer ran for 25 days without
+  enforcement because of this. After 1.5: an api_key means hosted is
+  authoritative; a local file is consulted only when no api_key, or
+  when `CONTROLZERO_LOCAL_OVERRIDE=1` is set explicitly as a
+  debug/offline escape hatch. An explicit `policy=` / `policy_file=`
+  arg passed to `Client(...)` still wins (caller is intentional) but
+  emits a loud stderr warning. `strict_hosted=True` upgrades the
+  warning to a `HybridModeError`. The active policy source is named
+  in a single stderr line at Client init so customer support can
+  debug in one glance; `CONTROLZERO_QUIET=1` silences it in CLI
+  subprocess contexts.
+
+### Added
+
+- **Governance audit event when LOCAL_OVERRIDE is used.** Every Client
+  init that bypasses the hosted bundle via
+  `CONTROLZERO_LOCAL_OVERRIDE=1` emits a one-shot audit event with
+  `reason_code=LOCAL_OVERRIDE_ACTIVE` to the remote audit sink. Ops
+  can filter / alert on this code in the audit dashboard so a silent
+  bypass is no longer possible.
+- **Cache GC on api_key rotation.** On every fresh bootstrap fetch
+  the SDK removes `cache/bootstrap-<scope>.json` +
+  `cache/bundle-<scope>.{bin,meta}` files whose scope does NOT match
+  the active api_key. Stray user files in the cache dir are
+  preserved.
+- **`policy.json` accepted alongside `policy.yaml`.** The cwd
+  auto-detect now probes `controlzero.{yaml,yml,json}` in order.
+  Schema is identical to YAML; default write is still YAML.
+- New reason_code: `LOCAL_OVERRIDE_ACTIVE`. Extends the SDK
+  reason-code enum from 8 to 9. Used only on lifecycle events; no
+  impact on guard decisions.
+
+### Refs
+
+GH #424 (umbrella), PRs #425 (precedence), #428 (cache GC), #427
+(dashboard dedupe), #429 (governance audit event).
+
 ## 1.4.7 -- 2026-05-11
 
 ### Added
+
 - **`controlzero debug bundle` -- inspect SDK-loaded rules + simulate guards**
   (T87, GH #392). The bundle on disk is encrypted+signed; `cat` returns
   nothing useful, so until now diagnosing a deny-deny incident meant
@@ -45,14 +103,13 @@
   The fix is a bidirectional alias shim. The enforcer now expands
   candidate actions through a single-source-of-truth alias table
   (`controlzero/_internal/action_aliases.py`) so:
-
-    - A pre-#350 rule with `actions: ["database:query"]` keeps matching
-      modern SELECT calls (which the SDK emits as `database:read`).
-    - A modern rule with `actions: ["database:read"]` keeps matching
-      legacy guard calls that pass `method="SELECT"`.
-    - The legacy ambiguous `database:delete` (used historically for
-      both row DELETE and table DROP) maps to BOTH `database:write`
-      and `database:admin`, so neither modern intent silently breaks.
+  - A pre-#350 rule with `actions: ["database:query"]` keeps matching
+    modern SELECT calls (which the SDK emits as `database:read`).
+  - A modern rule with `actions: ["database:read"]` keeps matching
+    legacy guard calls that pass `method="SELECT"`.
+  - The legacy ambiguous `database:delete` (used historically for
+    both row DELETE and table DROP) maps to BOTH `database:write`
+    and `database:admin`, so neither modern intent silently breaks.
 
   The alias table is byte-identical across Python, Node, and Go SDKs
   and is locked by the cross-SDK fixture at
@@ -71,7 +128,6 @@
   these all carried `policy_id=None` and rendered as a blank Policy
   column on the audit dashboard, making four very different bug
   classes look identical. The new sentinels are:
-
   - `synthetic:NO_RULE_MATCH` -- bundle loaded, no rule's actions
     matched the call.
   - `synthetic:NO_ACTIVE_POLICIES` -- bundle was structurally empty.
@@ -89,6 +145,7 @@
   Constants exported from `controlzero._internal.enforcer` as
   `SYNTHETIC_POLICY_ID_PREFIX`, `SYNTHETIC_NO_RULE_MATCH`, etc., plus
   `VALID_SYNTHETIC_POLICY_IDS` for runtime validation.
+
 ## 1.4.6 -- 2026-05-11
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.4.7
+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
@@ -239,19 +239,24 @@ these `log_*` options are ignored with a warning.
 
 ## Hybrid mode
 
-If you set both an API key AND pass a local policy, the local policy
-**overrides** the dashboard policy and you get a loud WARN log on init:
+Default (T103, 2026-05-12): when `CONTROLZERO_API_KEY` is set, the
+hosted (dashboard) policy wins. Pass `CONTROLZERO_LOCAL_OVERRIDE=1` to
+force the local file as a debug fallback.
+
+If you BOTH set an API key AND pass a `policy=` / `policy_file=` arg
+to `Client(...)`, the explicit local arg wins (caller is intentional)
+and you get a loud WARN log on init:
 
 ```
-WARNING: controlzero: manual policy override detected. ...
+WARNING: controlzero: explicit local policy overrides the hosted bundle. ...
 ```
 
-This is intentional: it makes accidental prod bypass impossible to miss.
-For prod environments, opt into strict mode to raise instead:
+This makes accidental prod bypass impossible to miss. For prod
+environments, opt into strict mode to raise instead:
 
 ```python
 cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
-# RuntimeError: manual policy override detected ...
+# HybridModeError: explicit local policy overrides the hosted bundle ...
 ```
 
 ## Coding agent hooks

{controlzero-1.4.7 → controlzero-1.5.1}/README.md

@@ -187,19 +187,24 @@ these `log_*` options are ignored with a warning.
 
 ## Hybrid mode
 
-If you set both an API key AND pass a local policy, the local policy
-**overrides** the dashboard policy and you get a loud WARN log on init:
+Default (T103, 2026-05-12): when `CONTROLZERO_API_KEY` is set, the
+hosted (dashboard) policy wins. Pass `CONTROLZERO_LOCAL_OVERRIDE=1` to
+force the local file as a debug fallback.
+
+If you BOTH set an API key AND pass a `policy=` / `policy_file=` arg
+to `Client(...)`, the explicit local arg wins (caller is intentional)
+and you get a loud WARN log on init:
 
 ```
-WARNING: controlzero: manual policy override detected. ...
+WARNING: controlzero: explicit local policy overrides the hosted bundle. ...
 ```
 
-This is intentional: it makes accidental prod bypass impossible to miss.
-For prod environments, opt into strict mode to raise instead:
+This makes accidental prod bypass impossible to miss. For prod
+environments, opt into strict mode to raise instead:
 
 ```python
 cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
-# RuntimeError: manual policy override detected ...
+# HybridModeError: explicit local policy overrides the hosted bundle ...
 ```
 
 ## Coding agent hooks

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

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

{controlzero-1.4.7 → controlzero-1.5.1}/controlzero/_internal/enforcer.py

@@ -59,6 +59,13 @@ REASON_CODE_BUNDLE_TAMPERED = "BUNDLE_TAMPERED"
 REASON_CODE_MACHINE_QUARANTINED = "MACHINE_QUARANTINED"
 REASON_CODE_NETWORK_ERROR = "NETWORK_ERROR"
 REASON_CODE_DLP_BLOCKED = "DLP_BLOCKED"
+# Governance trail (T108, 2026-05-12). Emitted once per Client init when
+# the user has set CONTROLZERO_LOCAL_OVERRIDE=1 with an api_key, telling
+# the SDK to bypass the hosted bundle in favour of a local file. Posted
+# to the remote audit sink so ops can detect override usage via the
+# normal audit dashboard + alert on it. NOT a deny / allow decision --
+# decision is "audit" and policy_id is "<lifecycle>".
+REASON_CODE_LOCAL_OVERRIDE_ACTIVE = "LOCAL_OVERRIDE_ACTIVE"
 
 VALID_REASON_CODES = frozenset({
     REASON_CODE_RULE_MATCH,
@@ -69,6 +76,7 @@ VALID_REASON_CODES = frozenset({
     REASON_CODE_MACHINE_QUARANTINED,
     REASON_CODE_NETWORK_ERROR,
     REASON_CODE_DLP_BLOCKED,
+    REASON_CODE_LOCAL_OVERRIDE_ACTIVE,
 })
 
 # Synthetic policy_id sentinels (T79 / Bryan deny-deny postmortem,

{controlzero-1.4.7 → controlzero-1.5.1}/controlzero/audit_remote.py

@@ -295,6 +295,12 @@ class BearerAuditSink:
             "policy_id": entry.get("policy_id", ""),
             "rule_id": entry.get("policy_id", ""),
             "reason": entry.get("reason", ""),
+            # T108 (2026-05-12): governance reason_code that the backend
+            # audit_logs column already accepts (#228 Phase 2). Lets
+            # ops filter / alert on synthetic lifecycle events (e.g.
+            # LOCAL_OVERRIDE_ACTIVE) without false-matching them against
+            # guard decisions.
+            "reason_code": entry.get("reason_code", ""),
             "hostname": hostname,
             "user": user,
             "mode": entry.get("mode", "hosted"),

{controlzero-1.4.7 → controlzero-1.5.1}/controlzero/cli/main.py

@@ -547,21 +547,65 @@ def hook_check(policy: Optional[str]):
         }))
         sys.exit(2)
 
-    # Resolve policy file
-    policy_path = _resolve_hook_policy(policy)
-
-    # Freshness check: if this machine is enrolled and the policy file is
-    # stale, attempt a quick background sync from the backend. This is a
-    # no-op for local-only (unenrolled) machines.
-    if policy_path is not None:
-        _maybe_refresh_policy(policy_path)
-    elif policy is None:
-        # Policy not found yet -- maybe a sync will create it.
-        _maybe_refresh_policy(GLOBAL_POLICY_PATH)
-        # Re-resolve after potential sync.
+    # Hoist api_key resolution above the precedence decision so a key
+    # stored only in ~/.controlzero/config.yaml correctly enables hosted
+    # mode. Pre-T103 this happened AFTER the resolver, so a user with the
+    # key in config.yaml but not in env fell through to the local-file
+    # path on every hook-check.
+    if not os.environ.get("CONTROLZERO_API_KEY"):
+        _config_path = GLOBAL_POLICY_DIR / "config.yaml"
+        if _config_path.exists():
+            try:
+                _config = yaml.safe_load(_config_path.read_text(encoding="utf-8"))
+                if _config and _config.get("api_key"):
+                    os.environ["CONTROLZERO_API_KEY"] = _config["api_key"]
+            except Exception:
+                pass
+
+    # T103 review (B1, B2): the CLI hook-check is a non-interactive
+    # subprocess that Claude Code / Gemini CLI / Codex CLI spawn fresh
+    # for every PreToolUse hook. Module-level "warn once per process"
+    # guards do nothing here: every tool call is a new process.
+    # Without this env var, every Bash / Edit / Read in an agent
+    # session would emit an active-source notification to stderr.
+    # Suppress for the hook subprocess context only; library callers
+    # still see it once per process. CLI runs may opt in by setting
+    # CONTROLZERO_VERBOSE_HOOK=1.
+    if os.environ.get("CONTROLZERO_VERBOSE_HOOK", "").lower() not in ("1", "true", "yes", "on"):
+        os.environ.setdefault("CONTROLZERO_QUIET", "1")
+
+    # T103 precedence (2026-05-12):
+    #   1. --policy <path> wins unconditionally.
+    #   2. api_key set => hosted mode. Client(api_key=...) loads the cached
+    #      bundle via hosted_policy and conditional-refreshes it on every
+    #      construction (content-hash via If-None-Match, not mtime). This
+    #      is the path John Na should have hit on every hook-check.
+    #   3. CONTROLZERO_LOCAL_OVERRIDE=1 with api_key => fall back to file.
+    #   4. No api_key, no enrollment => local file path.
+    #
+    # Before T103 the resolver fell back to ~/.controlzero/policy.yaml
+    # whenever it existed, even with a valid api_key. John Na's manually
+    # edited policy.yaml shadowed the dashboard policy with no warning.
+    _local_override = os.environ.get(
+        "CONTROLZERO_LOCAL_OVERRIDE", ""
+    ).lower() in ("1", "true", "yes", "on")
+    _hosted_active = bool(os.environ.get("CONTROLZERO_API_KEY")) and not _local_override
+
+    if policy is not None:
+        # Explicit --policy wins.
         policy_path = _resolve_hook_policy(policy)
+    elif _hosted_active:
+        # Hosted mode. No file resolution; the Client constructor will
+        # read the cache + conditional-refresh. policy_path stays None so
+        # we route through the hosted branch below.
+        policy_path = None
+    else:
+        # Local mode: enrollment-based pull (if enrolled) or static file.
+        policy_path = _resolve_hook_policy(policy)
+        if policy_path is not None:
+            _maybe_refresh_policy(policy_path)
 
-    if policy_path is None:
+    if policy_path is None and not _hosted_active:
         # No policy installed AND the carve-out already passed (user
         # is enrolled or has an API key). This is the BUNDLE_MISSING
         # path -- backend bundle never synced, sync failed, or the
@@ -597,20 +641,15 @@ def hook_check(policy: Optional[str]):
         }))
         sys.exit(2)
 
-    # --- Load API key from config.yaml if not in environment ---
-    if not os.environ.get("CONTROLZERO_API_KEY"):
-        config_path = GLOBAL_POLICY_DIR / "config.yaml"
-        if config_path.exists():
-            try:
-                config = yaml.safe_load(config_path.read_text(encoding="utf-8"))
-                if config and config.get("api_key"):
-                    os.environ["CONTROLZERO_API_KEY"] = config["api_key"]
-            except Exception:
-                pass
+    # api_key resolution moved above the precedence decision (see T103
+    # block). Do not re-load here.
 
-    # --- Tamper detection: policy file HMAC check ---
-    tamper_detected = False
-    tamper_detected = _check_policy_tamper(policy_path)
+    # --- Tamper detection ---
+    # Policy-file HMAC check applies ONLY to file-backed policies. In
+    # hosted mode (policy_path is None) the bundle is cryptographically
+    # signed and verified inside hosted_policy.load_hosted_policy at
+    # Client init time; a separate HMAC over a local file is meaningless.
+    tamper_detected = _check_policy_tamper(policy_path) if policy_path is not None else False
 
     # --- Tamper detection: audit log hash chain check ---
     audit_chain_broken = _check_audit_chain()
@@ -642,14 +681,30 @@ def hook_check(policy: Optional[str]):
             sys.exit(2)
 
     try:
-        cz = Client(
-            policy_file=str(policy_path),
-            log_path=str(GLOBAL_AUDIT_PATH),
-        )
+        if _hosted_active and policy_path is None:
+            # T103: hosted mode. Client() reads the cache and conditional-
+            # refreshes it on construction. No file-path argument.
+            cz = Client(log_path=str(GLOBAL_AUDIT_PATH))
+        else:
+            cz = Client(
+                policy_file=str(policy_path),
+                log_path=str(GLOBAL_AUDIT_PATH),
+            )
     except (PolicyLoadError, PolicyValidationError, PermissionError, OSError) as e:
         # Bad/unreadable policy file: log + allow (do not silently break the agent)
         click.echo(f"controlzero: policy file invalid ({e}); allowing", err=True)
         sys.exit(0)
+    except Exception as e:  # noqa: BLE001
+        # Hosted-pull failure (HostedAuthError, HostedBootstrapError, etc).
+        # Fail-closed with a clear reason; do NOT silently allow because
+        # that's what John Na is suffering from today.
+        click.echo(f"controlzero: hosted policy load failed ({e})", err=True)
+        click.echo(json.dumps({
+            "decision": "block",
+            "reason": f"[Control Zero] Hosted policy load failed: {e}",
+            "reason_code": REASON_CODE_BUNDLE_MISSING,
+        }))
+        sys.exit(2)
 
     decision = cz.guard(
         canonical_tool,
@@ -1095,65 +1150,33 @@ def _do_pull_and_write(state: object, policy_path: Path, state_dir: Path, result
         result["error"] = str(exc)
 
 
-def _do_hosted_pull_and_write(
-    api_key: str, policy_path: Path, result: dict
-) -> None:
-    """Worker: pull + verify + decrypt the signed bundle using the Bearer
-    API key path (no enrollment) and write the translated policy to disk.
-
-    Mirrors _do_pull_and_write but uses controlzero.hosted_policy instead
-    of the enrollment module. Enables CLI hook-check policy refresh for
-    users who configured the SDK with CONTROLZERO_API_KEY but never ran
-    `controlzero enroll`.
-    """
-    try:
-        from controlzero.hosted_policy import load_hosted_policy
-        bundle, _parsed = load_hosted_policy(api_key)
-        yaml_content = yaml.safe_dump(
-            {
-                "version": str(bundle.get("version", "1")),
-                "rules": bundle.get("rules", []),
-            },
-            default_flow_style=False,
-            allow_unicode=True,
-        )
-        tmp = policy_path.with_suffix(".yaml.tmp")
-        tmp.write_text(yaml_content, encoding="utf-8")
-        tmp.replace(policy_path)
-        result["refreshed"] = True
-        result["error"] = None
-    except Exception as exc:  # noqa: BLE001
-        result["refreshed"] = False
-        result["error"] = str(exc)
-
-
 def _maybe_refresh_policy(
     policy_path: Path,
     state_dir: Path = GLOBAL_POLICY_DIR,
     threshold_s: float = POLICY_STALENESS_THRESHOLD_S,
     timeout_s: float = POLICY_SYNC_TIMEOUT_S,
 ) -> None:
-    """If the policy is stale, attempt a sync in the background.
+    """If an ENROLLED machine's policy file is stale, sync in background.
+
+    T103 (2026-05-12): the Bearer api_key refresh branch was removed
+    here. api_key clients now go through ``Client(api_key=...)`` which
+    reads the signed bundle cache and conditional-refreshes via
+    ``hosted_policy.load_hosted_policy`` (If-None-Match etag). The CLI
+    no longer clobbers ``~/.controlzero/policy.yaml`` from a hosted pull,
+    because that destroyed user-edited content (John Na 2026-05-12).
 
-    Two refresh paths, tried in priority order:
-      1. Enrollment (signed per-machine requests) -- used when enrollment.json exists.
-      2. Bearer API key (hosted mode) -- used when CONTROLZERO_API_KEY is set
-         but the machine is not enrolled. Relies on the signed .czpolicy
-         bundle flow added in SDK 1.4.
+    This function now serves only the enrollment-based path used by
+    machines that ran ``controlzero login`` and persisted
+    enrollment.json. If no enrollment state, returns immediately.
 
     Uses a background thread with a join timeout so the hook never stalls
-    for longer than *timeout_s* seconds. On timeout or network failure,
-    falls back to the cached policy and logs a warning to stderr.
+    for longer than *timeout_s* seconds.
     """
     if not _is_policy_stale(policy_path, threshold_s):
         return
 
     state = _load_enrollment_state(state_dir)
-    api_key = os.environ.get("CONTROLZERO_API_KEY", "")
-    use_hosted = state is None and bool(api_key)
-
-    if state is None and not use_hosted:
-        # No enrollment and no API key -- local-only mode, nothing to sync.
+    if state is None:
         return
 
     # Compute staleness for the warning message.
@@ -1163,18 +1186,11 @@ def _maybe_refresh_policy(
         age_min = -1
 
     result: dict = {"refreshed": False, "error": None}
-    if use_hosted:
-        worker = threading.Thread(
-            target=_do_hosted_pull_and_write,
-            args=(api_key, policy_path, result),
-            daemon=True,
-        )
-    else:
-        worker = threading.Thread(
-            target=_do_pull_and_write,
-            args=(state, policy_path, state_dir, result),
-            daemon=True,
-        )
+    worker = threading.Thread(
+        target=_do_pull_and_write,
+        args=(state, policy_path, state_dir, result),
+        daemon=True,
+    )
     worker.start()
     worker.join(timeout=timeout_s)