proxilion 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

proxilion/exceptions.py

@@ -885,3 +885,87 @@ class EmergencyHaltError(ProxilionError):
             "triggered_by": triggered_by,
         }
         super().__init__(message, details)
+
+
+class ApprovalRequiredError(ProxilionError):
+    """
+    Raised when a tool requires approval before execution.
+
+    Tools marked with requires_approval=True must have approval granted
+    before they can be executed. This exception blocks execution until
+    the approval workflow is completed.
+
+    Attributes:
+        tool_name: Name of the tool that requires approval.
+        user: The user who attempted to execute the tool.
+        reason: Why approval is required.
+
+    Example:
+        >>> raise ApprovalRequiredError(
+        ...     tool_name="delete_database",
+        ...     user="user_123",
+        ...     reason="Tool is marked as high-risk and requires manager approval"
+        ... )
+    """
+
+    def __init__(
+        self,
+        tool_name: str,
+        user: str,
+        reason: str | None = None,
+    ) -> None:
+        self.tool_name = tool_name
+        self.user = user
+        self.reason = reason or "Tool requires approval before execution"
+
+        message = f"Approval required: Tool '{tool_name}' requires approval. {self.reason}"
+
+        details = {
+            "tool_name": tool_name,
+            "user": user,
+            "reason": self.reason,
+        }
+        super().__init__(message, details)
+
+
+class ScopeLoaderError(ProxilionError):
+    """
+    Raised when a scope loader encounters a temporary failure.
+
+    This exception distinguishes between permanent configuration errors
+    (which should be logged and denied) and temporary failures (network
+    issues, database timeouts) that callers may want to retry.
+
+    Attributes:
+        resource_type: Type of resource being loaded.
+        user_id: User for whom scope was being loaded.
+        original_error: The underlying error that caused the failure.
+
+    Example:
+        >>> raise ScopeLoaderError(
+        ...     resource_type="document",
+        ...     user_id="user_123",
+        ...     original_error=TimeoutError("Database connection timed out")
+        ... )
+    """
+
+    def __init__(
+        self,
+        resource_type: str,
+        user_id: str,
+        original_error: Exception | None = None,
+    ) -> None:
+        self.resource_type = resource_type
+        self.user_id = user_id
+        self.original_error = original_error
+
+        message = f"Scope loader failed for {resource_type} (user: {user_id})"
+        if original_error:
+            message += f": {original_error}"
+
+        details = {
+            "resource_type": resource_type,
+            "user_id": user_id,
+            "original_error": str(original_error) if original_error else None,
+        }
+        super().__init__(message, details)

proxilion/guards/output_guard.py

@@ -330,7 +330,7 @@ DEFAULT_LEAKAGE_PATTERNS: list[LeakagePattern] = [
     ),
     LeakagePattern(
         name="password_in_text",
-        pattern=r"(?i)(password|passwd|pwd)\s*[:=]\s*['\"]?[^\s'\"]{4,}['\"]?",
+        pattern=r"(?i)(password|passwd|pwd)\s*(?:is\s*)?[:=]\s*['\"]?[^\s'\"]{4,}['\"]?",
         category=LeakageCategory.CREDENTIAL,
         severity=0.9,
         description="Passwords in plaintext",

proxilion/observability/__init__.py

@@ -120,10 +120,12 @@ from proxilion.observability.metrics import (
     AlertRule,
     EventType,
     MetricsCollector,
-    MetricType as SecurityMetricType,
     PrometheusExporter,
     SecurityEvent,
 )
+from proxilion.observability.metrics import (
+    MetricType as SecurityMetricType,
+)
 
 # Session-based cost tracking
 from proxilion.observability.session_cost_tracker import (

proxilion/observability/metrics.py

@@ -38,12 +38,13 @@ import logging
 import threading
 import time
 from collections import defaultdict, deque
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Any, Callable
-from urllib.request import Request, urlopen
+from typing import Any
 from urllib.error import URLError
+from urllib.request import Request, urlopen
 
 logger = logging.getLogger(__name__)
 
@@ -232,7 +233,10 @@ class MetricsCollector:
         user: str | None = None,
     ) -> None:
         """Record a guard block."""
-        event_type = EventType.INPUT_GUARD_BLOCK if guard_type == "input" else EventType.OUTPUT_GUARD_BLOCK
+        if guard_type == "input":
+            event_type = EventType.INPUT_GUARD_BLOCK
+        else:
+            event_type = EventType.OUTPUT_GUARD_BLOCK
 
         self.record_event(SecurityEvent(
             event_type=event_type,
@@ -628,7 +632,10 @@ class AlertManager:
                         alert = Alert(
                             rule_name=rule.name,
                             severity=rule.severity,
-                            message=f"{rule.event_type.value} rate ({rate_per_minute:.1f}/min) exceeds threshold ({rule.threshold}/min)",
+                            message=(
+                                f"{rule.event_type.value} rate ({rate_per_minute:.1f}/min) "
+                                f"exceeds threshold ({rule.threshold}/min)"
+                            ),
                             value=rate_per_minute,
                             threshold=rule.threshold,
                             details={
@@ -728,7 +735,7 @@ class PrometheusExporter:
         lines: list[str] = []
 
         # Add header
-        lines.append(f"# Proxilion Security Metrics")
+        lines.append("# Proxilion Security Metrics")
         lines.append(f"# Generated at {datetime.now(timezone.utc).isoformat()}")
         lines.append("")
 
@@ -773,7 +780,8 @@ class PrometheusExporter:
             for bucket_le, count in buckets:
                 lines.append(f'{name}_bucket{{le="{bucket_le}"}} {count}')
 
-            lines.append(f'{name}_bucket{{le="+Inf"}} {self._collector._histogram_counts.get(hist_name, 0)}')
+            inf_count = self._collector._histogram_counts.get(hist_name, 0)
+            lines.append(f'{name}_bucket{{le="+Inf"}} {inf_count}')
             lines.append(f"{name}_sum {self._collector._histogram_sums.get(hist_name, 0):.6f}")
             lines.append(f"{name}_count {self._collector._histogram_counts.get(hist_name, 0)}")
             lines.append("")

proxilion/observability/session_cost_tracker.py

@@ -50,24 +50,21 @@ Example:
 
 from __future__ import annotations
 
-import hashlib
 import json
 import logging
 import threading
 import uuid
 from collections import defaultdict
+from collections.abc import Callable
 from dataclasses import asdict, dataclass, field
 from datetime import datetime, timedelta, timezone
 from enum import Enum
-from typing import Any, Callable
+from typing import Any
 
 from proxilion.observability.cost_tracker import (
     BudgetPolicy,
-    CostSummary,
     CostTracker,
-    ModelPricing,
     UsageRecord,
-    DEFAULT_PRICING,
 )
 
 logger = logging.getLogger(__name__)
@@ -622,8 +619,10 @@ class SessionCostTracker:
                 agent_profile.tool_calls += 1
 
                 if tool_name:
-                    agent_profile.by_tool[tool_name] = agent_profile.by_tool.get(tool_name, 0.0) + record.cost_usd
-                agent_profile.by_model[model] = agent_profile.by_model.get(model, 0.0) + record.cost_usd
+                    prev_tool = agent_profile.by_tool.get(tool_name, 0.0)
+                    agent_profile.by_tool[tool_name] = prev_tool + record.cost_usd
+                prev_model = agent_profile.by_model.get(model, 0.0)
+                agent_profile.by_model[model] = prev_model + record.cost_usd
 
                 if agent_profile.first_activity is None:
                     agent_profile.first_activity = record.timestamp

proxilion/policies/builtin.py

@@ -304,7 +304,8 @@ class AttributeBasedPolicy(Policy[Any]):
         Returns:
             True if authorized, False otherwise.
         """
-        ctx = context or {}
+        # Copy to avoid mutating caller's dict
+        ctx = dict(context) if context else {}
 
         # Add user attributes to context for convenience
         ctx["user_id"] = self.user.user_id

proxilion/policies/registry.py

@@ -339,6 +339,7 @@ class PolicyRegistry:
 
 # Global registry instance for convenience
 _global_registry: PolicyRegistry | None = None
+_global_registry_lock = threading.Lock()
 
 
 def get_global_registry() -> PolicyRegistry:
@@ -359,9 +360,13 @@ def get_global_registry() -> PolicyRegistry:
         ...     pass
     """
     global _global_registry
-    if _global_registry is None:
-        _global_registry = PolicyRegistry()
-    return _global_registry
+    if _global_registry is not None:
+        return _global_registry
+    with _global_registry_lock:
+        # Double-check after acquiring lock
+        if _global_registry is None:
+            _global_registry = PolicyRegistry()
+        return _global_registry
 
 
 def reset_global_registry() -> None:
@@ -371,6 +376,7 @@ def reset_global_registry() -> None:
     Clears the global registry instance. Primarily useful for testing.
     """
     global _global_registry
-    if _global_registry is not None:
-        _global_registry.clear()
-    _global_registry = None
+    with _global_registry_lock:
+        if _global_registry is not None:
+            _global_registry.clear()
+        _global_registry = None

proxilion/security/__init__.py

@@ -76,6 +76,31 @@ Quick Start:
     ... ))
 """
 
+from proxilion.security.agent_trust import (
+    AgentCredential,
+    AgentTrustManager,
+    DelegationChain,
+)
+from proxilion.security.agent_trust import (
+    DelegationToken as AgentDelegationToken,
+)
+from proxilion.security.agent_trust import (
+    SignedMessage as AgentSignedMessage,
+)
+from proxilion.security.agent_trust import (
+    TrustLevel as AgentTrustLevel,
+)
+from proxilion.security.agent_trust import (
+    VerificationResult as AgentVerificationResult,
+)
+from proxilion.security.behavioral_drift import (
+    BaselineStats,
+    BehavioralMonitor,
+    DriftDetector,
+    DriftMetric,
+    DriftResult,
+    KillSwitch,
+)
 from proxilion.security.cascade_protection import (
     CascadeAwareCircuitBreakerRegistry,
     CascadeEvent,
@@ -95,6 +120,16 @@ from proxilion.security.idor_protection import (
     IDPattern,
     ResourceScope,
 )
+from proxilion.security.intent_capsule import (
+    HijackDetection,
+    IntentCapsule,
+    IntentCapsuleManager,
+    IntentCategory,
+    IntentGuard,
+)
+from proxilion.security.intent_capsule import (
+    IntentValidator as IntentHijackValidator,
+)
 from proxilion.security.intent_validator import (
     AnomalyThresholds,
     IntentValidator,
@@ -102,6 +137,22 @@ from proxilion.security.intent_validator import (
     ValidationResult,
     WorkflowState,
 )
+
+# New ASI Top 10 features
+from proxilion.security.memory_integrity import (
+    ContextWindowGuard,
+    IntegrityViolation,
+    IntegrityViolationType,
+    MemoryIntegrityGuard,
+    RAGDocument,
+    RAGScanResult,
+)
+from proxilion.security.memory_integrity import (
+    SignedMessage as MemorySignedMessage,
+)
+from proxilion.security.memory_integrity import (
+    VerificationResult as MemoryVerificationResult,
+)
 from proxilion.security.rate_limiter import (
     MultiDimensionalRateLimiter,
     RateLimitConfig,
@@ -128,43 +179,6 @@ from proxilion.security.trust_boundaries import (
     TrustLevel,
 )
 
-# New ASI Top 10 features
-from proxilion.security.memory_integrity import (
-    ContextWindowGuard,
-    IntegrityViolation,
-    IntegrityViolationType,
-    MemoryIntegrityGuard,
-    RAGDocument,
-    RAGScanResult,
-    SignedMessage as MemorySignedMessage,
-    VerificationResult as MemoryVerificationResult,
-)
-from proxilion.security.agent_trust import (
-    AgentCredential,
-    AgentTrustManager,
-    DelegationChain,
-    DelegationToken as AgentDelegationToken,
-    SignedMessage as AgentSignedMessage,
-    TrustLevel as AgentTrustLevel,
-    VerificationResult as AgentVerificationResult,
-)
-from proxilion.security.intent_capsule import (
-    HijackDetection,
-    IntentCapsule,
-    IntentCapsuleManager,
-    IntentCategory,
-    IntentGuard,
-    IntentValidator as IntentHijackValidator,
-)
-from proxilion.security.behavioral_drift import (
-    BaselineStats,
-    BehavioralMonitor,
-    DriftDetector,
-    DriftMetric,
-    DriftResult,
-    KillSwitch,
-)
-
 __all__ = [
     # Rate limiting
     "TokenBucketRateLimiter",

proxilion/security/agent_trust.py

@@ -55,7 +55,6 @@ import hashlib
 import hmac
 import json
 import logging
-import secrets
 import threading
 import time
 import uuid
@@ -126,17 +125,28 @@ class AgentCredential:
         return datetime.now(timezone.utc) > self.expires_at
 
     def has_capability(self, capability: str) -> bool:
-        """Check if agent has a specific capability."""
-        # Wildcard capability
+        """Check if agent has a specific capability.
+
+        Capability matching rules:
+        - Exact match: "read" matches "read"
+        - Wildcard: "*" matches everything
+        - Explicit wildcard pattern: "read:*" matches "read:documents"
+
+        Note: An agent with "read" does NOT automatically get "read:documents".
+        Use explicit wildcards like "read:*" for hierarchical access.
+        """
+        # Full wildcard capability
         if "*" in self.capabilities:
             return True
         # Exact match
         if capability in self.capabilities:
             return True
-        # Prefix match (e.g., "read" matches "read:documents")
+        # Explicit wildcard patterns (e.g., "read:*" matches "read:documents")
         for cap in self.capabilities:
-            if capability.startswith(cap + ":"):
-                return True
+            if cap.endswith(":*"):
+                prefix = cap[:-1]  # "read:" from "read:*"
+                if capability.startswith(prefix):
+                    return True
         return False
 
     def can_delegate_to(self, other: AgentCredential) -> bool:
@@ -317,7 +327,11 @@ class DelegationChain:
             if i > 0:
                 prev_token = self._chain[i - 1]
                 if token.issuer_agent != prev_token.delegate_agent:
-                    return False, f"Chain break at position {i}: {prev_token.delegate_agent} != {token.issuer_agent}"
+                    msg = (
+                        f"Chain break at position {i}: "
+                        f"{prev_token.delegate_agent} != {token.issuer_agent}"
+                    )
+                    return False, msg
 
         return True, None
 
@@ -611,7 +625,8 @@ class AgentTrustManager:
             token_id = str(uuid.uuid4())
 
             # Sign the token
-            token_data = f"{token_id}|{from_agent}|{to_agent}|{sorted(capabilities)}|{now.isoformat()}"
+            caps_str = str(sorted(capabilities))
+            token_data = f"{token_id}|{from_agent}|{to_agent}|{caps_str}|{now.isoformat()}"
             signature = hmac.new(
                 issuer._secret.encode(),
                 token_data.encode(),

proxilion/security/behavioral_drift.py

@@ -39,17 +39,17 @@ Example:
 from __future__ import annotations
 
 import logging
-import math
 import statistics
 import threading
 import time
 from collections import deque
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Any, Callable
+from typing import Any
 
-from proxilion.exceptions import BehavioralDriftError, EmergencyHaltError
+from proxilion.exceptions import EmergencyHaltError
 
 logger = logging.getLogger(__name__)
 
@@ -386,8 +386,14 @@ class BehavioralMonitor:
                     min_value=min(samples),
                     max_value=max(samples),
                     sample_count=len(samples),
-                    percentile_95=sorted_samples[p95_idx] if p95_idx < len(sorted_samples) else max(samples),
-                    percentile_99=sorted_samples[p99_idx] if p99_idx < len(sorted_samples) else max(samples),
+                    percentile_95=(
+                        sorted_samples[p95_idx] if p95_idx < len(sorted_samples)
+                        else max(samples)
+                    ),
+                    percentile_99=(
+                        sorted_samples[p99_idx] if p99_idx < len(sorted_samples)
+                        else max(samples)
+                    ),
                 )
 
             self._baseline_locked = True
@@ -647,7 +653,9 @@ class KillSwitch:
             return {
                 "active": self._active,
                 "reason": self._activation_reason,
-                "activation_time": self._activation_time.isoformat() if self._activation_time else None,
+                "activation_time": (
+                    self._activation_time.isoformat() if self._activation_time else None
+                ),
             }
 
 

proxilion/security/idor_protection.py

@@ -14,7 +14,7 @@ from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any
 
-from proxilion.exceptions import IDORViolationError
+from proxilion.exceptions import IDORViolationError, ScopeLoaderError
 
 logger = logging.getLogger(__name__)
 
@@ -228,9 +228,13 @@ class IDORProtector:
                 try:
                     allowed_ids = loader(user_id)
                     return object_id in allowed_ids
-                except Exception as e:
-                    logger.error(f"Scope loader failed: {e}")
+                except (KeyError, ValueError, AttributeError) as e:
+                    # Permanent configuration error - deny access
+                    logger.error(f"Scope loader configuration error: {e}")
                     return False
+                except Exception as e:
+                    # Temporary failure - let caller handle retry
+                    raise ScopeLoaderError(resource_type, user_id, e) from e
 
             if scope is None:
                 # No scope defined - default deny
@@ -254,8 +258,12 @@ class IDORProtector:
                     dynamic_ids = scope.scope_loader(user_id)
                     if object_id in dynamic_ids:
                         return True
+                except (KeyError, ValueError, AttributeError) as e:
+                    # Permanent configuration error - deny access
+                    logger.error(f"Dynamic scope loader configuration error: {e}")
                 except Exception as e:
-                    logger.error(f"Dynamic scope loader failed: {e}")
+                    # Temporary failure - let caller handle retry
+                    raise ScopeLoaderError(resource_type, user_id, e) from e
 
             return False
 

proxilion/security/intent_capsule.py

@@ -756,7 +756,6 @@ class IntentCapsuleManager:
         """Revoke a capsule."""
         with self._lock:
             if capsule_id in self._capsules:
-                capsule = self._capsules[capsule_id]
                 del self._capsules[capsule_id]
 
                 # Remove from user's list
@@ -770,11 +769,13 @@ class IntentCapsuleManager:
             return False
 
     def verify_capsule(self, capsule_id: str) -> bool:
-        """Verify a capsule's signature."""
+        """Verify a capsule's signature and that it hasn't expired."""
         with self._lock:
             capsule = self._capsules.get(capsule_id)
             if not capsule:
                 return False
+            if capsule.is_expired():
+                return False
             return capsule.verify(self._secret_key)
 
     def create_guard(

proxilion/security/intent_validator.py

@@ -13,6 +13,7 @@ import time
 from collections import defaultdict
 from collections.abc import Callable
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from enum import Enum
 from typing import Any
 
@@ -128,6 +129,11 @@ class IntentValidator:
 
         self._lock = threading.RLock()
 
+        # Memory cleanup tracking
+        self._last_cleanup = time.time()
+        self._cleanup_interval = 300.0  # 5 minutes
+        self._cleanup_call_count = 0
+
     def register_workflow(
         self,
         workflow_name: str,
@@ -247,6 +253,16 @@ class IntentValidator:
             if entry[0] > cutoff
         ]
 
+        # Remove empty user history immediately
+        if not self._call_history[user_id]:
+            del self._call_history[user_id]
+
+        # Periodic cleanup of stale users
+        self._cleanup_call_count += 1
+        if self._cleanup_call_count >= 100:
+            self._cleanup_call_count = 0
+            self._cleanup_stale_users()
+
     def _validate_workflow(
         self,
         user_id: str,
@@ -339,8 +355,9 @@ class IntentValidator:
                 details={"unique_resources": len(unique_resources)},
             )
 
-        # Check for unusual hours (local time check would require timezone)
-        hour = time.localtime(now).tm_hour
+        # Check for unusual hours using explicit UTC to ensure consistent behavior
+        now_dt = datetime.fromtimestamp(now, tz=timezone.utc)
+        hour = now_dt.hour
         if self.thresholds.suspicious_hour_start <= hour < self.thresholds.suspicious_hour_end:
             return ValidationOutcome(
                 result=ValidationResult.SUSPICIOUS,
@@ -493,3 +510,73 @@ class IntentValidator:
         """Get a user's current workflow state."""
         with self._lock:
             return self._user_states.get(user_id, {}).get(workflow_name)
+
+    def _cleanup_stale_users(self) -> None:
+        """Clean up stale user data to prevent memory growth."""
+        now = time.time()
+        cutoff = now - 3600  # 1 hour
+
+        # Clean up empty call histories
+        empty_history_users = [
+            uid for uid, history in self._call_history.items()
+            if not history
+        ]
+        for uid in empty_history_users:
+            del self._call_history[uid]
+
+        # Clean up stale call histories (no recent activity)
+        stale_users = []
+        for uid, history in list(self._call_history.items()):
+            if history and history[-1][0] < cutoff:
+                stale_users.append(uid)
+
+        for uid in stale_users:
+            del self._call_history[uid]
+            # Also clean up related state for stale users
+            self._user_states.pop(uid, None)
+            self._failure_counts.pop(uid, None)
+
+        if empty_history_users or stale_users:
+            logger.debug(
+                f"Cleaned up {len(empty_history_users)} empty + "
+                f"{len(stale_users)} stale user histories"
+            )
+
+    def cleanup(self, max_age_seconds: float = 3600.0) -> int:
+        """
+        Remove stale user data to prevent unbounded memory growth.
+
+        Args:
+            max_age_seconds: Maximum age for inactive users (default 1 hour).
+
+        Returns:
+            Number of users cleaned up.
+        """
+        with self._lock:
+            now = time.time()
+            cutoff = now - max_age_seconds
+            cleaned = 0
+
+            # Clean up call histories
+            for uid in list(self._call_history.keys()):
+                history = self._call_history[uid]
+                # Remove entries older than cutoff
+                history[:] = [e for e in history if e[0] > cutoff]
+                # Remove empty histories
+                if not history:
+                    del self._call_history[uid]
+                    self._user_states.pop(uid, None)
+                    self._failure_counts.pop(uid, None)
+                    cleaned += 1
+
+            # Clean up users with only state but no history
+            orphan_users = set(self._user_states.keys()) - set(self._call_history.keys())
+            for uid in orphan_users:
+                del self._user_states[uid]
+                self._failure_counts.pop(uid, None)
+                cleaned += 1
+
+            if cleaned:
+                logger.debug(f"Cleaned up {cleaned} stale users")
+
+            return cleaned