flaskapi-guard 0.1.0__py3-none-any.whl

flaskapi_guard/__init__.py

@@ -0,0 +1,40 @@
+# flaskapi_guard/__init__.py
+from flaskapi_guard.decorators import RouteConfig, SecurityDecorator
+from flaskapi_guard.extension import FlaskAPIGuard
+from flaskapi_guard.handlers.behavior_handler import BehaviorRule, BehaviorTracker
+from flaskapi_guard.handlers.cloud_handler import CloudManager, cloud_handler
+from flaskapi_guard.handlers.ipban_handler import IPBanManager, ip_ban_manager
+from flaskapi_guard.handlers.ipinfo_handler import IPInfoManager
+from flaskapi_guard.handlers.ratelimit_handler import RateLimitManager, rate_limit_handler
+from flaskapi_guard.handlers.redis_handler import RedisManager, redis_handler
+from flaskapi_guard.handlers.security_headers_handler import (
+    SecurityHeadersManager,
+    security_headers_manager,
+)
+from flaskapi_guard.handlers.suspatterns_handler import sus_patterns_handler
+from flaskapi_guard.models import SecurityConfig
+from flaskapi_guard.protocols.geo_ip_protocol import GeoIPHandler
+from flaskapi_guard.protocols.redis_protocol import RedisHandlerProtocol
+
+__all__ = [
+    "FlaskAPIGuard",
+    "SecurityConfig",
+    "SecurityDecorator",
+    "RouteConfig",
+    "BehaviorTracker",
+    "BehaviorRule",
+    "ip_ban_manager",
+    "IPBanManager",
+    "cloud_handler",
+    "CloudManager",
+    "IPInfoManager",
+    "rate_limit_handler",
+    "RateLimitManager",
+    "redis_handler",
+    "RedisManager",
+    "security_headers_manager",
+    "SecurityHeadersManager",
+    "sus_patterns_handler",
+    "GeoIPHandler",
+    "RedisHandlerProtocol",
+]

flaskapi_guard/core/__init__.py

@@ -0,0 +1,13 @@
+"""Extension supporting modules.
+
+This package contains event bus, metrics, and security check modules
+that support the main FlaskAPIGuard class.
+
+The FlaskAPIGuard class itself is defined in flaskapi_guard/extension.py
+and should be imported from there:
+    from flaskapi_guard.extension import FlaskAPIGuard
+"""
+
+from flaskapi_guard.core.events import MetricsCollector, SecurityEventBus
+
+__all__ = ["SecurityEventBus", "MetricsCollector"]

flaskapi_guard/core/behavioral/__init__.py

@@ -0,0 +1,7 @@
+# flaskapi_guard/core/behavioral/__init__.py
+"""Behavioral rule processing module."""
+
+from flaskapi_guard.core.behavioral.context import BehavioralContext
+from flaskapi_guard.core.behavioral.processor import BehavioralProcessor
+
+__all__ = ["BehavioralContext", "BehavioralProcessor"]

flaskapi_guard/core/behavioral/context.py

@@ -0,0 +1,17 @@
+# flaskapi_guard/core/behavioral/context.py
+from dataclasses import dataclass
+from logging import Logger
+
+from flaskapi_guard.core.events import SecurityEventBus
+from flaskapi_guard.decorators.base import BaseSecurityDecorator
+from flaskapi_guard.models import SecurityConfig
+
+
+@dataclass
+class BehavioralContext:
+    """Context for behavioral rule processing."""
+
+    config: SecurityConfig
+    logger: Logger
+    event_bus: SecurityEventBus
+    guard_decorator: BaseSecurityDecorator | None

flaskapi_guard/core/behavioral/processor.py

@@ -0,0 +1,113 @@
+# flaskapi_guard/core/behavioral/processor.py
+from flask import Request, Response, current_app
+
+from flaskapi_guard.core.behavioral.context import BehavioralContext
+from flaskapi_guard.decorators.base import RouteConfig
+
+
+class BehavioralProcessor:
+    """Handles behavioral rule processing operations."""
+
+    def __init__(self, context: BehavioralContext) -> None:
+        """
+        Initialize the BehavioralProcessor.
+
+        Args:
+            context: Behavioral context with config, logger, and dependencies
+        """
+        self.context = context
+
+    def process_usage_rules(
+        self, request: Request, client_ip: str, route_config: RouteConfig
+    ) -> None:
+        """Process behavioral usage rules from decorators before request processing."""
+        if not self.context.guard_decorator:
+            return
+
+        endpoint_id = self.get_endpoint_id(request)
+        for rule in route_config.behavior_rules:
+            if rule.rule_type in ["usage", "frequency"]:
+                behavior_tracker = self.context.guard_decorator.behavior_tracker
+                threshold_exceeded = behavior_tracker.track_endpoint_usage(
+                    endpoint_id, client_ip, rule
+                )
+                if threshold_exceeded:
+                    details = f"{rule.threshold} calls in {rule.window}s"
+                    message = f"Behavioral {rule.rule_type}"
+                    reason = "threshold exceeded"
+
+                    # Send decorator violation event for behavioral rule violation
+                    self.context.event_bus.send_middleware_event(
+                        event_type="decorator_violation",
+                        request=request,
+                        action_taken="behavioral_action_triggered",
+                        reason=f"{message} {reason}: {details}",
+                        decorator_type="behavioral",
+                        violation_type=rule.rule_type,
+                        threshold=rule.threshold,
+                        window=rule.window,
+                        action=rule.action,
+                        endpoint_id=endpoint_id,
+                    )
+
+                    self.context.guard_decorator.behavior_tracker.apply_action(
+                        rule,
+                        client_ip,
+                        endpoint_id,
+                        f"Usage threshold exceeded: {details}",
+                    )
+
+    def process_return_rules(
+        self,
+        request: Request,
+        response: Response,
+        client_ip: str,
+        route_config: RouteConfig,
+    ) -> None:
+        """Process behavioral return pattern rules from decorators after response."""
+        if not self.context.guard_decorator:
+            return
+
+        endpoint_id = self.get_endpoint_id(request)
+        for rule in route_config.behavior_rules:
+            if rule.rule_type == "return_pattern":
+                behavior_tracker = self.context.guard_decorator.behavior_tracker
+                pattern_detected = behavior_tracker.track_return_pattern(
+                    endpoint_id, client_ip, response, rule
+                )
+                if pattern_detected:
+                    details = f"{rule.threshold} for '{rule.pattern}' in {rule.window}s"
+
+                    # Send decorator violation event for return pattern violation
+                    self.context.event_bus.send_middleware_event(
+                        event_type="decorator_violation",
+                        request=request,
+                        action_taken="behavioral_action_triggered",
+                        reason=f"Return pattern threshold exceeded: {details}",
+                        decorator_type="behavioral",
+                        violation_type="return_pattern",
+                        threshold=rule.threshold,
+                        window=rule.window,
+                        pattern=rule.pattern,
+                        action=rule.action,
+                        endpoint_id=endpoint_id,
+                    )
+
+                    self.context.guard_decorator.behavior_tracker.apply_action(
+                        rule,
+                        client_ip,
+                        endpoint_id,
+                        f"Return pattern threshold exceeded: {details}",
+                    )
+
+    def get_endpoint_id(self, request: Request) -> str:
+        """Generate unique endpoint identifier."""
+        if request.endpoint is None:
+            return f"{request.method}:{request.path}"
+        view_func = current_app.view_functions.get(request.endpoint)
+        if view_func is not None:
+            # This is an internal identifier for tracking, not returned to users.
+            # Values come from Python introspection (module,
+            # qualname), not from user input.
+            return f"{view_func.__module__}.{view_func.__qualname__}"
+        return f"{request.method}:{request.path}"

flaskapi_guard/core/bypass/__init__.py

@@ -0,0 +1,7 @@
+# flaskapi_guard/core/bypass/__init__.py
+"""Bypass handler module."""
+
+from flaskapi_guard.core.bypass.context import BypassContext
+from flaskapi_guard.core.bypass.handler import BypassHandler
+
+__all__ = ["BypassContext", "BypassHandler"]

flaskapi_guard/core/bypass/context.py

@@ -0,0 +1,21 @@
+# flaskapi_guard/core/bypass/context.py
+from dataclasses import dataclass
+from logging import Logger
+
+from flaskapi_guard.core.events import SecurityEventBus
+from flaskapi_guard.core.responses import ErrorResponseFactory
+from flaskapi_guard.core.routing import RouteConfigResolver
+from flaskapi_guard.core.validation import RequestValidator
+from flaskapi_guard.models import SecurityConfig
+
+
+@dataclass
+class BypassContext:
+    """Context for bypass handler operations."""
+
+    config: SecurityConfig
+    logger: Logger
+    event_bus: SecurityEventBus
+    route_resolver: RouteConfigResolver
+    response_factory: ErrorResponseFactory
+    validator: RequestValidator

flaskapi_guard/core/bypass/handler.py

@@ -0,0 +1,71 @@
+# flaskapi_guard/core/bypass/handler.py
+from flask import Request, Response
+
+from flaskapi_guard.core.bypass.context import BypassContext
+from flaskapi_guard.decorators.base import RouteConfig
+
+
+class BypassHandler:
+    """Handles security check bypassing operations."""
+
+    def __init__(self, context: BypassContext) -> None:
+        """
+        Initialize the BypassHandler.
+
+        Args:
+            context: Bypass context with config, logger, and dependencies
+        """
+        self.context = context
+
+    def handle_passthrough(
+        self,
+        request: Request,
+    ) -> Response | None:
+        """
+        Handle special cases that require immediate passthrough.
+
+        This includes requests with no client information and excluded paths.
+
+        Returns:
+            None to let Flask proceed with the request
+        """
+        # No client information
+        if not request.remote_addr:
+            return None
+
+        # Excluded paths
+        if self.context.validator.is_path_excluded(request):
+            return None
+
+        return None
+
+    def handle_security_bypass(
+        self,
+        request: Request,
+        route_config: RouteConfig | None,
+    ) -> Response | None:
+        """
+        Handle bypassed security checks.
+
+        Returns:
+            None to let Flask proceed with the request
+        """
+        if not route_config or not self.context.route_resolver.should_bypass_check(
+            "all", route_config
+        ):
+            return None
+
+        # Send security bypass event for monitoring
+        self.context.event_bus.send_middleware_event(
+            event_type="security_bypass",
+            request=request,
+            action_taken="all_checks_bypassed",
+            reason="Route configured to bypass all security checks",
+            bypassed_checks=list(route_config.bypassed_checks),
+            endpoint=request.path,
+        )
+
+        if not self.context.config.passive_mode:
+            return None
+
+        return None

flaskapi_guard/core/checks/__init__.py

@@ -0,0 +1,48 @@
+# flaskapi_guard/core/checks/__init__.py
+"""Security checks module with modular architecture."""
+
+from flaskapi_guard.core.checks.base import SecurityCheck
+from flaskapi_guard.core.checks.implementations import (
+    AuthenticationCheck,
+    CloudIpRefreshCheck,
+    CloudProviderCheck,
+    CustomRequestCheck,
+    CustomValidatorsCheck,
+    EmergencyModeCheck,
+    HttpsEnforcementCheck,
+    IpSecurityCheck,
+    RateLimitCheck,
+    ReferrerCheck,
+    RequestLoggingCheck,
+    RequestSizeContentCheck,
+    RequiredHeadersCheck,
+    RouteConfigCheck,
+    SuspiciousActivityCheck,
+    TimeWindowCheck,
+    UserAgentCheck,
+)
+from flaskapi_guard.core.checks.pipeline import SecurityCheckPipeline
+
+__all__ = [
+    # Base
+    "SecurityCheck",
+    "SecurityCheckPipeline",
+    # Implementations
+    "RouteConfigCheck",
+    "EmergencyModeCheck",
+    "HttpsEnforcementCheck",
+    "RequestLoggingCheck",
+    "RequestSizeContentCheck",
+    "RequiredHeadersCheck",
+    "AuthenticationCheck",
+    "ReferrerCheck",
+    "CustomValidatorsCheck",
+    "TimeWindowCheck",
+    "CloudIpRefreshCheck",
+    "IpSecurityCheck",
+    "CloudProviderCheck",
+    "UserAgentCheck",
+    "RateLimitCheck",
+    "SuspiciousActivityCheck",
+    "CustomRequestCheck",
+]

flaskapi_guard/core/checks/base.py

@@ -0,0 +1,115 @@
+# flaskapi_guard/core/checks/base.py
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from flask import Request, Response
+
+from flaskapi_guard.models import SecurityConfig
+
+if TYPE_CHECKING:
+    from flaskapi_guard.extension import FlaskAPIGuard
+
+
+class SecurityCheck(ABC):
+    """
+    Base class for security checks in the middleware pipeline.
+
+    Each security check implements a single security concern and can
+    independently block or allow a request to proceed.
+    """
+
+    def __init__(self, middleware: "FlaskAPIGuard") -> None:
+        """
+        Initialize the security check.
+
+        Args:
+            middleware: Reference to the parent FlaskAPIGuard instance
+                       for accessing config, handlers, and utilities.
+        """
+        self.middleware = middleware
+        assert middleware.config is not None, (
+            "FlaskAPIGuard must be initialized with config"
+        )
+        self.config: SecurityConfig = middleware.config
+        assert middleware.logger is not None, (
+            "FlaskAPIGuard must be initialized with logger"
+        )
+        self.logger: logging.Logger = middleware.logger
+
+    @abstractmethod
+    def check(self, request: Request) -> Response | None:
+        """
+        Perform the security check on the request.
+
+        Args:
+            request: The incoming Flask request.
+
+        Returns:
+            Response if the check fails and request should be blocked.
+            None if the check passes and request should continue.
+        """
+        pass  # pragma: no cover
+
+    @property
+    @abstractmethod
+    def check_name(self) -> str:
+        """
+        Name of this security check for logging and debugging.
+
+        Returns:
+            Human-readable name of the check (e.g., "https_enforcement").
+        """
+        pass  # pragma: no cover
+
+    def send_event(
+        self,
+        event_type: str,
+        request: Request,
+        action_taken: str,
+        reason: str,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Send a security event to the agent handler if enabled.
+
+        This is a helper method to simplify event sending from checks.
+
+        Args:
+            event_type: Type of security event.
+            request: The request that triggered the event.
+            action_taken: Action taken by the check.
+            reason: Reason for the action.
+            **kwargs: Additional metadata for the event.
+        """
+        if self.middleware.event_bus is None:
+            return
+        self.middleware.event_bus.send_middleware_event(
+            event_type=event_type,
+            request=request,
+            action_taken=action_taken,
+            reason=reason,
+            **kwargs,
+        )
+
+    def create_error_response(self, status_code: int, default_message: str) -> Response:
+        """
+        Create an error response with custom message and security headers.
+
+        Args:
+            status_code: HTTP status code for the error.
+            default_message: Default error message if no custom message configured.
+
+        Returns:
+            Response object with appropriate status and headers.
+        """
+        return self.middleware.create_error_response(status_code, default_message)
+
+    def is_passive_mode(self) -> bool:
+        """
+        Check if middleware is in passive mode (log only, don't block).
+
+        Returns:
+            True if passive mode is enabled, False otherwise.
+        """
+        return self.config.passive_mode