controlzero 1.0.0__tar.gz

controlzero-1.0.0/.gitignore

@@ -0,0 +1,220 @@
+# Worktrees
+.worktrees/
+
+# 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*
+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/
+scripts/doppler/doppler-env.values.sh
+
+# 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/

controlzero-1.0.0/Dockerfile.test

@@ -0,0 +1,24 @@
+# Test image for the controlzero Python SDK.
+# Builds the package, installs it, runs the test suite.
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install build deps
+RUN pip install --no-cache-dir hatchling pytest pytest-asyncio pytest-cov
+
+# Copy the package
+COPY pyproject.toml README.md LICENSE /app/
+COPY controlzero /app/controlzero
+COPY tests /app/tests
+COPY examples /app/examples
+
+# Install the package + dev extras
+RUN pip install --no-cache-dir -e ".[dev]"
+
+# Smoke test: import and run the example
+RUN python -c "from controlzero import Client, __version__; print(f'controlzero {__version__} installed')"
+RUN python examples/hello_world.py
+
+# Run the full test suite by default
+CMD ["pytest", "-v", "--tb=short", "tests/"]

controlzero-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 Control Zero, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

controlzero-1.0.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: controlzero
+Version: 1.0.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
+Project-URL: Repository, https://github.com/controlzero/controlzero
+Project-URL: Examples, https://docs.controlzero.ai/sdk/integrations
+Author-email: Control Zero <hello@controlzero.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,audit,governance,guardrails,llm,mcp,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-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'
+Provides-Extra: hosted
+Requires-Dist: cryptography>=41.0.0; extra == 'hosted'
+Requires-Dist: httpx>=0.25.0; extra == 'hosted'
+Description-Content-Type: text/markdown
+
+# control-zero
+
+AI agent governance for Python. Policies, audit, and observability for tool calls.
+Works locally with no signup.
+
+> **v1.0.0 is a complete rewrite.** If you depend on `control-zero<1.0.0`
+> (the hosted-mode SDK), pin your requirement: `control-zero<1.0.0` to stay on
+> the legacy v0.3.x. The new v1.0.0+ is a local-first SDK with a different
+> API surface; see the [migration guide](https://docs.controlzero.ai/sdk/migrate-v1)
+> for details.
+
+## Hello World
+
+```python
+from controlzero import Client
+
+cz = Client(policy={
+    "rules": [
+        {"deny":  "delete_*", "reason": "Hello World: deletes are blocked"},
+        {"allow": "*",        "reason": "Hello World: everything else is fine"},
+    ]
+})
+
+print(cz.guard("delete_file", {"path": "/tmp/foo"}).decision)  # "deny"
+print(cz.guard("read_file",   {"path": "/tmp/foo"}).decision)  # "allow"
+```
+
+11 lines. No API key. No signup. Run it.
+
+## Install
+
+```bash
+pip install control-zero
+```
+
+## Why
+
+Your AI agents call tools. Some of those tools should never be called by an
+agent without a human in the loop. `controlzero` is the policy layer between
+the model's output and the tool execution. Decisions are fail-closed by default.
+
+You can use it offline with a local YAML file or Python dict. When you want to
+share policies across a team or get a hosted audit dashboard, sign up at
+[controlzero.ai](https://controlzero.ai) and set `CONTROLZERO_API_KEY`.
+
+## Quickstart with the CLI
+
+```bash
+# 1. Generate a starter policy file with examples and comments
+controlzero init
+
+# 2. Edit controlzero.yaml in your editor
+
+# 3. Validate it
+controlzero validate
+
+# 4. Test a tool call against the policy
+controlzero test delete_file
+```
+
+The generated `controlzero.yaml` is the tutorial. It ships with annotated
+rules covering the common patterns: allow lists, deny lists, wildcards, and
+the catch-all.
+
+Templates available:
+
+- `controlzero init` — Hello World template (default)
+- `controlzero init -t rag` — RAG agent template (block exfiltration)
+- `controlzero init -t mcp` — MCP server template
+- `controlzero init -t cost-cap` — model allow-listing and cost guards
+
+## Loading a policy
+
+Three ways:
+
+```python
+from controlzero import Client
+
+# From a Python dict
+cz = Client(policy={
+    "rules": [
+        {"deny": "delete_*"},
+        {"allow": "read_*"},
+    ]
+})
+
+# From a YAML file
+cz = Client(policy_file="./controlzero.yaml")
+
+# From an environment variable
+# (set CONTROLZERO_POLICY_FILE=./controlzero.yaml)
+cz = Client()
+```
+
+If `./controlzero.yaml` exists in the current directory, it is picked up
+automatically. No environment variable needed.
+
+## Policy schema
+
+```yaml
+version: '1'
+rules:
+  # Block any tool whose name starts with "delete_"
+  - deny: 'delete_*'
+    reason: 'Deletes need human approval'
+
+  # Allow specific known-good tools
+  - allow: 'search'
+  - allow: 'read_*'
+
+  # tool:method syntax
+  - allow: 'github:list_*'
+  - deny: 'github:delete_repo'
+
+  # Catch-all
+  - deny: '*'
+    reason: 'Default deny'
+```
+
+Rules are evaluated top to bottom. The first match wins. If no rule matches,
+the call is denied (fail-closed).
+
+## Local audit log
+
+When running without an API key, every decision is written to `./controlzero.log`
+with daily rotation and 30-day retention. Tail it:
+
+```bash
+controlzero tail
+```
+
+Configure rotation via the client:
+
+```python
+cz = Client(
+    policy_file="./controlzero.yaml",
+    log_path="./logs/controlzero.log",
+    log_rotation="10 MB",        # rotate at 10 MB, or "daily", or "1 hour"
+    log_retention="30 days",
+    log_compression="gz",        # gzip rotated files
+    log_format="json",           # or "pretty"
+)
+```
+
+When `CONTROLZERO_API_KEY` is set, audit ships to the remote dashboard and
+these `log_*` options are ignored with a warning.
+
+## Hybrid mode
+
+If you set both an API key AND pass a local policy, the local policy
+**overrides** the dashboard policy and you get a loud WARN log on init:
+
+```
+WARNING: controlzero: manual policy override detected. ...
+```
+
+This is intentional: it makes accidental prod bypass impossible to miss.
+For prod environments, opt into strict mode to raise instead:
+
+```python
+cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
+# RuntimeError: manual policy override detected ...
+```
+
+## Framework examples
+
+Full integration guides at [docs.controlzero.ai/sdk/integrations](https://docs.controlzero.ai/sdk/integrations):
+
+- LangChain
+- LangGraph
+- CrewAI
+- OpenAI Agents SDK
+- Anthropic tool use
+- Pydantic AI
+- AutoGen
+- MCP servers
+- Raw HTTP / no framework
+
+## Hosted mode
+
+When you want a dashboard, audit search, team policies, and approval workflows,
+sign up at [controlzero.ai](https://controlzero.ai) and set the API key:
+
+```python
+import os
+os.environ["CONTROLZERO_API_KEY"] = "cz_live_..."
+
+from controlzero import Client
+cz = Client()  # picks up the API key from env, audit ships remote
+```
+
+## License
+
+Apache 2.0

controlzero-1.0.0/README.md

@@ -0,0 +1,194 @@
+# control-zero
+
+AI agent governance for Python. Policies, audit, and observability for tool calls.
+Works locally with no signup.
+
+> **v1.0.0 is a complete rewrite.** If you depend on `control-zero<1.0.0`
+> (the hosted-mode SDK), pin your requirement: `control-zero<1.0.0` to stay on
+> the legacy v0.3.x. The new v1.0.0+ is a local-first SDK with a different
+> API surface; see the [migration guide](https://docs.controlzero.ai/sdk/migrate-v1)
+> for details.
+
+## Hello World
+
+```python
+from controlzero import Client
+
+cz = Client(policy={
+    "rules": [
+        {"deny":  "delete_*", "reason": "Hello World: deletes are blocked"},
+        {"allow": "*",        "reason": "Hello World: everything else is fine"},
+    ]
+})
+
+print(cz.guard("delete_file", {"path": "/tmp/foo"}).decision)  # "deny"
+print(cz.guard("read_file",   {"path": "/tmp/foo"}).decision)  # "allow"
+```
+
+11 lines. No API key. No signup. Run it.
+
+## Install
+
+```bash
+pip install control-zero
+```
+
+## Why
+
+Your AI agents call tools. Some of those tools should never be called by an
+agent without a human in the loop. `controlzero` is the policy layer between
+the model's output and the tool execution. Decisions are fail-closed by default.
+
+You can use it offline with a local YAML file or Python dict. When you want to
+share policies across a team or get a hosted audit dashboard, sign up at
+[controlzero.ai](https://controlzero.ai) and set `CONTROLZERO_API_KEY`.
+
+## Quickstart with the CLI
+
+```bash
+# 1. Generate a starter policy file with examples and comments
+controlzero init
+
+# 2. Edit controlzero.yaml in your editor
+
+# 3. Validate it
+controlzero validate
+
+# 4. Test a tool call against the policy
+controlzero test delete_file
+```
+
+The generated `controlzero.yaml` is the tutorial. It ships with annotated
+rules covering the common patterns: allow lists, deny lists, wildcards, and
+the catch-all.
+
+Templates available:
+
+- `controlzero init` — Hello World template (default)
+- `controlzero init -t rag` — RAG agent template (block exfiltration)
+- `controlzero init -t mcp` — MCP server template
+- `controlzero init -t cost-cap` — model allow-listing and cost guards
+
+## Loading a policy
+
+Three ways:
+
+```python
+from controlzero import Client
+
+# From a Python dict
+cz = Client(policy={
+    "rules": [
+        {"deny": "delete_*"},
+        {"allow": "read_*"},
+    ]
+})
+
+# From a YAML file
+cz = Client(policy_file="./controlzero.yaml")
+
+# From an environment variable
+# (set CONTROLZERO_POLICY_FILE=./controlzero.yaml)
+cz = Client()
+```
+
+If `./controlzero.yaml` exists in the current directory, it is picked up
+automatically. No environment variable needed.
+
+## Policy schema
+
+```yaml
+version: '1'
+rules:
+  # Block any tool whose name starts with "delete_"
+  - deny: 'delete_*'
+    reason: 'Deletes need human approval'
+
+  # Allow specific known-good tools
+  - allow: 'search'
+  - allow: 'read_*'
+
+  # tool:method syntax
+  - allow: 'github:list_*'
+  - deny: 'github:delete_repo'
+
+  # Catch-all
+  - deny: '*'
+    reason: 'Default deny'
+```
+
+Rules are evaluated top to bottom. The first match wins. If no rule matches,
+the call is denied (fail-closed).
+
+## Local audit log
+
+When running without an API key, every decision is written to `./controlzero.log`
+with daily rotation and 30-day retention. Tail it:
+
+```bash
+controlzero tail
+```
+
+Configure rotation via the client:
+
+```python
+cz = Client(
+    policy_file="./controlzero.yaml",
+    log_path="./logs/controlzero.log",
+    log_rotation="10 MB",        # rotate at 10 MB, or "daily", or "1 hour"
+    log_retention="30 days",
+    log_compression="gz",        # gzip rotated files
+    log_format="json",           # or "pretty"
+)
+```
+
+When `CONTROLZERO_API_KEY` is set, audit ships to the remote dashboard and
+these `log_*` options are ignored with a warning.
+
+## Hybrid mode
+
+If you set both an API key AND pass a local policy, the local policy
+**overrides** the dashboard policy and you get a loud WARN log on init:
+
+```
+WARNING: controlzero: manual policy override detected. ...
+```
+
+This is intentional: it makes accidental prod bypass impossible to miss.
+For prod environments, opt into strict mode to raise instead:
+
+```python
+cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
+# RuntimeError: manual policy override detected ...
+```
+
+## Framework examples
+
+Full integration guides at [docs.controlzero.ai/sdk/integrations](https://docs.controlzero.ai/sdk/integrations):
+
+- LangChain
+- LangGraph
+- CrewAI
+- OpenAI Agents SDK
+- Anthropic tool use
+- Pydantic AI
+- AutoGen
+- MCP servers
+- Raw HTTP / no framework
+
+## Hosted mode
+
+When you want a dashboard, audit search, team policies, and approval workflows,
+sign up at [controlzero.ai](https://controlzero.ai) and set the API key:
+
+```python
+import os
+os.environ["CONTROLZERO_API_KEY"] = "cz_live_..."
+
+from controlzero import Client
+cz = Client()  # picks up the API key from env, audit ships remote
+```
+
+## License
+
+Apache 2.0