controlzero 1.0.0__py3-none-any.whl

controlzero/cli/templates/langchain.yaml

@@ -0,0 +1,89 @@
+# controlzero policy: LangChain / LangGraph template
+# Schema version 1
+#
+# This template is opinionated for LangChain and LangGraph agents. The
+# assumption: your agent is a chain of Tools, and you want each Tool call
+# gated by Control Zero before it executes.
+#
+# Wire it into code:
+#
+#   from controlzero import Client
+#   from langchain_core.tools import tool
+#
+#   cz = Client(policy_file="./controlzero.yaml")
+#
+#   @tool
+#   def delete_user(user_id: str) -> str:
+#       cz.guard("delete_user", {"user_id": user_id})
+#       # ... your delete logic ...
+#
+# The guard() call raises PolicyDeniedError if the policy denies. Your
+# LangGraph state machine can catch it and route to a human-in-the-loop
+# node, or just propagate it as a tool error back to the model.
+#
+# What this template blocks out of the box:
+#   - Destructive DB tools (drop, truncate, delete_all)
+#   - Filesystem writes to sensitive paths
+#   - Outbound network to arbitrary hosts
+#
+# What it allows:
+#   - Read-heavy tools (search, lookup, fetch_*)
+#   - Scoped writes (insert, update, append)
+#
+# Customize the allow/deny lists at the bottom for your own tool names.
+
+version: '1'
+
+rules:
+  # ============================================================
+  # DENY: destructive DB operations
+  # ============================================================
+  - id: deny-db-drop
+    deny: 'db_drop_*'
+    reason: 'Dropping database objects requires manual approval'
+
+  - id: deny-db-truncate
+    deny: 'db_truncate_*'
+    reason: 'Truncating tables is destructive; requires manual approval'
+
+  - id: deny-bulk-delete
+    deny: 'delete_all_*'
+    reason: 'Bulk deletes require manual approval'
+
+  # ============================================================
+  # DENY: filesystem writes to sensitive paths
+  # ============================================================
+  # v0.1 can only match on tool name, not arguments. This denies
+  # any Tool named *_etc_* or *_ssh_* as a defensive first pass.
+  - id: deny-fs-etc
+    deny: '*_etc_*'
+    reason: 'Writes to /etc are blocked'
+
+  - id: deny-fs-ssh
+    deny: '*_ssh_*'
+    reason: 'SSH config writes are blocked'
+
+  # ============================================================
+  # ALLOW: common LangChain tool names
+  # ============================================================
+  - id: allow-search
+    allow: 'search*'
+    reason: 'Search tools are safe by default'
+
+  - id: allow-fetch
+    allow: 'fetch_*'
+    reason: 'Fetch tools are safe by default'
+
+  - id: allow-lookup
+    allow: 'lookup_*'
+    reason: 'Lookup tools are safe by default'
+
+  - id: allow-list
+    allow: 'list_*'
+    reason: 'List tools are safe by default'
+
+  # ============================================================
+  # Default: deny anything not explicitly allowed (fail-closed)
+  # ============================================================
+  # No catch-all allow at the bottom. The v0.1 evaluator already
+  # fails closed, so anything that falls through lands in deny.

controlzero/cli/templates/mcp.yaml

@@ -0,0 +1,79 @@
+# controlzero policy file: MCP server template
+# Schema version 1
+#
+# This template is for MCP (Model Context Protocol) servers. It assumes you
+# expose tools to AI assistants like Claude Desktop, Claude Code, Cursor, etc.
+#
+# Goals:
+#   - Allow read/list/search tools by default
+#   - Require explicit allow for write/delete tools
+#   - Block dangerous operations entirely
+#
+# Run:
+#   controlzero validate controlzero.yaml
+#   controlzero test fs:delete --policy controlzero.yaml
+
+version: '1'
+
+rules:
+  # ---------- ALLOW: read-only operations across all MCP tools ----------
+  - id: allow-mcp-reads
+    allow: '*:read'
+    reason: 'All MCP read methods are allowed'
+
+  - id: allow-mcp-lists
+    allow: '*:list'
+    reason: 'All MCP list methods are allowed'
+
+  - id: allow-mcp-search
+    allow: '*:search'
+    reason: 'All MCP search methods are allowed'
+
+  - id: allow-mcp-get
+    allow: '*:get'
+    reason: 'All MCP get methods are allowed'
+
+  # ---------- ALLOW: scoped writes for known-good tools ----------
+  - id: allow-notes-write
+    allow: 'notes:create'
+    reason: 'Creating notes is fine'
+
+  - id: allow-tasks-update
+    allow: 'tasks:update'
+    reason: 'Updating task state is fine'
+
+  # ---------- DENY: dangerous filesystem operations ----------
+  - id: deny-fs-delete
+    deny: 'fs:delete'
+    reason: 'Filesystem deletes require human approval'
+
+  - id: deny-fs-write
+    deny: 'fs:write'
+    reason: 'Filesystem writes require explicit allow per path'
+
+  # ---------- DENY: code execution ----------
+  - id: deny-shell
+    deny: 'shell:*'
+    reason: 'Shell commands are blocked'
+
+  - id: deny-exec
+    deny: 'exec:*'
+    reason: 'Process execution is blocked'
+
+  # ---------- DENY: network egress ----------
+  - id: deny-http-post
+    deny: 'http:post'
+    reason: 'Outbound POST blocked, use a specific tool'
+
+  - id: deny-http-put
+    deny: 'http:put'
+    reason: 'Outbound PUT blocked, use a specific tool'
+
+  - id: deny-http-delete
+    deny: 'http:delete'
+    reason: 'Outbound DELETE blocked'
+
+  # ---------- DENY: catch-all ----------
+  - id: catch-all-deny
+    deny: '*'
+    reason: 'MCP tool not on the allow list. Add a rule above to permit it.'

controlzero/cli/templates/rag.yaml

@@ -0,0 +1,63 @@
+# controlzero policy file: RAG / agent template
+# Schema version 1
+#
+# This template is for retrieval-augmented generation (RAG) and agent apps.
+# Goals:
+#   - Allow the agent to read from your knowledge base and search the web
+#   - Block exfiltration: writes to external systems, file deletes, code exec
+#   - Allow well-defined tool calls; deny anything novel
+#
+# Run:
+#   controlzero validate controlzero.yaml
+#   controlzero test exfiltrate_data --policy controlzero.yaml
+
+version: '1'
+
+rules:
+  # ---------- ALLOW: knowledge base reads ----------
+  - id: allow-vector-search
+    allow: 'vector_search'
+    reason: 'Vector search over our own knowledge base is safe'
+
+  - id: allow-document-fetch
+    allow: 'fetch_document'
+    reason: 'Fetching documents from our KB is safe'
+
+  - id: allow-web-search
+    allow: 'web_search'
+    reason: 'Read-only web search is allowed'
+
+  # ---------- ALLOW: model and tool inspection ----------
+  - id: allow-list-tools
+    allow: 'list_*'
+    reason: 'Listing/inspecting tools is read-only'
+
+  # ---------- DENY: exfiltration vectors ----------
+  - id: deny-http-post
+    deny: 'http_post'
+    reason: 'Outbound POST is a data exfiltration vector'
+
+  - id: deny-send-email
+    deny: 'send_email'
+    reason: 'Email sends require human approval'
+
+  - id: deny-shell-exec
+    deny: 'shell_exec'
+    reason: 'Shell execution is high risk'
+
+  - id: deny-eval
+    deny: 'eval'
+    reason: 'Code eval is forbidden'
+
+  - id: deny-file-writes
+    deny: 'write_*'
+    reason: 'File writes from agents are blocked'
+
+  - id: deny-file-deletes
+    deny: 'delete_*'
+    reason: 'File deletes are blocked'
+
+  # ---------- DENY: catch-all ----------
+  - id: catch-all-deny
+    deny: '*'
+    reason: 'Default deny: tool not on the allow list for this RAG app'

controlzero/client.py

@@ -0,0 +1,398 @@
+"""ControlZero Client. The user-facing entry point.
+
+Three states, one client:
+
+  state                          policy source        audit destination
+  ---------------------------------------------------------------------
+  no API key + local policy      local (dict/file)    local rotated log
+  API key + no local policy      dashboard (hosted)   remote audit trail
+  API key + local policy         local OVERRIDES      remote audit trail
+                                  + WARN log
+  no API key + no local policy   none                 stderr (one warning)
+                                  + pass-through
+
+Resolution order for finding a policy:
+  1. explicit `policy=` or `policy_file=` arg
+  2. CONTROLZERO_POLICY_FILE env var
+  3. ./controlzero.yaml in cwd
+  4. CONTROLZERO_API_KEY env var (hosted mode)
+  5. nothing => no-op pass-through with one-time stderr warning
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import warnings
+from pathlib import Path
+from typing import Any, Optional, Union
+
+from controlzero._internal.dlp_scanner import (
+    DLPScanner,
+    load_dlp_rules_from_policy,
+)
+from controlzero._internal.enforcer import (
+    PolicyDecision,
+    PolicyDeniedError,
+    PolicyEvaluator,
+)
+from controlzero.audit_local import LocalAuditLogger
+from controlzero.audit_remote import RemoteAuditSink
+from controlzero.errors import (
+    HostedModeNotImplemented,
+    HybridModeError,
+    PolicyLoadError,
+    PolicyValidationError,
+)
+from controlzero.policy_loader import load_policy
+
+# One-time warning state per process
+_NO_POLICY_WARNED = False
+_HYBRID_WARNED = False
+
+
+class Client:
+    """The ControlZero policy client.
+
+    Hello World (no API key, no signup):
+
+        from controlzero import Client
+
+        cz = Client(policy={
+            "rules": [{"deny": "delete_*", "reason": "Hello World"}]
+        })
+
+        result = cz.guard("delete_file", {"path": "/tmp/foo"})
+        print(result.decision)  # "deny"
+
+    Hosted mode (with API key, audit ships to dashboard):
+
+        cz = Client(api_key="cz_live_...")  # or set CONTROLZERO_API_KEY env var
+
+    Hybrid (API key + local policy override): emits a WARN log on init.
+    Use `strict_hosted=True` to raise instead of warn.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        policy: Optional[dict] = None,
+        policy_file: Optional[Union[str, Path]] = None,
+        strict_hosted: bool = False,
+        log_path: str = "./controlzero.log",
+        log_rotation: str = "daily",
+        log_retention: str = "30 days",
+        log_compression: Optional[str] = None,
+        log_format: str = "json",
+    ):
+        if policy is not None and policy_file is not None:
+            raise ValueError(
+                "Pass either `policy` or `policy_file`, not both."
+            )
+
+        # Resolve API key from arg or env
+        self._api_key = api_key or os.environ.get("CONTROLZERO_API_KEY")
+
+        # Resolve local policy source
+        local_source = self._resolve_local_source(policy, policy_file)
+
+        # Decide mode
+        self._has_api_key = bool(self._api_key)
+        self._has_local_policy = local_source is not None
+
+        # SECURITY: Hosted mode is not implemented in this slim package.
+        # If a user sets CONTROLZERO_API_KEY without a local policy, they expect
+        # remote dashboard policies to enforce their tool calls. Silently
+        # returning "allow" for everything would be a security incident waiting
+        # to happen. Refuse to construct, loud and immediate.
+        if self._has_api_key and not self._has_local_policy:
+            raise HostedModeNotImplemented(
+                "controlzero: hosted mode (dashboard policies + remote audit) "
+                "is not yet implemented in this package.\n"
+                "  - For local mode, provide a policy: Client(policy={...}) "
+                "or Client(policy_file='./controlzero.yaml')\n"
+                "  - For hosted mode today, install the legacy package: "
+                "pip install 'control-zero<=0.3.0'\n"
+                "  - Hosted mode in this package is coming in a future release."
+            )
+
+        # Hybrid detection: API key + local policy
+        if self._has_api_key and self._has_local_policy:
+            self._handle_hybrid(strict_hosted)
+
+        # Load local policy if present
+        self._evaluator: Optional[PolicyEvaluator] = None
+        if self._has_local_policy:
+            try:
+                rules = load_policy(local_source)
+            except (PolicyLoadError, PolicyValidationError):
+                # Re-raise: caller needs to fix their config
+                raise
+
+            # Initialize DLP scanner with built-in patterns + any custom
+            # dlp_rules from the policy file.
+            dlp_scanner = DLPScanner()
+            raw_policy_data = self._get_raw_policy_data(local_source)
+            if raw_policy_data:
+                custom_dlp = load_dlp_rules_from_policy(raw_policy_data)
+                if custom_dlp:
+                    dlp_scanner.add_rules(custom_dlp)
+
+            self._evaluator = PolicyEvaluator(rules, dlp_scanner=dlp_scanner)
+
+        # Set up local audit logger ONLY in pure-local mode.
+        # When hosted, audit goes through the remote forwarder (not implemented in
+        # this skinny client; see hosted SDK in the legacy package for now).
+        self._audit: Optional[LocalAuditLogger] = None
+        if not self._has_api_key:
+            # log_* options are honored
+            self._audit = LocalAuditLogger(
+                log_path=log_path,
+                rotation=log_rotation,
+                retention=log_retention,
+                compression=log_compression,
+                log_format=log_format,
+            )
+        else:
+            # Hosted: log_* options are ignored. Warn if user tried to set them.
+            user_set_log_opts = (
+                log_path != "./controlzero.log"
+                or log_rotation != "daily"
+                or log_retention != "30 days"
+                or log_compression is not None
+                or log_format != "json"
+            )
+            if user_set_log_opts:
+                warnings.warn(
+                    "controlzero: log_* options are ignored when an API key is set "
+                    "(audit is managed server-side).",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+        # Set up remote audit sink if this machine is enrolled.
+        # The remote sink is additive: local file is always written first,
+        # then the entry is buffered for async POST to the backend.
+        self._remote_sink: Optional[RemoteAuditSink] = None
+        self._init_remote_sink()
+
+    # ---------------- public API ----------------
+
+    def guard(
+        self,
+        tool: str,
+        args: Optional[dict] = None,
+        method: str = "*",
+        raise_on_deny: bool = False,
+        context: Optional[dict] = None,
+    ) -> PolicyDecision:
+        """Evaluate a tool call against the loaded policy.
+
+        Args:
+            tool: The tool name (e.g. "delete_file", "github").
+            args: The arguments the tool would be called with. Logged for audit.
+            method: Optional method name. Defaults to "*" (any method).
+            raise_on_deny: If True, raises PolicyDeniedError on a deny decision.
+            context: Optional context dict with `resource` and `tags` keys for
+                     resource-level matching and identity tags.
+
+        Returns:
+            PolicyDecision. Always returns; never raises unless raise_on_deny.
+        """
+        if self._evaluator is None:
+            return self._noop_decision(tool, method)
+
+        try:
+            decision = self._evaluator.evaluate(
+                tool, method, context=context, args=args,
+            )
+        except Exception as e:
+            # Fail closed on any evaluator crash. NEVER allow on error.
+            decision = PolicyDecision(
+                effect="deny",
+                reason=f"Evaluator error: {type(e).__name__}: {e}. Failing closed.",
+            )
+
+        self._audit_decision(tool, method, args or {}, decision, context=context)
+
+        if raise_on_deny and decision.denied:
+            raise PolicyDeniedError(decision)
+
+        return decision
+
+    def close(self) -> None:
+        """Flush and close audit sinks (local + remote)."""
+        if self._remote_sink is not None:
+            self._remote_sink.close()
+            self._remote_sink = None
+        if self._audit is not None:
+            self._audit.close()
+            self._audit = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+
+    # ---------------- internals ----------------
+
+    def _init_remote_sink(self) -> None:
+        """Create a RemoteAuditSink if this machine is enrolled.
+
+        Enrollment state lives in ~/.controlzero/enrollment.json. If the
+        file exists and is valid, we create a sink that will buffer audit
+        entries and POST them to the backend asynchronously. If enrollment
+        is absent or the enrollment module is not installed (no 'hosted'
+        extras), we silently skip -- local audit still works.
+        """
+        try:
+            from controlzero.enrollment import load_state
+        except ImportError:
+            # 'hosted' extras not installed -- no remote audit
+            return
+
+        try:
+            state = load_state()
+        except Exception:
+            return
+
+        if state is None:
+            return
+
+        if not state.api_url or not state.machine_id or not state.org_id:
+            return
+
+        try:
+            self._remote_sink = RemoteAuditSink(
+                api_url=state.api_url,
+                machine_token="",  # auth via signed request headers
+                org_id=state.org_id,
+                machine_id=state.machine_id,
+            )
+        except Exception:
+            # Any failure creating the sink should not block the client
+            pass
+
+    @staticmethod
+    def _get_raw_policy_data(
+        source: Union[dict, Path],
+    ) -> Optional[dict]:
+        """Read the raw policy dict to extract non-rule sections (e.g. dlp_rules).
+
+        If source is already a dict, return it directly. If it is a file path,
+        parse it again to get the full dict (including sections that load_policy
+        strips out).
+        """
+        if isinstance(source, dict):
+            return source
+        if isinstance(source, Path) and source.exists():
+            import json as _json
+            text = source.read_text(encoding="utf-8")
+            suffix = source.suffix.lower()
+            if suffix in (".yaml", ".yml"):
+                try:
+                    import yaml
+                    return yaml.safe_load(text)
+                except Exception:
+                    return None
+            elif suffix == ".json":
+                try:
+                    return _json.loads(text)
+                except Exception:
+                    return None
+        return None
+
+    def _resolve_local_source(
+        self,
+        policy: Optional[dict],
+        policy_file: Optional[Union[str, Path]],
+    ) -> Optional[Union[dict, Path]]:
+        """Find a local policy source by priority order."""
+        if policy is not None:
+            return policy
+        if policy_file is not None:
+            return Path(policy_file)
+
+        env_path = os.environ.get("CONTROLZERO_POLICY_FILE")
+        if env_path:
+            return Path(env_path)
+
+        cwd_default = Path.cwd() / "controlzero.yaml"
+        if cwd_default.exists():
+            return cwd_default
+
+        return None
+
+    def _handle_hybrid(self, strict: bool) -> None:
+        """API key + local policy = hybrid. Warn loudly or raise."""
+        global _HYBRID_WARNED
+        msg = (
+            "controlzero: manual policy override detected. "
+            "An API key is set AND a local policy was provided; the local policy "
+            "will be used and the dashboard policy will be IGNORED for this client "
+            "instance. Audit will still ship to the remote dashboard. "
+            "If this is unintentional, remove the local policy or unset CONTROLZERO_API_KEY."
+        )
+        if strict:
+            raise HybridModeError(msg + " (strict_hosted=True)")
+        if not _HYBRID_WARNED:
+            print("WARNING: " + msg, file=sys.stderr)
+            _HYBRID_WARNED = True
+
+    def _noop_decision(self, tool: str, method: str) -> PolicyDecision:
+        """No policy configured: pass through with a one-time warning."""
+        global _NO_POLICY_WARNED
+        if not _NO_POLICY_WARNED:
+            print(
+                "WARNING: controlzero: no policy configured, calls are not being checked. "
+                "Pass `policy=...`, `policy_file=...`, set CONTROLZERO_POLICY_FILE, "
+                "create ./controlzero.yaml, or set CONTROLZERO_API_KEY.",
+                file=sys.stderr,
+            )
+            _NO_POLICY_WARNED = True
+        return PolicyDecision(
+            effect="allow",
+            reason="No policy configured (pass-through)",
+            policy_id="<noop>",
+        )
+
+    def _audit_decision(
+        self,
+        tool: str,
+        method: str,
+        args: dict,
+        decision: PolicyDecision,
+        context: Optional[dict] = None,
+    ) -> None:
+        entry = {
+            "decision": decision.effect,
+            "tool": tool,
+            "method": method,
+            "policy_id": decision.policy_id,
+            "reason": decision.reason,
+            "args_keys": sorted(args.keys()),
+            "mode": "local",
+        }
+        # Include DLP findings in audit entry
+        if decision.dlp_findings:
+            entry["dlp_findings"] = decision.dlp_findings
+
+        # Include tamper detection flags from context if present
+        if context is not None:
+            if "tamper_detected" in context:
+                entry["tamper_detected"] = context["tamper_detected"]
+            if "audit_chain_broken" in context:
+                entry["audit_chain_broken"] = context["audit_chain_broken"]
+
+        # Local file first (always)
+        if self._audit is not None:
+            self._audit.log(entry)
+
+        # Remote sink second (best-effort, non-blocking)
+        if self._remote_sink is not None:
+            try:
+                self._remote_sink.log(entry)
+            except Exception:
+                # Never let remote sink failure affect the caller
+                pass