cortexhub 0.1.0__py3-none-any.whl

cortexhub/__init__.py

@@ -0,0 +1,143 @@
+"""CortexHub Python SDK - Runtime Governance for AI Agents.
+
+Add 2 lines to your existing agent code to get full governance:
+
+    import cortexhub
+    cortex = cortexhub.init("my_agent", cortexhub.Framework.LANGGRAPH)
+
+That's it! CortexHub will:
+- Monitor all tool calls and LLM interactions  
+- Detect PII, secrets, and sensitive data in real-time
+- Enforce policies (block, redact, require approval) based on your configuration
+
+IMPORTANT: A valid API key is REQUIRED. Get yours at https://app.cortexhub.ai
+
+Supported Agent Frameworks:
+- LangGraph: Stateful agents with checkpointing and interrupt()
+- CrewAI: Multi-agent crews with human_input support
+- OpenAI Agents SDK: Native agents with needsApproval
+- Claude Agent SDK: Computer-use agents with subagents
+
+Installation:
+    # Core SDK (includes Cedar, OpenTelemetry, Presidio, detect-secrets)
+    pip install cortexhub
+    
+    # With framework adapter
+    pip install cortexhub[langgraph]      # + LangGraph
+    pip install cortexhub[crewai]         # + CrewAI  
+    pip install cortexhub[openai-agents]  # + OpenAI Agents SDK
+    pip install cortexhub[claude-agents]  # + Claude Agent SDK
+
+Usage:
+    import cortexhub
+    
+    # Set your API key (or use CORTEXHUB_API_KEY environment variable)
+    # For LangGraph
+    cortex = cortexhub.init("my_agent", cortexhub.Framework.LANGGRAPH)
+    
+    # For CrewAI
+    cortex = cortexhub.init("my_crew", cortexhub.Framework.CREWAI)
+    
+    # For OpenAI Agents
+    cortex = cortexhub.init("my_agent", cortexhub.Framework.OPENAI_AGENTS)
+    
+    # For Claude Agents
+    cortex = cortexhub.init("my_agent", cortexhub.Framework.CLAUDE_AGENTS)
+"""
+
+from cortexhub.client import CortexHub
+from cortexhub.frameworks import Framework
+from cortexhub.version import __version__
+from cortexhub.errors import (
+    CortexHubError,
+    ConfigurationError,
+    PolicyViolationError,
+    GuardrailViolationError,
+    ApprovalRequiredError,
+    ApprovalDeniedError,
+    PolicyLoadError,
+)
+
+# Global instance for simple init() usage
+_global_instance: CortexHub | None = None
+
+
+def init(
+    agent_id: str,
+    framework: Framework,
+    *,
+    api_key: str | None = None,
+    privacy: bool = True,
+) -> CortexHub:
+    """Initialize CortexHub governance for your AI agent.
+    
+    Call this ONCE at the start of your application, BEFORE importing
+    your AI framework. CortexHub will automatically govern all tool 
+    calls and LLM interactions.
+    
+    Args:
+        agent_id: A stable identifier for your agent. Use something
+                  descriptive like "customer_support_agent" or 
+                  "financial_analysis_crew".
+        framework: The AI agent framework you're using:
+                   - Framework.LANGGRAPH (LangGraph)
+                   - Framework.CREWAI (CrewAI)
+                   - Framework.OPENAI_AGENTS (OpenAI Agents SDK)
+                   - Framework.CLAUDE_AGENTS (Claude Agent SDK)
+        api_key: Your CortexHub API key. Can also be set via the
+                 CORTEXHUB_API_KEY environment variable.
+        privacy: If True (default), only metadata is sent to cloud.
+                 If False, raw data is included for testing redaction.
+    
+    Returns:
+        CortexHub instance
+    
+    Example:
+        import cortexhub
+        
+        # Initialize before importing your framework
+        cortex = cortexhub.init("customer_support", cortexhub.Framework.LANGGRAPH)
+        
+        # Now import and use LangGraph as normal
+        from langgraph.prebuilt import create_react_agent
+        
+        # All tool calls are now governed by CortexHub
+    """
+    global _global_instance
+    
+    _global_instance = CortexHub(
+        api_key=api_key,
+        agent_id=agent_id,
+        privacy=privacy,
+    )
+    
+    # Apply the framework-specific adapter
+    _global_instance.protect(framework)
+    
+    return _global_instance
+
+
+def get_instance() -> CortexHub | None:
+    """Get the global CortexHub instance.
+    
+    Returns None if init() hasn't been called.
+    """
+    return _global_instance
+
+
+__all__ = [
+    # Main API
+    "init",
+    "get_instance",
+    "CortexHub",
+    "Framework",
+    "__version__",
+    # Errors (for exception handling)
+    "CortexHubError",
+    "ConfigurationError",
+    "PolicyViolationError",
+    "GuardrailViolationError",
+    "ApprovalRequiredError",
+    "ApprovalDeniedError",
+    "PolicyLoadError",
+]

cortexhub/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Framework adapters for intercepting tool calls."""
+
+from cortexhub.adapters.base import ToolAdapter
+
+__all__ = ["ToolAdapter"]

cortexhub/adapters/base.py

@@ -0,0 +1,131 @@
+"""Base adapter interface for framework interception.
+
+Critical: Adapters MUST NOT infer intent, classify tools, rewrite arguments, or suppress failures.
+They MUST ONLY construct AuthorizationRequest and run the enforcement pipeline.
+
+Architectural rules:
+- Adapter is DUMB plumbing
+- SDK orchestrates everything
+- Adapter explicitly branches on Decision
+- Async-safe with output guardrails
+- No hidden behavior
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class ToolAdapter(ABC):
+    """Base class for framework-specific tool adapters.
+
+    Adapters intercept tool calls at the framework level and enforce policies
+    before execution.
+
+    Architectural Rules:
+    - MUST NOT infer intent
+    - MUST NOT classify tools
+    - MUST NOT rewrite arguments
+    - MUST NOT suppress failures
+    - MUST construct AuthorizationRequest and run pipeline only
+    - MUST explicitly branch on Decision (ALLOW/DENY/ESCALATE)
+    - MUST support unpatch() for test isolation
+    """
+
+    def __init__(self, cortex_hub: Any):  # Type: CortexHub, but avoiding circular import
+        """Initialize adapter.
+
+        Args:
+            cortex_hub: CortexHub instance for policy enforcement
+        """
+        self.cortex_hub = cortex_hub
+        logger.info(
+            "Adapter initialized", adapter=self.__class__.__name__, framework=self.framework_name
+        )
+
+    @property
+    @abstractmethod
+    def framework_name(self) -> str:
+        """Name of the framework this adapter supports."""
+        pass
+
+    @abstractmethod
+    def patch(self) -> None:
+        """Patch the framework to intercept tool calls.
+
+        This method should monkey-patch or wrap the framework's tool execution
+        mechanism to enforce governance before actual execution.
+        
+        Pipeline that MUST be followed:
+        1. Build AuthorizationRequest (don't flatten!)
+        2. Log tool invocation (pending)
+        3. Run input guardrails
+        4. Evaluate policy -> get Decision
+        5. EXPLICITLY branch on Decision
+        6. Execute tool
+        7. Run output guardrails (async-safe)
+        8. Log execution result
+        """
+        pass
+
+    def unpatch(self) -> None:
+        """Restore original framework methods.
+        
+        Useful for:
+        - Test isolation
+        - REPL usage
+        - Multiple SDK instances
+        
+        Default implementation does nothing.
+        Subclasses should override if they store original methods.
+        """
+        logger.debug("unpatch() not implemented for this adapter")
+
+    @abstractmethod
+    def intercept(
+        self, tool_fn: Callable, tool_name: str, args: dict[str, Any], **kwargs: Any
+    ) -> Any:
+        """Intercept a tool call and enforce policies.
+
+        NOTE: Most adapters should use govern_execution() from pipeline.py
+        instead of implementing this directly.
+
+        Args:
+            tool_fn: The actual tool function to execute (if allowed)
+            tool_name: Name of the tool being invoked
+            args: Arguments passed to the tool
+            **kwargs: Additional metadata from the framework
+
+        Returns:
+            Result of tool execution (if allowed)
+
+        Raises:
+            PolicyViolationError: If policy denies execution
+            GuardrailViolationError: If guardrails block execution
+            ApprovalDeniedError: If approval is denied
+        """
+        pass
+
+    def is_framework_available(self) -> bool:
+        """Check if the framework is available (imported).
+
+        Returns:
+            True if the framework is available
+        """
+        import sys
+
+        # Check if framework module is in sys.modules
+        framework_modules = self._get_framework_modules()
+        return any(mod in sys.modules for mod in framework_modules)
+
+    @abstractmethod
+    def _get_framework_modules(self) -> list[str]:
+        """Get list of module names that indicate framework presence.
+
+        Returns:
+            List of module names to check in sys.modules
+        """
+        pass

cortexhub/adapters/claude_agents.py

@@ -0,0 +1,322 @@
+"""Claude Agent SDK adapter for tool interception.
+
+The Claude Agent SDK provides agentic capabilities including:
+- Computer use (bash, files, code)
+- Custom MCP tools via @tool decorator
+- Subagents for parallelization
+- Hooks for pre/post tool execution
+
+We integrate by:
+1. Wrapping the @tool decorator to govern custom tools
+2. Using hooks (PreToolUse, PostToolUse) to govern built-in tools
+
+Reference: https://docs.anthropic.com/en/docs/agent-sdk/python
+
+Architectural rules:
+- Adapter is DUMB plumbing
+- Adapter calls ONE SDK entrypoint: govern_execution()
+- SDK orchestrates everything
+- No governance logic in adapter
+"""
+
+import os
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Awaitable
+
+import structlog
+
+from cortexhub.adapters.base import ToolAdapter
+from cortexhub.pipeline import govern_execution
+
+if TYPE_CHECKING:
+    from cortexhub.client import CortexHub
+
+logger = structlog.get_logger(__name__)
+
+# Attribute names for storing originals
+_ORIGINAL_TOOL_ATTR = "__cortexhub_original_tool__"
+_PATCHED_ATTR = "__cortexhub_patched__"
+
+
+class ClaudeAgentsAdapter(ToolAdapter):
+    """Adapter for Claude Agent SDK.
+
+    Integrates CortexHub governance via two mechanisms:
+    
+    1. @tool decorator wrapping:
+       Custom MCP tools created with @tool are wrapped to run
+       governance pipeline before/after execution.
+    
+    2. Hooks integration:
+       PreToolUse and PostToolUse hooks intercept built-in tools
+       like Bash, Read, Write, Edit, etc.
+    
+    For approval workflows:
+    - PreToolUse hook can block tool execution
+    - Custom tools can raise ApprovalRequiredError
+    
+    Key properties:
+    - Adapter is dumb plumbing
+    - Calls SDK entrypoint, doesn't implement governance
+    """
+
+    @property
+    def framework_name(self) -> str:
+        return "claude_agents"
+
+    def _get_framework_modules(self) -> list[str]:
+        return ["claude_agent_sdk"]
+
+    def patch(self) -> None:
+        """Patch Claude Agent SDK tool creation.
+        
+        Wraps the @tool decorator to intercept custom tool creation
+        and add CortexHub governance.
+        """
+        try:
+            import claude_agent_sdk
+            from claude_agent_sdk import tool as original_tool_decorator
+            
+            # Check if already patched
+            if getattr(claude_agent_sdk, _PATCHED_ATTR, False):
+                logger.info("Claude Agent SDK already patched")
+                return
+            
+            cortex_hub = self.cortex_hub
+            tools = self._discover_tools()
+            if tools:
+                cortex_hub.backend.register_tool_inventory(
+                    agent_id=cortex_hub.agent_id,
+                    framework=self.framework_name,
+                    tools=tools,
+                )
+            
+            # Store original decorator
+            if not hasattr(claude_agent_sdk, _ORIGINAL_TOOL_ATTR):
+                setattr(claude_agent_sdk, _ORIGINAL_TOOL_ATTR, original_tool_decorator)
+            
+            original_tool = getattr(claude_agent_sdk, _ORIGINAL_TOOL_ATTR)
+            
+            def patched_tool(
+                name: str,
+                description: str,
+                input_schema: type | dict[str, Any],
+            ) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], Any]:
+                """Wrapped @tool decorator that adds CortexHub governance."""
+                
+                def decorator(handler: Callable[[Any], Awaitable[dict[str, Any]]]) -> Any:
+                    # Create the original tool
+                    original_decorated = original_tool(name, description, input_schema)(handler)
+                    
+                    # Wrap the handler with governance
+                    original_handler = original_decorated.handler
+                    tool_name = original_decorated.name
+                    tool_description = original_decorated.description
+                    
+                    @wraps(original_handler)
+                    async def governed_handler(args: dict[str, Any]) -> dict[str, Any]:
+                        """Governed tool execution."""
+                        tool_metadata = {
+                            "name": tool_name,
+                            "description": tool_description,
+                            "framework": "claude_agents",
+                        }
+                        
+                        governed_fn = govern_execution(
+                            tool_fn=lambda **kw: original_handler(args),
+                            tool_metadata=tool_metadata,
+                            cortex_hub=cortex_hub,
+                        )
+                        
+                        # Execute with governance (async)
+                        result = governed_fn(**args)
+                        if hasattr(result, '__await__'):
+                            result = await result
+                        return result
+                    
+                    # Replace the handler
+                    original_decorated.handler = governed_handler
+                    return original_decorated
+                
+                return decorator
+            
+            # Apply patch
+            claude_agent_sdk.tool = patched_tool
+            setattr(claude_agent_sdk, _PATCHED_ATTR, True)
+            
+            logger.info("Claude Agent SDK @tool decorator patched successfully")
+            
+        except ImportError:
+            logger.debug("Claude Agent SDK not installed, skipping adapter")
+        except Exception as e:
+            logger.error("Failed to patch Claude Agent SDK", error=str(e))
+
+    def unpatch(self) -> None:
+        """Restore original @tool decorator."""
+        try:
+            import claude_agent_sdk
+            
+            if hasattr(claude_agent_sdk, _ORIGINAL_TOOL_ATTR):
+                original = getattr(claude_agent_sdk, _ORIGINAL_TOOL_ATTR)
+                claude_agent_sdk.tool = original
+                setattr(claude_agent_sdk, _PATCHED_ATTR, False)
+                logger.info("Claude Agent SDK adapter unpatched")
+        except ImportError:
+            pass
+
+    def intercept(self, tool_fn, tool_name, args, **kwargs):
+        """Not used - governance happens via wrapped decorator."""
+        raise NotImplementedError("Use govern_execution via wrapped decorator")
+
+    def _discover_tools(self) -> list[dict[str, Any]]:
+        """Discover tools from Claude Agent SDK (best-effort)."""
+        return []
+    
+    def create_governance_hooks(self) -> dict[str, list]:
+        """Create CortexHub governance hooks for Claude Agent SDK.
+        
+        These hooks can be passed to ClaudeAgentOptions to govern
+        built-in tools like Bash, Read, Write, Edit, etc.
+        
+        Returns:
+            Dict of hook configurations for PreToolUse and PostToolUse
+        
+        Example:
+            adapter = ClaudeAgentsAdapter(cortex_hub)
+            hooks = adapter.create_governance_hooks()
+            
+            options = ClaudeAgentOptions(
+                hooks=hooks,
+                allowed_tools=["Bash", "Read", "Write"],
+            )
+        """
+        cortex_hub = self.cortex_hub
+        
+        async def pre_tool_governance(
+            input_data: dict[str, Any],
+            tool_use_id: str | None,
+            context: Any,
+        ) -> dict[str, Any]:
+            """Pre-tool governance hook.
+            
+            Evaluates policy BEFORE tool execution.
+            Can block the tool by returning decision="block".
+            """
+            tool_name = input_data.get("tool_name", "unknown")
+            tool_input = input_data.get("tool_input", {})
+            
+            tool_metadata = {
+                "name": tool_name,
+                "description": f"Claude Agent SDK built-in tool: {tool_name}",
+                "framework": "claude_agents",
+            }
+            
+            # Build authorization request and evaluate
+            from cortexhub.policy.models import (
+                Action,
+                Principal,
+                Resource as PolicyResource,
+            )
+            
+            request = cortex_hub.build_request(
+                principal=Principal(type="Agent", id=cortex_hub.agent_id),
+                action=Action(type="tool.invoke", name=tool_name),
+                resource=PolicyResource(type="Tool", id=tool_name),
+                args=tool_input,
+                framework="claude_agents",
+            )
+            
+            # Evaluate policy if in enforcement mode
+            if cortex_hub.enforce and cortex_hub.evaluator:
+                from cortexhub.policy.effects import Effect
+                decision = cortex_hub.evaluator.evaluate(request)
+                
+                if decision.effect == Effect.DENY:
+                    return {
+                        "hookSpecificOutput": {
+                            "hookEventName": "PreToolUse",
+                            "permissionDecision": "deny",
+                            "permissionDecisionReason": decision.reasoning,
+                        }
+                    }
+                
+                if decision.effect == Effect.ESCALATE:
+                    try:
+                        context_hash = cortex_hub._compute_context_hash(tool_name, tool_input)
+                        approval_response = cortex_hub.backend.create_approval(
+                            run_id=cortex_hub.session_id,
+                            trace_id=cortex_hub._get_current_trace_id(),
+                            tool_name=tool_name,
+                            tool_args_values=tool_input if not cortex_hub.privacy else None,
+                            context_hash=context_hash,
+                            policy_id=decision.policy_id or "",
+                            policy_name=decision.policy_name or "Unknown Policy",
+                            policy_explanation=decision.reasoning,
+                            risk_category=None,
+                            agent_id=cortex_hub.agent_id,
+                            framework="claude_agents",
+                            environment=os.getenv("CORTEXHUB_ENVIRONMENT"),
+                        )
+                        approval_id = approval_response.get("approval_id", "unknown")
+                    except Exception as e:
+                        logger.error("Failed to create approval", error=str(e))
+                        return {
+                            "hookSpecificOutput": {
+                                "hookEventName": "PreToolUse",
+                                "permissionDecision": "deny",
+                                "permissionDecisionReason": (
+                                    f"Tool '{tool_name}' requires approval but failed to create approval record: {e}"
+                                ),
+                            }
+                        }
+
+                    return {
+                        "hookSpecificOutput": {
+                            "hookEventName": "PreToolUse",
+                            "permissionDecision": "ask",
+                            "permissionDecisionReason": (
+                                f"Approval required: {decision.reasoning}\n\nApproval ID: {approval_id}"
+                            ),
+                        }
+                    }
+            
+            # Allow execution
+            return {}
+        
+        async def post_tool_governance(
+            input_data: dict[str, Any],
+            tool_use_id: str | None,
+            context: Any,
+        ) -> dict[str, Any]:
+            """Post-tool governance hook.
+            
+            Logs tool execution results for audit.
+            """
+            tool_name = input_data.get("tool_name", "unknown")
+            tool_response = input_data.get("tool_response", {})
+            
+            # Log the tool execution
+            logger.debug(
+                "Tool executed",
+                tool=tool_name,
+                framework="claude_agents",
+            )
+            
+            return {}
+        
+        # Return hook configuration
+        # Note: HookMatcher is from claude_agent_sdk
+        try:
+            from claude_agent_sdk import HookMatcher
+            
+            return {
+                "PreToolUse": [
+                    HookMatcher(hooks=[pre_tool_governance])
+                ],
+                "PostToolUse": [
+                    HookMatcher(hooks=[post_tool_governance])
+                ],
+            }
+        except ImportError:
+            logger.warning("Could not create hooks - claude_agent_sdk not installed")
+            return {}