exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.3__py3-none-any.whl

exonware/xwsystem/security/__init__.py

@@ -1,10 +1,13 @@
+#exonware/xwsystem/src/exonware/xwsystem/security/__init__.py
 """
 XSystem Security Package
 
 Provides security utilities including:
 - Path validation and resource limits
-- Advanced authentication (OAuth2, JWT, SAML)
+- Security contracts and interfaces (IAuthenticatable, IAuthorization, ISecurityToken)
+- Abstract base classes for authentication (AAuthProvider, ATokenInfo, AUserInfo)
 - Cryptography and encryption
+- Security errors and definitions
 """
 
 from .path_validator import PathValidator, PathSecurityError
@@ -14,17 +17,31 @@ from .resource_limits import (
     get_resource_limits,
     reset_resource_limits,
 )
-from .auth import (
-    OAuth2Provider,
-    JWTProvider,
-    SAMLProvider,
-    EnterpriseAuth,
+from .file_security import (
+    FileSecurity,
+    FileSecurityError,
+    FileSizeLimitError,
+    FileIOError,
+    get_file_security,
+    set_file_security,
 )
+from .audit import SecurityAuditor, SecurityLevel, SecurityIssue, audit_security
+# Security implementations
+from .validator import SecurityValidator
+from .monitor import SecurityMonitor
+from .policy import SecurityPolicy
+# Base classes and contracts (kept in xwsystem - foundation layer)
 from .base import (
     AAuthProvider,
     ATokenInfo,
     AUserInfo,
+    ASecurityValidatorBase,
+    ASecurityMonitorBase,
+    ASecurityPolicyBase,
 )
+# Unified Facades
+from .facade import XWSecurity, XWCrypto
+
 from .errors import (
     AuthenticationError,
     AuthorizationError,
@@ -34,8 +51,22 @@ from .errors import (
     SAMLError,
 )
 from .defs import OAuth2GrantType
+# Contracts/interfaces (kept in xwsystem - foundation layer)
+from .contracts import (
+    IAuthenticatable,
+    IAuthorization,
+    ISecurityToken,
+    ISecure,
+    IAuditable,
+    ISecurityValidator,
+    ISecurityMonitor,
+    ISecurityPolicy,
+)
 
 __all__ = [
+    # Unified Facades
+    "XWSecurity",
+    "XWCrypto",
     # Path & Resources
     "PathValidator",
     "PathSecurityError",
@@ -43,19 +74,45 @@ __all__ = [
     "GenericLimitError",
     "get_resource_limits",
     "reset_resource_limits",
-    # Authentication
-    "OAuth2Provider",
-    "JWTProvider",
-    "SAMLProvider",
-    "EnterpriseAuth",
+    # File Security
+    "FileSecurity",
+    "FileSecurityError",
+    "FileSizeLimitError",
+    "FileIOError",
+    "get_file_security",
+    "set_file_security",
+    # Security Implementations
+    "SecurityValidator",
+    "SecurityMonitor",
+    "SecurityPolicy",
+    # Authentication Base Classes (foundation - kept in xwsystem)
     "AAuthProvider",
     "ATokenInfo",
     "AUserInfo",
+    "ASecurityValidatorBase",
+    "ASecurityMonitorBase",
+    "ASecurityPolicyBase",
+    # Security Errors
     "AuthenticationError",
     "AuthorizationError",
     "TokenExpiredError",
     "OAuth2Error",
     "JWTError",
     "SAMLError",
+    # Security Definitions
     "OAuth2GrantType",
+    # Security Audit
+    "SecurityAuditor",
+    "SecurityLevel",
+    "SecurityIssue",
+    "audit_security",
+    # Security Contracts/Interfaces (foundation - kept in xwsystem)
+    "IAuthenticatable",
+    "IAuthorization",
+    "ISecurityToken",
+    "ISecure",
+    "IAuditable",
+    "ISecurityValidator",
+    "ISecurityMonitor",
+    "ISecurityPolicy",
 ]

exonware/xwsystem/security/audit.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+#exonware/xwsystem/src/exonware/xwsystem/security/audit.py
+
+Generic Security Audit Utilities for xwsystem.
+
+Provides generic security auditing that can be used by any library:
+- Security issue detection
+- Security audit reporting
+- Generic security level definitions
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: 26-Jan-2025
+"""
+
+from typing import Any, Optional
+from dataclasses import dataclass
+from enum import Enum
+from exonware.xwsystem import get_logger
+
+logger = get_logger(__name__)
+
+
+class SecurityLevel(Enum):
+    """Security issue severity levels."""
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+@dataclass
+class SecurityIssue:
+    """A security issue found during audit."""
+    level: SecurityLevel
+    category: str
+    description: str
+    recommendation: str
+    location: Optional[str] = None
+
+
+class SecurityAuditor:
+    """
+    Generic security audit utilities.
+    
+    Can be used by any library to audit security issues.
+    """
+    
+    @staticmethod
+    def audit_object(obj: Any, object_type: str = "object") -> list[SecurityIssue]:
+        """
+        Audit an object for security issues.
+        
+        Args:
+            obj: Object instance to audit
+            object_type: Type name of the object (e.g., "strategy", "node", "component")
+            
+        Returns:
+            List of SecurityIssue objects
+        """
+        issues = []
+        obj_name = getattr(obj, '__class__', {}).__name__ if hasattr(obj, '__class__') else 'Unknown'
+        
+        # Check for input validation
+        if not hasattr(obj, 'validate_input'):
+            issues.append(SecurityIssue(
+                level=SecurityLevel.MEDIUM,
+                category="Input Validation",
+                description=f"{object_type.capitalize()} {obj_name} does not have explicit input validation",
+                recommendation="Add validate_input method to check inputs before processing",
+                location=f"{obj_name}.validate_input"
+            ))
+        
+        # Check for bounds checking (if applicable)
+        if hasattr(obj, 'get') and not hasattr(obj, '_check_bounds'):
+            issues.append(SecurityIssue(
+                level=SecurityLevel.LOW,
+                category="Bounds Checking",
+                description=f"{object_type.capitalize()} {obj_name} may not check bounds on get operations",
+                recommendation="Ensure all index/key access operations validate bounds",
+                location=f"{obj_name}.get"
+            ))
+        
+        # Check for error handling
+        methods = [m for m in dir(obj) if not m.startswith('_') and callable(getattr(obj, m, None))]
+        error_handling_count = sum(1 for m in methods if 'error' in m.lower() or 'exception' in m.lower())
+        if error_handling_count == 0:
+            issues.append(SecurityIssue(
+                level=SecurityLevel.MEDIUM,
+                category="Error Handling",
+                description=f"{object_type.capitalize()} {obj_name} may lack comprehensive error handling",
+                recommendation="Add explicit error handling for edge cases and invalid inputs",
+                location=f"{obj_name}"
+            ))
+        
+        # Check for data sanitization (if applicable)
+        if hasattr(obj, 'put') or hasattr(obj, 'set'):
+            issues.append(SecurityIssue(
+                level=SecurityLevel.INFO,
+                category="Data Sanitization",
+                description=f"{object_type.capitalize()} {obj_name} should sanitize data before storage",
+                recommendation="Consider adding data sanitization for user-provided inputs",
+                location=f"{obj_name}.put/set"
+            ))
+        
+        return issues
+    
+    @staticmethod
+    def generate_report(issues: list[SecurityIssue]) -> dict[str, Any]:
+        """
+        Generate a security audit report.
+        
+        Args:
+            issues: List of security issues
+            
+        Returns:
+            Dictionary with report data
+        """
+        by_level = {}
+        by_category = {}
+        
+        for issue in issues:
+            # Group by level
+            level = issue.level.value
+            if level not in by_level:
+                by_level[level] = []
+            by_level[level].append(issue)
+            
+            # Group by category
+            if issue.category not in by_category:
+                by_category[issue.category] = []
+            by_category[issue.category].append(issue)
+        
+        return {
+            'total_issues': len(issues),
+            'by_level': {k: len(v) for k, v in by_level.items()},
+            'by_category': {k: len(v) for k, v in by_category.items()},
+            'issues': [
+                {
+                    'level': issue.level.value,
+                    'category': issue.category,
+                    'description': issue.description,
+                    'recommendation': issue.recommendation,
+                    'location': issue.location
+                }
+                for issue in issues
+            ]
+        }
+
+
+def audit_security(obj: Any, object_type: str = "object") -> dict[str, Any]:
+    """
+    Convenience function to audit an object's security.
+    
+    Args:
+        obj: Object instance to audit
+        object_type: Type name of the object
+        
+    Returns:
+        Security audit report
+    """
+    issues = SecurityAuditor.audit_object(obj, object_type)
+    return SecurityAuditor.generate_report(issues)

exonware/xwsystem/security/base.py

@@ -1,23 +1,24 @@
+#exonware/xwsystem/src/exonware/xwsystem/security/base.py
 #exonware/xwsystem/security/base.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Security module base classes - abstract classes for security functionality.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from .defs import HashAlgorithm, EncryptionAlgorithm, SecurityLevel
 
 
 class ACryptographicBase(ABC):
     """Abstract base class for cryptographic operations."""
     
-    def __init__(self, algorithm: Union[HashAlgorithm, EncryptionAlgorithm]):
+    def __init__(self, algorithm: HashAlgorithm | EncryptionAlgorithm):
         """
         Initialize cryptographic base.
         
@@ -44,32 +45,32 @@ class ACryptographicBase(ABC):
         pass
     
     @abstractmethod
-    def encrypt(self, data: Union[str, bytes]) -> bytes:
+    def encrypt(self, data: str | bytes) -> bytes:
         """Encrypt data."""
         pass
     
     @abstractmethod
-    def decrypt(self, encrypted_data: bytes) -> Union[str, bytes]:
+    def decrypt(self, encrypted_data: bytes) -> str | bytes:
         """Decrypt data."""
         pass
     
     @abstractmethod
-    def hash(self, data: Union[str, bytes]) -> str:
+    def hash(self, data: str | bytes) -> str:
         """Hash data."""
         pass
     
     @abstractmethod
-    def verify_hash(self, data: Union[str, bytes], hash_value: str) -> bool:
+    def verify_hash(self, data: str | bytes, hash_value: str) -> bool:
         """Verify data hash."""
         pass
     
     @abstractmethod
-    def sign(self, data: Union[str, bytes]) -> bytes:
+    def sign(self, data: str | bytes) -> bytes:
         """Sign data."""
         pass
     
     @abstractmethod
-    def verify_signature(self, data: Union[str, bytes], signature: bytes) -> bool:
+    def verify_signature(self, data: str | bytes, signature: bytes) -> bool:
         """Verify data signature."""
         pass
 
@@ -88,17 +89,17 @@ class AHashBase(ABC):
         self._salt: Optional[bytes] = None
     
     @abstractmethod
-    def hash(self, data: Union[str, bytes], salt: Optional[bytes] = None) -> str:
+    def hash(self, data: str | bytes, salt: Optional[bytes] = None) -> str:
         """Hash data."""
         pass
     
     @abstractmethod
-    def hash_file(self, file_path: Union[str, bytes]) -> str:
+    def hash_file(self, file_path: str | bytes) -> str:
         """Hash file content."""
         pass
     
     @abstractmethod
-    def verify_hash(self, data: Union[str, bytes], hash_value: str, salt: Optional[bytes] = None) -> bool:
+    def verify_hash(self, data: str | bytes, hash_value: str, salt: Optional[bytes] = None) -> bool:
         """Verify data hash."""
         pass
     
@@ -118,7 +119,7 @@ class AHashBase(ABC):
         pass
     
     @abstractmethod
-    def hash_with_salt(self, data: Union[str, bytes]) -> tuple[str, bytes]:
+    def hash_with_salt(self, data: str | bytes) -> tuple[str, bytes]:
         """Hash data with generated salt."""
         pass
 
@@ -158,22 +159,22 @@ class AEncryptionBase(ABC):
         pass
     
     @abstractmethod
-    def encrypt(self, data: Union[str, bytes], key: Optional[bytes] = None, iv: Optional[bytes] = None) -> bytes:
+    def encrypt(self, data: str | bytes, key: Optional[bytes] = None, iv: Optional[bytes] = None) -> bytes:
         """Encrypt data."""
         pass
     
     @abstractmethod
-    def decrypt(self, encrypted_data: bytes, key: Optional[bytes] = None, iv: Optional[bytes] = None) -> Union[str, bytes]:
+    def decrypt(self, encrypted_data: bytes, key: Optional[bytes] = None, iv: Optional[bytes] = None) -> str | bytes:
         """Decrypt data."""
         pass
     
     @abstractmethod
-    def encrypt_file(self, file_path: Union[str, bytes], output_path: Union[str, bytes]) -> bool:
+    def encrypt_file(self, file_path: str | bytes, output_path: str | bytes) -> bool:
         """Encrypt file."""
         pass
     
     @abstractmethod
-    def decrypt_file(self, encrypted_file_path: Union[str, bytes], output_path: Union[str, bytes]) -> bool:
+    def decrypt_file(self, encrypted_file_path: str | bytes, output_path: str | bytes) -> bool:
         """Decrypt file."""
         pass
 
@@ -193,37 +194,37 @@ class APathValidatorBase(ABC):
         self._blocked_paths: list[str] = []
     
     @abstractmethod
-    def validate_path(self, path: Union[str, bytes]) -> bool:
+    def validate_path(self, path: str | bytes) -> bool:
         """Validate file path."""
         pass
     
     @abstractmethod
-    def sanitize_path(self, path: Union[str, bytes]) -> str:
+    def sanitize_path(self, path: str | bytes) -> str:
         """Sanitize file path."""
         pass
     
     @abstractmethod
-    def is_safe_path(self, path: Union[str, bytes]) -> bool:
+    def is_safe_path(self, path: str | bytes) -> bool:
         """Check if path is safe."""
         pass
     
     @abstractmethod
-    def is_absolute_path(self, path: Union[str, bytes]) -> bool:
+    def is_absolute_path(self, path: str | bytes) -> bool:
         """Check if path is absolute."""
         pass
     
     @abstractmethod
-    def is_relative_path(self, path: Union[str, bytes]) -> bool:
+    def is_relative_path(self, path: str | bytes) -> bool:
         """Check if path is relative."""
         pass
     
     @abstractmethod
-    def contains_path_traversal(self, path: Union[str, bytes]) -> bool:
+    def contains_path_traversal(self, path: str | bytes) -> bool:
         """Check if path contains traversal sequences."""
         pass
     
     @abstractmethod
-    def normalize_path(self, path: Union[str, bytes]) -> str:
+    def normalize_path(self, path: str | bytes) -> str:
         """Normalize file path."""
         pass
     
@@ -398,6 +399,102 @@ class AUserInfo:
     attributes: dict[str, Any] = field(default_factory=dict)
 
 
+class ASecurityMonitorBase(ABC):
+    """Abstract base class for security monitoring."""
+    
+    def __init__(self):
+        """Initialize security monitor."""
+        pass
+    
+    @abstractmethod
+    def detect_intrusion(self, event_data: dict[str, Any]) -> bool:
+        """Detect intrusion attempts."""
+        pass
+    
+    @abstractmethod
+    def monitor_failed_logins(self, user: str, max_attempts: int = 5) -> bool:
+        """Monitor failed login attempts."""
+        pass
+    
+    @abstractmethod
+    def detect_anomaly(self, behavior_data: dict[str, Any]) -> bool:
+        """Detect anomalous behavior."""
+        pass
+    
+    @abstractmethod
+    def get_security_alerts(self) -> list[dict[str, Any]]:
+        """Get security alerts."""
+        pass
+    
+    @abstractmethod
+    def clear_security_alerts(self) -> None:
+        """Clear security alerts."""
+        pass
+    
+    @abstractmethod
+    def get_threat_level(self) -> SecurityLevel:
+        """Get current threat level."""
+        pass
+    
+    @abstractmethod
+    def set_threat_level(self, level: SecurityLevel) -> None:
+        """Set threat level."""
+        pass
+    
+    @abstractmethod
+    def get_security_metrics(self) -> dict[str, Any]:
+        """Get security metrics."""
+        pass
+
+
+class ASecurityPolicyBase(ABC):
+    """Abstract base class for security policies."""
+    
+    def __init__(self):
+        """Initialize security policy manager."""
+        self._policies: dict[str, dict[str, Any]] = {}
+    
+    @abstractmethod
+    def get_policy(self, policy_name: str) -> dict[str, Any]:
+        """Get security policy."""
+        pass
+    
+    @abstractmethod
+    def set_policy(self, policy_name: str, policy: dict[str, Any]) -> None:
+        """Set security policy."""
+        pass
+    
+    @abstractmethod
+    def validate_policy(self, policy: dict[str, Any]) -> tuple[bool, list[str]]:
+        """Validate security policy."""
+        pass
+    
+    @abstractmethod
+    def apply_policy(self, policy_name: str, context: dict[str, Any]) -> bool:
+        """Apply security policy."""
+        pass
+    
+    @abstractmethod
+    def list_policies(self) -> list[str]:
+        """List all security policies."""
+        pass
+    
+    @abstractmethod
+    def remove_policy(self, policy_name: str) -> bool:
+        """Remove security policy."""
+        pass
+    
+    @abstractmethod
+    def get_policy_violations(self) -> list[dict[str, Any]]:
+        """Get policy violations."""
+        pass
+    
+    @abstractmethod
+    def clear_policy_violations(self) -> None:
+        """Clear policy violations."""
+        pass
+
+
 class AAuthProvider(ABC):
     """Abstract base class for authentication providers."""