Arodonata v2

Arodonata v2 (2.0.0) is an async-first Python 3.13+ library, declarative Policy-as-Code (CPCRUD) engine, auditable change report generator, and Streamable-HTTP Model Context Protocol (MCP) server for Check Point Security Management and Multi-Domain Security Management (MDSM).

Looking for Arodonata v1 (1.16.0)? Legacy v1 remains frozen in this repository on branch master_v1 and tag v1.16.0. All new projects and downstream integrations should target Arodonata v2.

Quickstart

import asyncio
from arodonata import ArodonataClient


async def main() -> None:
    # Reads ARODONATA_* / MGMT_* environment variables and initializes SQLite/PostgreSQL cache
    async with ArodonataClient() as client:
        domains = await client.get_domains()
        print(f"Discovered {len(domains)} domains: {[d.name for d in domains]}")

        # Smart cache-first read across hosts in Domain4
        hosts = await client.get_hosts(domain="Domain4", cache_mode="smart")
        print(f"Domain4 has {len(hosts)} cached hosts")

        # Multi-term search with recursive parent group resolution
        search = await client.search_objects("10.1.10.50, *.internal.corp", max_depth=2)
        for obj in search.objects:
            print(f"Matched {obj.type} {obj.name} ({obj.uid}) in {obj.domain_name}")


asyncio.run(main())

Core Capability Matrix

Documentation Map

• Getting Started: Installation & Overview, Your First Script, and CPCRUD Quickstart.
• Downstream Integration Contract: Capabilities & Integration Guide (CAPABILITIES.md) — mandatory reading for host applications (e.g., FPCR v2).
• Architecture Deep Dives:
  • Architecture Overview & Hexagonal Ports & Adapters
  • Database Schema Reference (15 arodonata_* Tables)
  • Caching, Incremental Sync & Search
  • Sessions, MDSM & SessionOverlay
  • CPCRUD Engine Internals
• User Guides & MCP:
  • Declarative CPCRUD Operations
  • Auditable Change Reports
  • Model Context Protocol (MCP) Server & Consolidated Tool Surface
• Configuration: Environment Variables & Settings, Multi-Server Topology, and TLS Verification (pinned / tofu / lab-memory).
• Examples (01..12): Runnable Examples Catalog.
• Development: Testing & Quality Gates (./pytest.sh) and Changelog.

Arodonata v2: Capabilities & Downstream Integration Guide

Version: 2.0.0 · Status: Canonical Architecture Specification · Date: October 2026

1. Executive Summary & Architectural Role

Arodonata v2 is an async-first Python 3.13+ platform library, hexagonal SDK, Policy-as-Code (CPCRUD) engine, auditable change report generator, and Streamable-HTTP MCP server for Check Point Security Management and Multi-Domain Security Management (MDSM).

In the enterprise automation ecosystem (such as FPCR v2, web portals, CLIs, and AI agent platforms), Arodonata acts as the single authoritative engine for all Check Point interactions:

• Native aiohttp transport, post-handshake SHA-256 certificate verification (pinned, tofu, lab-memory), per-MDS-member rate limiting, and 70s login throttle recovery (LoginGate).
• Database-backed caching across 15 arodonata_*-prefixed SQLModel tables (PostgreSQL asyncpg and SQLite aiosqlite) with SHA-256 schema hash auto-migration, naive UTC timestamp uniformity (tzinfo=None), and distributed locks (arodonata_distributed_locks).
• Incremental (show-changes) and full synchronization across domains, objects, services, assets (gateways/clusters/VSX), and rulebases with typed streaming progress events (SyncProgressEvent).
• Isolated write sessions (WriteSession) with contextvars-bound SessionOverlay for read-your-own-writes isolation prior to publish.
• Declarative Policy-as-Code (CPCRUDService): offline JSON Schema validation, HybridStateReader, two-axis conflict policies (NameConflictPolicy × IpConflictPolicy), pre-publish staleness verification (DomainStamp), staged session handoff (take-over-session), and compensating rollback generation (inverse).
• Normalized 6-table rulebase cache with exact SmartConsole hierarchical rule numbering (1, 2.1, 3), reverse UID lookup (locate_rules), and local rulebase filtering (filter_rulebase, including output_format="cpcrud").
• Auditable change evidence collection and offline multi-format rendering (HTML, Markdown, JSON).
• Consolidated Model Context Protocol (arodonata.mcp) server with 13 cache-aligned core tools and 5 tamper-proof HMAC-signed CPCRUD tools.

Core Architectural Principle for Downstream Consumers

"Delegate, Never Duplicate" Downstream applications MUST NOT implement custom Check Point HTTP callers, bespoke SQL cache tables for Check Point objects/rules, manual sid session pools, custom rulebase numbering parsers, or ad-hoc object naming algorithms. Consumer applications act strictly as business workflow orchestrators, state machines, user interfaces, and authorization/audit coordinators.

2. Capability Catalog & Consumer Contracts

3. Deep-Dive: Host Application Integration Patterns

3.1 Shared AsyncEngine & Namespace Coexistence

Host applications (such as FastAPI backends using SQLAlchemy/SQLModel) can pass their existing AsyncEngine directly to ArodonataClient(engine=host_engine).

• Non-Destructive Ownership (owns_engine=False): When an external AsyncEngine is passed, await client.close() closes Arodonata's HTTP transport and background tasks without disposing the host application's AsyncEngine.
• Strict Table Namespace Isolation (arodonata_*): All 15 Arodonata tables are prefixed with arodonata_ (ARODONATA_TABLE_NAMES). DatabaseManager.initialize() inspects and migrates only arodonata_* tables, completely ignoring any host application tables registered in SQLModel.metadata (even if the host app has tables named assets, domains, or distributed_locks).
• Naive UTC Timestamp Uniformity: All Arodonata models and database columns use naive UTC (DateTime(timezone=False), tzinfo=None via to_naive_utc() and utc_now()), eliminating asyncpg offset-naive vs offset-aware DataError crashes on PostgreSQL.

from sqlalchemy.ext.asyncio import create_async_engine
from arodonata import ArodonataClient, ArodonataSettings

engine = create_async_engine("postgresql+asyncpg://app:secret@db:5432/fpcr")
settings = ArodonataSettings()

client = ArodonataClient(settings, engine=engine)
await client.initialize()
# ... serve requests ...
await client.close()  # Leaves `engine` open for the host application

3.2 Streaming Synchronization to Web UIs (SSE)

Every batch refresh method (refresh_objects, refresh_services, refresh_assets, refresh_rulebases) and CPCRUD execution (cpcrud.apply) has a paired async generator (stream_refresh_*, cpcrud.stream_apply, stream_publish_staged_session) yielding typed domain events (SyncProgressEvent, CPCRUDEvent).

To stream progress over HTTP Server-Sent Events (SSE), convert domain events at the HTTP boundary using arodonata.adapters.sse.to_sse_event:

from arodonata.adapters.sse import to_sse_event

async for event in client.stream_refresh_objects(domains=["Domain4"], mode="smart-fast"):
    sse = to_sse_event(event)
    yield sse.encode()  # "event: ...\ndata: {...}\n\n"

3.3 Exact Search, Human-Readable Composite IDs, Cross-Domain Structured Queries, and Rule-to-CPCRUD Export

1. Human-Readable Composite Identifiers (object_id, service_id, asset_id) & Dual Topology Links:
   • Every cached entity carries both a collision-safe UID primary key (id = "{mgmt_name}:{domain_name}:{uid}") and an indexed human-readable composite identifier (object_id, service_id, or asset_id = "{mgmt_name}:{domain_name}:{name}").
   • Gateway, cluster, and VSX assets (Asset / arodonata_assets) expose both UID and human-readable parent/child links (parent_uid, parent_name, parent_id, parent_asset_id, member_uids, member_asset_ids, virtual_system_uids, virtual_system_asset_ids), automatically resolving cross-domain VSX-to-Virtual-System relationships across domains on the same management server.
   • find_object(), get_group_members(), search_objects(), and query_objects() accept raw UIDs, object names, or composite identifiers (e.g., "mds:Domain4:hWebHost" or "mds:VSX:VSX-Cluster-01").
2. Exact vs Substring Search: Pass exact_match=True to await client.search_objects(".example.com", exact_match=True) when validating whether an exact FQDN or object name exists without matching subdomains (sub.example.com). Each GroupMembershipNode in SearchResult.memberships includes id, object_id, parent_uids, and parent_object_ids.
3. Cross-Domain Structured Queries (query_objects): Use await client.query_objects(types=["host", "network"], group_by=["domain_name", "type"], aggregate="count") to build dashboard summaries or filter across domains (scope_origin="local" | "global" | "all", plus object_id, service_id, asset_id, parent_id, parent_asset_id) without writing raw SQL against cache tables.
4. Exporting Existing Rules to CPCRUD (output_format="cpcrud"): Use await client.filter_rulebase(mgmt, domain, layer="Standard Network", filter_query="10.1.10.50", output_format="cpcrud") or rule_to_cpcrud_operation(rule) to convert cached rules directly into schema-valid CPCRUD rule dicts for modification or migration.

3.4 Staged CPCRUD Sessions for Approval Workflows

When a workflow requires peer review before publishing to Check Point:

# Phase 1: Stage changes in a dedicated Check Point session without publishing
plan = await client.cpcrud.plan(template)
report = await client.cpcrud.apply(plan, no_publish=True, keep_session=True)
staged_uid = report.staged_sessions[0].session_uid

# Phase 2a: Collect a rich HTML/Markdown ChangeReport from the unpublished session!
evidence = await client.build_change_report(
    [{"mgmt_name": mgmt, "domain": "Domain4", "session_uids": [staged_uid]}],
    formats=["html", "markdown"],
)

# Phase 2b: After human approval, adopt via take-over-session and publish (or discard)
await client.publish_staged_session(mgmt, "Domain4", session_uid=staged_uid)
# Or on rejection:
# await client.discard_staged_session(mgmt, "Domain4", session_uid=staged_uid)

Database Schema Reference (15 arodonata_* Tables)

Arodonata v2 persists all cached topology, shared sessions, distributed locks, objects, services, gateway/VSX assets, and normalized policy rulebases across 15 SQLModel tables defined in src/arodonata/adapters/storage/tables.py (ARODONATA_TABLE_NAMES).

Both PostgreSQL (postgresql+asyncpg://) and SQLite (sqlite+aiosqlite://) are first-class supported backends.

1. Host Application Coexistence & Auto-Migration Design

Arodonata v2 is engineered to share a single database and SQLModel.metadata registry safely with host applications (such as FPCR v2):

1. Strict arodonata_ Table Namespace (ARODONATA_TABLE_NAMES):
   • Every table owned by Arodonata is prefixed with arodonata_ (including arodonata_assets, arodonata_domains, arodonata_distributed_locks, arodonata_sid_cache, arodonata_domain_sync_state).
   • DatabaseManager.initialize() inspects and migrates only tables in ARODONATA_TABLE_NAMES. Any host application tables in the same database or SQLModel.metadata (such as a host app's own assets or domains table) are never touched, altered, or dropped.
2. SHA-256 Schema Hash Auto-Migration (arodonata_schema_version):
   • DatabaseManager computes a deterministic SHA-256 digest (compute_schema_hash()) over the table names, column names, SQL types, primary keys, nullability, and indexes of all 15 arodonata_* tables.
   • If the current schema_hash is already recorded in arodonata_schema_version and all 15 tables exist, startup skips column inspection and completes in < 2ms.
   • When the schema evolves, DatabaseManager adds missing columns/indexes via savepoint-protected (begin_nested()) ALTER TABLE statements—or drops and recreates ephemeral arodonata_* cache tables if primary keys or NOT NULL constraints changed—and records the new schema_hash.
3. Cross-Worker Migration Serialization:
   • Multi-worker Uvicorn/Gunicorn startups are serialized using SELECT pg_advisory_xact_lock(...) on PostgreSQL and BEGIN IMMEDIATE on SQLite, with a double-check of arodonata_schema_version after acquiring the lock.
4. Legacy v1 Table Fingerprint Cleanup:
   • If upgrading an existing database from Arodonata v1, DatabaseManager drops legacy unprefixed domains or sid_cache tables only if they contain positive v1 column fingerprints (mdm_dmn or mgmt_dmn_key), guaranteeing zero risk to unprefixed host tables.
5. Naive UTC Timestamp Uniformity (DateTime(timezone=False)):
   • Every timestamp column in Arodonata uses Column(DateTime(timezone=False)) normalized via to_naive_utc() (tzinfo=None in UTC), preventing asyncpg offset-naive vs offset-aware errors on PostgreSQL.
6. UID Primary Keys (id) + Human-Readable Composite Identifiers (object_id, service_id, asset_id):
   • Check Point permits distinct objects in the same domain (or visible from Global) to share the same name across different object classes (e.g., built-in objects named email) while having distinct uid values, and allows existing objects to be renamed across publishes.
   • Therefore, arodonata_objects, arodonata_services, and arodonata_assets retain a UID-based primary key id = "{mgmt_name}:{domain_name}:{uid}" (preventing primary-key collisions and orphaned rows on rename during smart-fast incremental sync) while simultaneously exposing an indexed, non-unique human-readable composite identifier:
     • CPObject.object_id (arodonata_objects.object_id): "{mgmt_name}:{domain_name}:{name}"
     • CPService.service_id (arodonata_services.service_id): "{mgmt_name}:{domain_name}:{name}"
     • Asset.asset_id (arodonata_assets.asset_id): "{mgmt_name}:{domain_name}:{name}"
   • In addition, arodonata_assets maintains dual UID and human-readable parent/child topology links (parent_uid, parent_name, parent_id, parent_asset_id, member_uids, member_asset_ids, virtual_system_uids, and virtual_system_asset_ids), supporting both intra-domain clusters and cross-domain VSX topology (where a physical VSX gateway/cluster resides in an infrastructure domain like VSX and its Virtual Systems reside in tenant domains like Domain4).

2. Entity-Relationship Diagram (15 Tables)

3. Detailed Table Catalog

3.1 Infrastructure, Sessions & Synchronization Tables

1. arodonata_schema_version (SchemaVersionRecord)

Tracks applied SQLModel metadata SHA-256 hashes so workers skip redundant table migration inspections.

2. arodonata_distributed_locks (DistributedLockRecord)

Coordinates cross-process critical sections (per-domain cache refreshes, login coordination, rate-limit slots).

3. arodonata_sid_cache (SIDCacheRecord)

Persistent shared read-only Check Point session store. Strictly omits sid from __repr__ and __str__.