controlzero 1.11.8__tar.gz → 1.12.0__tar.gz

{controlzero-1.11.8 → controlzero-1.12.0}/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 1.12.0 -- 2026-06-25 (per-agent key authority + per-agent bundle cache + whoami)
+
+### Added
+
+- **`controlzero whoami`.** Prints which API key the SDK will actually use for a
+  surface (per-agent / env / global), its prefix only (never the full key), and
+  the project + org it resolves to. Diagnoses the most common "my audit logs are
+  missing" cause: a `CONTROLZERO_API_KEY` exported in the shell that maps to a
+  different project than the integration you installed, so events land in the
+  wrong tenant and the dashboard shows nothing.
+- **Per-agent bundle cache.** Each governed surface now caches its policy bundle
+  under `~/.controlzero/integrations/<agent>/cache/` (next to the per-agent
+  `config.yaml`), so two surfaces on one machine each bound to their own project
+  no longer share a bundle. A read fallback keeps existing installs working on
+  upgrade: an empty per-agent cache transparently reads the legacy shared cache
+  until the first fetch re-caches it (no fail-closed on upgrade).
+
+### Changed
+
+- **Per-agent key is now AUTHORITATIVE in the enforcement hook.** Hook-check
+  precedence becomes per-agent (for the active surface) > env > global. A key
+  installed via `install <agent> --api-key` / `kiro init --api-key` now wins over
+  a stale ambient `CONTROLZERO_API_KEY`, with a loud one-line warning when they
+  differ. This closes the silent wrong-tenant bug where a hook spooled + uploaded
+  + ingested correctly but attributed the events to whatever key was exported in
+  the shell, so the dashboard for the installed project showed "no audit entries".
+  Non-hook resolution (`status`, install-time display) is unchanged
+  (env > per-agent > global).
+- **Cache bundle extension is now `.czpolicy`** (was `.bin`), matching the UI
+  policy export (both are the same signed bundle format). Legacy `.bin` caches
+  are still read and garbage-collected, so nothing breaks on upgrade.
+
+## 1.11.9 -- 2026-06-25 (policy-posture remediation: honest hosted/local CLI, per-agent keys, key-validity diagnostics)
+
+### Added
+
+- **Severity-level CLI output (`controlzero.cli.output`).** All CLI prose now
+  routes through one renderer with INFO / WARNING / SUCCESS / ERROR levels:
+  WARNING + ERROR go to stderr, INFO + SUCCESS to stdout, colour honours
+  `NO_COLOR` / `CONTROLZERO_NO_COLOR` / `TERM=dumb` / non-TTY. No emojis. The
+  hook decision path and wire payloads are untouched -- the renderer is never
+  used inside `hook_check`, so decision reasons emit verbatim.
+- **Per-integration (per-agent) API keys.** Each coding agent can bind its own
+  project key at `integrations/<agent>/config.yaml`. Resolution order is
+  `env (explicit) > per-agent (for that agent) > global`, fully back-compatible
+  (no per-agent key -> falls back to the global key). Per-agent dir `0700` /
+  file `0600`; the raw key is never echoed. This lets one machine run different
+  agents bound to different projects, each enforcing its own hosted bundle.
+- **`controlzero status` rewrite.** Shows resolved runtime truth (mode, config
+  source, key, enrolled, audit dest) plus a per-agent bindings table and
+  per-key backend validity (active / expired / revoked) so a rejected key is
+  diagnosable from the CLI instead of only via the coarse E1101 at first tool
+  call (#1472).
+
+### Changed
+
+- **Honest hosted/local posture messaging.** One canonical wording each for the
+  HOSTED and LOCAL install paths, routed through every installer. The HOSTED
+  banner states that the local `policy.yaml` is IGNORED while an API key is set,
+  and the unmatched-tool default (DENY fail-closed unless the project is set to
+  Allow by default) -- removing the "install said ALLOW ALL but runtime denied"
+  ambiguity.
+- **Archive-on-hosted.** When an API key is configured, the local `policy.yaml`
+  (and its `.sig`) is moved (not deleted) into `archive/policy-<UTC-ts>.yaml`,
+  symlink-safe, every error non-fatal -- a hosted machine never silently runs a
+  stale local policy.
+
+### Fixed
+
+- **`synthetic:UNATTRIBUTED_DENY`** added to the synthetic policy-id catalog so
+  an unattributed fail-closed deny renders a stable, documented policy id across
+  every surface instead of an opaque blank (#1472).
+- **Audit attribution.** SDK audit wire builders forward `project_id`
+  unconditionally so signed-sink audit events are attributed to the right
+  project (pairs with the backend ingest fix).
+
 ## 1.11.8 -- 2026-06-22 (DLP mask enforcement + I/O capture: enrolled-machine capture fix + server-side PII redaction)
 
 ### Added

{controlzero-1.11.8 → controlzero-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.11.8
+Version: 1.12.0
 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
@@ -185,6 +185,32 @@ rules:
 Rules are evaluated top to bottom. The first match wins. If no rule matches,
 the call is denied (fail-closed).
 
+## Localized block messages (`reason_localized`)
+
+The `reason` shown when a rule fires is plain UTF-8 text, so you can write it
+in any language. To serve more than one language from the same policy, add a
+`reason_localized` map and select a locale with the `CONTROLZERO_LOCALE`
+environment variable (e.g. `ko`, `ko-KR`):
+
+```yaml
+version: '1'
+rules:
+  - deny: 'delete_*'
+    reason: 'Deletes need human approval' # English default
+    reason_localized:
+      ko: '삭제는 사람의 승인이 필요합니다'
+  - allow: '*'
+```
+
+- When `CONTROLZERO_LOCALE` is unset (or set to a locale the rule has no entry
+  for), the plain `reason` is used -- existing behavior is unchanged.
+- The SDK's own built-in messages (no-rule-match, DLP block, empty/observe
+  bundle) ship an English default plus a Korean translation, selected the same
+  way. The packs are pure in-binary maps (no runtime i18n dependency), so this
+  is air-gap safe.
+- Localization is display-only: it never changes which rule matches or the
+  decided effect.
+
 ## Tamper detection and quarantine
 
 The policy YAML supports a `settings:` section that controls how the SDK

{controlzero-1.11.8 → controlzero-1.12.0}/README.md

@@ -131,6 +131,32 @@ rules:
 Rules are evaluated top to bottom. The first match wins. If no rule matches,
 the call is denied (fail-closed).
 
+## Localized block messages (`reason_localized`)
+
+The `reason` shown when a rule fires is plain UTF-8 text, so you can write it
+in any language. To serve more than one language from the same policy, add a
+`reason_localized` map and select a locale with the `CONTROLZERO_LOCALE`
+environment variable (e.g. `ko`, `ko-KR`):
+
+```yaml
+version: '1'
+rules:
+  - deny: 'delete_*'
+    reason: 'Deletes need human approval' # English default
+    reason_localized:
+      ko: '삭제는 사람의 승인이 필요합니다'
+  - allow: '*'
+```
+
+- When `CONTROLZERO_LOCALE` is unset (or set to a locale the rule has no entry
+  for), the plain `reason` is used -- existing behavior is unchanged.
+- The SDK's own built-in messages (no-rule-match, DLP block, empty/observe
+  bundle) ship an English default plus a Korean translation, selected the same
+  way. The packs are pure in-binary maps (no runtime i18n dependency), so this
+  is air-gap safe.
+- Localization is display-only: it never changes which rule matches or the
+  decided effect.
+
 ## Tamper detection and quarantine
 
 The policy YAML supports a `settings:` section that controls how the SDK

{controlzero-1.11.8 → controlzero-1.12.0}/controlzero/__init__.py

@@ -41,7 +41,7 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.11.8"
+__version__ = "1.12.0"
 
 __all__ = [
     "Client",

controlzero-1.12.0/controlzero/_internal/_messages.py

@@ -0,0 +1,273 @@
+"""In-binary localization pack for the SDK-GENERATED decision reasons.
+
+Why this exists ( checklist #25, gh#1439)
+--------------------------------------------------
+The user-facing ``reason`` string is carried end-to-end as UTF-8, so an
+operator can already localize ANY rule today by typing the target-language
+text into that rule's ``reason:`` -- or, for per-locale overrides, into the
+new ``reason_localized:`` map (a ``{locale: message}`` dict on the rule). That
+covers operator-authored rules. This module covers the OTHER half: the
+messages the SDK itself GENERATES for the no-rule-match / empty-bundle /
+missing-bundle / tampered / DLP paths. Those have no operator-authored text to
+carry, so they need an in-binary pack.
+
+No runtime i18n library is used: these are pure dict lookups, which keeps the
+SDK air-gap safe (the PoC ships self-hosted with no network).
+
+Contract
+--------
+- The ``en`` value is the single source of truth for the inline paths that now
+  read it (no-match, DLP, tamper, quarantine): it MUST stay byte-identical to
+  the legacy hard-coded string so existing consumers that regex-match the
+  ``reason`` text are unaffected. ``tests/test_localized_reason.py`` pins this.
+- English remains the literal DEFAULT whenever ``CONTROLZERO_LOCALE`` is unset
+  or a locale key is missing from a pack entry.
+- For the synthetic empty/missing-bundle rules the English text stays on the
+  rule's ``reason`` (unchanged bundle output); the pack supplies ONLY the
+  localized (non-en) override, looked up by the rule's ``reason_code``.
+
+KOREAN COPY IS A PROFESSIONAL DRAFT and MUST be reviewed/approved by the customer
+before being presented as final. See KO_Localization_2026-06-22 in the project
+vault. The English default is never blocked on that review.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+DEFAULT_LOCALE = "en"
+
+
+def resolve_locale(explicit: Optional[str] = None) -> str:
+    """Resolve the active locale.
+
+    Precedence: explicit arg > ``CONTROLZERO_LOCALE`` env > "" (English).
+    Returned lower-cased and stripped so lookups are case-insensitive.
+    """
+    if explicit:
+        return explicit.strip().lower()
+    return (os.environ.get("CONTROLZERO_LOCALE", "") or "").strip().lower()
+
+
+def _locale_candidates(locale: str) -> list[str]:
+    """Return lookup candidates for a locale, most specific first.
+
+    ``ko-KR`` / ``ko_KR`` -> ``["ko-kr", "ko"]`` so a pack keyed by the bare
+    primary subtag ("ko") still matches a region-qualified request.
+    """
+    loc = (locale or "").strip().lower()
+    if not loc:
+        return []
+    out = [loc]
+    for sep in ("-", "_"):
+        if sep in loc:
+            primary = loc.split(sep, 1)[0]
+            if primary and primary not in out:
+                out.append(primary)
+            break
+    return out
+
+
+# message key -> {locale -> template}. Templates use str.format placeholders
+# ({action}, {rule_name}, {category}). The English values for the inline paths
+# (NO_RULE_MATCH:*, DLP_BLOCKED:*, BUNDLE_TAMPERED, MACHINE_QUARANTINED) are
+# byte-identical to the legacy strings. For the synthetic-rule codes
+# (OBSERVE_MODE_NO_POLICY, NO_ACTIVE_POLICIES, BUNDLE_MISSING) the English is
+# documentation/parity only -- the live English comes from the rule's reason.
+SYSTEM_MESSAGES: dict[str, dict[str, str]] = {
+    # No-rule-match fallthrough (the most common block a Korean operator sees).
+    "NO_RULE_MATCH:deny": {
+        "en": (
+            "No matching policy rule for '{action}' (fail-closed default; "
+            "default_on_missing=deny). This tool is neither allowed nor "
+            "denied by any rule in your hosted policy, so it is blocked. "
+            "Add a rule that allows it (e.g. allow: '*' as a catch-all, or "
+            "allow: '{action}'), or set the project/org default to allow, "
+            "in the Control Zero dashboard."
+        ),
+        # ko: "'{action}'에 일치하는 정책 규칙이 없어 기본 차단됩니다 ..."
+        "ko": (
+            "'{action}'에 일치하는 정책 규칙이 없습니다(기본 차단; "
+            "default_on_missing=deny). 이 도구는 정책에서 허용되지도 "
+            "거부되지도 않았으므로 차단됩니다. Control Zero 대시보드에서 "
+            "이를 허용하는 규칙을 추가하거나(예: 포괄 규칙 allow: '*' 또는 "
+            "allow: '{action}'), 프로젝트/조직 기본값을 allow로 "
+            "설정하십시오."
+        ),
+    },
+    "NO_RULE_MATCH:allow": {
+        "en": "No matching policy rule for '{action}' (default_action=allow)",
+        # ko: "'{action}'에 일치하는 정책 규칙이 없습니다 (default_action=allow)"
+        "ko": "'{action}'에 일치하는 정책 규칙이 없습니다(default_action=allow)",
+    },
+    "NO_RULE_MATCH:warn": {
+        "en": "No matching policy rule for '{action}' (default_action=warn)",
+        # ko: "'{action}'에 일치하는 정책 규칙이 없습니다 (default_action=warn)"
+        "ko": "'{action}'에 일치하는 정책 규칙이 없습니다(default_action=warn)",
+    },
+    # DLP overrides (the tool-name policy allowed, but a DLP rule vetoed).
+    "DLP_BLOCKED:match": {
+        "en": (
+            "DLP rule '{rule_name}' matched {category} content in tool "
+            "arguments"
+        ),
+        # ko: "DLP 규칙 '{rule_name}'이(가) 도구 인자에서 {category} 콘텐츠와 ..."
+        "ko": (
+            "DLP 규칙 '{rule_name}'이(가) 도구 인자에서 {category} "
+            "콘텐츠와 일치하여 호출이 차단되었습니다."
+        ),
+    },
+    "DLP_BLOCKED:boundary": {
+        "en": (
+            "DLP rule '{rule_name}' matched {category} content that spans "
+            "argument boundaries and could not be safely masked; blocking "
+            "(fail-closed) rather than forwarding an un-redacted value"
+        ),
+        # ko: "DLP 규칙 '{rule_name}'이(가) 인자 경계에 걸친 {category} 콘텐츠와 ..."
+        "ko": (
+            "DLP 규칙 '{rule_name}'이(가) 인자 경계에 걸쳐 있는 "
+            "{category} 콘텐츠와 일치하여 안전하게 마스킹할 수 없으므로, "
+            "마스킹되지 않은 값을 전달하는 대신 차단합니다(기본 차단)."
+        ),
+    },
+    # Tamper / quarantine (constructed in client.py + cli/main.py).
+    "BUNDLE_TAMPERED": {
+        "en": (
+            "Policy tampering detected. Call blocked by tamper enforcement "
+            "policy."
+        ),
+        # ko: "정책 변조가 감지되었습니다. 변조 시행 정책에 의해 호출이 차단되었습니다."
+        "ko": (
+            "정책 변조가 감지되었습니다. 변조 시행 정책에 의해 호출이 "
+            "차단되었습니다."
+        ),
+    },
+    # CLI hook-check tamper enforcement (cli/main.py). Carries a {source}
+    # discriminator (policy_hmac / audit_chain) and the [Control Zero] prefix.
+    "BUNDLE_TAMPERED:cli": {
+        "en": (
+            "[Control Zero] Tamper detected ({source}). Blocked by enforcement "
+            "policy."
+        ),
+        # ko: "[Control Zero] 변조가 감지되었습니다({source}). 시행 정책에 의해 ..."
+        "ko": (
+            "[Control Zero] 변조가 감지되었습니다({source}). 시행 정책에 "
+            "의해 차단되었습니다."
+        ),
+    },
+    "MACHINE_QUARANTINED": {
+        "en": (
+            "Machine quarantined: policy tampering detected. All calls denied "
+            "until recovery."
+        ),
+        # ko: "머신이 격리되었습니다: 정책 변조가 감지되었습니다. 복구될 때까지 ..."
+        "ko": (
+            "머신이 격리되었습니다: 정책 변조가 감지되었습니다. 복구될 "
+            "때까지 모든 호출이 거부됩니다."
+        ),
+    },
+    # Synthetic empty / missing-bundle rules. English here is parity-only --
+    # the live English comes from the rule's `reason` (bundle output unchanged);
+    # the enforcer reads ONLY the localized (non-en) value below, by code.
+    "OBSERVE_MODE_NO_POLICY": {
+        "en": (
+            "OBSERVE MODE: no policies are active on this project, so "
+            "Control Zero is monitoring and auditing tool calls but "
+            "NOT enforcing -- every call is allowed and logged. Attach "
+            "a policy (or set the empty-project default to deny) in the "
+            "Control Zero dashboard to start enforcing."
+        ),
+        # ko: "관찰 모드: 이 프로젝트에 활성 정책이 없으므로 ... 차단하지 않습니다 ..."
+        "ko": (
+            "관찰 모드: 이 프로젝트에 활성 정책이 없으므로 Control Zero는 "
+            "도구 호출을 모니터링하고 감사 기록을 남기지만 차단하지는 "
+            "않습니다 -- 모든 호출이 허용되고 기록됩니다. 시행을 시작하려면 "
+            "Control Zero 대시보드에서 정책을 연결하거나(또는 빈 프로젝트 "
+            "기본값을 deny로 설정) 하십시오."
+        ),
+    },
+    "NO_ACTIVE_POLICIES": {
+        "en": (
+            "No policies are active on this project. If the dashboard "
+            "shows attached policies, regenerate the policy bundle."
+        ),
+        # ko: "이 프로젝트에 활성 정책이 없습니다. 대시보드에 연결된 정책이 표시되면 ..."
+        "ko": (
+            "이 프로젝트에 활성 정책이 없습니다. 대시보드에 연결된 정책이 "
+            "표시되면 정책 번들을 다시 생성하십시오."
+        ),
+    },
+    # BUNDLE_MISSING covers two English variants (degraded bundle vs. bundle
+    # not loaded), both reason_code=BUNDLE_MISSING. The localized override is a
+    # single accurate general message; the precise English stays on the rule.
+    "BUNDLE_MISSING": {
+        "en": (
+            "Policy bundle could not be loaded or produced zero enforceable "
+            "rules. Control Zero is failing CLOSED (deny) rather than allowing "
+            "every tool call. Regenerate the policy bundle in the Control Zero "
+            "dashboard; contact support if this persists."
+        ),
+        # ko: "정책 번들을 로드할 수 없거나 시행 가능한 규칙을 생성하지 못했습니다 ..."
+        "ko": (
+            "정책 번들을 로드할 수 없거나 시행 가능한 규칙을 생성하지 "
+            "못했습니다(미동기화, 백엔드 연결 불가, 복호화 실패 또는 손상/"
+            "부분/오래된 번들). Control Zero는 모든 호출을 허용하는 대신 "
+            "차단(기본 차단)합니다. Control Zero 대시보드에서 정책 번들을 "
+            "다시 생성하고, 문제가 지속되면 지원팀에 문의하십시오."
+        ),
+    },
+}
+
+
+def system_message(key: str, locale: Optional[str] = None, **fmt: object) -> Optional[str]:
+    """Return the fully-resolved system message for ``key``, English-default.
+
+    Resolution: ``pack[key][locale]`` (region subtag tolerated) falling back to
+    ``pack[key]["en"]``. Returns ``None`` only when ``key`` is unknown. Used by
+    the inline paths (no-match, DLP, tamper, quarantine) where the pack is the
+    source of the English text.
+    """
+    entry = SYSTEM_MESSAGES.get(key)
+    if not entry:
+        return None
+    template = None
+    for cand in _locale_candidates(resolve_locale(locale)):
+        if cand in entry:
+            template = entry[cand]
+            break
+    if template is None:
+        template = entry.get(DEFAULT_LOCALE)
+    if template is None:
+        return None
+    if fmt:
+        try:
+            return template.format(**fmt)
+        except (KeyError, IndexError):
+            return template
+    return template
+
+
+def localized_override(key: str, locale: Optional[str] = None, **fmt: object) -> Optional[str]:
+    """Return ONLY a non-English localized message for ``key``, else ``None``.
+
+    Unlike :func:`system_message` this never falls back to English. Used for
+    the synthetic empty/missing-bundle rules, whose English text stays on the
+    rule's ``reason`` (bundle output unchanged) -- the enforcer applies this
+    override only when an actual localized string exists for the active locale.
+    """
+    entry = SYSTEM_MESSAGES.get(key)
+    if not entry:
+        return None
+    for cand in _locale_candidates(resolve_locale(locale)):
+        if cand == DEFAULT_LOCALE:
+            continue
+        if cand in entry:
+            template = entry[cand]
+            if fmt:
+                try:
+                    return template.format(**fmt)
+                except (KeyError, IndexError):
+                    return template
+            return template
+    return None

{controlzero-1.11.8 → controlzero-1.12.0}/controlzero/_internal/bundle.py

@@ -943,4 +943,19 @@ def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
     if escalate is not None:
         translated["escalate_on_deny"] = bool(escalate)
 
+    # #25 (gh#1439): the SAME allowlist-strip trap (the gh#175 /
+    # #1303 family). A backend-signed bundle copies only an allowlist of
+    # rule fields into the local rule shape; without this line a hosted
+    # policy's `reason_localized` map is silently dropped and a Korean
+    # operator would see only the English fallback. Forward it intact.
+    # (The backend bundle wire struct must ALSO carry the field -- see
+    # bundle_handler.go PolicyRule -- or it never reaches this translator.)
+    reason_localized = rule.get("reason_localized")
+    if isinstance(reason_localized, dict) and reason_localized:
+        translated["reason_localized"] = {
+            str(k).strip().lower(): str(v)
+            for k, v in reason_localized.items()
+            if isinstance(k, str) and isinstance(v, str)
+        }
+
     return translated