controlzero 1.3.0__tar.gz → 1.4.0__tar.gz

{controlzero-1.3.0 → controlzero-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.3.0
+Version: 1.4.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
@@ -27,13 +27,18 @@ Requires-Dist: loguru>=0.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
+Requires-Dist: cryptography>=41.0.0; extra == 'dev'
+Requires-Dist: httpx>=0.25.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 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: 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'
 Description-Content-Type: text/markdown
 
 # control-zero
@@ -158,6 +163,46 @@ rules:
 Rules are evaluated top to bottom. The first match wins. If no rule matches,
 the call is denied (fail-closed).
 
+## Tamper detection and quarantine
+
+The policy YAML supports a `settings:` section that controls how the SDK
+responds when it detects that the local policy file has been modified outside
+of normal channels (manual edits, unexpected hash changes, etc.):
+
+```yaml
+version: '1'
+settings:
+  tamper_behavior: warn # Options: warn | deny | deny-all | quarantine
+rules:
+  - deny: 'delete_*'
+  - allow: '*'
+```
+
+| Mode         | Behavior                                                                 |
+| ------------ | ------------------------------------------------------------------------ |
+| `warn`       | Log a warning but continue evaluating rules normally.                    |
+| `deny`       | Deny the current tool call that triggered the tamper check.              |
+| `deny-all`   | Deny all tool calls and place the machine in quarantine until recovered. |
+| `quarantine` | Same as `deny-all`, plus report a tamper alert to the backend dashboard. |
+
+**Quarantine recovery.** When a machine enters quarantine (`deny-all` or
+`quarantine`), every tool call is denied until you re-establish trust with one
+of these commands:
+
+```bash
+controlzero enroll
+controlzero policy-pull
+controlzero sign-policy
+```
+
+**Org-level policy signing.** When a machine is enrolled via `controlzero enroll`,
+it receives the organization's signing public key. Policy bundles pulled from
+the backend are cryptographically signed and verified by the SDK automatically.
+No extra configuration is required.
+
+**Tamper alert reporting.** In `quarantine` mode, the SDK reports a tamper alert
+to the Control Zero backend so your team can see it on the dashboard.
+
 ## Local audit log
 
 When running without an API key, every decision is written to `./controlzero.log`

{controlzero-1.3.0 → controlzero-1.4.0}/README.md

@@ -120,6 +120,46 @@ rules:
 Rules are evaluated top to bottom. The first match wins. If no rule matches,
 the call is denied (fail-closed).
 
+## Tamper detection and quarantine
+
+The policy YAML supports a `settings:` section that controls how the SDK
+responds when it detects that the local policy file has been modified outside
+of normal channels (manual edits, unexpected hash changes, etc.):
+
+```yaml
+version: '1'
+settings:
+  tamper_behavior: warn # Options: warn | deny | deny-all | quarantine
+rules:
+  - deny: 'delete_*'
+  - allow: '*'
+```
+
+| Mode         | Behavior                                                                 |
+| ------------ | ------------------------------------------------------------------------ |
+| `warn`       | Log a warning but continue evaluating rules normally.                    |
+| `deny`       | Deny the current tool call that triggered the tamper check.              |
+| `deny-all`   | Deny all tool calls and place the machine in quarantine until recovered. |
+| `quarantine` | Same as `deny-all`, plus report a tamper alert to the backend dashboard. |
+
+**Quarantine recovery.** When a machine enters quarantine (`deny-all` or
+`quarantine`), every tool call is denied until you re-establish trust with one
+of these commands:
+
+```bash
+controlzero enroll
+controlzero policy-pull
+controlzero sign-policy
+```
+
+**Org-level policy signing.** When a machine is enrolled via `controlzero enroll`,
+it receives the organization's signing public key. Policy bundles pulled from
+the backend are cryptographically signed and verified by the SDK automatically.
+No extra configuration is required.
+
+**Tamper alert reporting.** In `quarantine` mode, the SDK reports a tamper alert
+to the Control Zero backend so your team can see it on the dashboard.
+
 ## Local audit log
 
 When running without an API key, every decision is written to `./controlzero.log`

controlzero-1.4.0/controlzero/_internal/bundle.py

@@ -0,0 +1,409 @@
+"""Policy bundle parser (`.czpolicy`).
+
+See `docs/designs/policy-bundle-format.md` for the authoritative spec.
+
+This module is a *pure function* parser: given bundle bytes plus the
+project encryption key and the project signing public key, it either
+returns the decrypted policy payload as a dict, or raises a
+:class:`BundleVerificationError` / :class:`BundleFormatError`.
+
+The parser performs **no I/O**. It does not read from disk. It does not
+make network calls. It does not mutate global state. This is
+intentional: the integrity of the policy flow depends on the parser
+being auditable in isolation. All I/O (fetching bundles, caching,
+retries) lives in :mod:`controlzero.hosted_policy`.
+
+Wire format (little-endian throughout):
+
+    offset  size  field
+    0       4     magic           ASCII "CZ01"
+    4       2     schema_version  uint16
+    6       8     created_at      uint64 UNIX seconds
+    14      2     policy_count    uint16 (informational)
+    16      4     sig_offset      uint32 (absolute byte offset of signature)
+    20      4     sig_len         uint32 (must be 64)
+    24      8     reserved        must be zero
+    32      N     payload         authenticated-encryption over zstd(json)
+    32+N    64    signature       signature over header[0:32] || payload
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import dataclass
+from typing import Optional  # noqa: F401  (used in type annotations below)
+
+# --- Exceptions ------------------------------------------------------------
+
+
+class BundleFormatError(ValueError):
+    """Bundle bytes do not match the expected wire format.
+
+    Raised for structural problems: wrong magic, impossible offsets,
+    truncated data, unknown schema version. Never raised for cryptographic
+    failures -- use :class:`BundleVerificationError` for those.
+    """
+
+
+class BundleVerificationError(ValueError):
+    """Bundle signature or AES-GCM authentication tag failed to verify.
+
+    This is the fail-closed signal. The SDK MUST NOT use any policy data
+    extracted before this exception was raised.
+    """
+
+
+# --- Constants -------------------------------------------------------------
+
+_MAGIC = b"CZ01"
+_HEADER_SIZE = 32
+_SIG_LEN = 64
+_SCHEMA_VERSION_MAX = 1
+
+# AES-GCM constants. Matches the backend's encryptAESGCM helper:
+# nonce(12) || ciphertext || tag(16)
+_GCM_NONCE_SIZE = 12
+_GCM_TAG_SIZE = 16
+
+
+# --- Parsed structures -----------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BundleHeader:
+    schema_version: int
+    created_at: int
+    policy_count: int
+    sig_offset: int
+    sig_len: int
+
+
+@dataclass(frozen=True)
+class ParsedBundle:
+    """The decrypted and authenticated policy bundle."""
+
+    header: BundleHeader
+    payload: dict  # the JSON-decoded policy bundle
+
+
+# --- Public API ------------------------------------------------------------
+
+
+def parse_bundle(
+    blob: bytes,
+    encryption_key: bytes,
+    signing_pubkey: bytes,
+    *,
+    max_bundle_bytes: int = 16 * 1024 * 1024,
+) -> ParsedBundle:
+    """Verify signature, decrypt, and decode a policy bundle.
+
+    Args:
+        blob: The raw bundle bytes as returned by ``/v1/sdk/policies/pull``.
+        encryption_key: 32-byte symmetric key for the project.
+        signing_pubkey: 32-byte signing public key for the project.
+        max_bundle_bytes: Defensive cap on bundle size. Rejects huge blobs
+            before doing any crypto work (default 16 MiB).
+
+    Returns:
+        A :class:`ParsedBundle` with the decoded header and payload dict.
+
+    Raises:
+        BundleFormatError: if the wire format is malformed.
+        BundleVerificationError: if the signature does not verify, or if
+            authenticated-encryption tag validation fails.
+    """
+    if not isinstance(blob, (bytes, bytearray)):
+        raise BundleFormatError(
+            f"bundle must be bytes, got {type(blob).__name__}"
+        )
+    blob = bytes(blob)
+
+    if len(blob) > max_bundle_bytes:
+        raise BundleFormatError(
+            f"bundle size {len(blob)} exceeds max {max_bundle_bytes}"
+        )
+
+    header, encrypted_payload, signature = _split_bundle(blob)
+
+    # Signature covers header[0:32] || encrypted_payload. Verify BEFORE
+    # decrypt so we never touch ciphertext for an unauthenticated blob.
+    if len(signing_pubkey) != 32:
+        raise BundleVerificationError(
+            f"signing public key must be 32 bytes, got {len(signing_pubkey)}"
+        )
+    _verify_ed25519(signing_pubkey, blob[:_HEADER_SIZE] + encrypted_payload, signature)
+
+    # Decrypt the payload.
+    if len(encryption_key) != 32:
+        raise BundleVerificationError(
+            f"encryption key must be 32 bytes, got {len(encryption_key)}"
+        )
+    plaintext_compressed = _decrypt_aes_gcm(encryption_key, encrypted_payload)
+
+    # zstd decompress.
+    plaintext_json = _zstd_decompress(plaintext_compressed)
+
+    # Parse JSON.
+    try:
+        payload = json.loads(plaintext_json.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        # We already verified the signature, so this is either a server
+        # bug or a successful decryption of corrupted content. Report as
+        # format error so the caller surfaces a clear message.
+        raise BundleFormatError(f"payload is not valid JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise BundleFormatError(
+            f"payload root must be an object, got {type(payload).__name__}"
+        )
+
+    return ParsedBundle(header=header, payload=payload)
+
+
+# --- Header / split --------------------------------------------------------
+
+
+def _split_bundle(blob: bytes) -> tuple[BundleHeader, bytes, bytes]:
+    """Validate the header and split the blob into (header, payload, signature)."""
+    if len(blob) < _HEADER_SIZE + _SIG_LEN:
+        raise BundleFormatError(
+            f"bundle too short: {len(blob)} bytes, need at least "
+            f"{_HEADER_SIZE + _SIG_LEN}"
+        )
+
+    if blob[:4] != _MAGIC:
+        raise BundleFormatError(
+            f"bad magic: expected CZ01, got {blob[:4]!r}"
+        )
+
+    # Parse the fixed-layout header.
+    (
+        schema_version,
+        created_at,
+        policy_count,
+        sig_offset,
+        sig_len,
+    ) = struct.unpack_from("<HQHII", blob, 4)
+
+    # The reserved 8 bytes at offset 24 must be zero. This gives us room
+    # to extend the header in a backwards-compatible way later.
+    reserved = blob[24:32]
+    if reserved != b"\x00" * 8:
+        raise BundleFormatError(f"reserved bytes must be zero, got {reserved!r}")
+
+    if schema_version < 1 or schema_version > _SCHEMA_VERSION_MAX:
+        raise BundleFormatError(
+            f"unsupported schema version {schema_version}, this SDK "
+            f"supports 1..{_SCHEMA_VERSION_MAX}. Upgrade the SDK."
+        )
+
+    if sig_len != _SIG_LEN:
+        raise BundleFormatError(
+            f"unexpected signature length {sig_len}, want {_SIG_LEN}"
+        )
+
+    if sig_offset < _HEADER_SIZE:
+        raise BundleFormatError(
+            f"sig_offset {sig_offset} must be >= header size {_HEADER_SIZE}"
+        )
+
+    if sig_offset + sig_len > len(blob):
+        raise BundleFormatError(
+            f"signature extends past end of bundle: sig_offset={sig_offset} "
+            f"sig_len={sig_len} bundle_len={len(blob)}"
+        )
+
+    if sig_offset + sig_len != len(blob):
+        # Trailing bytes after the signature are not allowed. This prevents
+        # smuggling data past the authenticated region.
+        raise BundleFormatError(
+            f"trailing bytes after signature: "
+            f"sig_offset+sig_len={sig_offset + sig_len} bundle_len={len(blob)}"
+        )
+
+    encrypted_payload = blob[_HEADER_SIZE:sig_offset]
+    signature = blob[sig_offset : sig_offset + sig_len]
+
+    return (
+        BundleHeader(
+            schema_version=schema_version,
+            created_at=created_at,
+            policy_count=policy_count,
+            sig_offset=sig_offset,
+            sig_len=sig_len,
+        ),
+        encrypted_payload,
+        signature,
+    )
+
+
+# --- Crypto primitives -----------------------------------------------------
+
+
+def _verify_ed25519(pubkey: bytes, message: bytes, signature: bytes) -> None:
+    """Verify a detached signature. Raises BundleVerificationError on failure."""
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+            Ed25519PublicKey,
+        )
+    except ImportError as exc:
+        # The cryptography package is a hard dependency of the SDK. If it
+        # is missing, we cannot verify a bundle and MUST NOT accept it.
+        raise BundleVerificationError(
+            "cryptography library is not installed; cannot verify bundle"
+        ) from exc
+
+    try:
+        pk = Ed25519PublicKey.from_public_bytes(pubkey)
+        pk.verify(signature, message)
+    except InvalidSignature as exc:
+        raise BundleVerificationError(
+            "signature verification failed: bundle is not authentic"
+        ) from exc
+    except Exception as exc:  # noqa: BLE001
+        raise BundleVerificationError(
+            f"signature verification error: {exc}"
+        ) from exc
+
+
+def _decrypt_aes_gcm(key: bytes, encrypted: bytes) -> bytes:
+    """Authenticated-encryption decrypt. Expects nonce(12) || ciphertext || tag(16)."""
+    try:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    except ImportError as exc:
+        raise BundleVerificationError(
+            "cryptography library is not installed; cannot decrypt bundle"
+        ) from exc
+
+    if len(encrypted) < _GCM_NONCE_SIZE + _GCM_TAG_SIZE:
+        raise BundleFormatError(
+            f"encrypted payload too short ({len(encrypted)} bytes) to contain "
+            f"nonce and tag"
+        )
+
+    nonce = encrypted[:_GCM_NONCE_SIZE]
+    ciphertext_with_tag = encrypted[_GCM_NONCE_SIZE:]
+
+    try:
+        aesgcm = AESGCM(key)
+        return aesgcm.decrypt(nonce, ciphertext_with_tag, None)
+    except Exception as exc:  # noqa: BLE001
+        # Authenticated-encryption tag check failed or key mismatch.
+        # Either way, the bundle is not trusted.
+        raise BundleVerificationError(
+            f"bundle decryption failed: {exc}"
+        ) from exc
+
+
+def _zstd_decompress(data: bytes) -> bytes:
+    """Zstd decompress. Tries multiple Python bindings for portability."""
+    # Preferred: `zstandard` is the de-facto PyPI package.
+    try:
+        import zstandard as zstd
+
+        return zstd.ZstdDecompressor().decompress(data)
+    except ImportError:
+        pass
+
+    # Fallback: `pyzstd`.
+    try:
+        import pyzstd
+
+        return pyzstd.decompress(data)
+    except ImportError:
+        pass
+
+    raise BundleVerificationError(
+        "zstd decompression library not installed; "
+        "install with: pip install 'controlzero[hosted]' or pip install zstandard"
+    )
+
+
+# --- Schema translation ----------------------------------------------------
+
+
+def translate_to_local_policy(payload: dict) -> dict:
+    """Translate a decrypted bundle payload to the local policy dict shape.
+
+    The bundle's `policies` list comes from the backend in the shape
+    produced by :func:`BundleHandler.SDKPull` (Go: bundlePolicy). The
+    local :class:`PolicyEvaluator` expects the input format from
+    :func:`controlzero.policy_loader.load_policy`: a dict with
+    ``version: "1"`` and a flat ``rules`` list where each entry is
+    either ``{"deny": "<tool>"}``, ``{"allow": "<tool>"}`` or
+    ``{"effect": "<deny|allow|warn|audit>", "action": "<tool>"}``.
+
+    Policies are sorted by ``priority`` ascending so SDKs in every
+    language produce identical decisions from identical input.
+    """
+    policies = payload.get("policies") or []
+    policies = sorted(
+        [p for p in policies if isinstance(p, dict)],
+        key=lambda p: int(p.get("priority", 100)),
+    )
+
+    flat: list[dict] = []
+    for pol in policies:
+        raw_rules = pol.get("rules")
+        if isinstance(raw_rules, dict):
+            rule_list = list(raw_rules.values())
+        elif isinstance(raw_rules, list):
+            rule_list = raw_rules
+        else:
+            continue
+
+        for r in rule_list:
+            if not isinstance(r, dict):
+                continue
+            translated = _translate_rule(r, pol.get("id", ""))
+            if translated is not None:
+                flat.append(translated)
+
+    if not flat:
+        # Empty policy set: default deny-all. An empty hosted project is
+        # not "everything allowed" -- it's "nothing configured yet."
+        flat.append({
+            "effect": "deny",
+            "action": "*",
+            "reason": (
+                "No active policies. Define one in the Control Zero dashboard."
+            ),
+        })
+
+    return {"version": "1", "rules": flat}
+
+
+def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
+    """Translate a single backend rule to the local rule shape."""
+    effect = rule.get("effect") or rule.get("action") or "allow"
+    if effect not in ("allow", "deny", "warn", "audit"):
+        effect = "allow"
+
+    # Find the tool pattern. The backend may put it under several keys
+    # depending on the policy form (LLM, tool-call, etc.).
+    pattern = rule.get("tool")
+    if not pattern:
+        pattern = rule.get("pattern")
+    if not pattern:
+        match = rule.get("match")
+        if isinstance(match, dict):
+            pattern = match.get("tool") or match.get("action")
+    if not pattern:
+        # Final fallback: universal match. Combined with a non-allow
+        # effect, this is still meaningful (e.g. deny-all).
+        pattern = "*"
+
+    translated: dict = {
+        "effect": effect,
+        "action": pattern,
+        "reason": rule.get("reason") or f"policy:{policy_id}",
+    }
+
+    resources = rule.get("resources") or rule.get("resource")
+    if resources:
+        translated["resources"] = resources
+
+    return translated