controlzero 1.4.6__tar.gz → 1.5.0__tar.gz

controlzero-1.5.0/CHANGELOG.md

@@ -0,0 +1,226 @@
+# Changelog
+
+## 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
+  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
+
+- **resources:["*"] no longer requires a caller resource** (T83).
+  Hosted policy bundles emit `resources:["*"]` for any rule that does
+  not scope by resource. The enforcer's resource gate previously
+  required a caller-supplied `context.resource` even when the rule's
+  resources list was the universal wildcard, causing every rule to be
+  silently skipped on calls that didn't pass a resource. Result: every
+  `cz.guard()` returned `deny` with `reason_code=NO_RULE_MATCH` regardless
+  of what the policy said. Now rules with `*` in their resources match
+  universally; non-wildcard resource patterns still require a caller
+  resource (no silent broadening). Three regression tests added in
+  `tests/test_glob_matching.py` including the exact bundle shape from
+  the customer reproduction.
+
+## 1.4.5 -- 2026-05-05
+
+### Added
+
+- **Cross-CLI canonical tool coverage** (#341). The shared
+  `tool_extractors.json` is now spec_version 2 and adds three new
+  canonical tools (`web_search`, `file_search`, `task`) plus extended
+  aliases so PowerShell shell-command emission, Codex CLI's
+  `apply_patch`, Gemini CLI's `read_many_files`, and the WebFetch
+  family all resolve to the existing canonical tools. One rule
+  `action: Bash:rm` now covers Claude Code, Gemini CLI, Codex CLI,
+  and PowerShell on Windows.
+- **SQL semantic-class layer** (#345/#350). New `sql_semantic_class()`
+  helper emits a parallel `database:read|write|admin|exec` action
+  alongside the existing per-keyword `database:SELECT|DROP|...`
+  action. Write portable rules like `allow: database:read` that cover
+  SELECT, EXPLAIN, SHOW, DESCRIBE, and CTE in one rule, without
+  enumerating every keyword the dialect accepts. Multi-statement
+  piggybacks like `SELECT 1; DROP TABLE x` correctly resolve to
+  `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`
+  explaining canonical tool names, alias coverage per host CLI, and
+  the contract for adding new clients.
+- New SQL semantic class section in `canonical-tools.md` plus updated
+  quickstart and read-only-database recipe.
+
+## 1.4.4 -- 2026-04-19
+
+### Fixed
+
+- Hosted mode now refreshes the policy bundle periodically (default 60 seconds) so dashboard edits reach long-running clients without a process restart. New `Client(refresh_interval_seconds=...)` constructor arg controls cadence: pass `None` to disable, `0` to refresh on every `guard()` call (tests only). Added public `Client.refresh()` for on-demand reloads and `Client.last_refreshed_at` for ops visibility. Swap is protected by a lock so multi-threaded callers never observe torn state.
+- Bundle translator now reads plural `actions: [...]` rules from the hosted bundle. Previously every such rule collapsed to a universal `*` match, turning narrow denies like `deny database:execute` into deny-all.
+- Backend now stamps `api_keys.last_used_at` on the SDK pull endpoint on both fresh-bundle and 304 paths, so the dashboard can distinguish "SDK online with cached bundle" from "SDK has never connected". Best-effort write; stamp failures never block the response.
+
+## 1.4.1 -- 2026-04-15
+
+### Added
+
+- `agent_name` arg + `CZ_AGENT_NAME` env var contract on the `Client` constructor (issue #71). Order: explicit arg > env > `default-agent`.
+- `CZ_DEBUG=1` (or `true`/`yes`/`on`) flips the controlzero logger to DEBUG at construction. Cheap escape hatch for support.
+- Optional install extras: `controlzero[google]`, `controlzero[openai]`, `controlzero[anthropic]` (issue #68). Pin the matching upstream SDK so users do not see import errors.
+- Cross-SDK action canonicalization parity test (issue #69). Mirrors the same fixture in the Node and Go SDKs.
+- Smoke + denial + error-propagation tests for the `wrap_google` integration (issue #68).
+
+## 1.4.0 -- 2026-04-15
+
+### Breaking changes
+
+- Integration wrappers now emit simplified action names (`llm:generate`, `embedding:generate`, `tool:call`) instead of provider-prefixed ones (`llm:openai:chat.completions.create`). Policies targeting the old action names must be updated. Provider and model move into `context` tags. See docs/integrations for current patterns.
+- Google integration rewritten against `google-genai` (deprecated `google.generativeai` removed). Install `google-genai`.
+- `integrations.langchain.agent.GovernedAgent` wrapping `AgentExecutor` is deprecated in LangChain v1.x. Use `integrations.langchain.modern.create_governed_agent`.
+
+### New integrations
+
+- `integrations.autogen` - first-party helper for autogen-agentchat v0.7+
+- `integrations.pydantic_ai` - first-party helper for pydantic-ai v1.x
+- `integrations.langchain.modern` - LangGraph create_agent pattern
+
+### New features
+
+- Policy rule `conditions` field is now evaluated in the local enforcer. Conditions are matched against merged context + args with glob patterns. All keys must match.
+
+### Enhancements
+
+- `integrations.litellm` - async + success/failure hooks for streaming audit.

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

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

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

controlzero-1.5.0/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.5.0}/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.5.0}/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,40 @@ 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,
+# 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
@@ -245,13 +286,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 +324,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 +366,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,

{controlzero-1.4.6 → controlzero-1.5.0}/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"),