controlzero 1.13.12__tar.gz → 1.13.13__tar.gz

{controlzero-1.13.12 → controlzero-1.13.13}/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 ## Unreleased
 
+## 1.13.13 (2026-08-16): a read-class METHOD could satisfy an allow the SQL would deny
+
+**Security fix. If you use a `database:read` allow rule, read this.**
+
+Our own documented read-only-database recipe permitted `DROP TABLE`. Driven
+against the published 1.13.12 wheel, using that page's own policy and its own
+verification command:
+
+    controlzero test database --method query --policy policy.yaml \
+        --args '{"sql":"DROP TABLE users"}'   ->  ALLOW, policy_id=read-only-db
+
+    same policy, no --method                  ->  DENY
+
+The alias table maps `read -> [query, SELECT, ...]`. A caller-supplied
+`method="query"` is itself a read-class alias, so `database:read` was injected
+FROM THE METHOD and satisfied the allow before the SQL extractor's `admin`
+class was consulted. "Most dangerous class wins" is the documented semantics;
+it did not happen whenever a method was supplied -- which is the SDK call shape
+we document (`cz.guard("database", method="query", args={"sql": ...})`).
+
+**Not a regression.** The `query -> read` alias predates the recipe. It has
+never worked. All releases up to and including 1.13.12 are affected.
+
+**Fixed:** when a method-derived class and an argument-derived class are both
+present, the most dangerous now governs. Method-only calls keep legacy alias
+expansion; concrete SQL overrides a stale caller-supplied semantic context.
+Python and Node.
+
+**If you cannot upgrade yet,** put explicit denies ahead of the allow. Verified
+on the vulnerable 1.13.12 build: DROP / DELETE / TRUNCATE / GRANT and the
+`SELECT 1; DROP TABLE x` piggyback all deny, while `SELECT` still allows.
+
+    rules:
+      - id: no-destructive-sql
+        deny: 'database:admin'
+      - id: no-writes
+        deny: 'database:write'
+      - id: read-only-db
+        allow: 'database:read'
+
+A `deny: 'database:admin'` rule was never affected -- it matches the
+argument-derived class regardless of the method. Only the allow-only shape was
+vulnerable.
+
+Tests: 124 explicit cells (31 method modes x 4 SQL classes) plus the four
+literal CLI cases, mirrored in Node. Adding a class or a method alias fails the
+matrix until its cells are filled.
+
+
 ## 1.13.12 (2026-08-16): your audit trail now states whether the HOST enforced, and deny rules that never fired now fire
 
 Two things in this release change what a customer can conclude from what we

{controlzero-1.13.12 → controlzero-1.13.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.13.12
+Version: 1.13.13
 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.13.12 → controlzero-1.13.13}/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.13.12"
+__version__ = "1.13.13"
 
 __all__ = [
     "Client",

{controlzero-1.13.12 → controlzero-1.13.13}/controlzero/_internal/action_aliases.py

@@ -87,6 +87,68 @@ for cls, aliases in _CLASSES.items():
     _CANONICAL_TO_LEGACY[canon] = {_canonical(a) for a in aliases}
 
 
+# Conflict-only ordering for a caller method versus the class derived from the
+# concrete SQL arguments (#2340). ``admin`` and ``exec`` are both privileged,
+# top-tier classes: neither may be treated as safer than the other. When they
+# conflict, the argument-derived class wins the tie because it describes the
+# SQL that will actually execute; the caller method is compatibility metadata.
+_DATABASE_CLASS_DANGER: dict[str, int] = {
+    "read": 0,
+    "write": 1,
+    "admin": 2,
+    "exec": 2,
+}
+
+
+def _database_classes_for_action(action: str) -> set[str]:
+    """Return canonical database classes represented by one action."""
+    if not isinstance(action, str) or not action or ":" not in action:
+        return set()
+    tool, method = action.split(":", 1)
+    if tool != TOOL:
+        return set()
+    if method in _DATABASE_CLASS_DANGER:
+        return {method}
+    return {
+        canonical_action.split(":", 1)[1]
+        for canonical_action in _LEGACY_TO_CANONICAL.get(method, ())
+    }
+
+
+def resolve_database_class_conflict(
+    method_action: str,
+    argument_action: str,
+) -> str | None:
+    """Return the sole governing action for a method/argument class conflict.
+
+    ``None`` means there is no explicit conflict to resolve: at least one side
+    is unclassified, or both sides represent exactly the same single class. In
+    those cases callers retain the additive compatibility behavior.
+
+    A returned action is a canonical ``database:<class>``. The evaluator must
+    build candidates from that action alone, making a less-dangerous method
+    alias absent rather than hoping a later deny rule detects it.
+    """
+    method_classes = _database_classes_for_action(method_action)
+    argument_classes = _database_classes_for_action(argument_action)
+
+    # Explicit positive gate: conflict resolution only applies when BOTH
+    # sources carry recognized classes and the argument side is unambiguous.
+    if not method_classes or len(argument_classes) != 1:
+        return None
+    argument_class = next(iter(argument_classes))
+    if method_classes == {argument_class}:
+        return None
+
+    method_class = max(method_classes, key=_DATABASE_CLASS_DANGER.__getitem__)
+    if (
+        _DATABASE_CLASS_DANGER[argument_class]
+        >= _DATABASE_CLASS_DANGER[method_class]
+    ):
+        return _canonical(argument_class)
+    return _canonical(method_class)
+
+
 def expand_candidate_actions(actions: Iterable[str]) -> list[str]:
     """Expand an iterable of candidate actions to include every known alias.
 
@@ -162,4 +224,9 @@ def alias_table_json() -> str:
     return json.dumps(payload, indent=2, sort_keys=False)
 
 
-__all__ = ["TOOL", "expand_candidate_actions", "alias_table_json"]
+__all__ = [
+    "TOOL",
+    "alias_table_json",
+    "expand_candidate_actions",
+    "resolve_database_class_conflict",
+]

{controlzero-1.13.12 → controlzero-1.13.13}/controlzero/_internal/enforcer.py

@@ -1171,18 +1171,21 @@ class PolicyEvaluator:
 
         # Semantic-class layer (#345): when the action carries a
         # canonical SQL class (database:read|write|admin|exec) the
-        # evaluator matches rules against BOTH the per-keyword action
-        # above AND this class action. A rule whose actions list
+        # evaluator normally matches rules against BOTH the per-keyword action
+        # above AND this class action. When recognized method and argument
+        # classes conflict, #2340 replaces both with the most-dangerous class
+        # below. A rule whose actions list
         # contains `database:read` therefore fires for any read-shaped
         # SQL (SELECT, EXPLAIN, SHOW, CTE, ...) regardless of dialect
         # spelling, while existing per-keyword rules
         # (`database:DROP`) keep working unchanged. Two sources for
         # the class action: the caller may provide it in
         # ``context['action_semantic_class']`` (used by the hook-check
-        # CLI), or we derive it on the fly from ``args['sql']`` when
-        # the tool is ``database`` and no class was provided.
+        # CLI), or we derive it on the fly from ``args['sql']``. Concrete SQL
+        # arguments are authoritative when both are present; otherwise a caller
+        # could suppress classification by passing a stale context value.
         semantic_action = ctx_dict.get("action_semantic_class") or ""
-        if not semantic_action and tool == "database" and args:
+        if tool == "database" and args:
             from controlzero._internal.hook_extractors import sql_semantic_class
             sql_text = args.get("sql") if isinstance(args, dict) else None
             if isinstance(sql_text, str) and sql_text:
@@ -1262,18 +1265,35 @@ class PolicyEvaluator:
         # ...) 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
+        from controlzero._internal.action_aliases import (
+            expand_candidate_actions,
+            resolve_database_class_conflict,
+        )
+
+        database_class_override = resolve_database_class_conflict(
+            action, semantic_action
+        )
         # PRE-#2245 candidate set: the single surviving tool name plus the
         # derived actions. Retained so phase 1 can answer "what would this
         # policy have decided before the widening" without guessing.
-        legacy_actions = expand_candidate_actions([action, *extra_actions])
-        # WIDENED candidate set: every name this call carried, plus the same
-        # derived actions. A strict superset of `legacy_actions`, which is
-        # what makes the phase-1 comparison below a two-outcome choice rather
-        # than an open-ended merge.
-        candidate_actions = expand_candidate_actions(
-            [*subject.candidates, *extra_actions]
-        )
+        if database_class_override is not None:
+            # #2340: a recognized caller method and a recognized SQL-argument
+            # class disagree. Build the candidate universe from the governing
+            # class ONLY. The less-dangerous alias is therefore unmatchable by
+            # construction; it cannot satisfy an early allow before the actual
+            # SQL class is consulted. This is conflict-only, so method-only and
+            # genuinely same-class calls retain the compatibility expansion.
+            legacy_actions = expand_candidate_actions([database_class_override])
+            candidate_actions = list(legacy_actions)
+        else:
+            legacy_actions = expand_candidate_actions([action, *extra_actions])
+            # WIDENED candidate set: every name this call carried, plus the same
+            # derived actions. A strict superset of `legacy_actions`, which is
+            # what makes the phase-1 comparison below a two-outcome choice rather
+            # than an open-ended merge.
+            candidate_actions = expand_candidate_actions(
+                [*subject.candidates, *extra_actions]
+            )
 
         resource = ctx_dict.get("resource")
         evaluated = 0

{controlzero-1.13.12 → controlzero-1.13.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.13.12"
+version = "1.13.13"
 description = "AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup."
 readme = "README.md"
 license = {text = "Apache-2.0"}