controlzero 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.2.0
+Version: 1.3.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

{controlzero-1.2.0 → controlzero-1.3.0}/controlzero/__init__.py

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

{controlzero-1.2.0 → controlzero-1.3.0}/controlzero/cli/main.py

@@ -15,6 +15,7 @@ from pathlib import Path
 from typing import Optional
 
 import click
+import yaml
 
 from controlzero import Client, __version__
 from controlzero.errors import PolicyLoadError, PolicyValidationError
@@ -390,6 +391,17 @@ def hook_check(policy: Optional[str]):
         )
         sys.exit(0)
 
+    # --- Load API key from config.yaml if not in environment ---
+    if not os.environ.get("CONTROLZERO_API_KEY"):
+        config_path = GLOBAL_POLICY_DIR / "config.yaml"
+        if config_path.exists():
+            try:
+                config = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+                if config and config.get("api_key"):
+                    os.environ["CONTROLZERO_API_KEY"] = config["api_key"]
+            except Exception:
+                pass
+
     # --- Tamper detection: policy file HMAC check ---
     tamper_detected = False
     tamper_detected = _check_policy_tamper(policy_path)
@@ -582,7 +594,6 @@ def _do_pull_and_write(state: object, policy_path: Path, state_dir: Path, result
             result["error"] = None
             return
         # Write the bundle rules as YAML to the policy file.
-        import yaml
         yaml_content = yaml.safe_dump(
             {
                 "version": str(bundle.get("version", "1")),
@@ -683,7 +694,6 @@ def _policy_has_deny_rules(policy_path: Path) -> bool:
     if the policy only has allow rules (or is empty/unparseable).
     """
     try:
-        import yaml
         text = policy_path.read_text(encoding="utf-8")
         data = yaml.safe_load(text)
         if not isinstance(data, dict):
@@ -834,6 +844,43 @@ def _warn_no_deny_rules(agent_name: str, template_path: Path) -> None:
             click.echo(f"  {line}", err=True)
 
 
+GLOBAL_CONFIG_PATH = GLOBAL_POLICY_DIR / "config.yaml"
+
+
+def _validate_api_key(api_key: str) -> bool:
+    """Return True if the API key has a valid cz_live_ or cz_test_ prefix."""
+    return api_key.startswith("cz_live_") or api_key.startswith("cz_test_")
+
+
+def _write_api_key_config(api_key: str) -> None:
+    """Write the API key to ~/.controlzero/config.yaml."""
+    GLOBAL_POLICY_DIR.mkdir(parents=True, exist_ok=True)
+    config_data: dict = {}
+    if GLOBAL_CONFIG_PATH.exists():
+        try:
+            existing = yaml.safe_load(GLOBAL_CONFIG_PATH.read_text(encoding="utf-8"))
+            if isinstance(existing, dict):
+                config_data = existing
+        except Exception:
+            pass
+    config_data["api_key"] = api_key
+    GLOBAL_CONFIG_PATH.write_text(
+        yaml.safe_dump(config_data, default_flow_style=False),
+        encoding="utf-8",
+    )
+
+
+def _print_api_key_status(api_key: Optional[str]) -> None:
+    """Print API key configuration status after install."""
+    if api_key:
+        click.echo("")
+        click.echo("API key configured. Audit logs will sync to the Control Zero dashboard.")
+        click.echo("View them at: https://app.controlzero.ai/audit")
+    else:
+        click.echo("")
+        click.echo("Tip: Pass --api-key cz_live_xxx to sync audit logs to the dashboard.")
+
+
 @cli.group()
 def install():
     """Install controlzero into a coding agent (Claude Code, Cursor, etc)."""
@@ -858,13 +905,28 @@ def install():
     default=None,
     help="Path to Claude Code settings.json. Defaults to ~/.claude/settings.json",
 )
-def install_claude_code(force: bool, merge: bool, settings: Optional[str]):
+@click.option(
+    "--api-key",
+    "-k",
+    default=None,
+    help="Control Zero API key (cz_live_* or cz_test_*). Enables audit log sync to the dashboard.",
+)
+def install_claude_code(force: bool, merge: bool, settings: Optional[str], api_key: Optional[str]):
     """Install controlzero as a Claude Code PreToolUse hook.
 
     Writes ~/.controlzero/policy.yaml from the claude-code template (idempotent
     unless --force is set) and merges a hook block into ~/.claude/settings.json.
     Existing hooks are preserved.
     """
+    if api_key is not None:
+        if not _validate_api_key(api_key):
+            click.echo(
+                "error: Invalid API key format. Must start with 'cz_live_' or 'cz_test_'.",
+                err=True,
+            )
+            sys.exit(1)
+        _write_api_key_config(api_key)
+
     template_path = TEMPLATE_DIR / "claude-code.yaml"
     if not template_path.exists():
         click.echo(f"error: claude-code template missing at {template_path}", err=True)
@@ -914,12 +976,15 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str]):
     pre_tool = hooks.setdefault("PreToolUse", [])
 
     # Idempotency: replace any existing controlzero hook block, preserve others
+    hook_command = "controlzero hook-check"
+    if api_key:
+        hook_command = f"CONTROLZERO_API_KEY={api_key} controlzero hook-check"
     new_block = {
         "matcher": "*",
         "hooks": [
             {
                 "type": "command",
-                "command": "controlzero hook-check",
+                "command": hook_command,
                 "timeout": 5000,
             }
         ],
@@ -929,7 +994,9 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str]):
         if not (
             isinstance(b, dict)
             and any(
-                isinstance(h, dict) and h.get("command") == "controlzero hook-check"
+                isinstance(h, dict)
+                and isinstance(h.get("command"), str)
+                and "controlzero hook-check" in h.get("command", "")
                 for h in b.get("hooks", [])
             )
         )
@@ -949,6 +1016,7 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str]):
     click.echo("")
     click.echo(f"Edit your policy: {GLOBAL_POLICY_PATH}")
     click.echo(f"Audit log:        {GLOBAL_AUDIT_PATH}")
+    _print_api_key_status(api_key)
 
 
 # =============================================================================
@@ -982,13 +1050,28 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str]):
     default=None,
     help="Path to Gemini CLI settings.json. Defaults to ~/.gemini/settings.json",
 )
-def install_gemini_cli(force: bool, merge: bool, settings: Optional[str]):
+@click.option(
+    "--api-key",
+    "-k",
+    default=None,
+    help="Control Zero API key (cz_live_* or cz_test_*). Enables audit log sync to the dashboard.",
+)
+def install_gemini_cli(force: bool, merge: bool, settings: Optional[str], api_key: Optional[str]):
     """Install controlzero as a Gemini CLI pre-tool-call hook.
 
     Writes ~/.controlzero/policy.yaml from the gemini-cli template
     (idempotent unless --force is set) and merges a hook block into
     ~/.gemini/settings.json. Existing hooks are preserved.
     """
+    if api_key is not None:
+        if not _validate_api_key(api_key):
+            click.echo(
+                "error: Invalid API key format. Must start with 'cz_live_' or 'cz_test_'.",
+                err=True,
+            )
+            sys.exit(1)
+        _write_api_key_config(api_key)
+
     template_path = TEMPLATE_DIR / "gemini-cli.yaml"
     if not template_path.exists():
         click.echo(f"error: gemini-cli template missing at {template_path}", err=True)
@@ -1035,16 +1118,23 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str]):
     hooks_root = existing.setdefault("hooks", {})
     pre_call = hooks_root.setdefault("BeforeTool", [])
 
+    hook_command = "controlzero hook-check"
+    if api_key:
+        hook_command = f"CONTROLZERO_API_KEY={api_key} controlzero hook-check"
     new_block = {
         "matcher": "*",
-        "command": "controlzero hook-check",
+        "command": hook_command,
         "timeout_ms": 5000,
     }
     # Idempotency: replace any existing controlzero hook block.
     pre_call[:] = [
         b
         for b in pre_call
-        if not (isinstance(b, dict) and b.get("command") == "controlzero hook-check")
+        if not (
+            isinstance(b, dict)
+            and isinstance(b.get("command"), str)
+            and "controlzero hook-check" in b.get("command", "")
+        )
     ]
     pre_call.append(new_block)
 
@@ -1061,6 +1151,7 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str]):
     click.echo("")
     click.echo(f"Edit your policy: {GLOBAL_POLICY_PATH}")
     click.echo(f"Audit log:        {GLOBAL_AUDIT_PATH}")
+    _print_api_key_status(api_key)
 
 
 # =============================================================================
@@ -1101,7 +1192,13 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str]):
     default=None,
     help="Path to Codex CLI config.toml. Defaults to ~/.codex/config.toml",
 )
-def install_codex_cli(force: bool, merge: bool, config: Optional[str]):
+@click.option(
+    "--api-key",
+    "-k",
+    default=None,
+    help="Control Zero API key (cz_live_* or cz_test_*). Enables audit log sync to the dashboard.",
+)
+def install_codex_cli(force: bool, merge: bool, config: Optional[str], api_key: Optional[str]):
     """Install controlzero as a Codex CLI tool approval hook.
 
     Writes ~/.controlzero/policy.yaml from the codex-cli template
@@ -1110,6 +1207,15 @@ def install_codex_cli(force: bool, merge: bool, config: Optional[str]):
     `[tool_approval_policy]` block to ~/.codex/config.toml pointing at
     the wrapper.
     """
+    if api_key is not None:
+        if not _validate_api_key(api_key):
+            click.echo(
+                "error: Invalid API key format. Must start with 'cz_live_' or 'cz_test_'.",
+                err=True,
+            )
+            sys.exit(1)
+        _write_api_key_config(api_key)
+
     template_path = TEMPLATE_DIR / "codex-cli.yaml"
     if not template_path.exists():
         click.echo(f"error: codex-cli template missing at {template_path}", err=True)
@@ -1142,13 +1248,16 @@ def install_codex_cli(force: bool, merge: bool, config: Optional[str]):
     hooks_dir = codex_dir / "hooks"
     hooks_dir.mkdir(parents=True, exist_ok=True)
     wrapper = hooks_dir / "controlzero.sh"
+    exec_line = "exec controlzero hook-check\n"
+    if api_key:
+        exec_line = f"exec env CONTROLZERO_API_KEY={api_key} controlzero hook-check\n"
     wrapper.write_text(
         "#!/usr/bin/env bash\n"
         "# Auto-generated by `controlzero install codex-cli`. Do not edit.\n"
         "# Codex CLI calls this wrapper with the tool call JSON on stdin;\n"
         "# we forward it to `controlzero hook-check` and propagate the\n"
         "# exit code. Exit 0 = allow, non-zero = deny.\n"
-        "exec controlzero hook-check\n",
+        + exec_line,
         encoding="utf-8",
     )
     wrapper.chmod(0o755)
@@ -1205,6 +1314,7 @@ def install_codex_cli(force: bool, merge: bool, config: Optional[str]):
     click.echo("")
     click.echo(f"Edit your policy: {GLOBAL_POLICY_PATH}")
     click.echo(f"Audit log:        {GLOBAL_AUDIT_PATH}")
+    _print_api_key_status(api_key)
 
 
 # =============================================================================
@@ -1256,7 +1366,9 @@ def uninstall_claude_code(settings: Optional[str]):
         if not (
             isinstance(b, dict)
             and any(
-                isinstance(h, dict) and h.get("command") == "controlzero hook-check"
+                isinstance(h, dict)
+                and isinstance(h.get("command"), str)
+                and "controlzero hook-check" in h.get("command", "")
                 for h in b.get("hooks", [])
             )
         )
@@ -1313,7 +1425,11 @@ def uninstall_gemini_cli(settings: Optional[str]):
     original_count = len(pre_call)
     cleaned = [
         b for b in pre_call
-        if not (isinstance(b, dict) and b.get("command") == "controlzero hook-check")
+        if not (
+            isinstance(b, dict)
+            and isinstance(b.get("command"), str)
+            and "controlzero hook-check" in b.get("command", "")
+        )
     ]
 
     if len(cleaned) == original_count:

{controlzero-1.2.0 → controlzero-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.2.0"
+version = "1.3.0"
 description = "AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{controlzero-1.2.0 → controlzero-1.3.0}/tests/test_coding_agent_hooks.py

@@ -38,6 +38,7 @@ from __future__ import annotations
 
 import importlib
 import json
+import os
 from pathlib import Path
 
 import pytest
@@ -604,3 +605,217 @@ class TestHelperFunctions:
         from controlzero.cli.main import _policy_has_deny_rules
         p = tmp_path / "nonexistent.yaml"
         assert _policy_has_deny_rules(p) is False
+
+
+# ===========================================================================
+# API KEY OPTION TESTS
+# ===========================================================================
+
+class TestApiKeyOption:
+    """Tests for the --api-key option on install commands."""
+
+    def test_api_key_validation_valid_live(self):
+        """cz_live_ prefix is accepted."""
+        from controlzero.cli.main import _validate_api_key
+        assert _validate_api_key("cz_live_abc123") is True
+
+    def test_api_key_validation_valid_test(self):
+        """cz_test_ prefix is accepted."""
+        from controlzero.cli.main import _validate_api_key
+        assert _validate_api_key("cz_test_abc123") is True
+
+    def test_api_key_validation_invalid(self):
+        """Invalid prefixes are rejected."""
+        from controlzero.cli.main import _validate_api_key
+        assert _validate_api_key("sk_live_abc123") is False
+        assert _validate_api_key("invalid") is False
+        assert _validate_api_key("") is False
+        assert _validate_api_key("cz_invalid_abc") is False
+
+    def test_install_claude_code_with_api_key_writes_config(
+        self, tmp_path, monkeypatch
+    ):
+        """install claude-code --api-key writes config.yaml with the key."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            ["install", "claude-code", "--api-key", "cz_live_testkey123"],
+        )
+        assert result.exit_code == 0
+
+        config_path = fake_home / ".controlzero" / "config.yaml"
+        assert config_path.exists()
+        config = yaml.safe_load(config_path.read_text())
+        assert config["api_key"] == "cz_live_testkey123"
+
+    def test_install_claude_code_with_api_key_updates_hook_command(
+        self, tmp_path, monkeypatch
+    ):
+        """install claude-code --api-key includes env var in hook command."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            ["install", "claude-code", "--api-key", "cz_live_testkey123"],
+        )
+        assert result.exit_code == 0
+
+        settings_path = fake_home / ".claude" / "settings.json"
+        settings = json.loads(settings_path.read_text())
+        pre_tool = settings["hooks"]["PreToolUse"]
+        assert len(pre_tool) == 1
+        hook_cmd = pre_tool[0]["hooks"][0]["command"]
+        assert "CONTROLZERO_API_KEY=cz_live_testkey123" in hook_cmd
+        assert "controlzero hook-check" in hook_cmd
+
+    def test_install_gemini_cli_with_api_key_updates_hook_command(
+        self, tmp_path, monkeypatch
+    ):
+        """install gemini-cli --api-key includes env var in hook command."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            ["install", "gemini-cli", "--api-key", "cz_test_geminikey"],
+        )
+        assert result.exit_code == 0
+
+        settings_path = fake_home / ".gemini" / "settings.json"
+        settings = json.loads(settings_path.read_text())
+        before_tool = settings["hooks"]["BeforeTool"]
+        assert len(before_tool) == 1
+        assert "CONTROLZERO_API_KEY=cz_test_geminikey" in before_tool[0]["command"]
+
+    def test_install_codex_cli_with_api_key_updates_wrapper(
+        self, tmp_path, monkeypatch
+    ):
+        """install codex-cli --api-key includes env var in wrapper script."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            ["install", "codex-cli", "--api-key", "cz_live_codexkey"],
+        )
+        assert result.exit_code == 0
+
+        wrapper_path = fake_home / ".codex" / "hooks" / "controlzero.sh"
+        assert wrapper_path.exists()
+        wrapper_text = wrapper_path.read_text()
+        assert "CONTROLZERO_API_KEY=cz_live_codexkey" in wrapper_text
+
+    def test_install_with_invalid_api_key_exits_with_error(
+        self, tmp_path, monkeypatch
+    ):
+        """install with invalid --api-key prints error and exits non-zero."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            ["install", "claude-code", "--api-key", "invalid_key"],
+        )
+        assert result.exit_code != 0
+        assert "Invalid API key format" in result.output
+
+    def test_install_without_api_key_shows_hint(
+        self, tmp_path, monkeypatch
+    ):
+        """install without --api-key shows tip about the option."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            ["install", "claude-code"],
+        )
+        assert result.exit_code == 0
+        assert "Tip: Pass --api-key" in result.output
+
+    def test_install_with_api_key_shows_dashboard_message(
+        self, tmp_path, monkeypatch
+    ):
+        """install with --api-key shows dashboard sync message."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            ["install", "claude-code", "--api-key", "cz_live_abc"],
+        )
+        assert result.exit_code == 0
+        assert "Audit logs will sync" in result.output
+        assert "https://app.controlzero.ai/audit" in result.output
+
+    def test_hook_check_reads_api_key_from_config(
+        self, tmp_path, monkeypatch
+    ):
+        """hook-check reads API key from config.yaml when env var not set."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        # Write config.yaml with API key
+        cz_dir = fake_home / ".controlzero"
+        cz_dir.mkdir(parents=True)
+        config_path = cz_dir / "config.yaml"
+        config_path.write_text(yaml.safe_dump({"api_key": "cz_live_fromconfig"}))
+
+        # Write a simple allow-all policy
+        policy_path = cz_dir / "policy.yaml"
+        policy_path.write_text(yaml.safe_dump({
+            "version": "1",
+            "rules": [{"allow": "*"}],
+        }))
+
+        # Ensure env var is NOT set
+        monkeypatch.delenv("CONTROLZERO_API_KEY", raising=False)
+        # Patch GLOBAL_POLICY_PATH and GLOBAL_POLICY_DIR to use fake home
+        monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", cz_dir)
+        monkeypatch.setattr(cli_main, "GLOBAL_POLICY_PATH", policy_path)
+        monkeypatch.setattr(cli_main, "GLOBAL_AUDIT_PATH", cz_dir / "audit.log")
+
+        runner = CliRunner()
+        payload = json.dumps({"tool_name": "Read", "tool_input": {}})
+        result = runner.invoke(cli_main.cli, ["hook-check"], input=payload)
+        assert result.exit_code == 0
+
+        # The env var should have been set by hook-check reading config.yaml
+        assert os.environ.get("CONTROLZERO_API_KEY") == "cz_live_fromconfig"
+
+        # Clean up env var
+        monkeypatch.delenv("CONTROLZERO_API_KEY", raising=False)
+
+    def test_hook_check_env_var_takes_precedence(
+        self, tmp_path, monkeypatch
+    ):
+        """CONTROLZERO_API_KEY env var takes precedence over config.yaml."""
+        fake_home, cli_main = _setup_fake_home(tmp_path, monkeypatch)
+
+        cz_dir = fake_home / ".controlzero"
+        cz_dir.mkdir(parents=True)
+        config_path = cz_dir / "config.yaml"
+        config_path.write_text(yaml.safe_dump({"api_key": "cz_live_fromconfig"}))
+
+        policy_path = cz_dir / "policy.yaml"
+        policy_path.write_text(yaml.safe_dump({
+            "version": "1",
+            "rules": [{"allow": "*"}],
+        }))
+
+        monkeypatch.setenv("CONTROLZERO_API_KEY", "cz_live_fromenv")
+        monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", cz_dir)
+        monkeypatch.setattr(cli_main, "GLOBAL_POLICY_PATH", policy_path)
+        monkeypatch.setattr(cli_main, "GLOBAL_AUDIT_PATH", cz_dir / "audit.log")
+
+        runner = CliRunner()
+        payload = json.dumps({"tool_name": "Read", "tool_input": {}})
+        result = runner.invoke(cli_main.cli, ["hook-check"], input=payload)
+        assert result.exit_code == 0
+
+        # Env var should remain as the original, not overwritten by config
+        assert os.environ.get("CONTROLZERO_API_KEY") == "cz_live_fromenv"
+
+        monkeypatch.delenv("CONTROLZERO_API_KEY", raising=False)