controlzero 1.5.4__tar.gz → 1.5.5__tar.gz

{controlzero-1.5.4 → controlzero-1.5.5}/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## Unreleased -- Tier 0a security hotfix (2026-05-15)
+
+### Security (P0 hotfix for #174)
+
+- **New `controlzero doctor` command**. Scans every known coding-agent
+  settings file (claude-code, gemini-cli, codex-cli, cursor, windsurf,
+  vscode, cline, antigravity, adal, jetbrains) for plaintext `cz_*_*`
+  API keys baked into hook commands. Reports findings compiler-style
+  with stable E#### error codes. Exit 1 on any ERROR finding so it
+  can run in CI / pre-push hooks.
+- **New `controlzero migrate` command**. Auto-rewrites every leaked
+  inline hook of the form `CONTROLZERO_API_KEY=cz_live_... controlzero
+hook-check` into the safe `controlzero hook-check` form, and
+  persists the recovered key to `~/.controlzero/config.yaml`
+  (mode 0o600, parent dir 0o700). Has `--dry-run`. Idempotent.
+- **Stable error-code catalog** (`controlzero.error_codes`). 24 E####
+  codes across security / auth / policy / cache / network / hook /
+  runtime ranges. Each entry has title, what, fix, and a docs slug
+  for the `docs.controlzero.ai/errors/` URL.
+- **`controlzero telemetry`** group: `full` / `anonymous` / `off`.
+  Opt-IN per the 2026-05-14 transparency mandate. Default unset =
+  silent. Non-interactive shells never prompt. State in
+  `~/.controlzero/telemetry.yaml` (mode 0o600).
+- **Tighter local-file permissions**. `_write_api_key_config` now
+  enforces 0o600 on `config.yaml` and 0o700 on the parent directory.
+  Best-effort on Windows / FAT (silent skip).
+- **Cross-SDK CI contract test**: `scripts/ci/check-no-key-leaks.sh`
+  fails the build on any new `cz_(live|test)_*` leak surface across
+  Python, Node, Go, frontend, docs.
+- **Rich CLI palette**: doctor + migrate now use the DESIGN.md
+  sage-green theme via `controlzero.cli.console`.
+
+If you previously ran `controlzero install <agent>` on a version
+older than 1.5.3, your agent settings file likely still contains
+the plaintext key. Run `controlzero doctor` to check; run
+`controlzero migrate` to fix.
+
+## 1.5.5a1 (pre-release) -- 2026-05-13
+
+This is a **pre-release**. `pip install control-zero` continues to
+resolve to the latest stable (1.5.3). To install this alpha:
+
+    pip install --pre control-zero
+    # or pin explicitly:
+    pip install control-zero==1.5.5a1
+
+Promotion to stable `1.5.5` will follow once we have soak time on the
+T96 + T101 layout changes in real customer environments.
+
+### Added
+
+- **`controlzero env-dump` diagnostic subcommand** (#438). Prints a
+  JSON snapshot of the SDK's effective environment: env vars
+  (redacted by default, `--show-secrets` to unredact with a loud
+  warning), host-adapter selection, file inventory (size + mtime,
+  not contents), and resolved API URL. With `--from-hook` it parses
+  a stdin payload so the output reflects what the hook subprocess
+  actually sees. Built for fast Windows-hook triage after the
+  2026-05-12 CloudShift incident -- a customer can now run a single
+  command and send us the JSON instead of guessing which env vars
+  their hook sees.
+
+- **Layout migration shim** (T101, SDK_LOCAL_LAYOUT spec). Folds any
+  legacy `~/.controlzero/events.log` into `audit.log` on first run of
+  the CLI or first `Client()` construction, then deletes the legacy
+  file. Writes a single `layout_migration` lifecycle marker into
+  `audit.log` so support can grep for the migration. Idempotent and
+  best-effort: a disk failure here never breaks the user's agent.
+  `controlzero status` no longer reads the legacy file; the shim
+  guarantees it's gone by the time any subcommand runs.
+
 ## 1.5.4 -- 2026-05-13
 
 ### Changed

{controlzero-1.5.4 → controlzero-1.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.4
+Version: 1.5.5
 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
@@ -28,6 +28,7 @@ Requires-Dist: httpx>=0.25.0
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
 Requires-Dist: zstandard>=0.22.0
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'

{controlzero-1.5.4 → controlzero-1.5.5}/controlzero/__init__.py

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

{controlzero-1.5.4 → controlzero-1.5.5}/controlzero/_internal/enforcer.py

@@ -20,10 +20,9 @@ from __future__ import annotations
 
 import fnmatch
 from dataclasses import dataclass, field
-from typing import Any, Optional
+from typing import Optional
 
 from controlzero._internal.dlp_scanner import (
-    DLPMatch,
     DLPScanner,
     extract_text_from_args,
 )

{controlzero-1.5.4 → controlzero-1.5.5}/controlzero/_internal/types.py

@@ -1,6 +1,6 @@
 """Internal type definitions. Public users should import from controlzero, not here."""
 
-from typing import Any, Optional
+from typing import Any
 from pydantic import BaseModel, Field
 
 

{controlzero-1.5.4 → controlzero-1.5.5}/controlzero/audit_remote.py

@@ -24,13 +24,44 @@ import json
 import logging
 import platform
 import threading
-import time
 import uuid
 from datetime import datetime, timezone
+from pathlib import Path
 from typing import Optional
 
 from controlzero.device import detect_client_name, detect_client_version
 
+# #495/v1 (2026-05-14): the normalized controlzero_sdk_version field
+# carried on every audit POST. Format is "<lang>@<version>" so the
+# backend can group/filter across SDKs without ambiguity (a version
+# string alone like "1.9.1" is shared between Python and Node).
+# Capped at 64 chars so a freak __version__ value cannot pollute the
+# LowCardinality column on the backend.
+#
+# Read via importlib.metadata rather than `from controlzero import
+# __version__`: audit_remote.py is imported transitively from
+# controlzero.client.Client, which is imported at the top of
+# controlzero/__init__.py before __version__ is defined. The naive
+# import triggers a circular-import ImportError on package load.
+# importlib.metadata reads from the installed dist-info and avoids
+# the partial-module problem entirely.
+def _resolve_sdk_version_wire() -> str:
+    try:
+        from importlib.metadata import version as _pkg_version
+        v = _pkg_version("controlzero")
+    except Exception:
+        # Editable install where the dist-info isn't on the metadata
+        # path, or any other import-time failure: fall back to empty
+        # so the audit pipeline doesn't carry a wrong value.
+        return ""
+    wire = "python@" + v
+    if len(wire) > 64:
+        return ""
+    return wire
+
+
+_CZ_SDK_VERSION_WIRE = _resolve_sdk_version_wire()
+
 logger = logging.getLogger("controlzero.audit_remote")
 
 # Buffer limits
@@ -48,7 +79,7 @@ class RemoteAuditSink:
         machine_token: str,  # not used for auth header, kept for future
         org_id: str,
         machine_id: str,
-        state_dir: Optional["Path"] = None,
+        state_dir: Optional[Path] = None,
     ):
         self._api_url = api_url.rstrip("/")
         self._machine_token = machine_token
@@ -132,6 +163,10 @@ class RemoteAuditSink:
             # coding-agent hook-check calls; SDK library integrations
             # pass an empty string until they adopt the same extractor.
             "extracted_method": entry.get("extracted_method", ""),
+            # v1 (2026-05-14): normalized controlzero SDK package version
+            # so support can pinpoint which SDK release made this POST.
+            # See top of file for the wire-format invariant.
+            "controlzero_sdk_version": _CZ_SDK_VERSION_WIRE,
         }
 
     # ---- flush mechanics ----
@@ -312,6 +347,10 @@ class BearerAuditSink:
             # coding-agent hook-check calls; SDK library integrations
             # pass an empty string until they adopt the same extractor.
             "extracted_method": entry.get("extracted_method", ""),
+            # v1 (2026-05-14): same controlzero SDK version wire field
+            # as the BearerAuditSink path above. Kept in lockstep so
+            # both sinks produce identical row shapes on the backend.
+            "controlzero_sdk_version": _CZ_SDK_VERSION_WIRE,
         }
 
     def _flush_async(self) -> None:

controlzero-1.5.5/controlzero/cli/_secrets.py

@@ -0,0 +1,135 @@
+"""API key redaction + leak-detection helpers (Tier 0a hotfix 2026-05-15).
+
+Single source of truth for:
+
+1. Detecting `cz_(live|test)_*` patterns in arbitrary text (used by
+   `controlzero doctor` to scan agent settings files + the cross-SDK
+   contract test that fails the CI on any leak surface).
+2. Redacting a full key to a last-4 form for display in CLI output
+   (`cz_live_***f7d7b22`). Matches the gh CLI / Stripe CLI convention.
+
+These helpers MUST stay pure (no I/O, no logging) so the contract test
+that depends on `find_key_leaks` can run in a sandbox without touching
+the user's actual filesystem.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, List, NamedTuple
+
+# A controlzero API key is 8-char prefix (cz_live_ / cz_test_) + 64 hex
+# characters in production. We also accept shorter trailing alphanumerics
+# so legacy short-form test keys (cz_test_localdev_...) are caught.
+# The pattern is deliberately greedy on the suffix so we catch:
+#   cz_live_d003253c33902c264d5a20146a3efc15475de1d1fe9e1efb0ccace0d7f7d7b22
+#   cz_test_localdev_000000000000000000000000
+#   cz_test_xxxxxxxx (rarer, but valid)
+# but stops at a non-alphanumeric so we don't gobble surrounding markup.
+_KEY_PATTERN = re.compile(r"cz_(live|test)_[A-Za-z0-9_]{4,}")
+
+
+class KeyMatch(NamedTuple):
+    """One match from `find_key_leaks`. The `key` field is the FULL
+    matched substring; callers that surface this in customer output
+    must run it through `redact_key` first."""
+
+    start: int
+    end: int
+    key: str
+    line_number: int
+
+
+def find_key_leaks(text: str) -> List[KeyMatch]:
+    """Return every `cz_(live|test)_*` substring in `text`.
+
+    Used by:
+    - `controlzero doctor` to scan ~/.claude/settings.json etc.
+    - The cross-SDK contract test to fail the PR on any leak.
+    - `controlzero migrate` to identify which entries to rewrite.
+
+    Pure function. No I/O. Deterministic. Safe to call on arbitrary
+    untrusted input (no regex catastrophic backtracking; pattern is
+    linear).
+    """
+    matches: List[KeyMatch] = []
+    if not text:
+        return matches
+    for m in _KEY_PATTERN.finditer(text):
+        # Compute the 1-indexed line number so doctor output reads
+        # like a compiler error: `foo.json:42:5`. Counts newlines
+        # from start of text to the match start.
+        line_number = text.count("\n", 0, m.start()) + 1
+        matches.append(
+            KeyMatch(
+                start=m.start(),
+                end=m.end(),
+                key=m.group(0),
+                line_number=line_number,
+            )
+        )
+    return matches
+
+
+def redact_key(key: str) -> str:
+    """Convert `cz_live_d003253c33902c264d5a20146a3efc15475de1d1fe9e1efb0ccace0d7f7d7b22`
+    to `cz_live_***d7b22` (last-5 of the secret payload).
+
+    The prefix (`cz_live_` / `cz_test_`) is preserved so the mode is
+    still readable: ops can tell at a glance which key family this
+    is. The last 5 hex chars are kept so two different keys are
+    distinguishable in support tickets without exposing enough to
+    reconstruct the key (5 hex chars = 20 bits = 1M combinations,
+    not enough to brute-force back to the full key but enough for a
+    human to disambiguate "is this Bryan's key or John's key").
+
+    Returns the input verbatim if it doesn't match the expected shape,
+    so caller-side `print(redact_key(maybe_key))` is always safe.
+    """
+    stripped = key.strip()
+    m = _KEY_PATTERN.fullmatch(stripped)
+    if not m:
+        return key
+    mode = m.group(1)  # 'live' or 'test'
+    last5 = stripped[-5:] if len(stripped) >= 5 else stripped
+    return f"cz_{mode}_***{last5}"
+
+
+def redact_text(text: str) -> str:
+    """Apply `redact_key` to every `cz_(live|test)_*` match inside an
+    arbitrary string.
+
+    Used to scrub log lines, error messages, and stderr before the SDK
+    prints them. Cheaper than wiring per-call-site escapes; safer too
+    because the redaction is centralized.
+    """
+
+    def _replace(m: re.Match[str]) -> str:
+        return redact_key(m.group(0))
+
+    return _KEY_PATTERN.sub(_replace, text)
+
+
+# Convenience: scan a list of file paths, return a flat list of
+# (path, KeyMatch) pairs for everything found. doctor + migrate both
+# consume this.
+def scan_files(paths: Iterable[str]) -> List[tuple[str, KeyMatch]]:
+    """Open each path, scan for key leaks, return matches with file
+    path attached. Missing files / unreadable files are silently
+    skipped -- the caller (doctor) handles "did we find the agent
+    config at all" via a separate codepath.
+    """
+    import pathlib
+
+    out: List[tuple[str, KeyMatch]] = []
+    for p in paths:
+        path = pathlib.Path(p).expanduser()
+        if not path.exists():
+            continue
+        try:
+            content = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for match in find_key_leaks(content):
+            out.append((str(path), match))
+    return out

controlzero-1.5.5/controlzero/cli/console.py

@@ -0,0 +1,125 @@
+"""Centralized Rich console for the controlzero CLI.
+
+Tier 0a hotfix piece 6 (#174 / DESIGN.md): every user-facing CLI
+output goes through this singleton so colors, padding, and spinner
+styles stay consistent across `controlzero doctor`, `controlzero
+migrate`, `controlzero install`, and the install-time consent prompt.
+
+Color palette pulled straight from DESIGN.md:
+
+- accent:   #22c55e  sage green (logo, active states, success)
+- success:  #22c55e  same as accent (allowed, healthy)
+- warning:  #eab308  yellow (approaching limits, soft errors)
+- error:    #ef4444  red (blocked, critical)
+- text-1:   #f0f0f3  primary (headings, values)
+- text-2:   #8b8b96  secondary (descriptions)
+- text-3:   #7a7a86  tertiary (labels)
+- border:   rgba(255,255,255,0.06)  (rendered as dim grey in terminal)
+
+Use the module-level helpers (`success`, `warn`, `error`, `info`,
+`panel`) rather than constructing rich objects in each command. This
+makes the CLI testable: tests can mock the singleton and assert on
+the rendered strings.
+
+If the user has NO_COLOR set, rich's automatic detection kicks in
+and we render plain text -- nothing to do here.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.style import Style
+from rich.text import Text
+from rich.theme import Theme
+
+
+# DESIGN.md color tokens. Names mirror the CSS custom property names
+# so a designer can grep across the repo and find every place a token
+# is consumed.
+_CZ_THEME = Theme({
+    "cz.accent": Style(color="#22c55e", bold=False),
+    "cz.success": Style(color="#22c55e", bold=True),
+    "cz.warning": Style(color="#eab308", bold=True),
+    "cz.error": Style(color="#ef4444", bold=True),
+    "cz.text1": Style(color="#f0f0f3"),
+    "cz.text2": Style(color="#8b8b96"),
+    "cz.text3": Style(color="#7a7a86"),
+    "cz.text4": Style(color="#5a5a65", dim=True),
+    "cz.code": Style(color="#f0f0f3", bgcolor="#222225"),
+    # Compound helpers used by panels.
+    "cz.heading": Style(color="#f0f0f3", bold=True),
+    "cz.dim_border": Style(color="#5a5a65", dim=True),
+})
+
+
+# Two consoles so callers can route errors to stderr without
+# leaking color escape codes into a redirected stdout.
+_stdout = Console(theme=_CZ_THEME, highlight=False)
+_stderr = Console(theme=_CZ_THEME, highlight=False, stderr=True)
+
+
+def stdout() -> Console:
+    """The shared stdout-bound console. Use this for normal CLI
+    output. Tests can monkeypatch this to capture rendered output."""
+    return _stdout
+
+
+def stderr() -> Console:
+    """The shared stderr-bound console. Use this for warnings + errors."""
+    return _stderr
+
+
+# -----------------------------------------------------------------------------
+# Helpers -- the public surface. Every CLI command should use these
+# rather than touching the underlying console.
+# -----------------------------------------------------------------------------
+
+
+def success(message: str) -> None:
+    """Bold sage-green check mark + message. Used for happy-path
+    completion lines like 'Installed claude-code hook'.
+    """
+    _stdout.print(Text.assemble(("[OK] ", "cz.success"), (message, "cz.text1")))
+
+
+def warn(message: str) -> None:
+    """Yellow warning. Used for soft errors that don't block the
+    operation but the user should know about (e.g. 'shell history
+    contains a key')."""
+    _stderr.print(Text.assemble(("[WARN] ", "cz.warning"), (message, "cz.text1")))
+
+
+def error(message: str, code: Optional[str] = None) -> None:
+    """Red error. If a stable E#### code is supplied, prepend it so
+    the user can search the docs site for the canonical fix."""
+    prefix = f"[ERROR {code}] " if code else "[ERROR] "
+    _stderr.print(Text.assemble((prefix, "cz.error"), (message, "cz.text1")))
+
+
+def info(message: str) -> None:
+    """Plain informational line, no color. Used for hints + status
+    lines that aren't the headline output."""
+    _stdout.print(Text(message, style="cz.text2"))
+
+
+def heading(message: str) -> None:
+    """Section heading. Bold, primary text color."""
+    _stdout.print(Text(message, style="cz.heading"))
+
+
+def code(snippet: str) -> Text:
+    """Render a short code snippet (filename, command, key) with the
+    code style. Returns a Text so callers can compose it into a
+    larger renderable."""
+    return Text(snippet, style="cz.code")
+
+
+def panel(content: str, title: str = "", style: str = "cz.dim_border") -> None:
+    """Outlined box with optional title. Used for the consent prompt
+    + the post-install confirmation summary so they don't drown in
+    other terminal output."""
+    p = Panel.fit(content, title=title or None, border_style=style)
+    _stdout.print(p)