mcpower-proxy 0.0.58__py3-none-any.whl → 0.0.73__py3-none-any.whl

ide_tools/common/hooks/shell_execution.py

@@ -0,0 +1,196 @@
+"""
+Common shell execution handler - IDE-agnostic
+
+Handles both request (before) and response (after) inspection for shell commands.
+"""
+
+import sys
+from typing import Optional, Dict, List
+
+from modules.logs.audit_trail import AuditTrailLogger
+from modules.logs.logger import MCPLogger
+from modules.redaction import redact
+from modules.utils.ids import get_session_id, read_app_uid, get_project_mcpower_dir
+from .types import HookConfig
+from .output import output_result, output_error
+from .utils import create_validator, inspect_and_enforce
+
+
+async def handle_shell_execution(
+    logger: MCPLogger,
+    audit_logger: AuditTrailLogger,
+    stdin_input: str,
+    prompt_id: str,
+    event_id: str,
+    cwd: Optional[str],
+    config: HookConfig,
+    tool_name: str,
+    is_request: bool = True
+):
+    """
+    Generic shell execution handler - handles both request and response
+    
+    Args:
+        logger: Logger instance
+        audit_logger: Audit logger instance
+        stdin_input: Raw input string from stdin
+        prompt_id: Prompt identifier
+        event_id: Event identifier
+        cwd: Current working directory
+        config: Hook configuration (IDE-specific)
+        tool_name: IDE-specific tool name (e.g., "beforeShellExecution", "PreToolUse(Bash)")
+        is_request: True for before (request), False for after (response)
+    """
+    await _handle_shell_operation(
+        logger=logger,
+        audit_logger=audit_logger,
+        stdin_input=stdin_input,
+        prompt_id=prompt_id,
+        event_id=event_id,
+        cwd=cwd,
+        config=config,
+        is_request=is_request,
+        required_fields={"command": str, "cwd": str} if is_request else {"command": str, "output": str},
+        redact_fields=["command"] if is_request else ["command", "output"],
+        tool_name=tool_name,
+        operation_name="Command" if is_request else "Command output",
+        audit_event_type="agent_request" if is_request else "mcp_response",
+        audit_forwarded_event_type="agent_request_forwarded" if is_request else "mcp_response_forwarded"
+    )
+
+
+async def _handle_shell_operation(
+    logger: MCPLogger,
+    audit_logger: AuditTrailLogger,
+    stdin_input: str,
+    prompt_id: str,
+    event_id: str,
+    cwd: Optional[str],
+    config: HookConfig,
+    is_request: bool,
+    required_fields: Dict[str, type],
+    redact_fields: List[str],
+    tool_name: str,
+    operation_name: str,
+    audit_event_type: str,
+    audit_forwarded_event_type: str
+):
+    """
+    Internal shell operation handler - shared logic for request and response
+    
+    Args:
+        is_request: True for request inspection, False for response inspection
+        required_fields: Fields to validate in input
+        redact_fields: Fields to redact for logging and API calls
+        tool_name: Hook name (e.g., "beforeShellExecution", "afterShellExecution")
+        operation_name: Display name (e.g., "Command", "Command output")
+        audit_event_type: Audit event name for incoming operation
+        audit_forwarded_event_type: Audit event name for forwarded operation
+    """
+    session_id = get_session_id()
+    
+    logger.info(f"{tool_name} handler started (client={config.client_name}, prompt_id={prompt_id}, event_id={event_id}, cwd={cwd})")
+    
+    try:
+        # Validate input
+        try:
+            validator = create_validator(required_fields=required_fields)
+            input_data = validator(stdin_input)
+        except ValueError as e:
+            logger.error(f"Input validation error: {e}")
+            output_error(logger, config.output_format, "permission", str(e))
+            return
+        
+        app_uid = read_app_uid(logger, get_project_mcpower_dir(cwd))
+        audit_logger.set_app_uid(app_uid)
+        
+        # Redact sensitive data for logging
+        redacted_data = {}
+        for k, v in input_data.items():
+            if k in required_fields:
+                redacted_data[k] = redact(v) if k in redact_fields else v
+        
+        logger.info(f"Analyzing {tool_name}: {redacted_data}")
+        
+        # Use different structure for request vs response events
+        # Requests: params nested, Responses: unpacked at root
+        if is_request:
+            audit_data = {
+                "server": config.server_name,
+                "tool": tool_name,
+                "params": redacted_data
+            }
+        else:
+            audit_data = {
+                "server": config.server_name,
+                "tool": tool_name,
+                **redacted_data
+            }
+        
+        audit_logger.log_event(
+            audit_event_type,
+            audit_data,
+            event_id=event_id
+        )
+        
+        # Build content_data with redacted fields
+        content_data = redacted_data
+        
+        # Call security API and enforce decision
+        try:
+            decision = await inspect_and_enforce(
+                is_request=is_request,
+                session_id=session_id,
+                logger=logger,
+                audit_logger=audit_logger,
+                app_uid=app_uid,
+                event_id=event_id,
+                server_name=config.server_name,
+                tool_name=tool_name,
+                content_data=content_data,
+                prompt_id=prompt_id,
+                cwd=cwd,
+                client_name=config.client_name
+            )
+            
+            # Log audit event for forwarding
+            # Use different structure for request vs response
+            if is_request:
+                forwarded_data = {
+                    "server": config.server_name,
+                    "tool": tool_name,
+                    "params": redacted_data
+                }
+            else:
+                forwarded_data = {
+                    "server": config.server_name,
+                    "tool": tool_name,
+                    **redacted_data
+                }
+            
+            audit_logger.log_event(
+                audit_forwarded_event_type,
+                forwarded_data,
+                event_id=event_id
+            )
+            
+            reasons = decision.get("reasons", [])
+            user_message = f"{operation_name} approved"
+            if not reasons:
+                agent_message = f"{operation_name} approved by security policy"
+            else:
+                agent_message = f"{operation_name} approved: {'; '.join(reasons)}"
+            output_result(logger, config.output_format, "permission", True, user_message, agent_message)
+            
+        except Exception as e:
+            # Decision enforcement failed - block
+            error_msg = str(e)
+            user_message = f"{operation_name} blocked by security policy"
+            if "User blocked" in error_msg or "User denied" in error_msg:
+                user_message = f"{operation_name} blocked by user"
+            
+            output_result(logger, config.output_format, "permission", False, user_message, error_msg)
+    
+    except Exception as e:
+        logger.error(f"Unexpected error in {tool_name} handler: {e}", exc_info=True)
+        output_error(logger, config.output_format, "permission", f"Unexpected error: {str(e)}")

ide_tools/common/hooks/types.py

@@ -0,0 +1,35 @@
+"""
+Common types for IDE hooks - IDE-agnostic
+"""
+
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+
+@dataclass
+class OutputFormat:
+    """
+    Defines how to format hook output for a specific IDE.
+    This is a generic interface - IDEs provide their own implementations.
+    """
+    # Exit codes
+    allow_exit_code: int
+    deny_exit_code: int
+    error_exit_code: int
+    
+    # Output formatter function
+    # Args: (hook_type: str, allowed: bool, user_msg: Optional[str], agent_msg: Optional[str]) -> str
+    formatter: Callable[[str, bool, Optional[str], Optional[str]], str]
+    
+    
+@dataclass
+class HookConfig:
+    """
+    Configuration for a specific hook execution.
+    IDE-specific modules create instances of this with their own output format.
+    """
+    output_format: OutputFormat
+    server_name: str  # IDE-specific tool server name
+    client_name: str  # IDE-specific client name (e.g. "cursor", "claude-code")
+    max_content_length: int  # Maximum content length before skipping API call
+

ide_tools/common/hooks/utils.py

@@ -0,0 +1,276 @@
+"""
+Common utilities for IDE hooks - IDE-agnostic
+"""
+
+import json
+import re
+from collections import Counter
+from typing import Dict, Any, List, Callable, Optional
+
+from mcpower_shared.mcp_types import create_policy_request, create_policy_response, AgentContext, EnvironmentContext
+from modules.apis.security_policy import SecurityPolicyClient
+from modules.decision_handler import DecisionHandler
+from modules.logs.audit_trail import AuditTrailLogger
+from modules.logs.logger import MCPLogger
+from modules.redaction import redact
+from modules.utils.json import safe_json_dumps
+from wrapper.__version__ import __version__
+
+
+def create_validator(
+        required_fields: Dict[str, type],
+        optional_fields: Optional[Dict[str, type]] = None
+) -> Callable[[str], Dict[str, Any]]:
+    """
+    Factory for input validators
+    
+    Args:
+        required_fields: Dict mapping field names to their expected types
+        optional_fields: Dict mapping optional field names to their expected types
+        
+    Returns:
+        Validator function that parses and validates input
+    """
+
+    def parse_and_validate_input(stdin_input: str) -> Dict[str, Any]:
+        try:
+            if not stdin_input.strip():
+                raise ValueError("No input provided")
+            input_data = json.loads(stdin_input)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Failed to parse input: {e}")
+
+        for field, expected_type in required_fields.items():
+            if field not in input_data:
+                raise ValueError(f"No {field} provided in input")
+            if not isinstance(input_data[field], expected_type):
+                raise ValueError(f"{field} must be a {expected_type.__name__}")
+
+        if optional_fields:
+            for field, expected_type in optional_fields.items():
+                if field in input_data and not isinstance(input_data[field], expected_type):
+                    raise ValueError(f"{field} must be a {expected_type.__name__}")
+
+        return input_data
+
+    return parse_and_validate_input
+
+
+def extract_redaction_patterns(redacted_content: str) -> Dict[str, int]:
+    """
+    Extract redaction pattern types and their counts from redacted content
+    
+    Args:
+        redacted_content: Content with [REDACTED-type] placeholders
+        
+    Returns:
+        Dict mapping redaction types to counts
+    """
+    pattern = r'\[REDACTED-([^\]]+)\]'
+    matches = re.findall(pattern, redacted_content)
+    return dict(Counter(matches))
+
+
+def build_sensitive_data_types(patterns: Dict[str, int], context: str = "file") -> Dict[str, Dict[str, Any]]:
+    """
+    Convert redaction patterns to structured sensitive_data_types dict
+    
+    Args:
+        patterns: Dict mapping pattern text to occurrence counts (from extract_redaction_patterns)
+        context: Context string for description (e.g., "file", "prompt text")
+        
+    Returns:
+        Dict mapping data types to occurrence info with descriptions
+    """
+    sensitive_data_types = {}
+    for pattern_text, count in patterns.items():
+        data_type = pattern_text.replace("[REDACTED-", "").replace("]", "")
+        sensitive_data_types[data_type] = {
+            "occurrences": count,
+            "description": f"Found {count} instance(s) of {data_type} in {context}"
+        }
+    return sensitive_data_types
+
+
+def process_single_file_for_redaction(
+        file_path: str,
+        content: str,
+        logger: MCPLogger
+) -> Optional[Dict[str, Any]]:
+    """
+    Process a single file's content for redaction patterns
+    
+    Args:
+        file_path: Path to the file being processed
+        content: File content to check for redactions
+        logger: MCPLogger instance
+        
+    Returns:
+        Dict with redaction info if sensitive data found, None otherwise
+    """
+    redacted = redact(content)
+    patterns = extract_redaction_patterns(redacted)
+    if patterns:
+        sensitive_data_types = build_sensitive_data_types(patterns, "file")
+        logger.info(f"Found {len(patterns)} sensitive data type(s) in: {file_path}")
+        return {
+            "file_path": file_path,
+            "contains_sensitive_data": True,
+            "sensitive_data_types": sensitive_data_types,
+            "risk_summary": f"File contains {sum(patterns.values())} sensitive data item(s) across {len(patterns)} type(s)"
+        }
+    return None
+
+
+def process_attachments_for_redaction(
+        attachments: List[Dict[str, Any]],
+        logger: MCPLogger
+) -> List[Dict[str, Any]]:
+    """
+    Process file attachments and extract redaction patterns
+    
+    Args:
+        attachments: List of attachment dicts with 'type' and 'file_path' or 'filePath'
+        logger: MCPLogger instance
+        
+    Returns:
+        List of files with redactions found
+    """
+    files_with_redactions = []
+
+    for attachment in attachments:
+        att_type = attachment.get("type")
+        att_path = attachment.get("file_path") or attachment.get("filePath")
+
+        if att_type != "file":
+            logger.debug(f"Skipping non-file attachment (type={att_type}): {att_path}")
+            continue
+
+        if not att_path:
+            logger.debug("Skipping attachment with no file_path")
+            continue
+
+        try:
+            with open(att_path, 'r', encoding='utf-8', errors='replace') as f:
+                content = f.read()
+
+            result = process_single_file_for_redaction(att_path, content, logger)
+            if result:
+                files_with_redactions.append(result)
+
+        except Exception as e:
+            logger.warning(f"Could not read attachment file {att_path}: {e}")
+
+    return files_with_redactions
+
+
+async def inspect_and_enforce(
+        is_request: bool,
+        session_id: str,
+        logger: MCPLogger,
+        audit_logger: AuditTrailLogger,
+        app_uid: str,
+        event_id: str,
+        server_name: str,
+        tool_name: str,
+        content_data: Dict[str, Any],
+        prompt_id: str,
+        cwd: Optional[str],
+        current_files: Optional[List[str]] = None,
+        client_name: str = "ide-tools"
+) -> Dict[str, Any]:
+    """
+    Generic handler for API inspection and decision enforcement
+    
+    Args:
+        is_request: True for request inspection, False for response inspection
+        session_id: Session identifier
+        logger: Logger instance
+        audit_logger: Audit logger instance
+        app_uid: Application UID
+        event_id: Event identifier
+        server_name: Server name (IDE-specific, e.g. "cursor_tools_mcp")
+        tool_name: Tool/hook name
+        content_data: Data to inspect
+        prompt_id: Prompt identifier
+        cwd: Current working directory
+        current_files: Optional list of current files
+        client_name: Client name (e.g. "cursor", "claude-code")
+        
+    Returns:
+        Decision dict from security API
+        
+    Raises:
+        Exception: If decision blocks the operation or API call fails
+    """
+    agent_context = AgentContext(
+        last_user_prompt="",
+        user_prompt_id=prompt_id,
+        context_summary=""
+    )
+
+    env_context = EnvironmentContext(
+        session_id=session_id,
+        workspace={
+            "roots": [cwd] if cwd else [],
+            "current_files": current_files or []
+        },
+        client=client_name,
+        client_version=__version__,
+        selection_hash=""
+    )
+
+    async with SecurityPolicyClient(
+            session_id=session_id,
+            logger=logger,
+            audit_logger=audit_logger,
+            app_id=app_uid
+    ) as client:
+        if is_request:
+            policy_request = create_policy_request(
+                event_id=event_id,
+                server_name=server_name,
+                server_transport="stdio",
+                tool_name=tool_name,
+                agent_context=agent_context,
+                env_context=env_context,
+                arguments=content_data
+            )
+            decision = await client.inspect_policy_request(
+                policy_request=policy_request,
+                prompt_id=prompt_id
+            )
+        else:
+            policy_response = create_policy_response(
+                event_id=event_id,
+                server_name=server_name,
+                server_transport="stdio",
+                tool_name=tool_name,
+                response_content=safe_json_dumps(content_data),
+                agent_context=agent_context,
+                env_context=env_context
+            )
+            decision = await client.inspect_policy_response(
+                policy_response=policy_response,
+                prompt_id=prompt_id
+            )
+
+    await DecisionHandler(
+        logger=logger,
+        audit_logger=audit_logger,
+        session_id=session_id,
+        app_id=app_uid
+    ).enforce_decision(
+        decision=decision,
+        is_request=is_request,
+        event_id=event_id,
+        tool_name=tool_name,
+        content_data=content_data,
+        operation_type="hook",
+        prompt_id=prompt_id,
+        server_name=server_name,
+        error_message_prefix=f"Operation blocked by security policy"
+    )
+
+    return decision
+

ide_tools/cursor/__init__.py

@@ -0,0 +1,11 @@
+"""
+Cursor IDE Handler
+
+Handles Cursor-specific hooks and operations.
+"""
+
+from .router import route_cursor_hook
+
+__all__ = [
+    "route_cursor_hook",
+]

ide_tools/cursor/constants.py

@@ -0,0 +1,58 @@
+"""
+Cursor Hook Constants
+
+Configuration values specific to Cursor hook handlers.
+"""
+
+from enum import Enum
+
+from ide_tools.common.hooks.types import HookConfig, OutputFormat
+from ide_tools.cursor.format import cursor_output_formatter
+
+
+class HookPermission(str, Enum):
+    """Cursor hook response permission values"""
+    ALLOW = "allow"
+    DENY = "deny"
+
+
+# Cursor-specific configuration
+CURSOR_CONFIG = HookConfig(
+    output_format=OutputFormat(
+        allow_exit_code=0,
+        deny_exit_code=1,
+        error_exit_code=1,
+        formatter=cursor_output_formatter
+    ),
+    server_name="mcpower_cursor",
+    client_name="cursor",
+    max_content_length=100000
+)
+
+# Hook descriptions from https://cursor.com/docs/agent/hooks#hook-events
+CURSOR_HOOKS = {
+    "beforeShellExecution": {
+        "name": "beforeShellExecution",
+        "description": "Triggered before a shell command is executed by the agent. "
+                       "Allows inspection and potential blocking of shell commands.",
+        "version": "1.0.0"
+    },
+    "afterShellExecution": {
+        "name": "afterShellExecution",
+        "description": "Triggered after a shell command completes execution. "
+                       "Provides access to command output and exit status.",
+        "version": "1.0.0"
+    },
+    "beforeReadFile": {
+        "name": "beforeReadFile",
+        "description": "Triggered before the agent reads a file. "
+                       "Allows inspection and potential blocking of file read operations.",
+        "version": "1.0.0"
+    },
+    "beforeSubmitPrompt": {
+        "name": "beforeSubmitPrompt",
+        "description": "Triggered before a prompt is submitted to the AI model. "
+                       "Allows inspection and modification of prompts.",
+        "version": "1.0.0"
+    }
+}

ide_tools/cursor/format.py

@@ -0,0 +1,35 @@
+"""
+Cursor-specific output formatting
+"""
+
+import json
+from typing import Optional
+
+
+def cursor_output_formatter(hook_type: str, allowed: bool, user_msg: Optional[str], agent_msg: Optional[str]) -> str:
+    """
+    Format output for Cursor IDE
+    
+    Args:
+        hook_type: "permission" or "continue"
+        allowed: True for allow/continue, False for deny/block
+        user_msg: Message for user
+        agent_msg: Message for agent/logs
+    
+    Returns:
+        JSON string in Cursor format
+    """
+    if hook_type == "permission":
+        result = {"permission": "allow" if allowed else "deny"}
+        if user_msg:
+            result["user_message"] = user_msg
+        if agent_msg:
+            result["agent_message"] = agent_msg
+    else:  # continue
+        result = {"continue": allowed}
+        if user_msg:
+            result["user_message"] = user_msg
+        if agent_msg:
+            result["agent_message"] = agent_msg
+
+    return json.dumps(result)