controlzero 1.4.6__tar.gz → 1.4.7__tar.gz

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

@@ -1,5 +1,94 @@
 # Changelog
 
+## 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
+  shipping the bundle back to engineering or attaching a debugger
+  (Bryan's deny-deny took ~3 hours to root-cause for exactly this
+  reason). The new subcommand reads the matching `bootstrap-<prefix>.json`
+  for keys, decrypts and verifies the cached bundle blob via the same
+  parser the SDK uses, and prints a human-readable summary: bundle id,
+  created_at / expires_at, default_action / default_on_missing /
+  default_on_tamper, every policy (id, name, version, is_enabled,
+  priority), and every rule (id, effect, principals, actions, resources,
+  conditions).
+
+  With `--simulate "tool method args"` it also runs the request through
+  the same `PolicyEvaluator` the SDK uses and prints the decision plus
+  which rule matched and why. The args grammar accepts either a JSON
+  object or whitespace-separated `key=value` pairs (values may contain
+  spaces, so `sql=SELECT id FROM orders` parses as a single value).
+
+  The output is designed to be pasted into a support thread: the
+  encryption key, signing public key, and API key are NEVER printed,
+  enforced by a final `_redact_sensitive` pass before emit.
+
+  Six tests in `tests/test_cli_debug_bundle.py` cover the happy path,
+  simulate-allow, simulate-no-rule-match, missing bootstrap, missing
+  bundle, and the privacy contract.
+
+### Fixed
+
+- **Pre-#350 customer rules using legacy database action names keep
+  matching** (T84, GitHub #389). The SDK started emitting canonical
+  SQL semantic classes (`database:read`, `database:write`,
+  `database:admin`, `database:exec`) in 1.4.x via #345/#350. That
+  silently broke any policy authored before #350 that used legacy
+  per-keyword actions like `database:query`, `database:DROP`, or
+  `database:execute`: the legacy rule and the modern call no longer
+  shared a string, so the rule never fired and the call fell through
+  to the default deny.
+
+  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.
+
+  The alias table is byte-identical across Python, Node, and Go SDKs
+  and is locked by the cross-SDK fixture at
+  `tests/parity/action_aliases.json`. Drift in any SDK fails its
+  parity test.
+
+  This is a NO-BREAKING-CHANGES fix: every existing rule continues to
+  work, modern rules continue to work, and only previously-broken
+  legacy rules start matching again.
+
+- **Synthetic policy_id sentinels** (T79, Bryan deny-deny postmortem).
+  `PolicyDecision.policy_id` is now stamped with one of six canonical
+  `synthetic:*` values whenever the deny was emitted by a fail-closed
+  code path (no rule matched, empty bundle, missing bundle, T83-class
+  resource gate skip, machine quarantine, evaluator crash). Previously
+  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.
+  - `synthetic:BUNDLE_MISSING` -- enrolled but no bundle loadable.
+  - `synthetic:RESOURCE_GATE_SKIP` -- a rule's actions matched but its
+    `resources:` list excluded the call (T83-class signature).
+  - `synthetic:QUARANTINE` -- machine in local quarantine.
+  - `synthetic:ENGINE_UNAVAILABLE` -- evaluator crashed mid-evaluate.
+
+  The `reason_code` field is unchanged; the synthetic policy_id is a
+  parallel signal that the dashboard reads to switch chip styling and
+  link to the matching troubleshooting anchor. Backwards-compatible:
+  consumers that only branch on `reason_code` keep working.
+
+  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
@@ -39,6 +128,12 @@
   `database:admin` so deny rules catch them. 21 new parity-test
   fixtures (cross-SDK byte-identical with the Node sibling).
 
+  Legacy action names continue to work: `database:query`,
+  `database:execute`, and `database:delete` are still matched against
+  the same calls and remain valid in policy rules. New policies
+  should prefer the canonical class names; existing rules keyed on
+  the legacy names need no migration.
+
 ### Documentation
 
 - New customer-facing reference at `docs/sdk/policies/canonical-tools.md`

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.4.6
+Version: 1.4.7
 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.4.6 → controlzero-1.4.7}/controlzero/__init__.py

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

controlzero-1.4.7/controlzero/_internal/action_aliases.py

@@ -0,0 +1,165 @@
+"""Bidirectional alias table between legacy and canonical action names.
+
+T84 / GitHub #389. Mandate: NO BREAKING CHANGES.
+
+Pre-#350 customer rules used legacy database action names directly: a
+rule with ``actions: ["database:query"]`` or ``actions: ["database:DROP"]``
+matched a guard call where the SDK passed ``method="query"`` /
+``method="DROP"``. Starting with #345/#350 the SDK emits canonical SQL
+semantic classes instead (``database:read``, ``database:write``,
+``database:admin``, ``database:exec``).
+
+Without an alias shim, that change broke every pre-#350 rule on the
+day a customer upgraded the SDK. The alias table fixes this in both
+directions:
+
+- A pre-#350 rule with ``actions: ["database:query"]`` keeps matching a
+  modern SELECT call (which the SDK emits as ``database:read``)
+  because ``database:read`` is the canonical form of ``query``.
+- A modern rule with ``actions: ["database:read"]`` keeps matching a
+  legacy guard call where the host passed ``method="SELECT"`` because
+  ``SELECT`` is one of the read-class aliases.
+
+The enforcer's candidate_actions list is expanded via
+``expand_candidate_actions`` to include every alias of every
+candidate. Any rule whose actions list contains ANY alias of the
+caller's action will match.
+
+The alias table itself is the single source of truth across all three
+SDKs (Python / Node / Go). The cross-SDK fixture at
+``tests/parity/action_aliases.json`` is byte-identical to the JSON
+dump of this table; drift is caught by the parity test in each SDK.
+
+The legacy ``database:delete`` action is intentionally ambiguous:
+older policies used it for both row-level DELETE and table-level DROP.
+We map it to BOTH ``database:write`` AND ``database:admin`` so neither
+modern intent is silently broken.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Iterable
+
+# Tool covered by this alias table. Currently only "database" carries
+# the legacy <-> canonical split; other tools were added post-#350 and
+# always emitted canonical names from day one.
+TOOL = "database"
+
+# Canonical class -> ordered list of legacy aliases. Order matters for
+# the JSON dump that the parity fixture compares against.
+_CLASSES: dict[str, list[str]] = {
+    "read": ["query", "SELECT", "EXPLAIN", "SHOW", "DESCRIBE", "FETCH", "READ"],
+    "write": ["UPDATE", "INSERT", "DELETE", "MERGE", "UPSERT", "REPLACE"],
+    "admin": ["DROP", "CREATE", "TRUNCATE", "ALTER", "GRANT", "REVOKE", "RENAME"],
+    "exec": ["execute", "EXECUTE", "EXEC", "CALL", "do"],
+}
+
+# Legacy aliases that map to MORE THAN ONE canonical class. A rule
+# written against the legacy ambiguous name keeps firing on either
+# modern intent. The match direction (legacy -> canonical) is the
+# important one here; reverse (canonical -> legacy) is handled by the
+# class table above.
+_AMBIGUOUS: dict[str, list[str]] = {
+    "delete": ["write", "admin"],
+}
+
+
+def _canonical(method: str) -> str:
+    return f"{TOOL}:{method}"
+
+
+# Forward map: legacy alias method -> set of canonical actions.
+# Built once at import time so guard() stays cheap on the hot path.
+_LEGACY_TO_CANONICAL: dict[str, set[str]] = {}
+for cls, aliases in _CLASSES.items():
+    canon = _canonical(cls)
+    for alias in aliases:
+        _LEGACY_TO_CANONICAL.setdefault(alias, set()).add(canon)
+for alias, classes in _AMBIGUOUS.items():
+    _LEGACY_TO_CANONICAL.setdefault(alias, set()).update(_canonical(c) for c in classes)
+
+# Reverse map: canonical method -> set of legacy aliases (as full
+# tool:method actions).
+_CANONICAL_TO_LEGACY: dict[str, set[str]] = {}
+for cls, aliases in _CLASSES.items():
+    canon = _canonical(cls)
+    _CANONICAL_TO_LEGACY[canon] = {_canonical(a) for a in aliases}
+
+
+def expand_candidate_actions(actions: Iterable[str]) -> list[str]:
+    """Expand an iterable of candidate actions to include every known alias.
+
+    Both directions are expanded:
+
+    - Legacy ``database:query`` adds canonical ``database:read``.
+    - Canonical ``database:read`` adds every legacy alias
+      (``database:query``, ``database:SELECT``, ...).
+    - Ambiguous legacy ``database:delete`` adds BOTH ``database:write``
+      and ``database:admin``.
+
+    The original action is always preserved at the head of the list so
+    callers that read the first element (audit trail provenance) keep
+    seeing the un-expanded form.
+
+    Order is stable: original actions first (in input order), then
+    expansions in deterministic class+alias order.
+    """
+    seen: set[str] = set()
+    out: list[str] = []
+
+    for action in actions:
+        if action and action not in seen:
+            seen.add(action)
+            out.append(action)
+
+    # Second pass: walk every original action and append its aliases.
+    # Two-pass keeps the input order for the originals and gives a
+    # deterministic ordering for the expansions.
+    for action in list(out):
+        if not action or ":" not in action:
+            continue
+        tool, method = action.split(":", 1)
+        if tool != TOOL:
+            continue
+        # Legacy method -> canonical(s).
+        for canon in sorted(_LEGACY_TO_CANONICAL.get(method, ())):
+            if canon not in seen:
+                seen.add(canon)
+                out.append(canon)
+        # Canonical method -> legacy aliases.
+        for legacy in sorted(_CANONICAL_TO_LEGACY.get(action, ())):
+            if legacy not in seen:
+                seen.add(legacy)
+                out.append(legacy)
+
+    return out
+
+
+def alias_table_json() -> str:
+    """Return the alias table as a deterministic JSON string.
+
+    Used by the parity test in each SDK to confirm byte-identical
+    alias content across Python / Node / Go. The on-disk fixture at
+    ``tests/parity/action_aliases.json`` carries an extra ``comment``
+    key documenting the contract; this dump omits the comment so each
+    SDK's hash check can compare apples to apples.
+    """
+    payload = {
+        "version": 1,
+        "tool": TOOL,
+        "classes": {
+            cls: {
+                "canonical": _canonical(cls),
+                "aliases": list(aliases),
+            }
+            for cls, aliases in _CLASSES.items()
+        },
+        "ambiguous_aliases": {
+            alias: list(classes) for alias, classes in _AMBIGUOUS.items()
+        },
+    }
+    return json.dumps(payload, indent=2, sort_keys=False)
+
+
+__all__ = ["TOOL", "expand_candidate_actions", "alias_table_json"]

{controlzero-1.4.6 → controlzero-1.4.7}/controlzero/_internal/bundle.py

@@ -449,6 +449,12 @@ def translate_to_local_policy(payload: dict) -> dict:
         flat.append({
             "effect": default_action,
             "action": "*",
+            # T79: stamp a synthetic policy_id so the audit dashboard
+            # can render a recognizable chip + tooltip linking to the
+            # right troubleshooting anchor. The reason_code stays the
+            # same; the synthetic id is purely an audit-presentation
+            # contract (audit ingest stores it verbatim).
+            "id": "synthetic:NO_ACTIVE_POLICIES",
             "reason": (
                 "No policies are active on this project. If the dashboard "
                 "shows attached policies, regenerate the policy bundle."
@@ -505,6 +511,10 @@ def make_bundle_missing_policy(
             {
                 "effect": effect,
                 "action": "*",
+                # T79: stamp a synthetic policy_id so the audit
+                # dashboard can render a recognizable chip + link to
+                # the BUNDLE_MISSING troubleshooting anchor.
+                "id": "synthetic:BUNDLE_MISSING",
                 "reason": reason,
                 "reason_code": "BUNDLE_MISSING",
             }

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

@@ -71,6 +71,39 @@ VALID_REASON_CODES = frozenset({
     REASON_CODE_DLP_BLOCKED,
 })
 
+# Synthetic policy_id sentinels (T79 / Bryan deny-deny postmortem,
+# 2026-05-11). When a deny is emitted by anything OTHER than a
+# user-authored rule, the SDK stamps the audit row's `policy_id` with
+# one of these `synthetic:*` values so the audit dashboard can render
+# a recognizable chip and link it to the right troubleshooting
+# anchor. Without this, four very different bug classes (stale
+# bundle, missing resource gate, vocabulary mismatch, genuine
+# no-match) all looked identical in the Policy column (blank
+# placeholder + Decision=Deny + reason_code=NO_RULE_MATCH).
+#
+# The `synthetic:` prefix is a contract: the backend audit ingest
+# stores it verbatim (no validation on policy_id content), the
+# frontend matches on the prefix to switch chip styling, and the
+# values themselves mirror the reason_code enum 1:1 PLUS one new
+# value (RESOURCE_GATE_SKIP) that captures the T83-class bug where
+# every action-matching rule was skipped purely on the resource gate.
+SYNTHETIC_POLICY_ID_PREFIX = "synthetic:"
+SYNTHETIC_NO_RULE_MATCH = "synthetic:NO_RULE_MATCH"
+SYNTHETIC_NO_ACTIVE_POLICIES = "synthetic:NO_ACTIVE_POLICIES"
+SYNTHETIC_BUNDLE_MISSING = "synthetic:BUNDLE_MISSING"
+SYNTHETIC_RESOURCE_GATE_SKIP = "synthetic:RESOURCE_GATE_SKIP"
+SYNTHETIC_QUARANTINE = "synthetic:QUARANTINE"
+SYNTHETIC_ENGINE_UNAVAILABLE = "synthetic:ENGINE_UNAVAILABLE"
+
+VALID_SYNTHETIC_POLICY_IDS = frozenset({
+    SYNTHETIC_NO_RULE_MATCH,
+    SYNTHETIC_NO_ACTIVE_POLICIES,
+    SYNTHETIC_BUNDLE_MISSING,
+    SYNTHETIC_RESOURCE_GATE_SKIP,
+    SYNTHETIC_QUARANTINE,
+    SYNTHETIC_ENGINE_UNAVAILABLE,
+})
+
 # Canonical bundle-level default values. These must stay in lockstep
 # with the backend's `DefaultBundleAction` / `DefaultBundleOnMissing`
 # / `DefaultBundleOnTamper` constants (bundle_handler.go). They are
@@ -245,13 +278,31 @@ class PolicyEvaluator:
         if semantic_action and semantic_action != action:
             candidate_actions.append(semantic_action)
 
+        # T84: expand candidate_actions through the legacy <-> canonical
+        # alias table so pre-#350 customer rules using legacy database
+        # action names (database:query, database:DROP, database:execute,
+        # ...) keep matching modern SDK calls that emit canonical
+        # semantic classes (database:read|write|admin|exec), and vice
+        # versa. NO BREAKING CHANGES contract -- see #389.
+        from controlzero._internal.action_aliases import expand_candidate_actions
+        candidate_actions = expand_candidate_actions(candidate_actions)
+
         resource = ctx_dict.get("resource")
         evaluated = 0
+        # T79: track whether the no-match path was caused PURELY by the
+        # resource gate (every action-matching rule was skipped because
+        # the resource didn't match) so the synthetic deny can be
+        # tagged RESOURCE_GATE_SKIP rather than the more generic
+        # NO_RULE_MATCH. This is the T83-class signature -- a rule's
+        # actions matched the call but its `resources:` list excluded it.
+        action_matched_resource_skipped = False
+        action_matched_any = False
 
         for rule in self._rules:
             evaluated += 1
             if not any(_glob_any(rule.actions, a) for a in candidate_actions):
                 continue
+            action_matched_any = True
             if rule.resources:
                 # T83: a rule whose resources list contains "*" matches
                 # universally and must NOT require the caller to supply
@@ -265,6 +316,7 @@ class PolicyEvaluator:
                 # require a caller-supplied resource and glob-match it.
                 if "*" not in rule.resources:
                     if not resource or not _glob_any(rule.resources, resource):
+                        action_matched_resource_skipped = True
                         continue
             if not self._conditions_match(rule.conditions, context, args):
                 continue
@@ -306,8 +358,24 @@ class PolicyEvaluator:
             reason = "No matching policy rule (default_action=allow)"
         else:  # "warn"
             reason = "No matching policy rule (default_action=warn)"
+
+        # T79: distinguish the T83-class signature ("a rule's actions
+        # matched but its resources gate excluded the call") from the
+        # generic no-match. Both still apply default_action; the
+        # synthetic policy_id is what the audit dashboard reads to
+        # surface the right remediation.
+        if (
+            self._default_action == "deny"
+            and action_matched_any
+            and action_matched_resource_skipped
+        ):
+            synthetic_id = SYNTHETIC_RESOURCE_GATE_SKIP
+        else:
+            synthetic_id = SYNTHETIC_NO_RULE_MATCH
+
         return PolicyDecision(
             effect=self._default_action,
+            policy_id=synthetic_id,
             reason=reason,
             reason_code=REASON_CODE_NO_RULE_MATCH,
             evaluated_rules=evaluated,