controlzero 1.4.3__tar.gz → 1.4.6__tar.gz

{controlzero-1.4.3 → controlzero-1.4.6}/.gitignore

@@ -194,7 +194,6 @@ SUMMARY_OFFENSIVE_*.md
 docs/deployment/
 docs/SSH_RECOVERY_GUIDE.md
 docs/HETZNER_OS_INSTALLATION.md
-docs/BACKUP_RECOVERY.md
 docs/VERCEL_SETUP_WEBAPPS.md
 scripts/fix-ssh-config.sh
 scripts/hetzner-post-install.sh
@@ -237,3 +236,6 @@ cz-revamp-live.png
 secrets/*.plain
 secrets/*.dec
 .claude/scheduled_tasks.lock
+
+# Local documentation, patent assets, and legal research (sensitive, never commit)
+doc_local/

controlzero-1.4.6/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## 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).
+
+### 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.3 → controlzero-1.4.6}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.4.3
+Version: 1.4.6
 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
 Project-URL: Repository, https://github.com/controlzero/controlzero
 Project-URL: Examples, https://docs.controlzero.ai/sdk/integrations
-Author-email: Control Zero <hello@controlzero.ai>
+Author-email: Control Zero <team@controlzero.ai>
 License: Apache-2.0
 License-File: LICENSE
 Keywords: agents,ai,audit,governance,guardrails,llm,mcp,policy
@@ -82,7 +82,7 @@ print(cz.guard("read_file",   {"path": "/tmp/foo"}).decision)  # "allow"
 ## Install
 
 ```bash
-pip install control-zero
+pip install controlzero
 ```
 
 ## Why
@@ -254,6 +254,18 @@ cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
 # RuntimeError: manual policy override detected ...
 ```
 
+## Coding agent hooks
+
+`controlzero hook-check` runs inside Claude Code, Gemini CLI, and Codex CLI
+on every tool use and evaluates the call against your policy before it fires.
+It extracts a canonical `tool:method` from the tool arguments so rules can
+target `database:SELECT` vs `database:DROP`, or allow `Bash:git` while denying
+`Bash:rm`. Multi-statement SQL and compound shell commands are resolved to the
+most dangerous token, so a `SELECT ... ; DROP TABLE users;` payload matches
+`database:DROP`, not `database:SELECT`. See
+[Hook action extraction](https://docs.controlzero.ai/concepts/hook-extractor)
+for the full extraction rules, security model, and per-tool examples.
+
 ## Framework examples
 
 Full integration guides at [docs.controlzero.ai/sdk/integrations](https://docs.controlzero.ai/sdk/integrations):

{controlzero-1.4.3 → controlzero-1.4.6}/README.md

@@ -30,7 +30,7 @@ print(cz.guard("read_file",   {"path": "/tmp/foo"}).decision)  # "allow"
 ## Install
 
 ```bash
-pip install control-zero
+pip install controlzero
 ```
 
 ## Why
@@ -202,6 +202,18 @@ cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
 # RuntimeError: manual policy override detected ...
 ```
 
+## Coding agent hooks
+
+`controlzero hook-check` runs inside Claude Code, Gemini CLI, and Codex CLI
+on every tool use and evaluates the call against your policy before it fires.
+It extracts a canonical `tool:method` from the tool arguments so rules can
+target `database:SELECT` vs `database:DROP`, or allow `Bash:git` while denying
+`Bash:rm`. Multi-statement SQL and compound shell commands are resolved to the
+most dangerous token, so a `SELECT ... ; DROP TABLE users;` payload matches
+`database:DROP`, not `database:SELECT`. See
+[Hook action extraction](https://docs.controlzero.ai/concepts/hook-extractor)
+for the full extraction rules, security model, and per-tool examples.
+
 ## Framework examples
 
 Full integration guides at [docs.controlzero.ai/sdk/integrations](https://docs.controlzero.ai/sdk/integrations):

{controlzero-1.4.3 → controlzero-1.4.6}/controlzero/__init__.py

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

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

@@ -349,7 +349,7 @@ def _zstd_decompress(data: bytes) -> bytes:
 
     raise BundleVerificationError(
         "zstd decompression library not installed; "
-        "install with: pip install 'controlzero[hosted]' or pip install zstandard"
+        "install with: pip install -U controlzero (or pip install zstandard)"
     )
 
 
@@ -369,7 +369,41 @@ def translate_to_local_policy(payload: dict) -> dict:
 
     Policies are sorted by ``priority`` ascending so SDKs in every
     language produce identical decisions from identical input.
+
+    Schema 1.1 (#228 Phase 2) adds three top-level enforcement-default
+    knobs -- ``default_action``, ``default_on_missing``, and
+    ``default_on_tamper`` -- that the translator surfaces into the
+    local policy dict's ``settings`` block so downstream
+    :func:`controlzero.policy_loader.load_policy` can pick them up
+    unchanged. Missing or unknown values fall back to the canonical
+    deny/deny/warn (matches pre-1.1 hard-coded behaviour, so old
+    bundles keep working).
     """
+    # Lazy import to avoid a cycle: enforcer imports from this file
+    # via policy_loader via client. Importing at call time breaks the
+    # cycle cleanly while still letting translate_to_local_policy own
+    # the canonical-default fallback (one source of truth).
+    from controlzero._internal.enforcer import (
+        DEFAULT_BUNDLE_ACTION,
+        DEFAULT_BUNDLE_ON_MISSING,
+        DEFAULT_BUNDLE_ON_TAMPER,
+        VALID_DEFAULT_ACTIONS,
+        VALID_DEFAULT_ON_MISSING,
+        VALID_DEFAULT_ON_TAMPER,
+    )
+
+    default_action = payload.get("default_action")
+    if default_action not in VALID_DEFAULT_ACTIONS:
+        default_action = DEFAULT_BUNDLE_ACTION
+
+    default_on_missing = payload.get("default_on_missing")
+    if default_on_missing not in VALID_DEFAULT_ON_MISSING:
+        default_on_missing = DEFAULT_BUNDLE_ON_MISSING
+
+    default_on_tamper = payload.get("default_on_tamper")
+    if default_on_tamper not in VALID_DEFAULT_ON_TAMPER:
+        default_on_tamper = DEFAULT_BUNDLE_ON_TAMPER
+
     policies = payload.get("policies") or []
     policies = sorted(
         [p for p in policies if isinstance(p, dict)],
@@ -394,47 +428,184 @@ def translate_to_local_policy(payload: dict) -> dict:
                 flat.append(translated)
 
     if not flat:
-        # Empty policy set: default deny-all. An empty hosted project is
-        # not "everything allowed" -- it's "nothing configured yet."
+        # Empty policy set: synthetic catchall rule. The effect
+        # mirrors the bundle-level default_action so "empty bundle"
+        # continues to deliver the operator's chosen posture. Prior
+        # to #228 Phase 2 this was hard-coded to deny; now an org
+        # that ships an empty-bundle-with-default=allow gets the
+        # expected allow (with the same NO_ACTIVE_POLICIES
+        # reason_code so dashboards still bucket it as "nothing
+        # attached").
+        #
+        # Copy-choice note (2026-04-19, Bryan's P0): the previous
+        # message -- "No active policies. Define one in the Control Zero
+        # dashboard." -- presumed the user had not defined any policies.
+        # That presumption was wrong in the common case: the user had
+        # defined several, but the library-attachments state on the
+        # backend did not include any active attachment row, so the
+        # bundle arrived with zero policies while the dashboard Library
+        # tab still showed them. The new wording removes the
+        # presumption and points at the actual recovery action.
         flat.append({
-            "effect": "deny",
+            "effect": default_action,
             "action": "*",
             "reason": (
-                "No active policies. Define one in the Control Zero dashboard."
+                "No policies are active on this project. If the dashboard "
+                "shows attached policies, regenerate the policy bundle."
             ),
+            "reason_code": "NO_ACTIVE_POLICIES",
         })
 
-    return {"version": "1", "rules": flat}
+    return {
+        "version": "1",
+        "rules": flat,
+        "settings": {
+            "default_action": default_action,
+            "default_on_missing": default_on_missing,
+            "default_on_tamper": default_on_tamper,
+        },
+    }
+
+
+def make_bundle_missing_policy(
+    default_on_missing: Optional[str] = None,
+) -> dict:
+    """Build the synthetic local-policy dict used when the bundle cannot load.
+
+    Returned shape matches what :func:`translate_to_local_policy`
+    produces, so downstream :func:`controlzero.policy_loader.load_policy`
+    accepts it unchanged.
+
+    Args:
+        default_on_missing: Effect to apply -- ``"deny"`` or ``"allow"``.
+            ``None`` or an unknown value coerces to the canonical deny
+            default, matching the pre-#228 hard-coded behaviour.
+
+    The single catchall rule carries ``reason_code=BUNDLE_MISSING`` so
+    audit pipelines can distinguish "no bundle at all" (this path) from
+    "bundle loaded but empty" (``NO_ACTIVE_POLICIES``) and from
+    "rule set evaluated, nothing matched" (``NO_RULE_MATCH``).
+    """
+    from controlzero._internal.enforcer import (
+        DEFAULT_BUNDLE_ACTION,
+        DEFAULT_BUNDLE_ON_MISSING,
+        DEFAULT_BUNDLE_ON_TAMPER,
+        VALID_DEFAULT_ON_MISSING,
+    )
+
+    effect = default_on_missing if default_on_missing in VALID_DEFAULT_ON_MISSING else DEFAULT_BUNDLE_ON_MISSING
+    reason = (
+        "Policy bundle could not be loaded (never synced, backend "
+        "unreachable, or decrypt failed). "
+        f"Honoring default_on_missing={effect}."
+    )
+    return {
+        "version": "1",
+        "rules": [
+            {
+                "effect": effect,
+                "action": "*",
+                "reason": reason,
+                "reason_code": "BUNDLE_MISSING",
+            }
+        ],
+        "settings": {
+            # Stamp the resolved default triple onto the synthetic
+            # policy so downstream code that reads settings sees
+            # consistent values. default_action mirrors the missing
+            # effect so no-match behaviour is predictable.
+            "default_action": effect if effect in {"deny", "allow"} else DEFAULT_BUNDLE_ACTION,
+            "default_on_missing": effect,
+            "default_on_tamper": DEFAULT_BUNDLE_ON_TAMPER,
+        },
+    }
 
 
 def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
-    """Translate a single backend rule to the local rule shape."""
-    effect = rule.get("effect") or rule.get("action") or "allow"
-    if effect not in ("allow", "deny", "warn", "audit"):
-        effect = "allow"
-
-    # Find the tool pattern. The backend may put it under several keys
-    # depending on the policy form (LLM, tool-call, etc.).
-    pattern = rule.get("tool")
-    if not pattern:
-        pattern = rule.get("pattern")
-    if not pattern:
+    """Translate a single backend rule to the local rule shape.
+
+    The backend (:file:`bundle_handler.go` ``PolicyRule``) emits rules
+    whose tool pattern lives under plural ``actions: [...]``. This
+    function used to ignore that key entirely and fell back to ``"*"``
+    for every such rule, causing e.g. a ``deny database:execute`` rule
+    to silently become ``deny *`` after round-tripping through the
+    bundle. Both the plural (backend wire-format) and the legacy
+    singular (``tool`` / ``pattern`` / ``action`` / ``match.tool``) forms
+    are now supported; plural wins when both are present.
+    """
+    # Accept several spellings of "effect". Policy engine has four
+    # canonical effects; anything else is treated as ``allow`` to stay
+    # fail-safe on forward-compat.
+    effect_raw = rule.get("effect")
+    if not effect_raw:
+        # Only fall back to rule["action"] for effect if it looks like
+        # one of the canonical effects. Otherwise "action" is a tool
+        # name and we should not use it here.
+        fallback = rule.get("action")
+        if fallback in ("allow", "deny", "warn", "audit"):
+            effect_raw = fallback
+    effect = effect_raw if effect_raw in ("allow", "deny", "warn", "audit") else "allow"
+
+    # Tool pattern resolution order:
+    #   1. plural ``actions`` (list, as emitted by the backend)
+    #   2. legacy singular ``tool`` / ``pattern``
+    #   3. legacy singular ``action`` (only if it is NOT an effect keyword)
+    #   4. nested ``match.tool`` / ``match.action``
+    #   5. default ``"*"`` (universal)
+    patterns: list[str] = []
+    raw_actions = rule.get("actions")
+    if isinstance(raw_actions, list):
+        patterns = [str(a) for a in raw_actions if isinstance(a, str) and a]
+
+    if not patterns:
+        candidate = rule.get("tool") or rule.get("pattern")
+        if candidate:
+            patterns = [str(candidate)]
+
+    if not patterns:
+        # Legacy singular "action" field -- only a tool pattern when
+        # it is NOT a canonical effect name (effect already captured
+        # above).
+        candidate = rule.get("action")
+        if candidate and candidate not in ("allow", "deny", "warn", "audit"):
+            patterns = [str(candidate)]
+
+    if not patterns:
         match = rule.get("match")
         if isinstance(match, dict):
-            pattern = match.get("tool") or match.get("action")
-    if not pattern:
+            candidate = match.get("tool") or match.get("action")
+            if candidate:
+                patterns = [str(candidate)]
+
+    if not patterns:
         # Final fallback: universal match. Combined with a non-allow
         # effect, this is still meaningful (e.g. deny-all).
-        pattern = "*"
+        patterns = ["*"]
 
     translated: dict = {
         "effect": effect,
-        "action": pattern,
+        # Emit plural ``actions`` so downstream
+        # :func:`controlzero.policy_loader.load_policy` can pass the
+        # full list through to :class:`PolicyRule.actions` unchanged.
+        # The loader accepts either ``action`` or ``actions``.
+        "actions": patterns if len(patterns) > 1 else patterns,
         "reason": rule.get("reason") or f"policy:{policy_id}",
     }
+    # Keep the singular ``action`` alias for single-pattern rules so
+    # older consumers that read the translated dict (tests, docs) still
+    # see a scalar. The loader prefers ``action`` when scalar.
+    if len(patterns) == 1:
+        translated["action"] = patterns[0]
 
     resources = rule.get("resources") or rule.get("resource")
     if resources:
         translated["resources"] = resources
 
+    # Propagate the machine-readable reason_code when the source rule
+    # carries one. Today only the synthetic empty-bundle deny (above)
+    # sets this; user-authored rules are unaffected.
+    rc = rule.get("reason_code")
+    if isinstance(rc, str) and rc:
+        translated["reason_code"] = rc
+
     return translated