cortexhub 0.1.0__py3-none-any.whl

cortexhub/policy/loader.py

@@ -0,0 +1,158 @@
+"""Policy loader for local Cedar policy bundles.
+
+Architectural invariants (from AGENTS.md):
+- MUST NOT make decisions
+- MUST NOT evaluate policies
+- ONLY loads and validates policy files
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from cortexhub.errors import PolicyLoadError
+
+logger = structlog.get_logger(__name__)
+
+
+class PolicyBundle:
+    """Represents a loaded policy bundle."""
+
+    def __init__(
+        self,
+        policies: str,
+        schema: dict[str, Any],
+        metadata: dict[str, Any],
+    ):
+        """Initialize policy bundle.
+
+        Args:
+            policies: Cedar policies as string
+            schema: Cedar schema as dict
+            metadata: Bundle metadata
+        """
+        self.policies = policies
+        self.schema = schema
+        self.metadata = metadata
+        self.version = metadata.get("version", "unknown")
+        self.default_behavior = metadata.get("default_behavior", "allow_and_log")
+
+
+class PolicyLoader:
+    """Loads Cedar policy bundles from local filesystem.
+
+    Responsibilities:
+    - Load policy files
+    - Validate structure
+    - Parse metadata
+
+    NOT responsible for:
+    - Making decisions
+    - Evaluating policies
+    """
+
+    def __init__(self, policies_dir: str = "./policies"):
+        """Initialize policy loader.
+
+        Args:
+            policies_dir: Directory containing Cedar policy bundle
+        """
+        self.policies_dir = Path(policies_dir)
+        logger.info("Policy loader initialized", policies_dir=str(self.policies_dir))
+
+    def load(self) -> PolicyBundle:
+        """Load policy bundle from filesystem.
+
+        Returns:
+            PolicyBundle with policies, schema, and metadata
+
+        Raises:
+            PolicyLoadError: If bundle cannot be loaded or is invalid
+        """
+        try:
+            # Load Cedar policies
+            policies_file = self.policies_dir / "cedar" / "policies.cedar"
+            if not policies_file.exists():
+                raise PolicyLoadError(
+                    f"Policies file not found: {policies_file}",
+                    policies_dir=str(self.policies_dir),
+                )
+
+            with open(policies_file) as f:
+                policies = f.read()
+
+            # Load Cedar schema
+            schema_file = self.policies_dir / "cedar" / "schema.json"
+            if not schema_file.exists():
+                raise PolicyLoadError(
+                    f"Schema file not found: {schema_file}",
+                    policies_dir=str(self.policies_dir),
+                )
+
+            with open(schema_file) as f:
+                schema = json.load(f)
+
+            # Load metadata
+            metadata_file = self.policies_dir / "metadata.json"
+            if not metadata_file.exists():
+                raise PolicyLoadError(
+                    f"Metadata file not found: {metadata_file}",
+                    policies_dir=str(self.policies_dir),
+                )
+
+            with open(metadata_file) as f:
+                metadata = json.load(f)
+
+            bundle = PolicyBundle(policies=policies, schema=schema, metadata=metadata)
+
+            logger.info(
+                "Policy bundle loaded",
+                version=bundle.version,
+                default_behavior=bundle.default_behavior,
+                policies_size=len(policies),
+            )
+
+            return bundle
+
+        except PolicyLoadError:
+            raise
+        except Exception as e:
+            raise PolicyLoadError(
+                f"Failed to load policy bundle: {e}",
+                policies_dir=str(self.policies_dir),
+            ) from e
+
+    def validate_bundle(self, bundle: PolicyBundle) -> None:
+        """Validate policy bundle structure.
+
+        Args:
+            bundle: Policy bundle to validate
+
+        Raises:
+            PolicyLoadError: If bundle is invalid
+        """
+        # Basic validation
+        if not bundle.policies:
+            raise PolicyLoadError(
+                "Policy bundle contains no policies",
+                policies_dir=str(self.policies_dir),
+            )
+
+        if not bundle.schema:
+            raise PolicyLoadError(
+                "Policy bundle contains no schema",
+                policies_dir=str(self.policies_dir),
+            )
+
+        # Validate metadata
+        required_metadata_fields = ["version", "default_behavior"]
+        for field in required_metadata_fields:
+            if field not in bundle.metadata:
+                raise PolicyLoadError(
+                    f"Metadata missing required field: {field}",
+                    policies_dir=str(self.policies_dir),
+                )
+
+        logger.info("Policy bundle validated successfully")

cortexhub/policy/models.py

@@ -0,0 +1,123 @@
+"""Core data models for authorization requests.
+
+Critical: DO NOT simplify or flatten these models.
+The structure is intentional and future-proof.
+"""
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Principal(BaseModel):
+    """Entity requesting to perform an action (e.g., an AI agent).
+    
+    Examples:
+        Principal(type="Agent", id="customer_support")
+        Principal(type="User", id="user_12345")
+        Principal(type="Service", id="payment_processor")
+    """
+
+    type: str  # e.g., "Agent", "User", "Service"
+    id: str  # e.g., "customer_support", "user_12345"
+
+
+class Action(BaseModel):
+    """Action being requested (e.g., tool invocation).
+    
+    Examples:
+        Action(type="tool.invoke", name="send_email")
+        Action(type="llm.call", name="gpt-4")
+        Action(type="data.read", name="customer_records")
+    """
+
+    type: str  # e.g., "tool.invoke", "llm.call", "data.read"
+    name: str  # e.g., "send_email", "gpt-4", "customer_records"
+
+
+class Resource(BaseModel):
+    """Resource being accessed (e.g., a tool, database, API).
+    
+    Examples:
+        Resource(type="Tool", id="send_email")
+        Resource(type="Database", id="customer_db")
+        Resource(type="API", id="payment_gateway")
+    """
+
+    type: str  # e.g., "Tool", "Database", "API"
+    id: str  # e.g., "send_email", "customer_db"
+
+
+class RuntimeContext(BaseModel):
+    """Runtime context about the framework and execution environment."""
+
+    framework: str  # e.g., "langchain", "openai_agents"
+    framework_version: str | None = None
+    confidence: float | None = None  # Optional confidence score from LLM
+
+
+class Metadata(BaseModel):
+    """Tracing metadata for debugging and audit."""
+
+    trace_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    session_id: str | None = None
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+
+class AuthorizationRequest(BaseModel):
+    """Complete authorization request sent to the policy engine.
+
+    This is the heart of the system. DO NOT simplify or flatten it.
+
+    The context dict contains reserved top-level keys:
+    - args: Tool arguments (dict)
+    - runtime: RuntimeContext (framework info)
+    - metadata: Metadata (trace_id, session_id, timestamp)
+    
+    Example:
+        AuthorizationRequest(
+            principal=Principal(type="Agent", id="customer_support"),
+            action=Action(type="tool.invoke", name="send_email"),
+            resource=Resource(type="Tool", id="send_email"),
+            context={
+                "args": {"to": "user@example.com", "body": "Hello"},
+                "runtime": {"framework": "langchain"},
+                "metadata": {"trace_id": "abc-123", "session_id": "sess-456"},
+            },
+        )
+    """
+
+    principal: Principal
+    action: Action
+    resource: Resource
+    context: dict[str, Any]  # Reserved keys: args, runtime, metadata
+
+    @property
+    def trace_id(self) -> str:
+        """Extract trace ID for logging/debugging."""
+        metadata = self.context.get("metadata", {})
+        if isinstance(metadata, dict):
+            return metadata.get("trace_id", "unknown")
+        if isinstance(metadata, Metadata):
+            return metadata.trace_id
+        return "unknown"
+    
+    @property
+    def args(self) -> dict[str, Any]:
+        """Extract args from context."""
+        return self.context.get("args", {})
+
+    def with_enriched_context(self, **kwargs) -> "AuthorizationRequest":
+        """Return a new request with additional context.
+        
+        Does NOT mutate the original request.
+        """
+        new_context = {**self.context, **kwargs}
+        return AuthorizationRequest(
+            principal=self.principal,
+            action=self.action,
+            resource=self.resource,
+            context=new_context,
+        )

cortexhub/policy/sync.py

@@ -0,0 +1,183 @@
+"""Policy Sync - downloads policy bundles from CortexHub cloud.
+
+This is the INBOUND flow: policies created by security/compliance team
+in the cloud UI are synced to the SDK for local enforcement.
+
+Key invariants:
+- Policies are PULLED by SDK, never pushed
+- SDK can operate 100% offline with local policies
+- Cloud policies override local policies when connected
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import httpx
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class PolicySync:
+    """Syncs policy bundles from CortexHub cloud.
+    
+    Flow:
+    1. Security team creates policies in cloud UI
+    2. SDK periodically pulls policy bundle
+    3. SDK enforces policies locally
+    4. No customer data involved in sync
+    """
+    
+    def __init__(
+        self,
+        api_key: str | None,
+        backend_url: str,
+        local_policies_dir: str = "./policies",
+        auto_sync: bool = True,
+        sync_interval_seconds: int = 300,  # 5 minutes
+    ):
+        """Initialize policy sync.
+        
+        Args:
+            api_key: API key for authentication
+            backend_url: Backend API URL
+            local_policies_dir: Directory for local policy cache
+            auto_sync: Whether to auto-sync on init
+            sync_interval_seconds: How often to sync (if background sync enabled)
+        """
+        self.api_key = api_key
+        self.backend_url = backend_url.rstrip("/")
+        self.local_policies_dir = Path(local_policies_dir)
+        self.auto_sync = auto_sync
+        self.sync_interval_seconds = sync_interval_seconds
+        
+        self._client: httpx.Client | None = None
+        self._last_sync_version: str | None = None
+        
+        if api_key:
+            self._client = httpx.Client(
+                base_url=self.backend_url,
+                headers={"X-API-Key": api_key},
+                timeout=30.0,
+            )
+        
+        # Ensure local directory exists
+        self.local_policies_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Auto-sync on init if enabled
+        if auto_sync and api_key:
+            self.sync()
+    
+    def sync(self) -> bool:
+        """Sync policies from cloud.
+        
+        Returns:
+            True if sync successful or no update needed
+        """
+        if not self.api_key or not self._client:
+            logger.debug("No API key - using local policies only")
+            return False
+        
+        try:
+            # Check for updates first (lightweight)
+            current_version = self._get_remote_version()
+            
+            if current_version == self._last_sync_version:
+                logger.debug("Policies up to date", version=current_version)
+                return True
+            
+            # Download full bundle
+            bundle = self._download_bundle()
+            
+            if bundle:
+                self._save_bundle(bundle)
+                self._last_sync_version = current_version
+                logger.info(
+                    "Policies synced from cloud",
+                    version=current_version,
+                    policy_count=len(bundle.get("policies", [])),
+                )
+                return True
+            
+            return False
+            
+        except httpx.ConnectError:
+            logger.warning("Backend unreachable - using local policies")
+            return False
+        except Exception as e:
+            logger.error("Policy sync error", error=str(e))
+            return False
+    
+    def _get_remote_version(self) -> str | None:
+        """Get current policy bundle version from cloud."""
+        if not self._client:
+            return None
+        
+        try:
+            response = self._client.get("/policies/version")
+            if response.status_code == 200:
+                return response.json().get("version")
+        except Exception:
+            pass
+        
+        return None
+    
+    def _download_bundle(self) -> dict[str, Any] | None:
+        """Download full policy bundle from cloud."""
+        if not self._client:
+            return None
+        
+        try:
+            response = self._client.get("/policies/bundle")
+            if response.status_code == 200:
+                return response.json()
+        except Exception as e:
+            logger.error("Failed to download policy bundle", error=str(e))
+        
+        return None
+    
+    def _save_bundle(self, bundle: dict[str, Any]) -> None:
+        """Save policy bundle to local cache."""
+        # Save Cedar policies
+        cedar_dir = self.local_policies_dir / "cedar"
+        cedar_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Save main policies file
+        policies_content = bundle.get("policies_cedar", "")
+        if policies_content:
+            (cedar_dir / "policies.cedar").write_text(policies_content)
+        
+        # Save schema
+        schema = bundle.get("schema", {})
+        if schema:
+            (cedar_dir / "schema.json").write_text(json.dumps(schema, indent=2))
+        
+        # Save metadata
+        metadata = {
+            "version": bundle.get("version"),
+            "synced_at": bundle.get("synced_at"),
+            "policy_count": len(bundle.get("policies", [])),
+        }
+        (self.local_policies_dir / "metadata.json").write_text(json.dumps(metadata, indent=2))
+        
+        logger.debug(
+            "Policy bundle saved locally",
+            path=str(self.local_policies_dir),
+        )
+    
+    def get_local_version(self) -> str | None:
+        """Get version of locally cached policies."""
+        metadata_file = self.local_policies_dir / "metadata.json"
+        if metadata_file.exists():
+            try:
+                metadata = json.loads(metadata_file.read_text())
+                return metadata.get("version")
+            except Exception:
+                pass
+        return None
+    
+    def close(self):
+        """Close the HTTP client."""
+        if self._client:
+            self._client.close()

cortexhub/telemetry/__init__.py

@@ -0,0 +1,40 @@
+"""CortexHub Telemetry - OpenTelemetry-based Governance Telemetry.
+
+CortexHub uses OpenTelemetry (OTel) for telemetry, providing:
+- Industry-standard OTLP protocol
+- Proper batching, retry, and backpressure
+- Interoperability with observability tools
+- AI/LLM semantic conventions
+
+Privacy Mode (default: enabled):
+- Tool name, description, argument names (NOT values)
+- PII/secret types detected (NOT actual data)
+- Agent ID, framework
+
+What is NEVER sent (when privacy=True):
+- Raw argument values
+- Prompts or LLM responses
+- PII literals (emails, SSNs, names, etc.)
+- Secrets (API keys, passwords, tokens)
+- Customer data
+
+Telemetry Modes:
+- privacy=True (DEFAULT): Metadata only, production-safe
+- privacy=False: Raw data included, for dev/staging testing only
+"""
+
+# OTel-based telemetry
+from cortexhub.telemetry.otel import (
+    OTelTelemetry,
+    init_telemetry,
+    get_telemetry,
+    shutdown_telemetry,
+)
+
+__all__ = [
+    # OTel-based telemetry
+    "OTelTelemetry",
+    "init_telemetry",
+    "get_telemetry",
+    "shutdown_telemetry",
+]