controlzero 1.13.12__tar.gz → 1.13.14__tar.gz

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

@@ -2,6 +2,94 @@
 
 ## Unreleased
 
+## 1.13.14 (2026-08-17): a tampered policy file silently flipped deny to allow
+
+**Security fix. If you sign your policy and rely on `tamper_behavior`, read this.**
+
+Reproduced against the published 1.13.13 wheel:
+
+```
+signed policy    -> some_tool: deny    (correct)
+TAMPERED policy  -> some_tool: allow   (tamper_behavior: deny was set)
+```
+
+Anyone with write access to the policy file could turn a `deny` into an
+`allow`, and `guard()` obeyed. The `.sig` sidecar sat alongside it, no longer
+matching, and nothing read it.
+
+`Client(policy=...).guard()` never verified the file's HMAC. Every piece of the
+tamper machinery existed and worked -- `load_signed_file` correctly rejects a
+mutated envelope, and `guard()` correctly fails closed when told tampering
+occurred -- but nothing connected the two. The tests for each half passed the
+entire time, because each tested its own half.
+
+Fixed: `guard()` now discovers tampering from the signed file itself on every
+evaluation and merges the result into a private copy of the context, so a
+caller cannot assert its own tamper state and enforcement and audit consume the
+same fact.
+
+**Who is affected:** callers who signed their policy with `controlzero
+sign-policy` and set `tamper_behavior`. An unsigned policy has no signature to
+verify and is unaffected -- that configuration never had the control.
+
+**Node has the same gap** and is tracked separately; this release fixes Python
+only.
+
+Upgrade:
+
+```bash
+pip install --upgrade controlzero
+```
+
+## 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.14}/PKG-INFO

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

{controlzero-1.13.12 → controlzero-1.13.14}/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.14}/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.14}/controlzero/client.py

@@ -698,6 +698,19 @@ class Client:
         )
         self._local_override_source_hint = str(local_source) if self._local_override_active else ""
 
+        # Keep the actual file-backed source so guard() can verify its HMAC on
+        # every evaluation. Dict policies and hosted bundles have no local HMAC
+        # sidecars; hosted signatures are verified by load_hosted_policy().
+        #
+        # Accept str as well as Path. `Client(policy="policy.yaml")` is the form
+        # every doc example uses, and an isinstance(local_source, Path) test
+        # silently skipped tamper verification for it -- the control would have
+        # been present, tested, and unreachable for almost every real caller.
+        # A dict policy has no file to verify and correctly yields None here.
+        self._local_policy_path = (
+            Path(local_source) if isinstance(local_source, (str, Path)) else None
+        )
+
         # Load local policy if present
         self._evaluator: Optional[PolicyEvaluator] = None
         self._policy_settings = PolicySettings()
@@ -1465,6 +1478,17 @@ class Client:
         # error is swallowed: the old bundle keeps working.
         self._maybe_refresh_policy()
 
+        # A caller cannot be trusted to report policy tampering in its own
+        # context. Discover it from the signed file and merge the result into a
+        # private copy so both enforcement and audit consume the same fact.
+        if self._local_policy_path is not None:
+            from controlzero.tamper import policy_file_tampered
+
+            if policy_file_tampered(self._local_policy_path):
+                context = dict(context or {})
+                context["tamper_detected"] = True
+                context.setdefault("tamper_source", "policy_hmac")
+
         # gh#175 P1.1 audit trail: resolve the client_name +
         # project_id once up front so the quarantine / tamper
         # fast-paths below stamp the audit row consistently with the

{controlzero-1.13.12 → controlzero-1.13.14}/controlzero/tamper.py

@@ -326,6 +326,31 @@ def load_or_create_secret(path: Path) -> bytes:
     return secret
 
 
+def policy_file_tampered(path: Path) -> bool:
+    """Return whether a signed local policy no longer matches its HMAC.
+
+    Unsigned policies remain supported: when either sidecar is absent there is
+    no integrity assertion to verify, so this returns False. Once both
+    ``<policy>.sig`` and ``tamper.key`` exist, a malformed or mismatched
+    signature is tampering.
+    """
+    policy_path = Path(path)
+    signature_path = policy_path.with_suffix(policy_path.suffix + ".sig")
+    key_path = policy_path.parent / "tamper.key"
+    if not signature_path.exists() or not key_path.exists():
+        return False
+
+    try:
+        secret = load_or_create_secret(key_path)
+        payload = policy_path.read_bytes()
+        signature = signature_path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError):
+        # Both sidecars assert that verification is required. If they cannot be
+        # read, the integrity claim cannot be established, so fail closed.
+        return True
+    return not verify_bundle(payload, signature, secret)
+
+
 # Imports below sit mid-module by design: the quarantine block is a
 # self-contained subsystem that came in later than the original file
 # (#383 quarantine support) and was kept locally scoped to make the
@@ -463,6 +488,7 @@ __all__ = [
     "write_signed_file",
     "HashChain",
     "load_or_create_secret",
+    "policy_file_tampered",
     "TamperState",
     "report_tamper_alert",
 ]

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

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