controlzero 1.6.0__tar.gz → 1.8.0__tar.gz

{controlzero-1.6.0 → controlzero-1.8.0}/.gitignore

@@ -114,6 +114,9 @@ letsencrypt/
 
 # DLP test reports (generated, not committed)
 reports/
+# ...but committed long-form markdown reports under docs/reports/ are kept
+!docs/reports/
+!docs/reports/**/*.md
 
 # MkDocs
 site/
@@ -246,3 +249,7 @@ doc_local/
 # Go build/module caches (generated by `go build`, `go test`, etc.)
 **/.gocache/
 **/.gomodcache/
+/node_modules
+
+# Antigravity (agy) CLI local workspace
+.antigravitycli/

{controlzero-1.6.0 → controlzero-1.8.0}/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 1.8.0 -- 2026-06-15 (Kiro, epic gh#877)
+
+### Added
+
+- **Kiro (AWS agentic IDE) governance.** Control Zero now governs Kiro the
+  same way it governs Claude Code / Codex / Gemini: tool calls route through
+  the shared `controlzero hook-check` -> policy engine -> audit path, with
+  project scope honored and audit rows attributed to `agent="kiro"`
+  (`canonical_source` `kiro_cli` / `kiro_ide`).
+
+  - **Kiro CLI (`kiro-cli chat`): BETA -- full fidelity.** The CLI passes the
+    event JSON on stdin in snake_case, byte-compatible with what hook-check
+    already consumes, so `preToolUse` / `postToolUse` / `userPromptSubmit`
+    governance (including argument-level deny rules) works directly. The new
+    `KiroCLIAdapter` claims these by their camelCase event names, which are
+    byte-disjoint from Claude Code's PascalCase events.
+
+  - **Kiro IDE: limited (see below).** The IDE delivers its hook payload via
+    the `USER_PROMPT` env var, not stdin. The packaged `cz-kiro-adapter`
+    console script normalises that to the stdin shape and pipes it to
+    hook-check. **The Prompt Submit and File Save hooks are active** (they
+    carry data). **The Pre Tool Use hook ships DISABLED** because upstream
+    Kiro (#7375/#7408/#7500, IDE v0.11) currently delivers an empty payload
+    (`USER_PROMPT={}`) to IDE `preToolUse` run-command hooks -- with no tool
+    context, an enabled hook would fail closed and block every tool call.
+    Re-enable it once upstream ships tool context (or set
+    `CZ_KIRO_UNKNOWN_PAYLOAD=open` to trade pre-tool policy for availability).
+
+  - **`controlzero kiro init`** one-command installer (`--surface cli|ide|both`,
+    idempotent, `--dry-run`, `--uninstall`). Writes the Kiro hook configs from
+    committed templates, installs the `~/.controlzero/policy.yaml` Kiro
+    template, and registers the Kiro agent fingerprint.
+
+  - **Fail-safe defaults.** The IDE shim never crashes the IDE: an empty /
+    unparseable payload is handled per `CZ_KIRO_UNKNOWN_PAYLOAD`
+    (default `closed` = block, governance-safe), and a missing `controlzero`
+    CLI allows rather than bricking the editor.
+
+  See `docs/integrations/kiro.md` for the covered-vs-bounded matrix and
+  `docs/integrations/kiro-hook-payloads.md` for the per-event payload shapes.
+
+## 1.7.0 -- 2026-05-19 (T86, gh#391)
+
+### Added
+
+- **Unknown-action validator at policy-load time** (T86, GitHub #391).
+  When `controlzero.policy_loader.load_policy()` parses a policy whose
+  rules target an action name that is not in the canonical-or-alias
+  table (typo, made-up name like `database:queryy`), the loader now
+  emits a `logging.WARNING` per offending action with a did-you-mean
+  suggestion list. The policy still loads -- the validator is
+  warn-not-block at the SDK level (the platform backend blocks publish
+  with 422 on the same condition).
+
+  This catches the silent "rule lands but never fires" class of bug
+  that T84's alias shim was created to prevent: a customer typing
+  `database:queryy` gets a one-line warning pointing at
+  `database:query (legacy)` instead of the rule silently never matching.
+
+  The validator's known-action set is the union of canonical SDK
+  extractor tools, host-tool aliases (e.g. `Read` -> `file_read`), the
+  four canonical SQL semantic classes plus every legacy alias from the
+  T84 alias table, and wildcards (`*`, `tool:*`, `*:method`). Adding
+  a new alias to `_internal/action_aliases.py` automatically widens
+  what the validator accepts.
+
+  See `docs/concepts/policies.md#validation` for the full contract.
+
 ## v1.6.0 -- 2026-05-17 (HITL-6a, gh#542)
 
 First minor that turns the Human-in-the-Loop approval workflow on. 1.5.8

{controlzero-1.6.0 → controlzero-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.6.0
+Version: 1.8.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
@@ -52,7 +52,7 @@ Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == 'openai'
 Description-Content-Type: text/markdown
 
-# control-zero
+# controlzero
 
 AI agent governance for Python. Policies, audit, and observability for tool calls.
 Works locally with no signup.
@@ -116,12 +116,19 @@ The generated `controlzero.yaml` is the tutorial. It ships with annotated
 rules covering the common patterns: allow lists, deny lists, wildcards, and
 the catch-all.
 
-Templates available:
+Templates available (`controlzero init -t <name>`):
 
-- `controlzero init` — Hello World template (default)
-- `controlzero init -t rag` — RAG agent template (block exfiltration)
-- `controlzero init -t mcp` — MCP server template
-- `controlzero init -t cost-cap` — model allow-listing and cost guards
+- `generic` — Hello World template (default)
+- `rag` — RAG agent template (block exfiltration)
+- `mcp` — MCP server template
+- `cost-cap` — model allow-listing and cost guards
+- `claude-code` — Claude Code hook starter
+- `langchain` — LangChain tool guardrails
+- `crewai` — CrewAI starter policy
+- `cursor` — Cursor / editor hook starter
+- `autogen` — AutoGen starter policy
+- `codex-cli` — Codex CLI hook starter
+- `gemini-cli` — Gemini CLI hook starter
 
 ## Loading a policy
 
@@ -368,7 +375,7 @@ async def async_poll(request_id: str) -> dict:
 resolved = await pending.wait_async(async_poll)
 ```
 
-A built-in HTTP poller is planned for 1.7.0.
+1.7.0 ships `client.get_secret_poll_fn()` as a built-in poller helper for the secret-read approval path. The general `request_approval()` flow still takes an explicit `poll_fn` so callers can plug their own HTTP stack.
 
 ### Mock backend for tests
 

{controlzero-1.6.0 → controlzero-1.8.0}/README.md

@@ -1,4 +1,4 @@
-# control-zero
+# controlzero
 
 AI agent governance for Python. Policies, audit, and observability for tool calls.
 Works locally with no signup.
@@ -62,12 +62,19 @@ The generated `controlzero.yaml` is the tutorial. It ships with annotated
 rules covering the common patterns: allow lists, deny lists, wildcards, and
 the catch-all.
 
-Templates available:
+Templates available (`controlzero init -t <name>`):
 
-- `controlzero init` — Hello World template (default)
-- `controlzero init -t rag` — RAG agent template (block exfiltration)
-- `controlzero init -t mcp` — MCP server template
-- `controlzero init -t cost-cap` — model allow-listing and cost guards
+- `generic` — Hello World template (default)
+- `rag` — RAG agent template (block exfiltration)
+- `mcp` — MCP server template
+- `cost-cap` — model allow-listing and cost guards
+- `claude-code` — Claude Code hook starter
+- `langchain` — LangChain tool guardrails
+- `crewai` — CrewAI starter policy
+- `cursor` — Cursor / editor hook starter
+- `autogen` — AutoGen starter policy
+- `codex-cli` — Codex CLI hook starter
+- `gemini-cli` — Gemini CLI hook starter
 
 ## Loading a policy
 
@@ -314,7 +321,7 @@ async def async_poll(request_id: str) -> dict:
 resolved = await pending.wait_async(async_poll)
 ```
 
-A built-in HTTP poller is planned for 1.7.0.
+1.7.0 ships `client.get_secret_poll_fn()` as a built-in poller helper for the secret-read approval path. The general `request_approval()` flow still takes an explicit `poll_fn` so callers can plug their own HTTP stack.
 
 ### Mock backend for tests
 

{controlzero-1.6.0 → controlzero-1.8.0}/controlzero/__init__.py

@@ -27,13 +27,33 @@ from controlzero.errors import (
     PolicyValidationError,
 )
 from controlzero.hitl import PendingApproval
+from controlzero.hitl.grant_protocol import (
+    REASON_HITL_BACKEND_UNREACHABLE,
+    REASON_HITL_GRANT_APPROVED,
+    REASON_HITL_GRANT_CANCELED,
+    REASON_HITL_GRANT_DENIED,
+    REASON_HITL_GRANT_EXPIRED,
+    REASON_HITL_GRANT_REVOKED,
+    REASON_HITL_GRANT_TIMEOUT,
+    REASON_HITL_RETRY_GUARD_FAILED,
+    REASON_HITL_RETRY_LOOP,
+)
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.6.0"
+__version__ = "1.8.0"
 
 __all__ = [
     "Client",
     "PendingApproval",
+    "REASON_HITL_BACKEND_UNREACHABLE",
+    "REASON_HITL_GRANT_APPROVED",
+    "REASON_HITL_GRANT_CANCELED",
+    "REASON_HITL_GRANT_DENIED",
+    "REASON_HITL_GRANT_EXPIRED",
+    "REASON_HITL_GRANT_REVOKED",
+    "REASON_HITL_GRANT_TIMEOUT",
+    "REASON_HITL_RETRY_GUARD_FAILED",
+    "REASON_HITL_RETRY_LOOP",
     "PolicyDecision",
     "PolicyDeniedError",
     "PolicyLoadError",

controlzero-1.8.0/controlzero/_internal/action_validator.py

@@ -0,0 +1,182 @@
+"""T86 / GitHub #391 -- unknown-action validator (warn-only at SDK load).
+
+Pairs with the backend validator at
+``apps/control-zero-platform/backend/internal/policy/action_aliases.go``.
+The backend BLOCKS publish on unknown actions (422); the SDK
+WARNS at load time so a customer running local-policy mode (no
+backend) still sees the typo before the rule silently never fires.
+
+The known-action set is the union of:
+
+- Canonical tools (``database``, ``Bash``, ``http``, ``web_search``,
+  ``browser``, ``file_read``, ``file_write``, ``file_search``,
+  ``task``) plus their host-tool aliases from the SDK extractor
+  spec (``sdks/python/controlzero/controlzero/_internal/tool_extractors.json``).
+- For the ``database`` tool: the four canonical SQL semantic classes
+  (``read``/``write``/``admin``/``exec``), every legacy alias from
+  the T84 alias table, and the ambiguous ``delete`` alias.
+
+For every other tool the validator accepts ANY method (open
+extractor outputs -- Bash basenames, HTTP verbs, browser action
+strings, etc.). Wildcards (``*``, ``tool:*``, ``*:method``) always
+pass.
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+from controlzero._internal.action_aliases import TOOL as _ALIAS_TOOL
+from controlzero._internal.action_aliases import _AMBIGUOUS, _CLASSES
+
+# Mirror of the canonical tool set + host-aliases the extractors
+# accept. Source of truth is tool_extractors.json; this list is
+# updated alongside it.
+_CANONICAL_TOOLS: set[str] = {
+    "Bash", "database", "http", "web_search", "browser",
+    "file_read", "file_write", "file_search", "task",
+    # database aliases
+    "sql", "Database", "PostgreSQL", "MySQL", "postgres", "sqlite",
+    # Bash aliases
+    "bash", "shell", "ShellTool", "run_shell_command",
+    "PowerShell", "powershell", "Shell",
+    # http aliases
+    "fetch", "web_fetch", "WebFetch", "HTTPRequest", "request",
+    # web_search aliases
+    "WebSearch", "google_web_search", "SearchTool",
+    # browser aliases
+    "playwright", "Puppeteer",
+    # file_read aliases
+    "read_file", "Read", "ReadFile", "read_many_files",
+    # file_write aliases
+    "write_file", "Write", "WriteFile", "edit_file", "Edit",
+    "replace", "apply_patch",
+    # file_search aliases
+    "Grep", "grep_search", "Glob", "glob",
+    # task aliases
+    "Task", "Agent", "subagent", "spawn_agent",
+}
+
+_DATABASE_TOOL_ALIASES = {
+    "database", "sql", "Database", "PostgreSQL", "MySQL", "postgres", "sqlite",
+}
+
+
+def _build_known_database_methods() -> set[str]:
+    out: set[str] = {"*"}
+    for cls, aliases in _CLASSES.items():
+        out.add(cls)
+        for a in aliases:
+            out.add(a)
+    for alias in _AMBIGUOUS:
+        out.add(alias)
+    return out
+
+
+_KNOWN_DATABASE_METHODS = _build_known_database_methods()
+
+
+def is_known_action(action: str) -> bool:
+    """Return True if ``action`` is recognised by the SDK extractors / aliases."""
+    if not action:
+        return False
+    if action == "*":
+        return True
+    if ":" not in action:
+        return action in _CANONICAL_TOOLS
+    tool, _, method = action.partition(":")
+    if tool == "*":
+        return True
+    if tool not in _CANONICAL_TOOLS:
+        return False
+    if method == "*" or method == "":
+        return True
+    if tool in _DATABASE_TOOL_ALIASES:
+        return method in _KNOWN_DATABASE_METHODS
+    # Other tools: any method accepted (open extractor outputs).
+    return True
+
+
+def _levenshtein(a: str, b: str) -> int:
+    if a == b:
+        return 0
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    prev = list(range(len(b) + 1))
+    curr = [0] * (len(b) + 1)
+    for i in range(1, len(a) + 1):
+        curr[0] = i
+        for j in range(1, len(b) + 1):
+            cost = 0 if a[i - 1] == b[j - 1] else 1
+            curr[j] = min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost)
+        prev, curr = curr, prev
+    return prev[len(b)]
+
+
+def _shares_tool_prefix(a: str, b: str) -> bool:
+    if ":" not in a or ":" not in b:
+        return False
+    ta, _, ma = a.partition(":")
+    tb, _, mb = b.partition(":")
+    if ta != tb or not ma or not mb:
+        return False
+    short = min(len(ma), len(mb))
+    overlap = 0
+    for i in range(short):
+        if ma[i].lower() != mb[i].lower():
+            break
+        overlap += 1
+    return overlap * 2 >= short
+
+
+def _candidates() -> list[tuple[str, bool]]:
+    """Enumerate (name, is_legacy) tuples for suggestion ranking."""
+    out: list[tuple[str, bool]] = []
+    for cls in _CLASSES:
+        out.append((f"{_ALIAS_TOOL}:{cls}", False))
+    for aliases in _CLASSES.values():
+        for a in aliases:
+            out.append((f"{_ALIAS_TOOL}:{a}", True))
+    for alias in _AMBIGUOUS:
+        out.append((f"{_ALIAS_TOOL}:{alias}", True))
+    for tool in _CANONICAL_TOOLS:
+        out.append((f"{tool}:*", False))
+    return out
+
+
+def suggest_for_action(action: str, max_suggestions: int = 3) -> list[str]:
+    """Return up to ``max_suggestions`` did-you-mean candidates for ``action``."""
+    max_distance = 3
+    cands = _candidates()
+    hits: list[tuple[str, int, bool]] = []
+    for name, legacy in cands:
+        d = _levenshtein(action, name)
+        if d > max_distance and not _shares_tool_prefix(action, name):
+            continue
+        hits.append((name, d, legacy))
+    # Sort by distance, then prefer canonical over legacy, then name.
+    hits.sort(key=lambda h: (h[1], h[2], h[0]))
+    out: list[str] = []
+    for name, _d, legacy in hits[:max_suggestions]:
+        out.append(f"{name} (legacy)" if legacy else name)
+    return out
+
+
+def validate_actions(actions: Iterable[str]) -> tuple[list[str], dict[str, list[str]]]:
+    """Return (unknown_actions, suggestions_map) for the given action list."""
+    unknown: list[str] = []
+    suggestions: dict[str, list[str]] = {}
+    seen: set[str] = set()
+    for a in actions:
+        if is_known_action(a):
+            continue
+        if a in seen:
+            continue
+        seen.add(a)
+        unknown.append(a)
+        suggestions[a] = suggest_for_action(a)
+    return unknown, suggestions
+
+
+__all__ = ["is_known_action", "suggest_for_action", "validate_actions"]

{controlzero-1.6.0 → controlzero-1.8.0}/controlzero/_internal/bundle.py

@@ -570,7 +570,7 @@ def translate_to_local_policy(payload: dict) -> dict:
             "reason_code": "NO_ACTIVE_POLICIES",
         })
 
-    return {
+    out = {
         "version": "1",
         "rules": flat,
         "settings": {
@@ -580,6 +580,20 @@ def translate_to_local_policy(payload: dict) -> dict:
         },
     }
 
+    # #906 / #907 Phase 2 seam (hosted path): carry the bundle-level
+    # ``dlp_rules`` array through to the translated local-policy dict under
+    # the SAME key the scanner reads (load_dlp_rules_from_policy reads
+    # ``dlp_rules``). Without this, a bundle-projected custom DLP rule reaches
+    # the hosted ``Client(api_key=...)`` path (via _get_raw_policy_data ->
+    # load_dlp_rules_from_policy) as nothing, so only the CLI /api/policy path
+    # would enforce custom rules. Only emit the key when present so the
+    # translated shape stays byte-identical for bundles without dlp_rules.
+    bundle_dlp_rules = payload.get("dlp_rules")
+    if isinstance(bundle_dlp_rules, list) and bundle_dlp_rules:
+        out["dlp_rules"] = bundle_dlp_rules
+
+    return out
+
 
 def make_bundle_missing_policy(
     default_on_missing: Optional[str] = None,