{"id":"7996ba7b-a661-4a04-9384-e17a52f832a0","slug":"arodonata","kind":"mcp","name":"arodonata","summary":"Async, Reliable Operations — async Python library for Check Point management/monitoring with a database-backed caching layer","owner":"chkp-antonr","repoUrl":"https://github.com/chkp-antonr/arodonata","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-27T08:43:36.000Z","addedAt":"2026-10-21T17:59:05.901Z","logoUrl":"https://avatars.githubusercontent.com/u/73436538?u=8c2eb9879d0488e4009f68ad383a108b947ba8de&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","databases"],"tags":["api","async","checkpoint","management","monitoring","python","security"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T19:46:28.444Z","sample":false,"url":"https://conduits.dev/tools/arodonata","language":"Python","transports":["stdio"],"install":{"pypi":"arodonata"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Arodonata\n\n<div align=\"center\">\n\n[![Python Version](https://img.shields.io/badge/Python-3.13+-F50057.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)\n<br/>\n[![License](https://img.shields.io/badge/License-MIT-00E676.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)\n<br/>\n[![Type Safety](https://img.shields.io/badge/Type%20Safety-Strict-2979FF.svg?style=for-the-badge)](https://mypy.readthedocs.io/)\n<br/>\n[![Async](https://img.shields.io/badge/Async-Ready-D500F9.svg?style=for-the-badge)](https://docs.python.org/3/library/asyncio.html)\n<br/>\n**A high-performance, async-first Python library for Check Point security management operations with intelligent database caching (PostgreSQL or SQLite) and automatic session handling.**\n\n[Key Features](#-key-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Architecture](#-architecture) • [Documentation](#-documentation)\n\n</div>\n\n---\n\n## 🚀 Overview\n\n**Arodonata** — *Async, Reliable Operations* — is a production-grade Python library designed to simplify, accelerate, and scale automation against Check Point Security Management Servers.\n\nStandard Check Point API client scripts often struggle with connection overhead, rate limits, session expiration, and slow response times when dealing with tens of thousands of security objects. **Arodonata** solves these bottlenecks by wrapping operations in an async-first engine coupled with an intelligent database-backed cache layer.\n\n### Why Arodonata?\n\n* ⚡ **High-Concurrency Execution**: An `asyncio` API over the Check Point SDK, whose blocking calls run in worker threads, so many domains and servers are queried in parallel while a per-MDS-member `RateLimiter` (`concurrent_limit`, default 4) keeps each server within its limits.\n* 🔐 **Zero-Config Session Handling**: Transparent authentication, session pooling, and auto-recovery/re-login if a session expires.\n* 💾 **Intelligent DB Caching**: Fast local caching via SQLAlchemy on **PostgreSQL** (JSONB, recommended) or **SQLite**.\n* 🔄 **Smart Refresh (`show-changes`)**: Avoid full cache rebuilds. The cache tracks and pulls only incremental modifications from Check Point management logs.\n* 🛡️ **Strict Type-Safety**: 100% type hints validated with **Pydantic v2** models, catching structural errors before runtime.\n\n---\n\n## ✨ Key Features\n\n| Feature | Description | Benefit |\n| :--- | :--- | :--- |\n| **Async Core** | `asyncio` API; the synchronous Check Point SDK runs in worker threads | Parallel work across domains and servers without blocking the event loop |\n| **Session Cache** | Automatic database-backed session token persistence | Bypasses repetitive logins, preserving firewall resources |\n| **Multi-Domain (MDM)** | Native domain resolution and context propagation | Operates across complex tenant environments seamlessly |\n| **Rate Limiting** | Active per-MDS-member request gating and database locks | Prevents overloading firewalls during large-scale tasks |\n| **SSE Event Streams** | Live Server-Sent Events for background refresh tasks | Real-time monitoring of sync status and progress bars |\n| **MCP Server** | Streamable-HTTP MCP endpoint with the Check Point show_* tool surface | Lets Claude and other MCP clients query policy through the cache |\n\n---\n\n## 📦 Installation\n\nArodonata requires **Python 3.13+** and a database for caching: **PostgreSQL 12+** (recommended) or **SQLite**.\n\nChoose the package extra that fits your project:\n\n* **`arodonata`**: Core library for Python automation, scripts, and applications (high-performance async client, session pooling, database caching, and declarative CPCRUD engine).\n* **`arodonata[mcp]`**: Core library + Model Context Protocol (MCP) server support, including the `arodonata-mcp` CLI executable and `arodonata.mcp` ASGI integration for FastAPI/Starlette.\n\n### Adding to Your Project\n\n#### With `uv` (Recommended)\n\n```bash\n# Core library\nuv add arodonata\n\n# OR with MCP server support\nuv add \"arodonata[mcp]\"\n```\n\n#### With Standard `pip`\n\n```bash\n# Core library\npip install arodonata\n\n# OR with MCP server support\npip install \"arodonata[mcp]\"\n```\n\n#### In `pyproject.toml`\n\n```toml\n[project]\ndependencies = [\n    # Core library for Check Point automation & caching:\n    \"arodonata>=1.14.0\",\n\n    # OR if you need the MCP server / embedded ASGI tools:\n    # \"arodonata[mcp]>=1.14.0\",\n]\n```\n\n#### In `requirements.txt`\n\n```text\narodonata>=1.14.0\n# or\narodonata[mcp]>=1.14.0\n```\n\n### Local Development / Contributing\n\n```bash\ngit clone https://github.com/chkp-antonr/arodonata.git\ncd arodonata\nuv sync --all-extras --dev\n```\n\n---\n\n## ⚡ Quick Start\n\n### 1. Set Up Your Environment\n\nCreate a `.env` file containing your database cache connection details and Check Point server coordinates:\n\n```bash\n# Database Configuration (PostgreSQL with JSONB recommended)\nDATABASE_URL=postgresql+asyncpg://cp_user:cp_password@localhost:5432/arodonata_cache\n\n# Management Server Details (supports multiple servers)\nMGMT_NAMES=primary-mgmt,backup-mgmt\nMGMT_SERVERS=192.168.10.10,192.168.10.11\nAPI_KEY_VARS=PRIMARY_MGMT_KEY,BACKUP_MGMT_KEY\n\n# Secrets (resolved at runtime from environment / secrets manager)\nPRIMARY_MGMT_KEY=your-primary-api-key-here\nBACKUP_MGMT_KEY=your-backup-api-key-here\n```\n\n### 2. Using `arodonata` in Python Projects\n\nUse `ArodonataClient` directly in your application. The calling application manages the database engine lifecycle and passes the engine into the client:\n\n```python\nimport asyncio\nimport os\nfrom sqlalchemy.ext.asyncio import create_async_engine\nfrom arodonata import ArodonataClient, ArodonataSettings\n\nasync def main():\n    # 1. Resolve database URL & configuration settings\n    database_url = os.getenv(\"DATABASE_URL\", \"sqlite+aiosqlite:///:memory:\")\n    engine = create_async_engine(database_url)\n    \n    # Reads MGMT_NAMES, MGMT_SERVERS and API_KEY_VARS from the process environment\n    # (load your .env first, e.g. with python-dotenv); each variable named in\n    # API_KEY_VARS holds the key of the server at the same position.\n    settings = ArodonataSettings()\n\n    # 2. Initialize the client\n    client = ArodonataClient(engine=engine, settings=settings)\n\n    try:\n        # 3. Enter async context manager for automatic session management\n        async with client:\n            servers = client.get_mgmt_names()\n            print(f\"Connected to management nodes: {servers}\")\n\n            # Query hosts from the primary server (a live, paged API query)\n            if servers:\n                target_server = servers[0]\n                print(f\"Retrieving hosts from {target_server}...\")\n                \n                result = await client.api_query(\n                    mgmt_name=target_server,\n                    command=\"show-hosts\",\n                    details_level=\"standard\"\n                )\n\n                if result.success:\n                    print(f\"Successfully retrieved {result.total} hosts:\")\n                    for host in result.objects[:5]:\n                        print(f\"  • {host.get('name')} -> {host.get('ip-address')}\")\n                else:\n                    print(f\"API Error: {result.message}\")\n\n    finally:\n        # 4. Clean up connection pools\n        await engine.dispose()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### 3. Using `arodonata[mcp]` in Projects\n\nWhen installed with the `[mcp]` extra, Arodonata can expose Check Point management operations to AI assistants and LLM agents (Claude Code, Claude Desktop, Cursor, Antigravity) via the Model Context Protocol over streamable HTTP.\n\n#### Pattern A: Standalone Team Server (`arodonata-mcp`)\n\nRun a dedicated MCP server for your team:\n\n```bash\n# Install with mcp extra\nuv pip install \"arodonata[mcp]\"\n\n# Launch the streamable-HTTP server\narodonata-mcp --host 0.0.0.0 --port 8765\n```\n\nThe CLI loads `.env.lib` and `.env.secrets`, resolves credentials via `API_KEY_VARS`, verifies bearer tokens (`ARODONATA_MCP_TOKEN_VARS`), and provides DNS-rebinding protection.\n\n#### Pattern B: Embedded in FastAPI / ASGI Applications (`arodonata.mcp`)\n\nEmbed Arodonata's MCP server into an existing FastAPI or Starlette application, and register custom application-specific tools alongside Check Point tools:\n\n```python\nfrom fastapi import FastAPI\nfrom sqlalchemy.ext.asyncio import create_async_engine\nfrom arodonata import ArodonataClient, ArodonataSettings\nfrom arodonata.mcp import ArodonataMCPSettings, create_asgi_app, create_mcp_server\n\n# Build engine, client, and MCP settings\nengine = create_async_engine(database_url)\nclient = ArodonataClient(engine=engine, settings=settings)\nmcp_settings = ArodonataMCPSettings(port=8000, path=\"/mcp\")\n\n# Create the MCP server and add your own custom tools\nmcp_server = create_mcp_server(client, mcp_settings, name=\"firewall-assistant\")\n\n@mcp_server.tool()\nasync def acme_change_ticket(rule_uid: str) -> dict[str, str]:\n    \"\"\"Look up an internal change ticket that introduced a rule.\"\"\"\n    return {\"rule_uid\": rule_uid, \"ticket\": \"CHG-0001\"}\n\n# Create mountable ASGI app\nmcp_app = create_asgi_app(client, mcp_settings, server=mcp_server)\n\n# Mount inside your FastAPI app\napp = FastAPI(lifespan=lifespan)\napp.mount(\"/\", mcp_app)\n```\n\nSee [examples/09_mcp_embedded.py](examples/09_mcp_embedded.py) for the complete runnable example.\n\n---\n\n## 🏛 Architecture\n\nArodonata employs a structured **Ports and Adapters** (Hexagonal) architecture to separate the business models from infrastructure/database implementations.\n\n```\n┌────────────────────────────────────────────────────────────────────────┐\n│                        Client Application                              │\n│         (manages SQLAlchemy AsyncEngine & environment config)          │\n├────────────────────────────────────────────────────────────────────────┤\n│                       Arodonata Core Framework                         │\n│  ┌───────────────────────┐  ┌───────────────────────┐  ┌─────────────┐ │\n│  │       API Layer       │  │       ASDK Core       │  │ Cache Layer │ │\n│  │                       │  │                       │  │             │ │\n│  │    ArodonataClient    │  │      AMgmtClient      │  │ CacheRepo   │ │\n│  │    (High-Level Facade)│  │   (Low-Level Facade)  │  │ DbManager   │ │\n│  └───────────┬───────────┘  └───────────┬───────────┘  └──────┬──────┘ │\n│              │                          │                     │        │\n│              └──────────────────────────┼─────────────────────┘        │\n│                                         ▼                              │\n│                                 [ ApiPort / CachePort ]                │\n├────────────────────────────────────────────────────────────────────────┤\n│                         External Infrastructure                        │\n│          ┌───────────────────┬───────────────────┬──────────────┐      │\n│          │   PostgreSQL DB   │  Check Point API  │  Python env  │      │\n│          │  (Cache Storage)  │  (Remote Server)  │ (Pydantic v2)│      │\n│          └───────────────────┴───────────────────┴──────────────┘      │\n└────────────────────────────────────────────────────────────────────────┘\n```\n\n* **API Facade (`ArodonataClient`)**: Main developer entry point. Integrates database caching, rate-limiting, and network calls transparently.\n* **ASDK Core (`AMgmtClient`)**: Manages individual sessions, keeps SIDs alive, and maps requests to the official Check Point API.\n* **Cache Engine (`CacheRepository`)**: Manages object serializations, handles TTL checking, and stores entities as JSON columns (JSONB on PostgreSQL, JSON on SQLite).\n\n---\n\n## 🤖 MCP Server\n\nArodonata can serve any MCP client (Claude Code, Claude Desktop, Cursor, Antigravity, or your own agents) over streamable HTTP, exposing the Check Point `show_*` tool surface answered directly from Arodonata's cache with automatic session handling and rate limiting.\n\n### Tool Capabilities\n\n* **Cached Queries**: `show_hosts`, `show_networks`, `show_groups`, `show_gateways_and_servers`, `show_domains`, `show_object`.\n* **Rulebases**: `show_access_rulebase`, `show_nat_rulebase`, `show_https_rulebase`, `show_threat_rulebase` with formats: `markdown` (clean table), `model_friendly`, or `raw` JSON.\n* **Native & Sync Operations**: `arodonata_init` (server & domain overview), `search_objects` (cross-domain search), `refresh_objects` (object cache re-sync, mode `skip`/`check`/`force`/`incremental`, default `force`), `refresh_rulebases`, and `api_call` (read-only by default, gated write mode).\n* **Live Compatibility**: ~40 live tools mirroring `@chkp/quantum-management-mcp`.\n* **Declarative CPCRUD (Opt-In)**: `cpcrud_validate`, `cpcrud_plan`, `cpcrud_apply` (dry-run by default), `cpcrud_inverse` for reversible Policy-as-Code changes.\n\n### Running the Server\n\n```bash\n# 1. Install with MCP support\nuv pip install \"arodonata[mcp]\"\n\n# 2. Launch the team server\narodonata-mcp --host 0.0.0.0 --port 8765\n```\n\n### Client Setup\n\n#### Claude Code\n\n```bash\nclaude mcp add --transport http arodonata http://127.0.0.1:8765/mcp --header \"Authorization: Bearer ${DEMO_MCP_TOKEN}\"\n```\n\n#### Claude Desktop\n\nIn your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"arodonata\": {\n      \"url\": \"http://127.0.0.1:8765/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_BEARER_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nFor full documentation on authentication modes (`static` vs `host`), TLS deployment, embedding in your own FastAPI application, and environment variables, see [docs/mcp/index.md](docs/mcp/index.md).\n\n---\n\n## 📖 Documentation\n\nComplete, searchable documentation is built with MkDocs and served locally or via static hosting:\n\n* **[Getting Started](docs/getting-started/index.md)** – Installation, environment variables, and a minimal first script.\n* **[Core Architecture](docs/architecture/index.md)** – Ports and adapters, caching/sync, sessions, and multi-domain resolution.\n* **[Configuration Guide](docs/configuration/index.md)** – Every `ArodonataSettings` field and multi-server setup.\n* **[MCP Server](docs/mcp/index.md)** – Standalone and embedded streamable-HTTP MCP server, authentication, and the tool list.\n* **[API Reference](docs/api/)** – Generated reference for every public class and function in `arodonata`.\n* **[Examples](docs/examples/index.md)** – Runnable, narrated scripts covering queries, search, refresh, and rulebases.\n\n### Local Doc Server\n\nRun the local server to explore the documentation offline:\n\n```bash\nuv run mkdocs serve\n```\n\nThen visit `http://localhost:8000` in your web browser.\n\n---\n\n## 🤝 Contributing\n\nWe welcome pull requests! To get set up for local development:\n\n1. Clone the repository:\n\n    ```bash\n    git clone https://github.com/chkp-antonr/arodonata\n    cd arodonata\n    ```\n\n2. Install dependencies:\n\n    ```bash\n    uv sync --all-extras --dev\n    ```\n\n3. Format and check code quality:\n\n    ```bash\n    uv run ruff check --fix\n    uv run ruff format .\n    uv run mypy src/arodonata\n    ```\n\n4. Run unit tests:\n\n    ```bash\n    uv run pytest\n    ```\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n*Copyright (c) 2024-2026 Anton Razumov (<arazumov@checkpoint.com>)*\n"}