proxilion 0.0.1__py3-none-any.whl

proxilion/security/scope_enforcer.py

@@ -0,0 +1,680 @@
+"""
+Semantic scope enforcement for Proxilion.
+
+Binds tool calls to execution scopes (read_only, read_write, admin) so that
+even if an agent has access to a tool, it can only use it within the scope
+of the current operation.
+
+Addresses:
+- OWASP ASI02 (Tool Misuse)
+- Principle of Least Privilege
+
+Example:
+    >>> from proxilion.security.scope_enforcer import (
+    ...     ScopeEnforcer, ExecutionScope, scoped_execution
+    ... )
+    >>> from proxilion import UserContext
+    >>>
+    >>> enforcer = ScopeEnforcer()
+    >>>
+    >>> # In a read-only scope, only read operations are allowed
+    >>> user = UserContext(user_id="user_123", roles=["viewer"])
+    >>> with scoped_execution(enforcer, "read_only", user) as ctx:
+    ...     ctx.validate_tool("get_user")  # OK
+    ...     ctx.validate_tool("delete_user")  # Raises ScopeViolationError
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import re
+import threading
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ExecutionScope(Enum):
+    """
+    Predefined execution scopes for tool calls.
+
+    Scopes define what categories of operations are permitted.
+    """
+
+    READ_ONLY = "read_only"
+    """Only read operations (get, list, search, query)."""
+
+    READ_WRITE = "read_write"
+    """Read and write operations (create, update, modify)."""
+
+    ADMIN = "admin"
+    """All operations including delete and execute."""
+
+    CUSTOM = "custom"
+    """Custom scope with explicit allow/deny lists."""
+
+
+@dataclass
+class ScopeBinding:
+    """
+    Binding between a scope and its allowed/denied operations.
+
+    Attributes:
+        scope: The execution scope this binding represents.
+        allowed_tools: Set of tool name patterns that are allowed.
+        denied_tools: Set of tool name patterns that are denied.
+        allowed_actions: Set of action names that are allowed.
+        denied_actions: Set of action names that are denied.
+        name: Optional name for the scope binding.
+        description: Optional description.
+    """
+
+    scope: ExecutionScope
+    allowed_tools: set[str] = field(default_factory=set)
+    denied_tools: set[str] = field(default_factory=set)
+    allowed_actions: set[str] = field(default_factory=set)
+    denied_actions: set[str] = field(default_factory=set)
+    name: str = ""
+    description: str = ""
+
+    def allows_action(self, action: str) -> bool:
+        """Check if an action is allowed in this scope."""
+        # If wildcard allowed, everything is allowed
+        if "*" in self.allowed_actions:
+            return action.lower() not in {a.lower() for a in self.denied_actions}
+
+        # Check if explicitly denied
+        if action.lower() in {a.lower() for a in self.denied_actions}:
+            return False
+
+        # Check if explicitly allowed
+        if action.lower() in {a.lower() for a in self.allowed_actions}:
+            return True
+
+        # If allowed_actions is non-empty and action not in it, deny
+        if self.allowed_actions:
+            return False
+
+        # Default to allow if no restrictions specified
+        return True
+
+    def allows_tool(self, tool_name: str) -> bool:
+        """Check if a tool is allowed in this scope."""
+        tool_lower = tool_name.lower()
+
+        # Check if explicitly denied by pattern
+        for pattern in self.denied_tools:
+            if fnmatch.fnmatch(tool_lower, pattern.lower()):
+                return False
+
+        # Check if explicitly allowed by pattern
+        if self.allowed_tools:
+            for pattern in self.allowed_tools:
+                if pattern == "*" or fnmatch.fnmatch(tool_lower, pattern.lower()):
+                    return True
+            return False  # Not in allowed list
+
+        # Default to allow if no tool restrictions
+        return True
+
+
+@dataclass
+class ToolClassification:
+    """
+    Classification of a tool's default scope and actions.
+
+    Attributes:
+        tool_name: Name of the tool.
+        default_scope: Default scope the tool belongs to.
+        actions: Set of actions the tool can perform.
+    """
+
+    tool_name: str
+    default_scope: ExecutionScope
+    actions: set[str] = field(default_factory=set)
+
+
+# Built-in scope bindings
+BUILTIN_SCOPES: dict[str, ScopeBinding] = {
+    "read_only": ScopeBinding(
+        scope=ExecutionScope.READ_ONLY,
+        allowed_actions={"read", "list", "get", "search", "query", "fetch", "find"},
+        denied_actions={
+            "write", "delete", "execute", "modify", "create", "update", "remove", "drop",
+        },
+        name="read_only",
+        description="Read-only operations only",
+    ),
+    "read_write": ScopeBinding(
+        scope=ExecutionScope.READ_WRITE,
+        allowed_actions={
+            "read", "list", "get", "search", "query", "fetch", "find",
+            "write", "create", "modify", "update", "add", "set",
+        },
+        denied_actions={"delete", "execute", "remove", "drop", "destroy", "run"},
+        name="read_write",
+        description="Read and write operations, no delete or execute",
+    ),
+    "admin": ScopeBinding(
+        scope=ExecutionScope.ADMIN,
+        allowed_actions={"*"},
+        denied_actions=set(),
+        name="admin",
+        description="All operations allowed",
+    ),
+}
+
+
+# Default tool classification patterns
+DEFAULT_TOOL_CLASSIFICATIONS: dict[str, ExecutionScope] = {
+    r"^(get|read|list|search|query|fetch|find|check|view|show)_": ExecutionScope.READ_ONLY,
+    r"^(create|write|update|modify|set|add|put|insert|save)_": ExecutionScope.READ_WRITE,
+    r"^(delete|remove|drop|destroy|execute|run|kill|terminate|purge)_": ExecutionScope.ADMIN,
+}
+
+
+class ScopeEnforcer:
+    """
+    Enforces execution scopes on tool calls.
+
+    The ScopeEnforcer validates that tool calls are permitted within
+    the current execution scope based on tool names, actions, and
+    explicit allow/deny rules.
+
+    Example:
+        >>> enforcer = ScopeEnforcer()
+        >>>
+        >>> # Validate a tool in read_only scope
+        >>> scope = enforcer.get_scope("read_only")
+        >>> allowed, reason = enforcer.validate_in_scope("get_user", "read", scope)
+        >>> print(allowed)  # True
+        >>>
+        >>> # Try write operation in read_only scope
+        >>> allowed, reason = enforcer.validate_in_scope("update_user", "write", scope)
+        >>> print(allowed)  # False
+    """
+
+    def __init__(
+        self,
+        default_scope: ExecutionScope = ExecutionScope.READ_ONLY,
+        custom_scopes: dict[str, ScopeBinding] | None = None,
+        tool_classifications: dict[str, ExecutionScope] | None = None,
+    ) -> None:
+        """
+        Initialize the scope enforcer.
+
+        Args:
+            default_scope: Default scope when no scope is specified.
+            custom_scopes: Additional custom scope bindings.
+            tool_classifications: Custom tool name patterns to scope mappings.
+        """
+        self._default_scope = default_scope
+        self._lock = threading.RLock()
+
+        # Initialize scopes with built-ins
+        self._scopes: dict[str, ScopeBinding] = dict(BUILTIN_SCOPES)
+        if custom_scopes:
+            self._scopes.update(custom_scopes)
+
+        # Initialize tool classifications
+        self._tool_classifications: dict[str, ExecutionScope] = dict(DEFAULT_TOOL_CLASSIFICATIONS)
+        if tool_classifications:
+            self._tool_classifications.update(tool_classifications)
+
+        # Cache for classified tools
+        self._tool_scope_cache: dict[str, ExecutionScope] = {}
+
+    def get_scope(self, scope: str | ExecutionScope) -> ScopeBinding:
+        """
+        Get a scope binding by name or enum.
+
+        Args:
+            scope: Scope name string or ExecutionScope enum.
+
+        Returns:
+            The ScopeBinding for the requested scope.
+
+        Raises:
+            ValueError: If scope is not found.
+        """
+        with self._lock:
+            if isinstance(scope, ExecutionScope):
+                # Return built-in scope for enum
+                scope_name = scope.value
+            else:
+                scope_name = scope.lower()
+
+            if scope_name in self._scopes:
+                return self._scopes[scope_name]
+
+            raise ValueError(f"Unknown scope: {scope}")
+
+    def create_scope(
+        self,
+        name: str,
+        allowed_tools: set[str] | None = None,
+        denied_tools: set[str] | None = None,
+        allowed_actions: set[str] | None = None,
+        denied_actions: set[str] | None = None,
+        base_scope: ExecutionScope = ExecutionScope.CUSTOM,
+        description: str = "",
+    ) -> ScopeBinding:
+        """
+        Create a custom scope binding.
+
+        Args:
+            name: Unique name for the scope.
+            allowed_tools: Set of tool patterns allowed.
+            denied_tools: Set of tool patterns denied.
+            allowed_actions: Set of actions allowed.
+            denied_actions: Set of actions denied.
+            base_scope: Base scope type.
+            description: Human-readable description.
+
+        Returns:
+            The created ScopeBinding.
+        """
+        binding = ScopeBinding(
+            scope=base_scope,
+            allowed_tools=allowed_tools or set(),
+            denied_tools=denied_tools or set(),
+            allowed_actions=allowed_actions or set(),
+            denied_actions=denied_actions or set(),
+            name=name,
+            description=description,
+        )
+
+        with self._lock:
+            self._scopes[name.lower()] = binding
+
+        return binding
+
+    def create_scope_from_enum(self, scope: ExecutionScope) -> ScopeBinding:
+        """
+        Create a scope binding from an ExecutionScope enum.
+
+        Args:
+            scope: The ExecutionScope enum value.
+
+        Returns:
+            A ScopeBinding matching the enum.
+        """
+        return self.get_scope(scope.value)
+
+    def classify_tool(
+        self,
+        tool_name: str,
+        scope: ExecutionScope | None = None,
+        actions: set[str] | None = None,
+    ) -> ToolClassification:
+        """
+        Classify a tool by name pattern or explicit assignment.
+
+        Args:
+            tool_name: Name of the tool.
+            scope: Explicit scope assignment (overrides pattern matching).
+            actions: Set of actions the tool performs.
+
+        Returns:
+            ToolClassification for the tool.
+        """
+        with self._lock:
+            if scope is not None:
+                # Explicit scope assignment
+                self._tool_scope_cache[tool_name.lower()] = scope
+                return ToolClassification(
+                    tool_name=tool_name,
+                    default_scope=scope,
+                    actions=actions or set(),
+                )
+
+            # Check cache first
+            if tool_name.lower() in self._tool_scope_cache:
+                return ToolClassification(
+                    tool_name=tool_name,
+                    default_scope=self._tool_scope_cache[tool_name.lower()],
+                    actions=actions or set(),
+                )
+
+            # Pattern matching
+            for pattern, pattern_scope in self._tool_classifications.items():
+                if re.match(pattern, tool_name, re.IGNORECASE):
+                    self._tool_scope_cache[tool_name.lower()] = pattern_scope
+                    return ToolClassification(
+                        tool_name=tool_name,
+                        default_scope=pattern_scope,
+                        actions=actions or self._infer_actions(tool_name),
+                    )
+
+            # Default to read_only for unknown tools
+            return ToolClassification(
+                tool_name=tool_name,
+                default_scope=self._default_scope,
+                actions=actions or set(),
+            )
+
+    def _infer_actions(self, tool_name: str) -> set[str]:
+        """Infer actions from tool name prefix."""
+        tool_lower = tool_name.lower()
+        actions = set()
+
+        read_prefixes = ("get_", "read_", "list_", "search_", "query_", "fetch_", "find_")
+        if any(tool_lower.startswith(p) for p in read_prefixes):
+            actions.add("read")
+        if any(tool_lower.startswith(p) for p in ("create_", "write_", "add_", "insert_", "save_")):
+            actions.add("write")
+            actions.add("create")
+        if any(tool_lower.startswith(p) for p in ("update_", "modify_", "set_", "put_")):
+            actions.add("write")
+            actions.add("modify")
+        delete_prefixes = ("delete_", "remove_", "drop_", "destroy_", "purge_")
+        if any(tool_lower.startswith(p) for p in delete_prefixes):
+            actions.add("delete")
+        if any(tool_lower.startswith(p) for p in ("execute_", "run_", "kill_", "terminate_")):
+            actions.add("execute")
+
+        return actions or {"execute"}  # Default to execute if unknown
+
+    def validate_in_scope(
+        self,
+        tool_name: str,
+        action: str,
+        scope: ScopeBinding,
+    ) -> tuple[bool, str | None]:
+        """
+        Validate if a tool call is allowed in the given scope.
+
+        Args:
+            tool_name: Name of the tool to validate.
+            action: The action being performed.
+            scope: The scope binding to validate against.
+
+        Returns:
+            Tuple of (allowed, reason). If not allowed, reason explains why.
+        """
+        # Check if tool is explicitly denied
+        if not scope.allows_tool(tool_name):
+            scope_id = scope.name or scope.scope.value
+            return False, f"Tool '{tool_name}' is not allowed in scope '{scope_id}'"
+
+        # Check if action is allowed
+        if not scope.allows_action(action):
+            scope_id = scope.name or scope.scope.value
+            return False, f"Action '{action}' is not allowed in scope '{scope_id}'"
+
+        # Check tool classification against scope
+        classification = self.classify_tool(tool_name)
+        tool_scope = classification.default_scope
+
+        # Scope hierarchy: READ_ONLY < READ_WRITE < ADMIN
+        scope_levels = {
+            ExecutionScope.READ_ONLY: 1,
+            ExecutionScope.READ_WRITE: 2,
+            ExecutionScope.ADMIN: 3,
+            ExecutionScope.CUSTOM: 0,  # Custom scopes use explicit rules
+        }
+
+        current_level = scope_levels.get(scope.scope, 0)
+        required_level = scope_levels.get(tool_scope, 0)
+
+        # Custom scopes only use explicit allow/deny rules
+        if scope.scope == ExecutionScope.CUSTOM:
+            return True, None
+
+        # Check if current scope level is sufficient
+        if required_level > current_level:
+            return False, (
+                f"Tool '{tool_name}' requires '{tool_scope.value}' scope, "
+                f"but current scope is '{scope.scope.value}'"
+            )
+
+        return True, None
+
+    def get_allowed_tools(self, scope: ScopeBinding) -> set[str]:
+        """
+        Get the set of allowed tool patterns for a scope.
+
+        Args:
+            scope: The scope binding.
+
+        Returns:
+            Set of allowed tool patterns.
+        """
+        if scope.allowed_tools:
+            return set(scope.allowed_tools)
+
+        # If no explicit allowed tools, return patterns based on scope level
+        if scope.scope == ExecutionScope.READ_ONLY:
+            return {"get_*", "read_*", "list_*", "search_*", "query_*", "fetch_*", "find_*"}
+        elif scope.scope == ExecutionScope.READ_WRITE:
+            return {
+                "get_*", "read_*", "list_*", "search_*", "query_*", "fetch_*", "find_*",
+                "create_*", "write_*", "update_*", "modify_*", "set_*", "add_*",
+            }
+        elif scope.scope == ExecutionScope.ADMIN:
+            return {"*"}
+
+        return set()
+
+    def add_scope(self, name: str, binding: ScopeBinding) -> None:
+        """
+        Add a scope binding.
+
+        Args:
+            name: Name for the scope.
+            binding: The ScopeBinding to add.
+        """
+        with self._lock:
+            self._scopes[name.lower()] = binding
+
+    def remove_scope(self, name: str) -> bool:
+        """
+        Remove a custom scope.
+
+        Args:
+            name: Name of the scope to remove.
+
+        Returns:
+            True if removed, False if not found or built-in.
+        """
+        name_lower = name.lower()
+        if name_lower in BUILTIN_SCOPES:
+            return False  # Cannot remove built-in scopes
+
+        with self._lock:
+            if name_lower in self._scopes:
+                del self._scopes[name_lower]
+                return True
+            return False
+
+    def get_scopes(self) -> dict[str, ScopeBinding]:
+        """Get all registered scopes."""
+        with self._lock:
+            return dict(self._scopes)
+
+    def add_tool_classification(self, pattern: str, scope: ExecutionScope) -> None:
+        """
+        Add a tool classification pattern.
+
+        Args:
+            pattern: Regex pattern to match tool names.
+            scope: Scope to assign to matching tools.
+        """
+        with self._lock:
+            self._tool_classifications[pattern] = scope
+            # Clear cache as classifications changed
+            self._tool_scope_cache.clear()
+
+
+class ScopeContext:
+    """
+    Context for scoped execution.
+
+    Tracks tool calls within a scope and validates them against
+    the scope's rules.
+
+    Example:
+        >>> ctx = ScopeContext(enforcer, scope, user)
+        >>> ctx.validate_tool("get_user")  # Returns True
+        >>> ctx.validate_tool("delete_user")  # Raises ScopeViolationError
+        >>> print(ctx.get_calls())  # ["get_user"]
+    """
+
+    def __init__(
+        self,
+        enforcer: ScopeEnforcer,
+        scope: ScopeBinding,
+        user: Any,
+    ) -> None:
+        """
+        Initialize scope context.
+
+        Args:
+            enforcer: The ScopeEnforcer instance.
+            scope: The scope binding for this context.
+            user: The user context.
+        """
+        self.enforcer = enforcer
+        self.scope = scope
+        self.user = user
+        self._calls: list[tuple[str, str]] = []  # (tool_name, action)
+        self._closed = False
+
+    def validate_tool(self, tool_name: str, action: str = "execute") -> bool:
+        """
+        Validate a tool call within this scope.
+
+        Args:
+            tool_name: Name of the tool.
+            action: Action being performed.
+
+        Returns:
+            True if allowed.
+
+        Raises:
+            ScopeViolationError: If the tool call is not allowed.
+        """
+        if self._closed:
+            raise RuntimeError("ScopeContext is closed")
+
+        # Import here to avoid circular import
+        from proxilion.exceptions import ScopeViolationError
+
+        allowed, reason = self.enforcer.validate_in_scope(tool_name, action, self.scope)
+        if not allowed:
+            raise ScopeViolationError(
+                tool_name=tool_name,
+                scope_name=self.scope.name or self.scope.scope.value,
+                reason=reason,
+            )
+
+        self._calls.append((tool_name, action))
+        logger.debug(
+            f"Tool '{tool_name}' (action: {action}) validated in scope '{self.scope.name}'"
+        )
+        return True
+
+    def is_tool_allowed(self, tool_name: str, action: str = "execute") -> bool:
+        """
+        Check if a tool is allowed without raising an exception.
+
+        Args:
+            tool_name: Name of the tool.
+            action: Action being performed.
+
+        Returns:
+            True if allowed, False otherwise.
+        """
+        if self._closed:
+            return False
+
+        allowed, _ = self.enforcer.validate_in_scope(tool_name, action, self.scope)
+        return allowed
+
+    def get_calls(self) -> list[tuple[str, str]]:
+        """Get all validated tool calls in this context."""
+        return list(self._calls)
+
+    def get_tool_names(self) -> list[str]:
+        """Get just the tool names from validated calls."""
+        return [call[0] for call in self._calls]
+
+    def close(self) -> None:
+        """Close the scope context."""
+        self._closed = True
+        logger.debug(
+            f"ScopeContext closed. Total calls: {len(self._calls)}"
+        )
+
+    @property
+    def is_closed(self) -> bool:
+        """Check if context is closed."""
+        return self._closed
+
+
+@contextmanager
+def scoped_execution(
+    enforcer: ScopeEnforcer,
+    scope: ExecutionScope | str,
+    user: Any,
+) -> Generator[ScopeContext, None, None]:
+    """
+    Context manager for scoped tool execution.
+
+    Creates a scope context that validates all tool calls against
+    the specified scope's rules.
+
+    Args:
+        enforcer: The ScopeEnforcer instance.
+        scope: Scope name or ExecutionScope enum.
+        user: The user context for this execution.
+
+    Yields:
+        ScopeContext for validating tool calls.
+
+    Example:
+        >>> with scoped_execution(enforcer, "read_only", user) as ctx:
+        ...     ctx.validate_tool("get_user")  # OK
+        ...     ctx.validate_tool("delete_user")  # Raises ScopeViolationError
+    """
+    if isinstance(scope, str):
+        scope_binding = enforcer.get_scope(scope)
+    else:
+        scope_binding = enforcer.create_scope_from_enum(scope)
+
+    ctx = ScopeContext(enforcer, scope_binding, user)
+    logger.debug(f"Entering scope '{scope_binding.name or scope_binding.scope.value}'")
+
+    try:
+        yield ctx
+    finally:
+        ctx.close()
+        logger.debug(
+            f"Exited scope '{scope_binding.name or scope_binding.scope.value}' "
+            f"with {len(ctx.get_calls())} tool calls"
+        )
+
+
+def create_scope_enforcer(
+    default_scope: ExecutionScope = ExecutionScope.READ_ONLY,
+    custom_scopes: dict[str, ScopeBinding] | None = None,
+) -> ScopeEnforcer:
+    """
+    Factory function to create a ScopeEnforcer.
+
+    Args:
+        default_scope: Default scope for unknown tools.
+        custom_scopes: Additional custom scope bindings.
+
+    Returns:
+        Configured ScopeEnforcer instance.
+    """
+    return ScopeEnforcer(
+        default_scope=default_scope,
+        custom_scopes=custom_scopes,
+    )