controlzero 1.12.0__tar.gz → 1.13.1__tar.gz

{controlzero-1.12.0 → controlzero-1.13.1}/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.13.1 (2026-06-27): shell semantic-class enforcement
+
+### Added
+
+- **Shell semantic-class extractor (#437/#1459).** The enforcer maps a shell
+  command's first meaningful token to a semantic class
+  (`file_write`/`file_delete`/`file_read`/`network`), so a `deny: file_write`
+  rule also blocks shell-mediated file operations (e.g. `Bash(touch x)` ->
+  `file_write`). Additive layer after the per-command action, most-dangerous-wins
+  (`file_delete > network > file_write > file_read`), byte-identical to the Node
+  and Go SDKs (shared `parity-cases.json`, 118 cases). Closes the cross-OS
+  bypass where a denied `Write` was retried as a PowerShell/`cmd`/Unix file
+  write through the Bash tool. Unwraps `sh -c`/`powershell -Command`/`cmd /c`
+  launchers and prefix wrappers; recurses `find -delete`/`find -exec`;
+  whole-line scan for `.NET` method calls and `/dev/tcp/`.
+
+## 1.13.0 (2026-06-26): policy-condition operator vocab
+
+### Added
+
+- **Condition operators.** A rule condition value may now be a tagged envelope
+  `{op, value}` honoring a closed operator set: `equals`, `contains`, `glob`,
+  `matches` (regex, BETA), `gt`/`lt`/`gte`/`lte`, `in`/`not_in`,
+  `in_range`/`outside_range`, `exists`/`not_exists`. Read-only aliases
+  `matches_pattern`/`greater_than`/`less_than` are canonicalized on load, so
+  existing dashboard templates work with zero migration. A legacy scalar value
+  (a plain string or number) keeps its prior glob/equals behavior exactly, so
+  existing policies and signed bundles evaluate unchanged.
+- **File-path conditions.** `file_path` / `path` / `notebook_path` now feed the
+  `input_text` condition value, so a condition like "input_text contains .env"
+  fires on Read/Write/Edit tool calls.
+
+### Notes
+
+- Fail-closed: a missing field is no-match for every operator except
+  `exists`/`not_exists`; an unknown operator is rejected at load; a malformed
+  condition fails closed. `matches` is BETA and length-capped to bound regex
+  backtracking. Secret detection stays on the DLP scanner, not a regex condition.
+
+## 1.12.1 (2026-06-26): deny rules actually deny
+
+### Fixed
+
+- **Deny rules now actually deny (#1011).** A policy DENY rule with a condition
+  (e.g. "block Bash when the command contains rm -rf") could silently fail to
+  match, so the action ran anyway. Reconciled the rule-authoring vocabulary with
+  the engine: tool names match case-insensitively (a rule for `bash:*` catches
+  the canonical `Bash:rm`), the command text is matched as `input_text` by
+  CONTAINS, and conditions are no longer dropped when a hosted policy is
+  translated for local enforcement. A present-but-malformed condition now fails
+  closed at load instead of silently becoming an unconditional allow.
+
 ## 1.12.0 -- 2026-06-25 (per-agent key authority + per-agent bundle cache + whoami)
 
 ### Added

{controlzero-1.12.0 → controlzero-1.13.1}/PKG-INFO

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

{controlzero-1.12.0 → controlzero-1.13.1}/controlzero/_internal/bundle.py

@@ -958,4 +958,21 @@ def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
             if isinstance(k, str) and isinstance(v, str)
         }
 
+    # #1011 follow-up: the SAME allowlist-strip trap. A hosted rule's
+    # `conditions` (e.g. {input_text: "rm -rf"}) was being dropped here, so a
+    # condition authored in the dashboard NEVER reached the local enforcer, so
+    # the rule silently matched on actions only (or, with a tool-case mismatch,
+    # not at all). Forward BOTH alias keys verbatim whenever present (incl. a
+    # malformed/falsy shape: [] / "" / 0 / False), and let the loader apply ONE
+    # consistent precedence + shape validation (truthy-first; reject any
+    # non-dict; a genuine empty dict {} is "no conditions"). Collapsing to a
+    # single key HERE re-introduces a divergent precedence where a present `{}`
+    # could shadow a real alias (codex re-review), so the bundle stays dumb and
+    # the loader is the single source of truth. (The backend wire struct carries
+    # Conditions; see bundle_handler.go PolicyRule.)
+    if "conditions" in rule:
+        translated["conditions"] = rule["conditions"]
+    if "when" in rule:
+        translated["when"] = rule["when"]
+
     return translated

controlzero-1.13.1/controlzero/_internal/condition_ops.py

@@ -0,0 +1,226 @@
+"""Policy-condition operator table (single source of truth) for #1011 / #1495.
+
+A rule condition value is either a LEGACY SCALAR (string -> glob, number/bool ->
+equals; evaluated in enforcer._conditions_match, byte-identical to pre-#1495) or
+a TAGGED ENVELOPE ``{"op": <name>, "value": <scalar|array>, "case_insensitive"?:
+bool}``. This module evaluates the envelope operators ONLY; the scalar path stays
+in the enforcer so existing policies and signed bundles evaluate unchanged.
+
+This is the Python reference; the Node twin (conditionOps.ts) MUST agree
+byte-for-byte (cross-SDK parity is proven by tests/parity/decisions.json). Go is
+paused and not part of this contract; the Go BACKEND engine evaluates only the
+reserved server-side keys (time_range/ip_whitelist/tags) and defers tool-level
+conditions to the SDK (it has no tool args).
+
+FAIL-CLOSED LAW: a MISSING field (value is None) is NO-MATCH for EVERY operator
+except ``exists``/``not_exists``. A regex that will not compile, or a numeric op
+on a non-numeric field, is NO-MATCH (never an error that fails open).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from typing import Any
+
+# Read-only aliases canonicalised on evaluation so the shipped templates
+# (matches_pattern / greater_than / less_than) load and evaluate with ZERO data
+# migration. The dashboard going forward emits the canonical names.
+_OP_ALIASES = {
+    "matches_pattern": "matches",
+    "greater_than": "gt",
+    "less_than": "lt",
+    "greater_than_or_equal": "gte",
+    "less_than_or_equal": "lte",
+}
+
+# The closed operator set the engine honors. The Go publish-time validator (and
+# the frontend) reject any op not in here, so an inert/typo'd operator can never
+# ship.
+KNOWN_OPS = frozenset(
+    {
+        "glob",
+        "equals",
+        "contains",
+        "matches",
+        "gt",
+        "lt",
+        "gte",
+        "lte",
+        "in",
+        "not_in",
+        "outside_range",
+        "in_range",
+        "exists",
+        "not_exists",
+    }
+)
+
+
+# Reserved structured condition keys are matched by KEY NAME (the Go backend's
+# server-side matchers) and are NEVER interpreted as a {op,value} envelope, even
+# when their value nests a sub-key literally named `op` (e.g. a tag named "op").
+# This closes the tags:{op:...} collision hole. The caller checks the KEY against
+# this set before treating a value as an envelope.
+RESERVED_STRUCTURED_KEYS = frozenset({"time_range", "ip_whitelist", "tags"})
+
+
+def canonicalize_op(op: str) -> str:
+    """Map a read alias to its canonical operator name; pass through otherwise."""
+    return _OP_ALIASES.get(op, op)
+
+
+def is_envelope(value: Any) -> bool:
+    """True iff ``value`` is a tagged operator envelope: a dict with a string
+    ``op`` key. Reserved structured keys are disambiguated by KEY NAME upstream,
+    never here, and a runtime args/context value is never treated as an envelope.
+    """
+    return isinstance(value, dict) and isinstance(value.get("op"), str)
+
+
+def _as_float(x: Any):
+    """Coerce to float for numeric ops; return None if not numeric (-> NO-MATCH)."""
+    if isinstance(x, bool):  # bool is an int subclass; never treat as a number here
+        return None
+    if isinstance(x, (int, float)):
+        return float(x)
+    if isinstance(x, str):
+        try:
+            return float(x.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _as_list(operand: Any) -> list:
+    """Operand for in/not_in: a JSON array, or a legacy comma-separated string
+    ('Saturday,Sunday') split by this compat shim so the shipped templates work
+    unmodified. A None / empty operand yields an EMPTY list (the caller treats an
+    empty operand as NO-MATCH, fail-closed (codex P2: a missing `value` must not
+    turn `not_in` into match-everything))."""
+    if operand is None:
+        return []
+    if isinstance(operand, (list, tuple)):
+        return [x for x in operand if x is not None]
+    if isinstance(operand, str):
+        return [p.strip() for p in operand.split(",") if p.strip()]
+    return [operand]
+
+
+# matches (regex) is BETA: Python `re` has no per-match timeout, so a pathological
+# author-supplied pattern can backtrack catastrophically against adversarial field
+# input (codex P1 ReDoS). Until a timeout / RE2 binding lands, bound BOTH the
+# scanned input and the pattern length so practical backtracking is capped; the
+# publish-time validator (#1498) also caps the pattern. A regex error stays
+# fail-closed (NO-MATCH).
+_MATCHES_INPUT_CAP = 8192
+_MATCHES_PATTERN_CAP = 1024
+
+
+def _range_bounds(operand: Any):
+    """[lo, hi] for in_range/outside_range: a 2-element array, or a legacy
+    'lo-hi' / 'HH:MM-HH:MM' string. Returns (lo_str, hi_str) or None if malformed.
+    Comparison is lexical for HH:MM (24h zero-padded) and numeric otherwise; both
+    sides are compared as strings of the same kind, matching the Go matchTimeRange
+    lexical compare for time."""
+    if isinstance(operand, (list, tuple)) and len(operand) == 2:
+        return str(operand[0]), str(operand[1])
+    if isinstance(operand, str) and "-" in operand:
+        lo, _, hi = operand.partition("-")
+        lo, hi = lo.strip(), hi.strip()
+        if lo and hi:
+            return lo, hi
+    return None
+
+
+def _in_range(value: Any, lo: str, hi: str) -> bool:
+    """Inclusive lo<=value<=hi. Numeric when all three parse as numbers, else a
+    lexical string compare (so 'HH:MM' 24h times order correctly)."""
+    fv, flo, fhi = _as_float(value), _as_float(lo), _as_float(hi)
+    if fv is not None and flo is not None and fhi is not None:
+        return flo <= fv <= fhi
+    sv = str(value)
+    return lo <= sv <= hi
+
+
+def match_operator(
+    op: str, value: Any, operand: Any, case_insensitive: bool = False
+) -> bool:
+    """Evaluate one field-level envelope operator. ``value`` is the field value
+    from the merged context+args dict (None if the field is absent); ``operand``
+    is the envelope's ``value``. Returns True iff the condition is satisfied.
+    Unknown op -> False (fail-closed; the validator rejects it at publish too)."""
+    op = canonicalize_op(op)
+
+    # Presence ops are the ONLY ones where a missing field can be a match.
+    if op == "exists":
+        return value is not None
+    if op == "not_exists":
+        return value is None
+
+    # Every other op: a missing field is NO-MATCH (uniform, fail-closed).
+    if value is None:
+        return False
+
+    if op in ("gt", "lt", "gte", "lte"):
+        fv, fo = _as_float(value), _as_float(operand)
+        if fv is None or fo is None:
+            return False  # non-numeric operand/field -> NO-MATCH
+        if op == "gt":
+            return fv > fo
+        if op == "lt":
+            return fv < fo
+        if op == "gte":
+            return fv >= fo
+        return fv <= fo
+
+    if op in ("in", "not_in"):
+        items = [str(x) for x in _as_list(operand)]
+        if not items:
+            # Malformed / empty operand -> NO-MATCH for BOTH in and not_in
+            # (fail-closed; a deny does not over-fire, an allow does not
+            # over-allow). The validator rejects an empty operand at publish.
+            return False
+        if case_insensitive:
+            present = str(value).casefold() in {i.casefold() for i in items}
+        else:
+            present = str(value) in items
+        return present if op == "in" else not present
+
+    if op in ("in_range", "outside_range"):
+        bounds = _range_bounds(operand)
+        if bounds is None:
+            return False
+        inside = _in_range(value, bounds[0], bounds[1])
+        return inside if op == "in_range" else not inside
+
+    # String ops below.
+    sval, soperand = str(value), str(operand)
+    if case_insensitive:
+        sval, soperand = sval.casefold(), soperand.casefold()
+
+    if op == "equals":
+        # Exact equality; wildcards are LITERAL (unlike glob).
+        return sval == soperand
+
+    if op == "contains":
+        # Substring; the operand's own glob metachars are literal (not wildcards).
+        return soperand in sval
+
+    if op == "glob":
+        return fnmatch.fnmatchcase(sval, soperand)
+
+    if op == "matches":
+        # Regex (re.search). Author owns anchoring. BETA: bound input + pattern
+        # length to cap ReDoS backtracking (codex P1); uncompilable / runtime
+        # error -> NO-MATCH (fail-closed), never an exception that fails open.
+        if len(soperand) > _MATCHES_PATTERN_CAP:
+            return False
+        flags = re.IGNORECASE if case_insensitive else 0
+        try:
+            return re.search(soperand, sval[:_MATCHES_INPUT_CAP], flags) is not None
+        except re.error:
+            return False
+
+    # Unknown operator: fail-closed (the publish-time validator also rejects it).
+    return False

{controlzero-1.12.0 → controlzero-1.13.1}/controlzero/_internal/enforcer.py

@@ -470,6 +470,30 @@ class PolicyEvaluator:
                 cls = sql_semantic_class(sql_text)
                 if cls:
                     semantic_action = f"{tool}:{cls}"
+        # Shell semantic-class layer (#437): the SAME additive pattern for
+        # shell-mediated file/network ops. When the tool is the canonical
+        # shell (`Bash`) and no class was provided, derive it from the
+        # command and promote it into the file_write/file_delete/file_read/
+        # network NAMESPACE (`<class>:<class>`) -- NOT `Bash:<class>` --
+        # so a rule `deny: file_write` (normalized `file_write:*`) ALSO
+        # blocks `Bash(touch x)`. Existing `Bash:*` rules are unaffected
+        # because the per-command `action` is always tried first. The
+        # hook-check CLI provides the class via
+        # ``context['action_semantic_class']``; this is the on-the-fly
+        # path for direct ``guard("Bash", args={"command": ...})`` callers.
+        if not semantic_action and tool == "Bash" and args:
+            from controlzero._internal.hook_extractors import shell_semantic_class
+            cmd_text = None
+            if isinstance(args, dict):
+                for _key in ("command", "CommandLine"):
+                    _v = args.get(_key)
+                    if isinstance(_v, str) and _v:
+                        cmd_text = _v
+                        break
+            if cmd_text:
+                cls = shell_semantic_class(cmd_text)
+                if cls:
+                    semantic_action = f"{cls}:{cls}"
         candidate_actions: list[str] = [action]
         if semantic_action and semantic_action != action:
             candidate_actions.append(semantic_action)
@@ -516,7 +540,9 @@ class PolicyEvaluator:
 
         for rule in self._rules:
             evaluated += 1
-            if not any(_glob_any(rule.actions, a) for a in candidate_actions):
+            # Action gate: tool-case-insensitive so `bash:*` matches `Bash:rm`
+            # (#1011). Resource/client/project gates below stay case-sensitive.
+            if not any(_action_glob_any(rule.actions, a) for a in candidate_actions):
                 continue
             # Client + project gates (gh#175). A rule whose selector
             # excludes this request does NOT apply to this surface, so
@@ -676,10 +702,22 @@ class PolicyEvaluator:
         All condition keys must match. Missing key = no match. Context keys
         override args on collision. Nested ``context['tags']`` dict is flattened.
         """
-        if not rule_conditions:
+        # #1011 follow-up (codex P1): the non-dict guard MUST run before the
+        # falsy short-circuit, otherwise a falsy-but-malformed conditions ([],
+        # "", 0, False) would be read as "no conditions" and the rule would match
+        # unconditionally (an allow rule -> unconditional allow, fail-open). A
+        # corrupt/tampered or future-shaped signed rule is unverifiable, so the
+        # rule does NOT match: an allow rule then does not fire and the default
+        # posture governs (fail-closed); a deny rule simply does not contribute.
+        # `None` is the genuine "no conditions" case and matches.
+        if not isinstance(rule_conditions, dict):
+            return rule_conditions is None
+        if not rule_conditions:  # empty dict -> no conditions to satisfy
             return True
         import fnmatch as _fn
 
+        from .io_capture_producer import _INPUT_TEXT_KEYS
+
         merged: dict = {}
         if args:
             merged.update(args)
@@ -688,11 +726,71 @@ class PolicyEvaluator:
             tags = context.get("tags") or {}
             if isinstance(tags, dict):
                 merged.update(tags)
+        # #1011 follow-up: derive `input_text` (the key the dashboard/templates
+        # author, "command/input contains X") DETERMINISTICALLY from the payload
+        # rather than trusting a caller-supplied label. The raw command/content
+        # is the GROUND TRUTH of what runs, so it wins first: neither a benign
+        # `input_text` nor a benign pre-extracted `input_payload` can shadow a
+        # dangerous `command` (codex P1: a payload setting input_text="ls" or
+        # input_payload="ls" while command="rm -rf /" would otherwise bypass the
+        # deny under default allow). Precedence: the canonical _INPUT_TEXT_KEYS
+        # scan (the SAME order audit extraction uses, so enforcement and audit
+        # never drift), then the host's pre-extracted input_payload, then any
+        # existing input_text, each only as a fallback when nothing richer is
+        # present.
+        _derived = None
+        for _k in _INPUT_TEXT_KEYS:
+            _v = merged.get(_k)
+            if _v:
+                _derived = _v
+                break
+        if not _derived:
+            _derived = merged.get("input_payload")
+        if not _derived:
+            _derived = merged.get("input_text")
+        if _derived:
+            merged["input_text"] = _derived
+        from .condition_ops import (
+            RESERVED_STRUCTURED_KEYS,
+            is_envelope,
+            match_operator,
+        )
+
         for key, pattern in rule_conditions.items():
+            # #1495: a TAGGED ENVELOPE {op, value} dispatches to the shared
+            # operator table (equals/contains/matches/gt/lt/in/not_in/range/
+            # exists/...). Everything else is a LEGACY SCALAR and keeps the exact
+            # pre-#1495 glob/CONTAINS path below, so existing policies and signed
+            # bundles evaluate byte-identically. exists/not_exists are the only
+            # ops where a missing field can match, so the envelope branch runs
+            # BEFORE the missing-key short-circuit. A RESERVED structured key is
+            # matched by key name, never as an envelope (the tags:{op:...} hole).
+            if key not in RESERVED_STRUCTURED_KEYS and is_envelope(pattern):
+                if not match_operator(
+                    pattern["op"],
+                    merged.get(key),
+                    pattern.get("value"),
+                    bool(pattern.get("case_insensitive")),
+                ):
+                    return False
+                continue
             value = merged.get(key)
             if value is None:
                 return False
-            if not _fn.fnmatchcase(str(value), str(pattern)):
+            sval, spat = str(value), str(pattern)
+            # Only `input_text` (the dashboard's authored text-content key) uses
+            # CONTAINS for a plain pattern, so `input_text: "rm -rf"` catches
+            # `rm -rf /tmp/foo`. A pattern with glob metacharacters still uses
+            # fnmatch; EVERY other key (including the raw `command`/`prompt`
+            # sources) keeps exact-glob semantics, so an existing exact-match
+            # allowlist is never silently broadened into a substring match
+            # (codex P1 fail-open regression).
+            if key.casefold() in _TEXT_CONTENT_CONDITION_KEYS and not any(
+                c in spat for c in "*?["
+            ):
+                if spat not in sval:
+                    return False
+            elif not _fn.fnmatchcase(sval, spat):
                 return False
         return True
 
@@ -836,8 +934,58 @@ def _glob_any(patterns: list[str], value: str) -> bool:
 
     fnmatchcase is case-sensitive (matches policy semantics) and supports the
     same syntax users learn from .gitignore: *, ?, [seq], [!seq].
+
+    NOTE: this stays case-sensitive and is used for the resource / client /
+    project selector gates. Action matching uses :func:`_action_glob_any`,
+    which case-folds the tool segment (see below).
     """
     for p in patterns:
         if fnmatch.fnmatchcase(value, p):
             return True
     return False
+
+
+def _norm_action_tool(s: str) -> str:
+    """Case-fold ONLY the tool segment of an action token (the part before the
+    first ``:``); leave the method/arg glob untouched.
+
+    The canonical action the SDK emits is capital-tool (e.g. ``Bash:rm``, the
+    canonical TOOL NAME from the extractor spec), but a user or a policy
+    template may author the tool in any case (``bash:*``). The tool name is a
+    fixed, known vocabulary, so case is never meaningful for it; folding it lets
+    a user-authored rule reconcile with the call the agent actually makes. The
+    METHOD stays case-sensitive so method-cased semantics (e.g. ``database:DROP``
+    vs ``database:drop``) are preserved. A token with no ``:`` (e.g. the
+    universal ``*``) is folded whole, a no-op for glob metacharacters.
+    """
+    tool, sep, method = s.partition(":")
+    return (tool.casefold() + sep + method) if sep else s.casefold()
+
+
+def _action_glob_any(patterns: list[str], action: str) -> bool:
+    """Action-gate matcher: like :func:`_glob_any` but case-INSENSITIVE on the
+    tool segment of both the rule pattern and the action (see
+    :func:`_norm_action_tool`).
+
+    This is what makes a deny rule authored as ``bash:*`` actually match the
+    canonical ``Bash:rm`` (#1011 follow-up: a customer's deny rule silently
+    never fired because the matcher compared the tool case-sensitively).
+    """
+    a = _norm_action_tool(action)
+    for p in patterns:
+        if fnmatch.fnmatchcase(a, _norm_action_tool(p)):
+            return True
+    return False
+
+
+# The ONE condition key whose plain (metachar-free) pattern is matched by
+# CONTAINS (substring): `input_text`. It is the key the dashboard/templates
+# author for "the command/input contains X", and a user typing `rm -rf` means
+# "contains rm -rf", not "IS exactly rm -rf". Patterns WITH glob metachars still
+# use fnmatch. This set is deliberately NARROW: the raw payload keys (command,
+# input_payload, prompt, ...) are seeding SOURCES for input_text, not author-
+# facing condition keys. Briefly including them here broadened any existing
+# exact-match allowlist keyed on `command` into a substring match, a fail-open
+# regression (codex P1). Every key except `input_text` keeps exact-glob
+# semantics. (#1011 follow-up.)
+_TEXT_CONTENT_CONDITION_KEYS = frozenset({"input_text"})