mcp-security-framework 2.2.0__tar.gz → 2.3.0__tar.gz

{mcp_security_framework-2.2.0 → mcp_security_framework-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-security-framework
-Version: 2.2.0
+Version: 2.3.0
 Summary: Universal security framework for microservices with SSL/TLS, authentication, authorization, and rate limiting. Added extensible security adapter system for custom operation validation, structured audit logging, and operation context support. Comprehensive test coverage with 1104+ tests. Fully backward compatible. Requires cryptography>=42.0.0 for certificate operations.
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 Maintainer-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>

{mcp_security_framework-2.2.0 → mcp_security_framework-2.3.0}/mcp_security_framework/__init__.py

@@ -79,7 +79,7 @@ from mcp_security_framework.schemas.responses import (
 )
 
 # Version information
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 __author__ = "Vasiliy Zdanovskiy"
 __email__ = "vasilyvz@gmail.com"
 __license__ = "MIT"

{mcp_security_framework-2.2.0 → mcp_security_framework-2.3.0}/mcp_security_framework/core/audit_logger.py

@@ -33,6 +33,22 @@ from typing import Any, Dict, List, Optional
 from ..schemas.operation_context import OperationContext
 
 
+class AuditLoggerConfigurationError(ValueError):
+    """
+    Raised when the audit logger is misconfigured or an unsupported
+    backend is requested.
+
+    This error indicates that the logger cannot be initialized with the
+    provided configuration, typically because a requested backend is not
+    supported or required configuration is missing.
+
+    Inherits from ValueError to maintain compatibility with existing
+    code that catches ValueError for configuration errors.
+    """
+
+    pass
+
+
 class AuditStatus(str, Enum):
     """
     Audit Status Enumeration
@@ -224,9 +240,10 @@ class AuditLogger:
         ... )
 
     Note:
-        Database and elasticsearch backends are currently placeholders
-        and will raise NotImplementedError if used. File and console
-        backends are fully implemented.
+        Only file and console backends are supported. Requesting any other
+        backend will raise AuditLoggerConfigurationError at initialization time
+        to prevent silent loss of audit records. This is not an extension point;
+        audit logs are security-critical and must never silently fail.
     """
 
     def __init__(
@@ -239,15 +256,16 @@ class AuditLogger:
 
         Args:
             backend (str): Backend type for audit logging. Supported values:
-                "file", "console", "database", "elasticsearch". Defaults
-                to "console" if not specified.
+                "file" or "console". Defaults to "console" if not specified.
             config (Optional[Dict[str, Any]]): Configuration dictionary for
                 the selected backend. For file backend, should contain
                 "log_file" key with file path. For console backend, can
                 be empty or None. Defaults to None.
 
         Raises:
-            ValueError: If backend type is not supported.
+            AuditLoggerConfigurationError: If backend type is not supported.
+                This is a fail-loud check at initialization time to prevent
+                silent loss of audit records.
             FileNotFoundError: If file backend is used and log file
                 directory does not exist.
 
@@ -266,11 +284,11 @@ class AuditLogger:
         self.logger = logging.getLogger(f"{__name__}.{self.backend}")
 
         # Validate backend type
-        supported_backends = ["file", "console", "database", "elasticsearch"]
-        if self.backend not in supported_backends:
-            raise ValueError(
+        implemented_backends = ["file", "console"]
+        if self.backend not in implemented_backends:
+            raise AuditLoggerConfigurationError(
                 f"Unsupported backend: {self.backend}. "
-                f"Supported backends: {supported_backends}"
+                f"Supported backends: {implemented_backends}"
             )
 
         # Initialize backend-specific configuration
@@ -310,8 +328,6 @@ class AuditLogger:
                 AuditEvent instance with all required fields.
 
         Raises:
-            NotImplementedError: If database or elasticsearch backend
-                is used (not yet implemented).
             IOError: If file backend is used and log file cannot be written.
 
         Example:
@@ -340,14 +356,6 @@ class AuditLogger:
             log_message = json.dumps(event_dict, default=str)
             self.logger.info(log_message)
 
-        elif self.backend == "database":
-            # Placeholder for database backend
-            raise NotImplementedError("Database backend not yet implemented")
-
-        elif self.backend == "elasticsearch":
-            # Placeholder for elasticsearch backend
-            raise NotImplementedError("Elasticsearch backend not yet implemented")
-
     def log_operation(
         self,
         operation: str,

{mcp_security_framework-2.2.0 → mcp_security_framework-2.3.0}/mcp_security_framework/core/auth_manager.py

@@ -702,6 +702,246 @@ class AuthManager:
                 error_code=-32004,
             )
 
+    def authenticate_basic(self, authorization_header: str) -> AuthResult:
+        """
+        Authenticate user using HTTP Basic Authentication.
+
+        This method validates an HTTP Basic Authentication header per RFC 7617,
+        parsing the base64-encoded credentials and verifying them against the
+        configured user store.
+
+        The method performs comprehensive basic auth validation including:
+        - Authorization header presence and format verification
+        - Base64 decoding of credentials
+        - Username and password extraction (split on first colon)
+        - Credential verification against stored password hashes
+        - User role and permission extraction
+
+        Args:
+            authorization_header (str): Full Authorization header value
+                (e.g., "Basic dXNlcm5hbWU6cGFzc3dvcmQ="). Must be in the format
+                "Basic <base64-encoded-credentials>" where credentials are
+                "username:password". Case-insensitive scheme matching.
+
+        Returns:
+            AuthResult: Authentication result object containing:
+                - is_valid (bool): True if authentication succeeded
+                - username (str): Authenticated username if valid
+                - roles (List[str]): User roles from user_roles mapping
+                - auth_method (str): Authentication method used ("basic")
+                - error_code (int): Error code if authentication failed
+                - error_message (str): Human-readable error message
+
+        Note on Error Indistinguishability:
+            An unknown username and a wrong password return identical status and
+            error messages. This prevents username enumeration attacks by making
+            it impossible for an attacker to determine whether a username is
+            valid or only its password is wrong. Both cases return
+            status=INVALID and a generic "Invalid credentials" message.
+
+        Raises:
+            AuthenticationError: When authentication process fails unexpectedly
+
+        Example:
+            >>> auth_manager = AuthManager(config, permission_manager)
+            >>> result = auth_manager.authenticate_basic("Basic dXNlcjpwYXNz")
+            >>> if result.is_valid:
+            ...     print(f"Authenticated user: {result.username}")
+            ...     print(f"User roles: {result.roles}")
+            >>> else:
+            ...     print(f"Authentication failed: {result.error_message}")
+
+        See Also:
+            authenticate_api_key: API key authentication method
+            authenticate_jwt_token: JWT token authentication method
+            authenticate_certificate: Certificate-based authentication
+        """
+        try:
+            from ..utils.crypto_utils import verify_password
+
+            # Validate input
+            if not authorization_header:
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32001,
+                    error_message="Authorization header is required",
+                )
+
+            # Parse Authorization header: "Basic <base64>"
+            parts = authorization_header.split(maxsplit=1)
+            if len(parts) != 2:
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32002,
+                    error_message="Invalid Authorization header format",
+                )
+
+            scheme, credentials_b64 = parts
+            if scheme.lower() != "basic":
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32003,
+                    error_message="Invalid Authorization header format",
+                )
+
+            # Decode base64
+            try:
+                credentials_bytes = __import__("base64").b64decode(credentials_b64)
+                credentials_str = credentials_bytes.decode("utf-8")
+            except Exception:
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32004,
+                    error_message="Invalid credentials encoding",
+                )
+
+            # Split on first colon only (password may contain colons)
+            if ":" not in credentials_str:
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32005,
+                    error_message="Invalid credentials format",
+                )
+
+            colon_idx = credentials_str.index(":")
+            username = credentials_str[:colon_idx]
+            password = credentials_str[colon_idx + 1 :]
+
+            # Validate username is provided
+            if not username:
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32006,
+                    error_message="Invalid credentials",
+                )
+
+            # Check if user exists in basic_auth_users
+            if (
+                not self.config.basic_auth_users
+                or username not in self.config.basic_auth_users
+            ):
+                # User not found - return same error as wrong password
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32007,
+                    error_message="Invalid credentials",
+                )
+
+            # Get stored credentials
+            stored_credentials = self.config.basic_auth_users[username]
+            stored_hash = stored_credentials.get("hash")
+            stored_salt = stored_credentials.get("salt")
+
+            if not stored_hash or not stored_salt:
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32008,
+                    error_message="Invalid credentials",
+                )
+
+            # Verify password
+            try:
+                if not verify_password(password, stored_hash, stored_salt):
+                    # Wrong password - return same error as unknown user
+                    return AuthResult(
+                        is_valid=False,
+                        status=AuthStatus.INVALID,
+                        auth_method="basic",
+                        error_code=-32009,
+                        error_message="Invalid credentials",
+                    )
+            except Exception as e:
+                self.logger.error(
+                    "Password verification failed",
+                    extra={"username": username, "error": str(e)},
+                )
+                return AuthResult(
+                    is_valid=False,
+                    status=AuthStatus.INVALID,
+                    auth_method="basic",
+                    error_code=-32010,
+                    error_message="Invalid credentials",
+                )
+
+            # Get user roles
+            user_roles = self._get_user_roles(username)
+
+            # Get user permissions from permission manager
+            user_permissions = set()
+            if self.permission_manager:
+                try:
+                    permissions_result = (
+                        self.permission_manager.get_effective_permissions(user_roles)
+                    )
+                    # Handle both set and mock objects
+                    if hasattr(permissions_result, "__iter__") and not isinstance(
+                        permissions_result, str
+                    ):
+                        user_permissions = set(permissions_result)
+                    else:
+                        user_permissions = set()
+                except Exception as e:
+                    self.logger.warning(
+                        "Failed to get user permissions",
+                        extra={
+                            "username": username,
+                            "roles": user_roles,
+                            "error": str(e),
+                        },
+                    )
+
+            # Create successful authentication result
+            auth_result = AuthResult(
+                is_valid=True,
+                status=AuthStatus.SUCCESS,
+                username=username,
+                roles=user_roles,
+                permissions=user_permissions,
+                auth_method="basic",
+                auth_timestamp=datetime.now(timezone.utc),
+            )
+
+            self.logger.info(
+                "Basic authentication successful",
+                extra={
+                    "username": username,
+                    "roles": user_roles,
+                    "auth_method": "basic",
+                },
+            )
+
+            return auth_result
+
+        except Exception as e:
+            self.logger.error(
+                "Basic authentication failed",
+                extra={
+                    "auth_header": (
+                        authorization_header[:20] + "..."
+                        if authorization_header
+                        else None
+                    ),
+                    "error": str(e),
+                },
+            )
+            raise AuthenticationError(f"Basic authentication failed: {str(e)}")
+
     def create_jwt_token(self, user_data: Dict) -> str:
         """
         Create JWT token for user.
@@ -978,26 +1218,48 @@ class AuthManager:
         self, username: str, credentials: Dict[str, Any]
     ) -> bool:
         """
-        Validate user against external authentication system.
+        Extension point for integrating with external authentication systems.
+
+        This method is provided as an extension point for frameworks and
+        applications that need to integrate with external authentication
+        systems such as LDAP, Active Directory, OAuth2 providers, SAML
+        identity providers, or other enterprise authentication backends.
 
-        This method provides a hook for integrating with external
-        authentication systems (LDAP, Active Directory, etc.).
+        This base implementation always returns False, indicating that the
+        extension point is not configured. Applications that wish to use
+        external authentication must either:
+        1. Subclass AuthManager and override this method
+        2. Call this base method as a fallback only after checking for
+           configuration that enables external authentication integration
 
         Args:
             username (str): Username to validate
-            credentials (Dict[str, Any]): User credentials
+            credentials (Dict[str, Any]): User credentials dictionary
 
         Returns:
-            bool: True if user is valid in external system
+            bool: True if user is valid in the external system, False if
+                not configured or validation failed.
+
+        Example:
+            To integrate with an external system, subclass AuthManager::
+
+                class LDAPAuthManager(AuthManager):
+                    def _validate_external_user(self, username, credentials):
+                        if not self.config.ldap_enabled:
+                            return False
+                        # Connect to LDAP server and validate credentials
+                        return self.ldap_client.verify(username, credentials)
+
+        See Also:
+            authenticate_api_key: API key authentication
+            authenticate_basic: HTTP Basic Authentication
+            authenticate_certificate: Certificate-based authentication
         """
-        # This is a placeholder for external authentication integration
-        # In a real implementation, this would connect to external auth systems
         self.logger.debug(
-            "External user validation called",
+            "External user validation called (not configured)",
             extra={"username": username, "method": "external"},
         )
 
-        # For now, return False to indicate external validation not implemented
         return False
 
     def _extract_username_from_certificate(

{mcp_security_framework-2.2.0 → mcp_security_framework-2.3.0}/mcp_security_framework/core/ssl_manager.py

@@ -235,10 +235,22 @@ class SSLManager:
 
             # Validate required files or data
             if cert_data is None and not cert_file:
+                if self.config.material_from_memory:
+                    raise SSLConfigurationError(
+                        "material_from_memory=True but cert_data was not supplied; "
+                        "provide cert_data as PEM bytes or "
+                        "set material_from_memory=False"
+                    )
                 raise SSLConfigurationError(
                     "Server certificate file or data is required"
                 )
             if key_data is None and not key_file:
+                if self.config.material_from_memory:
+                    raise SSLConfigurationError(
+                        "material_from_memory=True but key_data was not supplied; "
+                        "provide key_data as PEM bytes or "
+                        "set material_from_memory=False"
+                    )
                 raise SSLConfigurationError(
                     "Server private key file or data is required"
                 )
@@ -423,6 +435,18 @@ class SSLManager:
             verify_mode = verify_mode or self.config.verify_mode
             min_version = min_version or self.config.min_tls_version
 
+            # Validate that material_from_memory promises are kept
+            if cert_data is None and self.config.material_from_memory:
+                raise SSLConfigurationError(
+                    "material_from_memory=True but cert_data was not supplied; "
+                    "provide cert_data as PEM bytes or set material_from_memory=False"
+                )
+            if key_data is None and self.config.material_from_memory:
+                raise SSLConfigurationError(
+                    "material_from_memory=True but key_data was not supplied; "
+                    "provide key_data as PEM bytes or set material_from_memory=False"
+                )
+
             # Check cache (only for file-based contexts)
             cache_key = None
             if cert_data is None and key_data is None: