pywebguard 0.0.0__py3-none-any.whl

pywebguard/filters/ip_filter.py

@@ -0,0 +1,233 @@
+"""
+IP filtering functionality for PyWebGuard with both sync and async support.
+"""
+
+from typing import Dict, List, Optional, Union, Any
+import ipaddress
+from pywebguard.core.config import IPFilterConfig
+from pywebguard.storage.base import BaseStorage, AsyncBaseStorage
+from pywebguard.filters.base import BaseFilter, AsyncBaseFilter
+
+
+class IPFilter(BaseFilter):
+    """
+    Filter requests based on IP addresses (synchronous).
+    """
+
+    def __init__(
+        self,
+        config: IPFilterConfig,
+        storage: BaseStorage,
+    ):
+        """
+        Initialize the IP filter.
+
+        Args:
+            config: IP filter configuration
+            storage: Storage backend for persistent data
+        """
+        self.config = config
+        self.storage = storage
+
+        # Parse IP networks for efficient matching
+        self.whitelist_networks = self._parse_ip_networks(config.whitelist)
+        self.blacklist_networks = self._parse_ip_networks(config.blacklist)
+
+    def _parse_ip_networks(self, ip_list: List[str]) -> List:
+        """
+        Parse IP addresses and CIDR ranges into network objects.
+
+        Args:
+            ip_list: List of IP addresses and CIDR ranges
+
+        Returns:
+            List of network objects
+        """
+        networks = []
+        for ip in ip_list:
+            try:
+                # Handle CIDR notation
+                if "/" in ip:
+                    networks.append(ipaddress.ip_network(ip, strict=False))
+                else:
+                    # Convert single IP to network with /32 or /128 mask
+                    networks.append(ipaddress.ip_address(ip))
+            except ValueError:
+                # Log invalid IP address
+                pass
+        return networks
+
+    def is_allowed(self, ip_address: str) -> Dict[str, Union[bool, str]]:
+        """
+        Check if an IP address is allowed.
+
+        Args:
+            ip_address: The IP address to check
+
+        Returns:
+            Dict with allowed status and reason
+        """
+        if not self.config.enabled:
+            return {"allowed": True, "reason": ""}
+
+        # Re-parse networks in case config changed at runtime
+        self.whitelist_networks = self._parse_ip_networks(self.config.whitelist)
+        self.blacklist_networks = self._parse_ip_networks(self.config.blacklist)
+
+        try:
+            ip = ipaddress.ip_address(ip_address)
+
+            # Check if IP is banned (highest priority)
+            if self.storage.exists(f"banned_ip:{ip_address}"):
+                return {"allowed": False, "reason": "IP is banned"}
+
+            # Check if IP is in blacklist (second priority)
+            if self._is_ip_in_networks(ip, self.blacklist_networks):
+                return {"allowed": False, "reason": "IP in blacklist"}
+
+            # Check if IP is in whitelist (lowest priority)
+            if self.whitelist_networks and not self._is_ip_in_networks(
+                ip, self.whitelist_networks
+            ):
+                return {"allowed": False, "reason": "IP not in whitelist"}
+
+            # Additional checks for cloud providers, geolocation, etc. would go here
+
+            return {"allowed": True, "reason": ""}
+
+        except ValueError:
+            # Invalid IP address
+            return {"allowed": False, "reason": "Invalid IP address"}
+
+    def _is_ip_in_networks(self, ip, networks) -> bool:
+        """
+        Check if an IP is in a list of networks.
+
+        Args:
+            ip: IP address to check
+            networks: List of networks to check against
+
+        Returns:
+            True if IP is in any network, False otherwise
+        """
+        for network in networks:
+            if isinstance(network, ipaddress.IPv4Network) or isinstance(
+                network, ipaddress.IPv6Network
+            ):
+                if ip in network:
+                    return True
+            elif ip == network:  # Direct comparison for single IP addresses
+                return True
+        return False
+
+
+class AsyncIPFilter(AsyncBaseFilter):
+    """
+    Filter requests based on IP addresses (asynchronous).
+    """
+
+    def __init__(
+        self,
+        config: IPFilterConfig,
+        storage: AsyncBaseStorage,
+    ):
+        """
+        Initialize the async IP filter.
+
+        Args:
+            config: IP filter configuration
+            storage: Async storage backend for persistent data
+        """
+        self.config = config
+        self.storage = storage
+
+        # Parse IP networks for efficient matching
+        self.whitelist_networks = self._parse_ip_networks(config.whitelist)
+        self.blacklist_networks = self._parse_ip_networks(config.blacklist)
+
+    def _parse_ip_networks(self, ip_list: List[str]) -> List:
+        """
+        Parse IP addresses and CIDR ranges into network objects.
+
+        Args:
+            ip_list: List of IP addresses and CIDR ranges
+
+        Returns:
+            List of network objects
+        """
+        networks = []
+        for ip in ip_list:
+            try:
+                # Handle CIDR notation
+                if "/" in ip:
+                    networks.append(ipaddress.ip_network(ip, strict=False))
+                else:
+                    # Convert single IP to network with /32 or /128 mask
+                    networks.append(ipaddress.ip_address(ip))
+            except ValueError:
+                # Log invalid IP address
+                pass
+        return networks
+
+    async def is_allowed(self, ip_address: str) -> Dict[str, Union[bool, str]]:
+        """
+        Check if an IP address is allowed asynchronously.
+
+        Args:
+            ip_address: The IP address to check
+
+        Returns:
+            Dict with allowed status and reason
+        """
+        if not self.config.enabled:
+            return {"allowed": True, "reason": ""}
+
+        # Re-parse networks in case config changed at runtime
+        self.whitelist_networks = self._parse_ip_networks(self.config.whitelist)
+        self.blacklist_networks = self._parse_ip_networks(self.config.blacklist)
+
+        try:
+            ip = ipaddress.ip_address(ip_address)
+
+            # Check if IP is banned (highest priority)
+            if await self.storage.exists(f"banned_ip:{ip_address}"):
+                return {"allowed": False, "reason": "IP is banned"}
+
+            # Check if IP is in blacklist (second priority)
+            if self._is_ip_in_networks(ip, self.blacklist_networks):
+                return {"allowed": False, "reason": "IP in blacklist"}
+
+            # Check if IP is in whitelist (lowest priority)
+            if self.whitelist_networks and not self._is_ip_in_networks(
+                ip, self.whitelist_networks
+            ):
+                return {"allowed": False, "reason": "IP not in whitelist"}
+
+            # Additional checks for cloud providers, geolocation, etc. would go here
+
+            return {"allowed": True, "reason": ""}
+
+        except ValueError:
+            # Invalid IP address
+            return {"allowed": False, "reason": "Invalid IP address"}
+
+    def _is_ip_in_networks(self, ip, networks) -> bool:
+        """
+        Check if an IP is in a list of networks.
+
+        Args:
+            ip: IP address to check
+            networks: List of networks to check against
+
+        Returns:
+            True if IP is in any network, False otherwise
+        """
+        for network in networks:
+            if isinstance(network, ipaddress.IPv4Network) or isinstance(
+                network, ipaddress.IPv6Network
+            ):
+                if ip in network:
+                    return True
+            elif ip == network:  # Direct comparison for single IP addresses
+                return True
+        return False

pywebguard/filters/user_agent.py

@@ -0,0 +1,102 @@
+"""
+User agent filtering functionality for PyWebGuard with both sync and async support.
+"""
+
+from typing import Dict, Union
+from pywebguard.core.config import UserAgentConfig
+from pywebguard.storage.base import BaseStorage, AsyncBaseStorage
+from pywebguard.filters.base import BaseFilter, AsyncBaseFilter
+
+
+class UserAgentFilter(BaseFilter):
+    """
+    Filter requests based on user agent (synchronous).
+    """
+
+    def __init__(
+        self,
+        config: UserAgentConfig,
+        storage: BaseStorage,
+    ):
+        """
+        Initialize the user agent filter.
+
+        Args:
+            config: User agent filter configuration
+            storage: Storage backend for persistent data
+        """
+        self.config = config
+        self.storage = storage
+
+    def is_allowed(self, user_agent: str) -> Dict[str, Union[bool, str]]:
+        """
+        Check if a user agent is allowed.
+
+        Args:
+            user_agent: The user agent string to check
+
+        Returns:
+            Dict with allowed status and reason
+        """
+        if not self.config.enabled:
+            return {"allowed": True, "reason": ""}
+
+        if not user_agent:
+            return {"allowed": False, "reason": "Empty user agent"}
+
+        # Check if user agent is in blocked list
+        for blocked_agent in self.config.blocked_agents:
+            if blocked_agent.lower() in user_agent.lower():
+                return {
+                    "allowed": False,
+                    "reason": f"Blocked user agent: {blocked_agent}",
+                }
+
+        return {"allowed": True, "reason": ""}
+
+
+class AsyncUserAgentFilter(AsyncBaseFilter):
+    """
+    Filter requests based on user agent (asynchronous).
+    """
+
+    def __init__(
+        self,
+        config: UserAgentConfig,
+        storage: AsyncBaseStorage,
+    ):
+        """
+        Initialize the async user agent filter.
+
+        Args:
+            config: User agent filter configuration
+            storage: Async storage backend for persistent data
+        """
+        self.config = config
+        self.storage = storage
+
+    async def is_allowed(self, user_agent: str) -> Dict[str, Union[bool, str]]:
+        """
+        Check if a user agent is allowed asynchronously.
+
+        Args:
+            user_agent: The user agent string to check
+
+        Returns:
+            Dict with allowed status and reason
+        """
+        if not self.config.enabled:
+            return {"allowed": True, "reason": ""}
+
+        if not user_agent:
+            return {"allowed": False, "reason": "Empty user agent"}
+
+        # Check if user agent is in blocked list
+        for blocked_agent in self.config.blocked_agents:
+            if blocked_agent.lower() in user_agent.lower():
+                return {
+                    "allowed": False,
+                    "reason": f"Blocked user agent: {blocked_agent}",
+                }
+
+        return {"allowed": True, "reason": ""}

pywebguard/frameworks/_fastapi.py

@@ -0,0 +1,191 @@
+"""
+FastAPI integration for PyWebGuard.
+
+This module provides middleware for integrating PyWebGuard with FastAPI applications.
+It handles request interception, security checks, and response processing.
+
+Classes:
+    FastAPIGuard: FastAPI middleware for PyWebGuard
+"""
+
+from typing import Callable, Dict, Any, Optional, List, Union
+import time
+
+# Check if FastAPI is installed
+try:
+    from fastapi import FastAPI, Request, Response
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from fastapi.responses import JSONResponse
+
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FASTAPI_AVAILABLE = False
+
+    # Create dummy classes for type checking
+    class BaseHTTPMiddleware:
+        def __init__(self, app):
+            self.app = app
+
+    class Request:
+        pass
+
+    class Response:
+        pass
+
+    class JSONResponse:
+        pass
+
+
+from pywebguard.core.base import Guard, AsyncGuard
+from pywebguard.core.config import GuardConfig
+from pywebguard.storage.base import BaseStorage, AsyncBaseStorage
+from pywebguard.storage.memory import MemoryStorage, AsyncMemoryStorage
+
+
+class FastAPIGuard(BaseHTTPMiddleware):
+    """
+    FastAPI middleware for PyWebGuard supporting both sync and async guards.
+    """
+
+    def __init__(
+        self,
+        app,
+        config: Optional[GuardConfig] = None,
+        storage: Optional[Union[AsyncBaseStorage, BaseStorage]] = None,
+        route_rate_limits: Optional[List[Dict[str, Any]]] = None,
+        custom_response_handler: Optional[Callable] = None,
+    ):
+        """
+        Initialize the FastAPI guard.
+
+        Args:
+            app: The FastAPI application
+            config: Guard configuration
+            storage: Storage backend
+            route_rate_limits: Optional list of route-specific rate limits
+            custom_response_handler: Optional custom response handler for blocked requests
+        """
+        if not FASTAPI_AVAILABLE:
+            raise ImportError(
+                "FastAPI is not installed. Install it with 'pip install pywebguard[fastapi]' "
+                "or 'pip install fastapi>=0.68.0 starlette>=0.14.0'"
+            )
+
+        super().__init__(app)
+        self.app = app
+
+        # Use AsyncGuard instead of Guard
+        if isinstance(storage, AsyncBaseStorage):
+            self.guard = AsyncGuard(config, storage)
+        else:
+            raise ValueError(
+                "Storage must be an instance of AsyncBaseStorage for FastAPI integration"
+            )
+
+        # Add route-specific rate limits if provided
+        if route_rate_limits:
+            for route in route_rate_limits:
+                self.guard.rate_limiter.add_route_config(route["endpoint"], route)
+
+        # Set up default response handler if none provided
+        if custom_response_handler is None:
+            custom_response_handler = self._default_response_handler
+        self.custom_response_handler = custom_response_handler
+
+    async def _default_response_handler(
+        self, request: Request, reason: str
+    ) -> Response:
+        """
+        Default response handler for blocked requests.
+
+        Args:
+            request: The FastAPI request object
+            reason: The reason the request was blocked
+
+        Returns:
+            A JSON response with details about why the request was blocked
+        """
+        status_code = 429 if "rate limit" in reason.lower() else 403
+
+        return JSONResponse(
+            status_code=status_code,
+            content={
+                "error": "Request blocked",
+                "reason": reason,
+                "timestamp": time.time(),
+                "path": request.url.path,
+                "method": request.method,
+            },
+        )
+
+    async def dispatch(self, request: Request, call_next):
+        """
+        Process the request through the middleware.
+
+        Args:
+            request: The FastAPI request object
+            call_next: The next middleware/handler in the chain
+
+        Returns:
+            The response from the next middleware/handler
+        """
+        # Store the guard instance in the app's state if not already stored
+        if not hasattr(request.app.state, "guard"):
+            request.app.state.guard = self
+
+        client_ip = request.client.host
+
+        # Check if IP is banned first
+        is_banned = await self.guard.is_ip_banned(client_ip)
+        if is_banned:
+            ban_info = await self.guard.storage.get(f"banned_ip:{client_ip}")
+            response = await self.custom_response_handler(
+                request,
+                f"IP is banned: {ban_info.get('reason', 'Unknown reason')}",
+            )
+            # Log blocked request
+            request_info = {
+                "ip": client_ip,
+                "method": request.method,
+                "path": request.url.path,
+                "user_agent": request.headers.get("user-agent", "unknown"),
+            }
+            await self.guard.logger.log_blocked_request(
+                request_info,
+                "ip_ban",
+                f"IP is banned: {ban_info.get('reason', 'Unknown reason')}",
+            )
+            return response
+
+        # Check rate limits
+        rate_info = await self.guard.rate_limiter.check_limit(
+            client_ip, request.url.path
+        )
+        if not rate_info["allowed"]:
+            response = await self.custom_response_handler(request, rate_info["reason"])
+            # Log blocked request
+            request_info = {
+                "ip": client_ip,
+                "method": request.method,
+                "path": request.url.path,
+                "user_agent": request.headers.get("user-agent", "unknown"),
+            }
+            await self.guard.logger.log_security_event(
+                "WARNING",
+                f"Blocked request: {request.method} {request.url.path} - {rate_info['reason']}",
+            )
+            return response
+
+        # Continue with the request
+        response = await call_next(request)
+
+        # Log successful request
+        request_info = {
+            "ip": client_ip,
+            "method": request.method,
+            "path": request.url.path,
+            "user_agent": request.headers.get("user-agent", "unknown"),
+        }
+        await self.guard.logger.log_request(request_info, response)
+
+        return response