controlzero 1.0.0__py3-none-any.whl

controlzero/_internal/enforcer.py

@@ -0,0 +1,210 @@
+"""Local policy evaluator. Pure Python, in-process, fail-closed by default.
+
+Copied from the proven control_zero.policy.enforcer module and adapted for the
+local-first surface. The eval logic is identical so behavior is consistent
+across hosted and local modes.
+
+Pattern matching uses Python's stdlib fnmatch (shell-style globs). All friendly
+shorthand (e.g. "delete_*" -> "delete_*:*") is normalized in policy_loader.py
+BEFORE rules reach this evaluator. By the time rules arrive here, every action
+is canonical "tool:method" form. This keeps the evaluator simple and matches
+the legacy hosted engine's behavior.
+
+DLP scanning (added 2026-04-09): after the tool-name policy check, the
+evaluator optionally scans tool arguments for PII, secrets, and sensitive data
+patterns. A "block" DLP match overrides an "allow" decision. "detect" matches
+are recorded in the audit entry without blocking.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from controlzero._internal.dlp_scanner import (
+    DLPMatch,
+    DLPScanner,
+    extract_text_from_args,
+)
+from controlzero._internal.types import PolicyRule
+
+
+@dataclass
+class PolicyDecision:
+    """Result of a policy evaluation.
+
+    Attributes:
+        effect: One of "allow", "deny", "warn", "audit".
+        decision: Alias for effect, for ergonomic Hello World code.
+        policy_id: ID of the rule that matched, or None if no match.
+        reason: Human-readable reason for the decision.
+        evaluated_rules: How many rules were checked before a match.
+        dlp_findings: List of DLP match dicts for the audit trail.
+    """
+    effect: str
+    policy_id: Optional[str] = None
+    reason: Optional[str] = None
+    evaluated_rules: int = 0
+    dlp_findings: list[dict] = field(default_factory=list)
+
+    @property
+    def decision(self) -> str:
+        """Alias for `effect`. Reads more naturally in user code."""
+        return self.effect
+
+    @property
+    def allowed(self) -> bool:
+        """True if the call was allowed."""
+        return self.effect == "allow"
+
+    @property
+    def denied(self) -> bool:
+        """True if the call was denied."""
+        return self.effect == "deny"
+
+
+class PolicyDeniedError(Exception):
+    """Raised by `Client.guard(..., raise_on_deny=True)` when a policy denies an action."""
+
+    def __init__(self, decision: PolicyDecision):
+        self.decision = decision
+        super().__init__(
+            f"Policy denied: {decision.reason or 'no reason provided'}"
+        )
+
+
+class PolicyEvaluator:
+    """In-process policy evaluator. Fail-closed by default.
+
+    Loads a list of internal `PolicyRule` objects and evaluates tool calls
+    against them in order. The first matching rule wins. If no rule matches,
+    the call is denied (fail-closed).
+
+    Optionally accepts a DLPScanner to inspect tool arguments for sensitive
+    content after the tool-name policy check passes.
+
+    All pattern matching uses `fnmatch.fnmatchcase` (shell-style globs):
+        *           matches everything
+        delete_*    matches anything starting with "delete_"
+        github:*    matches any method on the github tool
+        *:read      matches the read method on any tool
+        model:*-haiku-*  matches any model with -haiku- in its name
+    """
+
+    def __init__(
+        self,
+        rules: Optional[list[PolicyRule]] = None,
+        dlp_scanner: Optional[DLPScanner] = None,
+    ):
+        self._rules: list[PolicyRule] = rules or []
+        self._dlp_scanner: Optional[DLPScanner] = dlp_scanner
+
+    def load(self, rules: list[PolicyRule]) -> None:
+        """Replace the rule set."""
+        self._rules = list(rules)
+
+    def set_dlp_scanner(self, scanner: DLPScanner) -> None:
+        """Set or replace the DLP scanner."""
+        self._dlp_scanner = scanner
+
+    def evaluate(
+        self,
+        tool: str,
+        method: str = "*",
+        context: Optional[dict] = None,
+        args: Optional[dict] = None,
+    ) -> PolicyDecision:
+        """Evaluate a tool call against the loaded rules.
+
+        Args:
+            tool: Tool name (e.g. "delete_file", "github").
+            method: Optional method name. Defaults to "*" which matches any.
+            context: Optional context dict with `resource` and `tags` keys.
+            args: Optional tool arguments dict. Scanned for DLP patterns if
+                  a DLPScanner is configured.
+
+        Returns:
+            PolicyDecision. Always returns; never raises.
+        """
+        action = f"{tool}:{method}"
+        resource = (context or {}).get("resource")
+        evaluated = 0
+
+        for rule in self._rules:
+            evaluated += 1
+            if not _glob_any(rule.actions, action):
+                continue
+            if rule.resources:
+                if not resource or not _glob_any(rule.resources, resource):
+                    continue
+            decision = PolicyDecision(
+                effect=rule.effect,
+                policy_id=rule.id or rule.name or None,
+                # User-provided reason wins. Falls back to canned text only if
+                # the rule had no `reason:` field in the source policy.
+                reason=rule.reason or f"Matched rule {rule.id or rule.name}".strip(),
+                evaluated_rules=evaluated,
+            )
+            # DLP scan: only when the policy decision is "allow" and args exist
+            if decision.allowed and args and self._dlp_scanner is not None:
+                decision = self._apply_dlp_scan(decision, args)
+            return decision
+
+        # Fail-closed default. No matching rule means deny.
+        return PolicyDecision(
+            effect="deny",
+            reason="No matching policy rule (fail-closed default)",
+            evaluated_rules=evaluated,
+        )
+
+    def _apply_dlp_scan(
+        self, decision: PolicyDecision, args: dict
+    ) -> PolicyDecision:
+        """Run DLP scanner on tool arguments and update decision if needed.
+
+        If any DLP rule has action="block", the decision is overridden to DENY.
+        If rules have action="detect" or "mask", findings are attached to the
+        decision for audit but the call is still allowed.
+        """
+        if self._dlp_scanner is None:
+            return decision
+
+        text = extract_text_from_args(args)
+        if not text:
+            return decision
+
+        matches = self._dlp_scanner.scan(text)
+        if not matches:
+            return decision
+
+        findings = self._dlp_scanner.get_findings_for_audit(matches)
+        decision.dlp_findings = findings
+
+        if self._dlp_scanner.has_blocking_match(matches):
+            # Find the first blocking rule for the reason message
+            blocking = next(m for m in matches if m.action == "block")
+            return PolicyDecision(
+                effect="deny",
+                policy_id=decision.policy_id,
+                reason=(
+                    f"DLP rule '{blocking.rule_name}' matched "
+                    f"{blocking.category} content in tool arguments"
+                ),
+                evaluated_rules=decision.evaluated_rules,
+                dlp_findings=findings,
+            )
+
+        return decision
+
+
+def _glob_any(patterns: list[str], value: str) -> bool:
+    """True if any pattern matches the value via fnmatch.fnmatchcase.
+
+    fnmatchcase is case-sensitive (matches policy semantics) and supports the
+    same syntax users learn from .gitignore: *, ?, [seq], [!seq].
+    """
+    for p in patterns:
+        if fnmatch.fnmatchcase(value, p):
+            return True
+    return False

controlzero/_internal/types.py

@@ -0,0 +1,19 @@
+"""Internal type definitions. Public users should import from controlzero, not here."""
+
+from typing import Any, Optional
+from pydantic import BaseModel, Field
+
+
+class PolicyRule(BaseModel):
+    """Internal canonical representation of a single policy rule.
+
+    The user-facing schema (see policy_loader) is friendlier; this is what the
+    evaluator consumes after translation.
+    """
+    id: str = ""
+    name: str = ""
+    effect: str  # "allow" or "deny"
+    actions: list[str] = Field(default_factory=list)
+    resources: list[str] = Field(default_factory=list)
+    conditions: dict[str, Any] = Field(default_factory=dict)
+    reason: str = ""  # Human-readable explanation, surfaced in audit + denies

controlzero/audit_local.py

@@ -0,0 +1,128 @@
+"""Local audit log sink built on loguru.
+
+When the SDK runs without an API key, audit entries are written to a local file
+with rotation. This module isolates the loguru config so the rest of the SDK
+does not depend on loguru directly.
+
+When an API key is set, this module is bypassed entirely and audit goes to the
+remote forwarder. The user-supplied log_* options are ignored with a warning
+(see Client.__init__).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+
+class LocalAuditLogger:
+    """Writes audit entries to a local rotated log file via loguru.
+
+    Falls back to stderr if the configured log path is not writable.
+    """
+
+    def __init__(
+        self,
+        log_path: str = "./controlzero.log",
+        rotation: str = "daily",
+        retention: str = "30 days",
+        compression: Optional[str] = None,
+        log_format: str = "json",
+    ):
+        self._log_path = log_path
+        self._rotation = rotation
+        self._retention = retention
+        self._compression = compression
+        self._format = log_format
+        self._logger = None
+        self._sink_id: Optional[int] = None
+        self._fallback = False
+        # Per-instance component tag prevents cross-instance log duplication
+        # when multiple Client objects exist in the same process. Each loguru
+        # sink filters on its own component string.
+        self._component = f"controlzero.audit.{id(self)}"
+        self._setup()
+
+    def _setup(self) -> None:
+        try:
+            from loguru import logger as _logger
+        except ImportError:
+            print(
+                "controlzero: loguru not installed, audit logs will go to stderr.",
+                file=sys.stderr,
+            )
+            self._fallback = True
+            return
+
+        path = Path(self._log_path)
+        try:
+            # Make sure the parent directory exists and is writable
+            parent = path.parent
+            if str(parent) and not parent.exists():
+                parent.mkdir(parents=True, exist_ok=True)
+
+            # Translate "daily" sugar to a loguru-friendly value
+            rotation_value: Any = self._rotation
+            if self._rotation == "daily":
+                rotation_value = "00:00"
+
+            self._logger = _logger.bind(component=self._component)
+            # Add a dedicated sink filtered on this instance's component tag,
+            # so each Client gets its own sink and lines never duplicate
+            # across instances. Capture self._component in the lambda's
+            # default arg to avoid late-binding issues.
+            comp = self._component
+            self._sink_id = _logger.add(
+                str(path),
+                rotation=rotation_value,
+                retention=self._retention,
+                compression=self._compression,
+                serialize=False,  # we format ourselves
+                format="{message}",
+                filter=lambda record, c=comp: record["extra"].get("component") == c,
+                enqueue=True,  # async-safe
+            )
+        except (OSError, PermissionError) as e:
+            print(
+                f"controlzero: cannot write to {self._log_path} ({e}), "
+                "falling back to stderr.",
+                file=sys.stderr,
+            )
+            self._fallback = True
+
+    def log(self, entry: dict) -> None:
+        """Write a single audit entry."""
+        line = self._format_entry(entry)
+        if self._fallback or self._logger is None:
+            print(line, file=sys.stderr)
+            return
+        self._logger.info(line)
+
+    def _format_entry(self, entry: dict) -> str:
+        # Always include a timestamp in UTC ISO 8601
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            **entry,
+        }
+        if self._format == "pretty":
+            # Compact human-readable form: ts | decision | tool | reason
+            parts = [
+                record.get("ts", ""),
+                record.get("decision", "?"),
+                record.get("tool", "?"),
+                record.get("reason", ""),
+            ]
+            return " | ".join(str(p) for p in parts)
+        return json.dumps(record, default=str)
+
+    def close(self) -> None:
+        if self._logger is not None and self._sink_id is not None:
+            try:
+                from loguru import logger as _logger
+                _logger.remove(self._sink_id)
+            except Exception:
+                pass
+            self._sink_id = None

controlzero/audit_remote.py

@@ -0,0 +1,221 @@
+"""Remote audit sink -- batches local audit entries and POSTs them to the backend.
+
+When an enrolled SDK evaluates a tool call, the decision is written to the local
+audit log first (fire-and-forget). This module buffers those entries and
+periodically flushes them to ``POST /api/audit`` on the backend so the
+governance admin dashboard shows real data from CLI hooks (Claude Code,
+Gemini CLI, Codex CLI, etc.).
+
+Design constraints:
+  - NEVER block or crash the hook-check critical path. Local audit is
+    always written first; remote is best-effort.
+  - Thread-safe: multiple guard() calls from different threads share
+    one buffer protected by a lock.
+  - Flush runs in a daemon thread so shutdown of the main process is
+    not blocked by a slow network.
+  - On 401 the sink disables itself (enrollment expired).
+  - On transient errors the buffer is retained for the next flush cycle.
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+import logging
+import platform
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+logger = logging.getLogger("controlzero.audit_remote")
+
+# Buffer limits
+MAX_BUFFER_SIZE = 50
+FLUSH_INTERVAL_S = 30.0
+FLUSH_TIMEOUT_S = 2.0
+
+
+class RemoteAuditSink:
+    """Buffers audit entries and flushes them to the backend in batches."""
+
+    def __init__(
+        self,
+        api_url: str,
+        machine_token: str,  # not used for auth header, kept for future
+        org_id: str,
+        machine_id: str,
+        state_dir: Optional["Path"] = None,
+    ):
+        self._api_url = api_url.rstrip("/")
+        self._machine_token = machine_token
+        self._org_id = org_id
+        self._machine_id = machine_id
+        self._state_dir = state_dir
+
+        self._buffer: list[dict] = []
+        self._lock = threading.Lock()
+        self._disabled = False
+        self._closed = False
+
+        # Start the periodic flush timer
+        self._start_flush_timer()
+
+    # ---- public API ----
+
+    def log(self, entry: dict) -> None:
+        """Append an audit entry to the buffer. Triggers flush if buffer is full."""
+        if self._disabled or self._closed:
+            return
+        with self._lock:
+            self._buffer.append(self._to_wire_format(entry))
+            should_flush = len(self._buffer) >= MAX_BUFFER_SIZE
+        if should_flush:
+            self._flush_async()
+
+    def close(self) -> None:
+        """Final flush on shutdown. Blocks briefly to drain the buffer."""
+        if self._closed:
+            return
+        self._closed = True
+        self._cancel_flush_timer()
+        # Synchronous flush -- we are shutting down
+        self._flush_sync()
+
+    # ---- wire format mapping ----
+
+    def _to_wire_format(self, entry: dict) -> dict:
+        """Map from the local audit entry shape to the backend wire format.
+
+        Backend expects (from audit_ingest_handler.go AuditIngestEntry):
+          id, user, tool_name, decision, policy_id, rule_id, reason,
+          hostname, mode, ts, verbosity_level
+        """
+        hostname = platform.node() or "unknown"
+        user = ""
+        try:
+            user = getpass.getuser()
+        except Exception:
+            pass
+
+        return {
+            "id": str(uuid.uuid4()),
+            "tool_name": entry.get("tool", ""),
+            "decision": entry.get("decision", "allow"),
+            "policy_id": entry.get("policy_id", ""),
+            "rule_id": entry.get("policy_id", ""),  # local entries use policy_id as rule_id
+            "reason": entry.get("reason", ""),
+            "hostname": hostname,
+            "user": user,
+            "mode": entry.get("mode", "local"),
+            "ts": datetime.now(timezone.utc).isoformat(),
+        }
+
+    # ---- flush mechanics ----
+
+    def _flush_async(self) -> None:
+        """Run flush in a daemon thread so it never blocks the caller."""
+        t = threading.Thread(target=self._flush_sync, daemon=True)
+        t.start()
+
+    def _flush_sync(self) -> None:
+        """POST buffered entries to the backend. On success, clear buffer."""
+        with self._lock:
+            if not self._buffer or self._disabled:
+                return
+            batch = list(self._buffer)
+
+        try:
+            self._post_batch(batch)
+            # Success: remove the flushed entries from the buffer
+            with self._lock:
+                # Only remove the entries we successfully sent; new entries
+                # may have been appended while we were posting.
+                self._buffer = self._buffer[len(batch):]
+        except _AuthExpiredError:
+            logger.warning(
+                "controlzero: remote audit sink disabled -- enrollment expired (401)"
+            )
+            with self._lock:
+                self._disabled = True
+                self._buffer.clear()
+        except Exception as exc:
+            # Transient error: keep entries in buffer for next flush
+            logger.warning(
+                "controlzero: remote audit flush failed (%s); "
+                "entries retained for retry",
+                exc,
+            )
+
+    def _post_batch(self, batch: list[dict]) -> None:
+        """Send a batch of entries to POST /api/audit with signed headers."""
+        try:
+            from controlzero.enrollment import load_state, sign_request
+        except ImportError:
+            # enrollment module not available -- cannot send
+            raise _AuthExpiredError("enrollment module not available")
+
+        state = load_state(self._state_dir) if self._state_dir else load_state()
+        if state is None:
+            raise _AuthExpiredError("no enrollment state")
+
+        body = json.dumps({"entries": batch}).encode("utf-8")
+        state_dir_kwarg = {"state_dir": self._state_dir} if self._state_dir else {}
+        headers = sign_request(state, "POST", "/api/audit", body, **state_dir_kwarg)
+        headers["Content-Type"] = "application/json"
+
+        try:
+            import httpx
+        except ImportError:
+            raise _AuthExpiredError("httpx not available")
+
+        resp = httpx.post(
+            f"{self._api_url}/api/audit",
+            content=body,
+            headers=headers,
+            timeout=FLUSH_TIMEOUT_S,
+        )
+        if resp.status_code == 401:
+            raise _AuthExpiredError("server returned 401")
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"audit ingest returned HTTP {resp.status_code}: {resp.text}"
+            )
+
+    # ---- periodic timer ----
+
+    def _start_flush_timer(self) -> None:
+        """Schedule the next periodic flush."""
+        if self._closed or self._disabled:
+            return
+        self._timer = threading.Timer(FLUSH_INTERVAL_S, self._on_timer)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _cancel_flush_timer(self) -> None:
+        timer = getattr(self, "_timer", None)
+        if timer is not None:
+            timer.cancel()
+
+    def _on_timer(self) -> None:
+        """Called by the periodic timer. Flush and reschedule."""
+        if self._closed or self._disabled:
+            return
+        self._flush_sync()
+        self._start_flush_timer()
+
+    # ---- properties for testing ----
+
+    @property
+    def disabled(self) -> bool:
+        return self._disabled
+
+    @property
+    def buffer(self) -> list[dict]:
+        with self._lock:
+            return list(self._buffer)
+
+
+class _AuthExpiredError(Exception):
+    """Internal: signals the remote sink should be permanently disabled."""

controlzero/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface for the controlzero SDK."""