cortexhub 0.1.0__py3-none-any.whl

cortexhub/interceptors/mcp.py

@@ -0,0 +1,96 @@
+"""MCP (Model Context Protocol) server interceptor.
+
+Intercepts calls to MCP servers and enforces policies before execution.
+"""
+
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class MCPInterceptor:
+    """Intercepts and governs MCP server calls.
+
+    MCP provides:
+    - Tool/resource discovery
+    - Prompts and sampling
+    - Bidirectional communication with context providers
+    """
+
+    def __init__(self, cortex_hub: Any):  # Type: CortexHub
+        """Initialize MCP interceptor.
+
+        Args:
+            cortex_hub: CortexHub instance for policy enforcement
+        """
+        self.cortex_hub = cortex_hub
+        logger.info("MCP interceptor initialized")
+
+    def intercept_mcp_client(self) -> None:
+        """Intercept MCP client calls."""
+        try:
+            # MCP client library (if available)
+            from mcp import Client
+
+            if hasattr(Client, "_original_call_tool"):
+                logger.info("MCP client already intercepted")
+                return
+
+            original_call_tool = Client.call_tool
+
+            async def governed_call_tool(self, server_name: str, tool_name: str, arguments: dict):
+                from cortexhub.policy.models import AuthorizationRequest
+
+                request = AuthorizationRequest.create(
+                    principal_id=self.cortex_hub.session_id,
+                    action_name=f"mcp.{tool_name}",
+                    resource_id=f"{server_name}.{tool_name}",
+                    args=arguments,
+                    framework="mcp",
+                )
+
+                self.cortex_hub.enforce(request)
+                return await original_call_tool(self, server_name, tool_name, arguments)
+
+            Client.call_tool = governed_call_tool
+            Client._original_call_tool = original_call_tool
+
+            logger.info("MCP client interceptor applied")
+
+        except ImportError:
+            logger.debug("MCP client not available, skipping interception")
+        except Exception as e:
+            logger.error("Failed to intercept MCP client", error=str(e))
+
+    def apply_all(self) -> None:
+        """Apply all MCP interceptors."""
+        self.intercept_mcp_client()
+        logger.info("All MCP interceptors applied")
+
+    async def discover_mcp_tools(self, mcp_client) -> list[dict]:
+        """Discover tools from MCP server via list_tools()."""
+
+        tools: list[dict] = []
+        try:
+            result = await mcp_client.list_tools()
+            for tool in result.tools:
+                tools.append(
+                    {
+                        "name": tool.name,
+                        "description": tool.description,
+                        "parameters_schema": {
+                            "type": "object",
+                            "properties": tool.inputSchema.get("properties", {}),
+                            "required": tool.inputSchema.get("required", []),
+                        }
+                        if tool.inputSchema
+                        else None,
+                        "source": "mcp",
+                        "mcp_server_name": getattr(mcp_client, "server_name", None),
+                    }
+                )
+        except Exception as e:
+            logger.warning("Failed to discover MCP tools", error=str(e))
+        return tools

cortexhub/pipeline.py

@@ -0,0 +1,92 @@
+"""Unified governance pipeline for adapters that can't use SDK entrypoint directly.
+
+This is a thin wrapper around cortex_hub.execute_governed_tool() for adapters
+that need to create governed wrappers (e.g., CrewAI, LlamaIndex).
+
+Architectural rules:
+- This is a convenience wrapper, not a separate pipeline
+- All governance logic lives in CortexHub client
+- Adapters should prefer calling SDK entrypoint directly when possible
+"""
+
+import asyncio
+from typing import Any, Callable
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+def is_async_callable(fn: Callable) -> bool:
+    """Check if a callable is async."""
+    return asyncio.iscoroutinefunction(fn)
+
+
+def govern_execution(
+    tool_fn: Callable,
+    tool_metadata: dict[str, Any],
+    cortex_hub: Any,  # Type: CortexHub
+) -> Callable:
+    """Create governed wrapper for sync or async execution.
+
+    This wraps the SDK's execute_governed_tool() for adapters that need
+    to create function wrappers.
+
+    Args:
+        tool_fn: The actual function to execute
+        tool_metadata: Tool information (name, framework, description)
+        cortex_hub: CortexHub instance
+
+    Returns:
+        Wrapped function (sync or async based on tool_fn)
+    """
+    execution_kind = tool_metadata.get("kind", "tool")
+    tool_name = tool_metadata.get("name", "unknown")
+    tool_description = tool_metadata.get("description")
+    framework = tool_metadata.get("framework", "unknown")
+    model = tool_metadata.get("model", "unknown")
+    prompt = tool_metadata.get("prompt")
+    call_original = tool_metadata.get("call_original")
+    if call_original is None:
+        call_original = tool_fn
+    
+    if execution_kind == "llm":
+        if is_async_callable(call_original):
+            async def async_wrapper(*args, **kwargs):
+                return await cortex_hub.execute_governed_llm_call_async(
+                    model=model,
+                    prompt=prompt,
+                    framework=framework,
+                    call_original=call_original,
+                )
+            return async_wrapper
+        else:
+            def sync_wrapper(*args, **kwargs):
+                return cortex_hub.execute_governed_llm_call(
+                    model=model,
+                    prompt=prompt,
+                    framework=framework,
+                    call_original=call_original,
+                )
+            return sync_wrapper
+
+    if is_async_callable(tool_fn):
+        async def async_wrapper(*args, **kwargs):
+            return await cortex_hub.execute_governed_tool_async(
+                tool_name=tool_name,
+                tool_description=tool_description,
+                args=kwargs,  # Use kwargs for structured arguments
+                framework=framework,
+                call_original=lambda: tool_fn(*args, **kwargs),
+            )
+        return async_wrapper
+    else:
+        def sync_wrapper(*args, **kwargs):
+            return cortex_hub.execute_governed_tool(
+                tool_name=tool_name,
+                tool_description=tool_description,
+                args=kwargs,  # Use kwargs for structured arguments
+                framework=framework,
+                call_original=lambda: tool_fn(*args, **kwargs),
+            )
+        return sync_wrapper

cortexhub/policy/__init__.py

@@ -0,0 +1,6 @@
+"""Policy engine for Cedar evaluation."""
+
+from cortexhub.policy.effects import Decision, Effect
+from cortexhub.policy.models import AuthorizationRequest
+
+__all__ = ["AuthorizationRequest", "Decision", "Effect"]

cortexhub/policy/effects.py

@@ -0,0 +1,87 @@
+"""Decision effects from policy evaluation.
+
+Critical: Determinism guarantee - Same AuthorizationRequest MUST always produce
+same Decision. This is essential for testing and auditability.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class Effect(str, Enum):
+    """Policy decision effect."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    ESCALATE = "escalate"
+    REDACT = "redact"  # PII/secrets were redacted before LLM call
+
+
+class Decision(BaseModel):
+    """Result of policy evaluation.
+
+    Attributes:
+        effect: The decision (ALLOW/DENY/ESCALATE)
+        reasoning: Human-readable explanation
+        policy_id: Which policy triggered this decision (if any)
+        policy_name: Friendly policy name (if available)
+    """
+
+    effect: Effect
+    reasoning: str
+    policy_id: str | None = None
+    policy_name: str | None = None
+
+    def is_allowed(self) -> bool:
+        """Check if the decision allows execution."""
+        return self.effect == Effect.ALLOW
+
+    def is_denied(self) -> bool:
+        """Check if the decision denies execution."""
+        return self.effect == Effect.DENY
+
+    def requires_approval(self) -> bool:
+        """Check if the decision requires approval (escalation)."""
+        return self.effect == Effect.ESCALATE
+
+    @classmethod
+    def allow(
+        cls,
+        reasoning: str = "Allowed by policy",
+        policy_id: str | None = None,
+        policy_name: str | None = None,
+    ):
+        """Create an ALLOW decision."""
+        return cls(
+            effect=Effect.ALLOW, reasoning=reasoning, policy_id=policy_id, policy_name=policy_name
+        )
+
+    @classmethod
+    def deny(cls, reasoning: str, policy_id: str | None = None, policy_name: str | None = None):
+        """Create a DENY decision."""
+        return cls(
+            effect=Effect.DENY, reasoning=reasoning, policy_id=policy_id, policy_name=policy_name
+        )
+
+    @classmethod
+    def escalate(
+        cls, reasoning: str, policy_id: str | None = None, policy_name: str | None = None
+    ):
+        """Create an ESCALATE decision."""
+        return cls(
+            effect=Effect.ESCALATE, reasoning=reasoning, policy_id=policy_id, policy_name=policy_name
+        )
+
+    @classmethod
+    def redact(
+        cls, reasoning: str, policy_id: str | None = None, policy_name: str | None = None
+    ):
+        """Create a REDACT decision (PII/secrets were redacted before execution)."""
+        return cls(
+            effect=Effect.REDACT, reasoning=reasoning, policy_id=policy_id, policy_name=policy_name
+        )
+
+    def is_redacted(self) -> bool:
+        """Check if the decision resulted in redaction."""
+        return self.effect == Effect.REDACT

cortexhub/policy/evaluator.py

@@ -0,0 +1,267 @@
+"""Policy evaluator using Cedar.
+
+Architectural invariants (from AGENTS.md):
+- MUST NOT read files directly (use loader.py)
+- MUST NOT make decisions (only evaluate)
+
+Uses cedarpy for production-grade policy evaluation.
+"""
+
+import os
+import time
+from datetime import datetime
+from typing import Any
+
+import structlog
+
+from cortexhub.errors import PolicyLoadError
+
+try:
+    import cedarpy as cedar_module
+except Exception as exc:
+    raise PolicyLoadError(
+        "Cedar policy engine is required for enforcement. Install with: uv add cedarpy",
+        policies_dir="backend",
+    ) from exc
+
+from cortexhub.policy.effects import Decision, Effect
+from cortexhub.policy.loader import PolicyBundle
+from cortexhub.policy.models import AuthorizationRequest
+
+logger = structlog.get_logger(__name__)
+
+
+class PolicyEvaluator:
+    """Evaluates authorization requests against Cedar policies.
+
+    Deterministic guarantee: Same input → same output, always.
+    Performance target: <0.5ms
+    """
+
+    def __init__(self, policy_bundle: PolicyBundle):
+        """Initialize policy evaluator.
+
+        Args:
+            policy_bundle: Loaded policy bundle (from loader.py)
+        """
+        self.policy_bundle = policy_bundle
+        self.default_behavior = policy_bundle.default_behavior
+
+        try:
+            logger.info(
+                "Cedar policy evaluator initialized",
+                version=policy_bundle.version,
+                default_behavior=self.default_behavior,
+                cedar_version="cedarpy",
+            )
+        except Exception as e:
+            raise PolicyLoadError(
+                f"Failed to initialize Cedar policy evaluator: {e}",
+                policies_dir="backend",
+            ) from e
+
+    def evaluate(self, request: AuthorizationRequest) -> Decision:
+        """Evaluate authorization request against policies.
+
+        Deterministic: Same request always produces same decision.
+        Performance target: <0.5ms
+
+        Args:
+            request: Authorization request to evaluate
+
+        Returns:
+            Decision (ALLOW/DENY/ESCALATE)
+        """
+        start_time = time.perf_counter()
+
+        try:
+            decision = self._evaluate_cedar(request)
+
+            latency_ms = (time.perf_counter() - start_time) * 1000
+
+            logger.info(
+                "Policy evaluated",
+                effect=decision.effect,
+                latency_ms=f"{latency_ms:.3f}",
+                trace_id=request.trace_id,
+                tool=request.action.name,
+            )
+
+            return decision
+
+        except Exception as e:
+            logger.error("Policy evaluation failed", error=str(e), trace_id=request.trace_id)
+            # Fail closed - deny on error
+            return Decision.deny(f"Policy evaluation error: {e}")
+
+    def _evaluate_cedar(self, request: AuthorizationRequest) -> Decision:
+        """Evaluate using real Cedar engine.
+
+        Args:
+            request: Authorization request
+
+        Returns:
+            Decision
+        """
+        principal_type = request.principal.type
+        principal_id = request.principal.id
+        action = request.action.type
+        resource_type = request.resource.type
+        resource_id = request.resource.id
+
+        cedar_request = {
+            "principal": f'{principal_type}::"{principal_id}"',
+            "action": f'Action::"{action}"',
+            "resource": f'{resource_type}::"{resource_id}"',
+            "context": self._json_safe(request.context),
+        }
+
+        result = cedar_module.is_authorized(
+            request=cedar_request,
+            policies=self.policy_bundle.policies,
+            entities=[],
+            schema=self.policy_bundle.schema or None,
+        )
+        policy_map = self.policy_bundle.metadata.get("policy_map", {}) if self.policy_bundle else {}
+        if os.getenv("CORTEXHUB_CEDAR_DEBUG", "").lower() in ("1", "true", "yes"):
+            logger.debug(
+                "Cedar evaluation",
+                decision=str(result.decision),
+                reasons=result.diagnostics.reasons,
+                policy_count=len(policy_map),
+                action=request.action.type,
+                resource=request.resource.type,
+                guardrails=self._json_safe(request.context.get("guardrails", {})),
+                redaction=self._json_safe(request.context.get("redaction", {})),
+                context_summary=self._summarize_context(request.context),
+            )
+
+        def _resolve_policy_metadata(policy_id: str | None) -> tuple[str | None, str | None, str | None]:
+            if policy_id:
+                meta = policy_map.get(policy_id, {})
+                return (
+                    meta.get("policy_document_id") or policy_id,
+                    meta.get("name"),
+                    meta.get("effect"),
+                )
+            if len(policy_map) == 1:
+                only_id = next(iter(policy_map.keys()))
+                meta = policy_map.get(only_id, {})
+                return (
+                    meta.get("policy_document_id") or only_id,
+                    meta.get("name"),
+                    meta.get("effect"),
+                )
+            return None, None, None
+
+        if result.decision == cedar_module.Decision.Allow:
+            reason = result.diagnostics.reasons[0] if result.diagnostics.reasons else None
+            policy_id, policy_name, policy_effect = _resolve_policy_metadata(reason)
+            return Decision.allow(
+                reasoning="Allowed by Cedar policy",
+                policy_id=policy_id,
+                policy_name=policy_name,
+            )
+        if result.decision == cedar_module.Decision.Deny:
+            if not result.diagnostics.reasons:
+                if self.default_behavior == "allow_and_log":
+                    return Decision.allow(
+                        f"Tool '{request.action.name}' allowed by default behavior",
+                        policy_id="default",
+                    )
+                if self.default_behavior == "deny_and_log":
+                    return Decision.deny(
+                        f"Tool '{request.action.name}' denied by default behavior (no matching policy)",
+                        policy_id="default",
+                    )
+                if self.default_behavior == "escalate":
+                    return Decision.escalate(
+                        f"Tool '{request.action.name}' requires approval (unknown tool)",
+                        policy_id="default",
+                    )
+                return Decision.deny("Invalid default behavior configuration", policy_id="error")
+            reason = result.diagnostics.reasons[0]
+            policy_id, policy_name, policy_effect = _resolve_policy_metadata(reason)
+            if policy_effect == "require_approval":
+                return Decision.escalate(
+                    reasoning="Approval required by policy",
+                    policy_id=policy_id,
+                    policy_name=policy_name,
+                )
+            if self._should_escalate(request):
+                return Decision.escalate(
+                    reasoning="High-risk operation requires approval",
+                    policy_id=policy_id,
+                    policy_name=policy_name,
+                )
+            return Decision.deny(
+                reasoning="Denied by CortexHub Policy",
+                policy_id=policy_id,
+                policy_name=policy_name,
+            )
+
+        # NoDecision: apply default behavior
+        if result.decision == cedar_module.Decision.NoDecision and self.default_behavior == "allow_and_log":
+            return Decision.allow(
+                f"Tool '{request.action.name}' allowed by default behavior",
+                policy_id="default",
+            )
+        if result.decision == cedar_module.Decision.NoDecision and self.default_behavior == "deny_and_log":
+            return Decision.deny(
+                f"Tool '{request.action.name}' denied by default behavior (no matching policy)",
+                policy_id="default",
+            )
+        if result.decision == cedar_module.Decision.NoDecision and self.default_behavior == "escalate":
+            return Decision.escalate(
+                f"Tool '{request.action.name}' requires approval (unknown tool)",
+                policy_id="default",
+            )
+        return Decision.deny("Invalid default behavior configuration", policy_id="error")
+
+    def _json_safe(self, value: Any) -> Any:
+        if value is None:
+            return None
+        if isinstance(value, datetime):
+            return value.isoformat()
+        if isinstance(value, dict):
+            cleaned: dict[str, Any] = {}
+            for key, val in value.items():
+                safe_val = self._json_safe(val)
+                if safe_val is not None:
+                    cleaned[key] = safe_val
+            return cleaned
+        if isinstance(value, list):
+            return [item for item in (self._json_safe(item) for item in value) if item is not None]
+        return value
+
+    def _summarize_context(self, context: dict[str, Any]) -> dict[str, Any]:
+        def summarize(value: Any) -> Any:
+            if isinstance(value, dict):
+                return {key: summarize(val) for key, val in value.items()}
+            if isinstance(value, list):
+                return [summarize(item) for item in value]
+            return type(value).__name__
+
+        return summarize(context)
+
+    def _should_escalate(self, request: AuthorizationRequest) -> bool:
+        """Determine if a DENY should be escalated to approval (Cedar version).
+
+        Args:
+            request: Authorization request
+
+        Returns:
+            True if should escalate
+        """
+        tool_name = request.action.name
+        args = request.context.get("args", {})
+
+        # High-value refunds
+        if tool_name == "refund_payment":
+            amount = args.get("amount", 0)
+            return amount > 100
+
+        # Other escalation rules can be added here
+        return False
+
+