controlzero 1.4.0__tar.gz → 1.4.3__tar.gz

controlzero-1.4.3/.gitignore

@@ -0,0 +1,239 @@
+# Worktrees
+.worktrees/
+
+# Transient QA / design captures at repo root.
+# Long-term reference screenshots live under docs-site/static/ or in Obsidian.
+/*.png
+/dashboard-*.md
+/uat-*.png
+/audit-*.png
+/billing-*.png
+/sso-*.png
+/notifications-*.png
+/settings-*.png
+
+# Dependencies
+node_modules/
+vendor/
+
+# Build outputs
+dist/
+build/
+.next/
+out/
+*.egg-info/
+# Go binaries
+apps/control-zero-platform/backend/server
+
+# Test & Coverage
+coverage/
+htmlcov/
+.coverage
+*.lcov
+.pytest_cache/
+.vitest/
+test-results/
+playwright-report/
+.playwright/
+__pycache__/
+*.pyc
+*.pyo
+
+# Environment and secrets (deny-all, allow explicitly)
+.env*
+!.envrc
+production-secrets*
+vault-backup.key
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa
+id_ed25519
+*.keystore
+# Firebase credentials and config (contains API keys / service account)
+firebase.js
+firebase.json
+firebase-service-account*.json
+*-firebase-adminsdk-*.json
+firebase-adminsdk-*.json
+serviceAccountKey.json
+cz-service-account.json
+firebase-credentials.json/
+google-services.json
+GoogleService-Info.plist
+!*.pub
+!.env.example
+!.env.local.example
+!.env.production.template
+!.env.production.example
+!.env.test
+
+# Explicitly block files that contain or may contain real credentials (override allowlist above)
+.env.dev
+.env.production
+.env.production.complete
+.env.production.local
+.env.local
+.env.*.local
+*.env.real
+*.env.secret
+.env.vercel
+
+# IDE & Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*.sublime-workspace
+*.sublime-project
+
+# OS files
+.DS_Store
+Thumbs.db
+*.log
+
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Docker
+docker-compose.override.yml
+.docker/
+
+# Production logs and certificates
+logs/
+letsencrypt/
+*.log
+
+# DLP test reports (generated, not committed)
+reports/
+
+# MkDocs
+site/
+
+# Turbo (if adopted)
+.turbo/
+
+# Changeset
+.changeset/*.md
+!.changeset/config.json
+!.changeset/README.md
+
+# Vercel
+.vercel/
+
+# Rust
+target/
+Cargo.lock
+*.rlib
+
+# Python virtual environments
+venv/
+.venv/
+*.egg-info/
+
+# Gateway
+apps/control-zero-gateway/.venv/
+apps/control-zero-gateway/__pycache__/
+
+# Selenium test outputs
+tests/selenium/screenshots/
+tests/selenium/report.html
+
+# Miscellaneous
+*.bak
+*.tmp
+*.temp
+.cache/
+.vercel
+# Internal documentation (sensitive -- do not track)
+docs/internal/
+
+# Playwright MCP
+.playwright-mcp/
+
+# Session artifacts (prevent future accumulation)
+*_SUMMARY.md
+*_STATUS.md
+*_COMPLETE.md
+
+# E2E test screenshots
+e2e-*.png
+cz-*.png
+.superpowers/
+
+# AI tooling directories
+.gemini/
+.claude/launch.json
+
+# Docusaurus build cache (should not be tracked)
+docs-site/.docusaurus/
+
+# Test/governance tester scripts (generated during testing sessions)
+*_tester.py
+verify_and_screenshot.js
+
+# HTML reports generated during testing sessions
+*_AUDIT.html
+*_REPORT.html
+*_ANALYSIS.html
+e2e-report.html
+sit-uat-report.html
+UAT_COMPREHENSIVE_REPORT.html
+uat-screenshots/
+
+# Offensive summary reports
+SUMMARY_OFFENSIVE_*.md
+.gstack/
+
+# Deployment docs (contain server-specific credentials)
+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
+docs/knowledge-base/
+docs/superpowers/
+# Air-gap build artifacts (generated tarballs and package directories)
+cz-air-gap-*/
+cz-air-gap-*.tar.gz
+cz-support-*.tar.gz
+
+# SSL Proxy -- customer CA certs and generated certs (never track secrets)
+services/ssl-proxy/certs/
+
+# UAT screenshot artifacts
+uat-*.png
+
+# Stray HTML reports in docs/. These are large exported artifacts
+# (SIT/UAT reports, factsheet, launch readiness) that accumulate
+# untracked and risk being swept up by `git add .`. The
+# sit-uat-report-2026-03-22.html in particular is 128MB and would
+# explode the repo. Real docs go under docs/knowledge-base/ or
+# docs/designs/ instead.
+docs/sit-uat-report-*.html
+docs/launch-readiness-report-*.html
+docs/control-zero-factsheet.html
+docs/control-zero-review.html
+
+# Reference screenshots (keep local, not in repo)
+agentdefenders-full.png
+cz-revamp-live.png
+
+# Agent worktrees (created by Claude Code during parallel work)
+.claude/worktrees/
+
+# direnv + sops secrets. Encrypted files under secrets/ are safe to
+# commit; anything matching *.plain or *.dec is a decryption artifact
+# and must NEVER land in git.
+.envrc.local
+.direnv/
+secrets/*.plain
+secrets/*.dec
+.claude/scheduled_tasks.lock

controlzero-1.4.3/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 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.0 → controlzero-1.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.4.0
+Version: 1.4.3
 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
@@ -23,9 +23,14 @@ Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Requires-Dist: click>=8.1.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.25.0
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: zstandard>=0.22.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
 Provides-Extra: dev
 Requires-Dist: cryptography>=41.0.0; extra == 'dev'
 Requires-Dist: httpx>=0.25.0; extra == 'dev'
@@ -35,10 +40,14 @@ Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: pyyaml>=6.0; extra == 'dev'
 Requires-Dist: respx>=0.20.0; extra == 'dev'
 Requires-Dist: zstandard>=0.22.0; extra == 'dev'
+Provides-Extra: google
+Requires-Dist: google-genai>=0.3.0; extra == 'google'
 Provides-Extra: hosted
 Requires-Dist: cryptography>=41.0.0; extra == 'hosted'
 Requires-Dist: httpx>=0.25.0; extra == 'hosted'
 Requires-Dist: zstandard>=0.22.0; extra == 'hosted'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
 Description-Content-Type: text/markdown
 
 # control-zero

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

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

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

@@ -299,16 +299,47 @@ def _decrypt_aes_gcm(key: bytes, encrypted: bytes) -> bytes:
 
 
 def _zstd_decompress(data: bytes) -> bytes:
-    """Zstd decompress. Tries multiple Python bindings for portability."""
+    """Zstd decompress. Tries multiple Python bindings for portability.
+
+    Some backend builds produce zstd frames without the frame content
+    size in the header (klauspost/compress EncodeAll variants). In that
+    case `zstd.ZstdDecompressor().decompress(data)` raises:
+
+        zstandard.backend_c.ZstdError:
+            could not determine content size in frame header
+
+    To decompress regardless of whether the size is declared, we fall
+    back to the streaming API with a hard upper bound of 16 MiB --
+    matching MAX_BUNDLE_BYTES enforced one layer up. This is the
+    standard robust-decompression pattern recommended by the zstandard
+    maintainers for untrusted / variable-source input. #113.
+    """
+    # 16 MiB upper bound on decompressed size; matches
+    # hosted_policy.MAX_BUNDLE_BYTES. Kept inline to avoid an import
+    # cycle between _internal and hosted_policy.
+    _MAX_DECOMPRESSED = 16 * 1024 * 1024
+
     # Preferred: `zstandard` is the de-facto PyPI package.
     try:
+        import io
         import zstandard as zstd
 
-        return zstd.ZstdDecompressor().decompress(data)
+        dctx = zstd.ZstdDecompressor()
+        # Streaming read works for frames that lack the declared
+        # content size. Cap the output to prevent a zip-bomb class
+        # of attack on a tampered bundle.
+        with dctx.stream_reader(io.BytesIO(data)) as reader:
+            out = reader.read(_MAX_DECOMPRESSED + 1)
+        if len(out) > _MAX_DECOMPRESSED:
+            raise BundleVerificationError(
+                f"zstd decompressed payload exceeds {_MAX_DECOMPRESSED} byte limit"
+            )
+        return out
     except ImportError:
         pass
 
-    # Fallback: `pyzstd`.
+    # Fallback: `pyzstd`. Its `decompress()` handles missing content
+    # size natively without needing streaming mode.
     try:
         import pyzstd
 

{controlzero-1.4.0 → controlzero-1.4.3}/controlzero/_internal/enforcer.py

@@ -138,6 +138,8 @@ class PolicyEvaluator:
             if rule.resources:
                 if not resource or not _glob_any(rule.resources, resource):
                     continue
+            if not self._conditions_match(rule.conditions, context, args):
+                continue
             decision = PolicyDecision(
                 effect=rule.effect,
                 policy_id=rule.id or rule.name or None,
@@ -158,6 +160,37 @@ class PolicyEvaluator:
             evaluated_rules=evaluated,
         )
 
+    def _conditions_match(
+        self,
+        rule_conditions: Optional[dict],
+        context: Optional[dict],
+        args: Optional[dict],
+    ) -> bool:
+        """Match rule.conditions against merged context+args using fnmatch globs.
+
+        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:
+            return True
+        import fnmatch as _fn
+
+        merged: dict = {}
+        if args:
+            merged.update(args)
+        if context:
+            merged.update(context)
+            tags = context.get("tags") or {}
+            if isinstance(tags, dict):
+                merged.update(tags)
+        for key, pattern in rule_conditions.items():
+            value = merged.get(key)
+            if value is None:
+                return False
+            if not _fn.fnmatchcase(str(value), str(pattern)):
+                return False
+        return True
+
     def _apply_dlp_scan(
         self, decision: PolicyDecision, args: dict
     ) -> PolicyDecision:

{controlzero-1.4.0 → controlzero-1.4.3}/controlzero/client.py

@@ -83,6 +83,7 @@ class Client:
         log_retention: str = "30 days",
         log_compression: Optional[str] = None,
         log_format: str = "json",
+        agent_name: Optional[str] = None,
     ):
         if policy is not None and policy_file is not None:
             raise ValueError(
@@ -92,6 +93,20 @@ class Client:
         # Resolve API key from arg or env
         self._api_key = api_key or os.environ.get("CONTROLZERO_API_KEY")
 
+        # Resolve agent identity. Used to tag audit events so multi-agent
+        # systems can attribute calls. Order: explicit arg > CZ_AGENT_NAME
+        # env > "default-agent".
+        self._agent_name = (
+            agent_name or os.environ.get("CZ_AGENT_NAME") or "default-agent"
+        )
+
+        # CZ_DEBUG=1 (or true/yes/on) flips the controlzero logger to DEBUG
+        # at construction time. Cheap escape hatch when a user reports
+        # weird behavior and we want them to send us a verbose log.
+        if os.environ.get("CZ_DEBUG", "").lower() in ("1", "true", "yes", "on"):
+            import logging as _logging
+            _logging.getLogger("controlzero").setLevel(_logging.DEBUG)
+
         # Resolve local policy source
         local_source = self._resolve_local_source(policy, policy_file)
 
@@ -215,6 +230,11 @@ class Client:
 
     # ---------------- public API ----------------
 
+    @property
+    def agent_name(self) -> str:
+        """The agent identity attached to audit events for this client."""
+        return self._agent_name
+
     def guard(
         self,
         tool: str,

{controlzero-1.4.0 → controlzero-1.4.3}/controlzero/integrations/anthropic.py

@@ -62,29 +62,32 @@ class _WrappedMessages:
     def _enforce_model(self, kwargs: dict, method: str) -> None:
         """Enforce policy for a messages API call."""
         model = kwargs.get("model", "unknown")
-        context: dict[str, Any] = {
-            "agent_id": self._agent_id,
+        tags: dict[str, Any] = {
             "provider": "anthropic",
-            "method": method,
-            "resource": f"model/{model}",
+            "agent_id": self._agent_id,
+            "action_detail": method,
         }
         tools = kwargs.get("tools")
         if tools:
-            context["tool_count"] = len(tools)
-            context["tool_names"] = [
+            tags["tool_count"] = len(tools)
+            tags["tool_names"] = [
                 t.get("name", "") for t in tools if isinstance(t, dict)
             ]
         self._cz.guard(
-            tool="llm:anthropic",
-            method=method,
+            "llm",
+            method="generate",
             raise_on_deny=True,
-            context=context,
+            context={
+                "resource": f"model/{model}",
+                "tags": tags,
+            },
         )
 
     def create(self, **kwargs: Any) -> Any:
         """Enforce policy then delegate to the original create()."""
         model = kwargs.get("model", "unknown")
-        self._enforce_model(kwargs, "messages.create")
+        self._enforce_model(kwargs, "messages.create")  # action_detail tag
+
         start = time.perf_counter()
         response = self._inner.create(**kwargs)
         latency_ms = int((time.perf_counter() - start) * 1000)
@@ -104,8 +107,8 @@ class _WrappedMessages:
                 reason="guard passed",
             )
             self._cz._audit_decision(
-                tool="llm:anthropic",
-                method="messages.create",
+                tool="llm",
+                method="generate",
                 args={
                     "model": model,
                     "input_tokens": input_tokens,
@@ -113,6 +116,13 @@ class _WrappedMessages:
                     "latency_ms": latency_ms,
                 },
                 decision=decision,
+                context={
+                    "tags": {
+                        "provider": "anthropic",
+                        "agent_id": self._agent_id,
+                        "action_detail": "messages.create",
+                    },
+                },
             )
         except Exception:
             pass

controlzero-1.4.3/controlzero/integrations/autogen.py

@@ -0,0 +1,144 @@
+"""Control Zero integration for AutoGen v0.4+ (autogen-agentchat).
+
+Compatible with autogen-agentchat >=0.7.0, tested against 0.7.5.
+
+Provides a ``governed_tool`` decorator for standalone AutoGen tool
+functions, and a ``GovernedAssistantAgent`` subclass that auto-wraps
+every tool passed into it.
+
+Usage::
+
+    from autogen_agentchat.agents import AssistantAgent
+    from controlzero import Client
+    from controlzero.integrations.autogen import (
+        governed_tool,
+        GovernedAssistantAgent,
+    )
+
+    cz = Client(api_key="cz_live_...")
+
+    @governed_tool(cz, "search_web", agent_id="researcher")
+    async def search_web(query: str) -> str:
+        return do_search(query)
+
+    agent = GovernedAssistantAgent(
+        name="researcher",
+        model_client=model_client,
+        tools=[search_web],
+        client=cz,
+        agent_id="researcher",
+    )
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, Iterable, Optional
+
+from controlzero.client import Client
+
+
+def governed_tool(
+    cz: Client,
+    tool_name: str,
+    method: str = "call",
+    agent_id: str = "",
+) -> Callable:
+    """Decorate an async tool function with Control Zero policy enforcement.
+
+    Args:
+        cz: The ``controlzero.Client`` instance.
+        tool_name: Logical tool name used for the guard action.
+        method: Method name for the guard action. Defaults to ``"call"``.
+        agent_id: Optional tag on the audit entry.
+
+    Returns:
+        A decorator that wraps an async function. On invocation the wrapped
+        function calls ``cz.guard(...)`` with ``raise_on_deny=True`` and then
+        awaits the original function.
+    """
+    def decorator(fn: Callable) -> Callable:
+        @functools.wraps(fn)
+        async def wrapped(*args: Any, **kwargs: Any) -> Any:
+            cz.guard(
+                tool_name,
+                method=method,
+                args={"args": list(args), "kwargs": kwargs},
+                context={
+                    "tags": {
+                        "agent_id": agent_id,
+                        "framework": "autogen",
+                    },
+                },
+                raise_on_deny=True,
+            )
+            return await fn(*args, **kwargs)
+
+        return wrapped
+
+    return decorator
+
+
+class GovernedAssistantAgent:
+    """Subclass of ``autogen_agentchat.agents.AssistantAgent`` that auto-wraps tools.
+
+    Every tool passed via ``tools=[...]`` is transparently wrapped in a
+    ``governed_tool`` decorator so the policy is evaluated before the tool
+    runs.
+
+    The import of ``autogen_agentchat`` is deferred to instantiation time so
+    that merely importing this module does not require the optional
+    dependency.
+    """
+
+    def __new__(
+        cls,
+        name: str,
+        model_client: Any,
+        tools: Optional[Iterable[Callable]] = None,
+        client: Optional[Client] = None,
+        agent_id: str = "",
+        **kwargs: Any,
+    ) -> Any:
+        try:
+            from autogen_agentchat.agents import AssistantAgent
+        except ImportError as exc:
+            raise ImportError(
+                "The 'autogen-agentchat' package is required for this integration. "
+                "Install it with: pip install autogen-agentchat"
+            ) from exc
+
+        if client is None:
+            raise ValueError("GovernedAssistantAgent requires a 'client' argument.")
+
+        wrapped_tools: list[Callable] = []
+        if tools:
+            for tool in tools:
+                tool_name = getattr(tool, "__name__", None) or getattr(
+                    tool, "name", "tool"
+                )
+                # Only wrap async callables; if something is already wrapped
+                # (a decorator already applied), it is idempotent because
+                # guard() is cheap.
+                wrapped = governed_tool(
+                    client,
+                    tool_name=tool_name,
+                    method="call",
+                    agent_id=agent_id,
+                )(tool)
+                # Preserve name/description attributes AutoGen might inspect.
+                for attr in ("name", "description"):
+                    if hasattr(tool, attr):
+                        try:
+                            setattr(wrapped, attr, getattr(tool, attr))
+                        except Exception:
+                            pass
+                wrapped_tools.append(wrapped)
+
+        # Instantiate the real AssistantAgent with the wrapped tools.
+        return AssistantAgent(
+            name=name,
+            model_client=model_client,
+            tools=wrapped_tools or None,
+            **kwargs,
+        )