security-use 0.1.1__py3-none-any.whl → 0.2.9__py3-none-any.whl

security_use/sensor/middleware.py

@@ -0,0 +1,521 @@
+"""Framework middleware adapters for security monitoring."""
+
+import asyncio
+import logging
+from io import BytesIO
+from typing import Any, Callable, Optional
+from urllib.parse import parse_qs
+
+from .alert_queue import get_alert_queue
+from .config import SensorConfig, create_config
+from .dashboard_alerter import DashboardAlerter
+from .detector import AttackDetector
+from .models import ActionTaken, RequestData
+from .webhook import WebhookAlerter
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityMiddleware:
+    """ASGI middleware for FastAPI/Starlette security monitoring.
+
+    Usage with dashboard (recommended):
+        from fastapi import FastAPI
+        from security_use.sensor import SecurityMiddleware
+
+        app = FastAPI()
+        app.add_middleware(
+            SecurityMiddleware,
+            api_key="su_...",  # Or set SECURITY_USE_API_KEY env var
+            block_on_detection=True,
+        )
+
+    Usage with auto-detection of vulnerable endpoints:
+        app.add_middleware(
+            SecurityMiddleware,
+            auto_detect_vulnerable=True,
+            project_path="./",
+        )
+
+    Legacy usage with webhook:
+        app.add_middleware(
+            SecurityMiddleware,
+            webhook_url="https://your-webhook.com/alerts",
+        )
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        api_key: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        block_on_detection: bool = True,
+        excluded_paths: Optional[list[str]] = None,
+        watch_paths: Optional[list[str]] = None,
+        auto_detect_vulnerable: bool = False,
+        project_path: Optional[str] = None,
+        enabled_detectors: Optional[list[str]] = None,
+        rate_limit_threshold: int = 100,
+        config: Optional[SensorConfig] = None,
+    ):
+        """Initialize the security middleware.
+
+        Args:
+            app: The ASGI application.
+            api_key: SecurityUse API key for dashboard alerting.
+            webhook_url: URL to send alerts to (legacy).
+            block_on_detection: Return 403 on attack detection.
+            excluded_paths: Paths to skip monitoring.
+            watch_paths: Only monitor these paths (None = all).
+            auto_detect_vulnerable: Auto-detect vulnerable endpoints.
+            project_path: Project path for auto-detection.
+            enabled_detectors: List of detector types to enable.
+            rate_limit_threshold: Requests per minute per IP.
+            config: Optional pre-configured SensorConfig.
+        """
+        self.app = app
+
+        if config:
+            self.config = config
+        else:
+            self.config = create_config(
+                api_key=api_key,
+                webhook_url=webhook_url,
+                block_on_detection=block_on_detection,
+                excluded_paths=excluded_paths,
+                watch_paths=watch_paths,
+                auto_detect_vulnerable=auto_detect_vulnerable,
+                project_path=project_path,
+                enabled_detectors=enabled_detectors,
+                rate_limit_threshold=rate_limit_threshold,
+            )
+
+        # Auto-detect vulnerable endpoints if requested
+        if self.config.auto_detect_vulnerable and self.config.project_path:
+            self._detect_vulnerable_endpoints()
+
+        self.detector = AttackDetector(
+            enabled_detectors=self.config.enabled_detectors,
+            rate_limit_threshold=self.config.rate_limit_threshold,
+            rate_limit_window=self.config.rate_limit_window,
+            rate_limit_cleanup_interval=self.config.rate_limit_cleanup_interval,
+            rate_limit_max_ips=self.config.rate_limit_max_ips,
+        )
+
+        # Set up alerters based on config
+        self.dashboard_alerter: Optional[DashboardAlerter] = None
+        self.webhook_alerter: Optional[WebhookAlerter] = None
+
+        if self.config.alert_mode in ("dashboard", "both"):
+            self.dashboard_alerter = DashboardAlerter(
+                api_key=self.config.api_key,
+                dashboard_url=self.config.dashboard_url,
+                timeout=self.config.webhook_timeout,
+                retry_count=self.config.webhook_retry_count,
+            )
+
+        if self.config.alert_mode in ("webhook", "both") and self.config.webhook_url:
+            self.webhook_alerter = WebhookAlerter(
+                webhook_url=self.config.webhook_url,
+                retry_count=self.config.webhook_retry_count,
+                timeout=self.config.webhook_timeout,
+                headers=self.config.webhook_headers,
+            )
+
+        # Log configuration
+        if self.config.watch_paths:
+            logger.info(f"SecurityMiddleware monitoring {len(self.config.watch_paths)} paths")
+        else:
+            logger.info("SecurityMiddleware monitoring all paths")
+
+    def _detect_vulnerable_endpoints(self) -> None:
+        """Auto-detect vulnerable endpoints from project scan."""
+        try:
+            from .endpoint_analyzer import VulnerableEndpointDetector
+
+            detector = VulnerableEndpointDetector()
+            paths = detector.get_watch_paths(self.config.project_path)
+
+            if paths:
+                # Merge with existing watch_paths
+                existing = set(self.config.watch_paths or [])
+                self.config.watch_paths = list(existing | set(paths))
+                logger.info(f"Auto-detected {len(paths)} vulnerable endpoints to monitor")
+            else:
+                logger.info("No vulnerable endpoints detected")
+
+        except Exception as e:
+            logger.warning(f"Failed to auto-detect vulnerable endpoints: {e}")
+
+    async def __call__(self, scope: dict, receive: Callable, send: Callable) -> None:
+        """ASGI interface."""
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # Extract request data
+        path = scope.get("path", "/")
+
+        # Check if path should be monitored
+        if not self.config.should_monitor_path(path):
+            await self.app(scope, receive, send)
+            return
+
+        # Buffer the body and create a replay receive function
+        body, receive_wrapper = await self._buffer_body(receive)
+
+        # Build request data for analysis
+        request_data = self._build_request_data(scope, body)
+
+        # Analyze for attacks
+        events = self.detector.analyze_request(request_data)
+
+        if events:
+            action = (
+                ActionTaken.BLOCKED
+                if self.config.block_on_detection
+                else ActionTaken.LOGGED
+            )
+
+            # Send alerts asynchronously
+            for event in events:
+                if self.dashboard_alerter:
+                    asyncio.create_task(self.dashboard_alerter.send_alert(event, action))
+                if self.webhook_alerter:
+                    asyncio.create_task(self.webhook_alerter.send_alert(event, action))
+
+            if self.config.block_on_detection:
+                # Return 403 Forbidden
+                await self._send_blocked_response(send, events[0])
+                return
+
+        # Continue to application with replay receive that provides the buffered body
+        await self.app(scope, receive_wrapper, send)
+
+    async def _buffer_body(self, receive: Callable) -> tuple[bytes, Callable]:
+        """Buffer the entire request body and create a replay receive function.
+
+        Returns:
+            Tuple of (full_body, receive_wrapper) where receive_wrapper
+            can be passed to the app to replay the body.
+        """
+        body_parts = []
+
+        # Read all body chunks
+        while True:
+            message = await receive()
+            if message["type"] == "http.request":
+                body_parts.append(message.get("body", b""))
+                if not message.get("more_body", False):
+                    break
+            elif message["type"] == "http.disconnect":
+                break
+
+        full_body = b"".join(body_parts)
+
+        # Handle large bodies - truncate for analysis if needed
+        max_body_size = getattr(self.config, "max_body_size", 1024 * 1024)
+        analysis_body = full_body[:max_body_size] if len(full_body) > max_body_size else full_body
+
+        # Create a receive function that replays the buffered body
+        body_sent = False
+
+        async def receive_wrapper() -> dict:
+            nonlocal body_sent
+            if not body_sent:
+                body_sent = True
+                return {
+                    "type": "http.request",
+                    "body": full_body,
+                    "more_body": False,
+                }
+            # After body is sent, wait for disconnect or return empty
+            return {
+                "type": "http.request",
+                "body": b"",
+                "more_body": False,
+            }
+
+        return analysis_body, receive_wrapper
+
+    def _build_request_data(self, scope: dict, body: bytes) -> RequestData:
+        """Build request data from ASGI scope and buffered body."""
+        method = scope.get("method", "GET")
+        path = scope.get("path", "/")
+        query_string = scope.get("query_string", b"").decode("utf-8")
+
+        # Parse query params
+        query_params = {}
+        if query_string:
+            parsed = parse_qs(query_string)
+            query_params = {k: v[0] if len(v) == 1 else v for k, v in parsed.items()}
+
+        # Extract headers
+        headers = {}
+        for key, value in scope.get("headers", []):
+            headers[key.decode("utf-8").lower()] = value.decode("utf-8")
+
+        # Get client IP
+        client = scope.get("client")
+        source_ip = client[0] if client else "unknown"
+
+        # Check for forwarded IP
+        if "x-forwarded-for" in headers:
+            source_ip = headers["x-forwarded-for"].split(",")[0].strip()
+        elif "x-real-ip" in headers:
+            source_ip = headers["x-real-ip"]
+
+        return RequestData(
+            method=method,
+            path=path,
+            query_params=query_params,
+            headers=headers,
+            body=body.decode("utf-8", errors="replace") if body else None,
+            source_ip=source_ip,
+        )
+
+    async def _send_blocked_response(self, send: Callable, event: Any) -> None:
+        """Send a 403 Forbidden response."""
+        body = b'{"error": "Request blocked due to security policy"}'
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 403,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(body)).encode()),
+                ],
+            }
+        )
+        await send(
+            {
+                "type": "http.response.body",
+                "body": body,
+            }
+        )
+
+
+class FlaskSecurityMiddleware:
+    """WSGI middleware for Flask security monitoring.
+
+    Usage with dashboard (recommended):
+        from flask import Flask
+        from security_use.sensor import FlaskSecurityMiddleware
+
+        app = Flask(__name__)
+        app.wsgi_app = FlaskSecurityMiddleware(
+            app.wsgi_app,
+            api_key="su_...",  # Or set SECURITY_USE_API_KEY env var
+        )
+
+    Usage with auto-detection:
+        app.wsgi_app = FlaskSecurityMiddleware(
+            app.wsgi_app,
+            auto_detect_vulnerable=True,
+            project_path="./",
+        )
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        api_key: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        block_on_detection: bool = True,
+        excluded_paths: Optional[list[str]] = None,
+        watch_paths: Optional[list[str]] = None,
+        auto_detect_vulnerable: bool = False,
+        project_path: Optional[str] = None,
+        enabled_detectors: Optional[list[str]] = None,
+        rate_limit_threshold: int = 100,
+        config: Optional[SensorConfig] = None,
+    ):
+        """Initialize the Flask security middleware.
+
+        Args:
+            app: The WSGI application.
+            api_key: SecurityUse API key for dashboard alerting.
+            webhook_url: URL to send alerts to (legacy).
+            block_on_detection: Return 403 on attack detection.
+            excluded_paths: Paths to skip monitoring.
+            watch_paths: Only monitor these paths (None = all).
+            auto_detect_vulnerable: Auto-detect vulnerable endpoints.
+            project_path: Project path for auto-detection.
+            enabled_detectors: List of detector types to enable.
+            rate_limit_threshold: Requests per minute per IP.
+            config: Optional pre-configured SensorConfig.
+        """
+        self.app = app
+
+        if config:
+            self.config = config
+        else:
+            self.config = create_config(
+                api_key=api_key,
+                webhook_url=webhook_url,
+                block_on_detection=block_on_detection,
+                excluded_paths=excluded_paths,
+                watch_paths=watch_paths,
+                auto_detect_vulnerable=auto_detect_vulnerable,
+                project_path=project_path,
+                enabled_detectors=enabled_detectors,
+                rate_limit_threshold=rate_limit_threshold,
+            )
+
+        # Auto-detect vulnerable endpoints if requested
+        if self.config.auto_detect_vulnerable and self.config.project_path:
+            self._detect_vulnerable_endpoints()
+
+        self.detector = AttackDetector(
+            enabled_detectors=self.config.enabled_detectors,
+            rate_limit_threshold=self.config.rate_limit_threshold,
+            rate_limit_window=self.config.rate_limit_window,
+            rate_limit_cleanup_interval=self.config.rate_limit_cleanup_interval,
+            rate_limit_max_ips=self.config.rate_limit_max_ips,
+        )
+
+        # Set up alerters based on config
+        self.dashboard_alerter: Optional[DashboardAlerter] = None
+        self.webhook_alerter: Optional[WebhookAlerter] = None
+
+        if self.config.alert_mode in ("dashboard", "both"):
+            self.dashboard_alerter = DashboardAlerter(
+                api_key=self.config.api_key,
+                dashboard_url=self.config.dashboard_url,
+                timeout=self.config.webhook_timeout,
+                retry_count=self.config.webhook_retry_count,
+            )
+
+        if self.config.alert_mode in ("webhook", "both") and self.config.webhook_url:
+            self.webhook_alerter = WebhookAlerter(
+                webhook_url=self.config.webhook_url,
+                retry_count=self.config.webhook_retry_count,
+                timeout=self.config.webhook_timeout,
+                headers=self.config.webhook_headers,
+            )
+
+        # Get shared alert queue for non-blocking alert delivery
+        self._alert_queue = get_alert_queue()
+
+        # Log configuration
+        if self.config.watch_paths:
+            logger.info(f"FlaskSecurityMiddleware monitoring {len(self.config.watch_paths)} paths")
+        else:
+            logger.info("FlaskSecurityMiddleware monitoring all paths")
+
+    def _detect_vulnerable_endpoints(self) -> None:
+        """Auto-detect vulnerable endpoints from project scan."""
+        try:
+            from .endpoint_analyzer import VulnerableEndpointDetector
+
+            detector = VulnerableEndpointDetector()
+            paths = detector.get_watch_paths(self.config.project_path)
+
+            if paths:
+                existing = set(self.config.watch_paths or [])
+                self.config.watch_paths = list(existing | set(paths))
+                logger.info(f"Auto-detected {len(paths)} vulnerable endpoints to monitor")
+            else:
+                logger.info("No vulnerable endpoints detected")
+
+        except Exception as e:
+            logger.warning(f"Failed to auto-detect vulnerable endpoints: {e}")
+
+    def __call__(self, environ: dict, start_response: Callable) -> Any:
+        """WSGI interface."""
+        path = environ.get("PATH_INFO", "/")
+
+        # Check if path should be monitored
+        if not self.config.should_monitor_path(path):
+            return self.app(environ, start_response)
+
+        request_data = self._extract_request_data(environ)
+
+        # Analyze for attacks
+        events = self.detector.analyze_request(request_data)
+
+        if events:
+            action = (
+                ActionTaken.BLOCKED
+                if self.config.block_on_detection
+                else ActionTaken.LOGGED
+            )
+
+            # Queue alerts for background sending (non-blocking)
+            for event in events:
+                if self.dashboard_alerter:
+                    self._alert_queue.enqueue(event, action, self.dashboard_alerter)
+                if self.webhook_alerter:
+                    self._alert_queue.enqueue(event, action, self.webhook_alerter)
+
+            if self.config.block_on_detection:
+                # Return 403 Forbidden
+                return self._blocked_response(start_response)
+
+        return self.app(environ, start_response)
+
+    def _extract_request_data(self, environ: dict) -> RequestData:
+        """Extract request data from WSGI environ."""
+        method = environ.get("REQUEST_METHOD", "GET")
+        path = environ.get("PATH_INFO", "/")
+        query_string = environ.get("QUERY_STRING", "")
+
+        # Parse query params
+        query_params = {}
+        if query_string:
+            parsed = parse_qs(query_string)
+            query_params = {k: v[0] if len(v) == 1 else v for k, v in parsed.items()}
+
+        # Extract headers
+        headers = {}
+        for key, value in environ.items():
+            if key.startswith("HTTP_"):
+                header_name = key[5:].lower().replace("_", "-")
+                headers[header_name] = value
+            elif key in ("CONTENT_TYPE", "CONTENT_LENGTH"):
+                headers[key.lower().replace("_", "-")] = value
+
+        # Get client IP
+        source_ip = environ.get("REMOTE_ADDR", "unknown")
+        if "HTTP_X_FORWARDED_FOR" in environ:
+            source_ip = environ["HTTP_X_FORWARDED_FOR"].split(",")[0].strip()
+        elif "HTTP_X_REAL_IP" in environ:
+            source_ip = environ["HTTP_X_REAL_IP"]
+
+        # Read body
+        body = None
+        content_length = environ.get("CONTENT_LENGTH")
+        if content_length:
+            try:
+                length = int(content_length)
+                if length > 0:
+                    wsgi_input = environ.get("wsgi.input")
+                    if wsgi_input:
+                        body_bytes = wsgi_input.read(length)
+                        body = body_bytes.decode("utf-8", errors="replace")
+                        # Reset stream for the application
+                        environ["wsgi.input"] = BytesIO(body_bytes)
+            except (ValueError, TypeError):
+                pass
+
+        return RequestData(
+            method=method,
+            path=path,
+            query_params=query_params,
+            headers=headers,
+            body=body,
+            source_ip=source_ip,
+        )
+
+    def _blocked_response(self, start_response: Callable) -> list[bytes]:
+        """Return a 403 Forbidden response."""
+        body = b'{"error": "Request blocked due to security policy"}'
+        start_response(
+            "403 Forbidden",
+            [
+                ("Content-Type", "application/json"),
+                ("Content-Length", str(len(body))),
+            ],
+        )
+        return [body]

security_use/sensor/models.py

@@ -0,0 +1,140 @@
+"""Data models for security sensor events and alerts."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+import uuid
+
+
+class AttackType(Enum):
+    """Types of attacks that can be detected."""
+
+    SQL_INJECTION = "sql_injection"
+    XSS = "xss"
+    PATH_TRAVERSAL = "path_traversal"
+    COMMAND_INJECTION = "command_injection"
+    RATE_LIMIT_EXCEEDED = "rate_limit_exceeded"
+    SUSPICIOUS_HEADER = "suspicious_header"
+
+
+class ActionTaken(Enum):
+    """Action taken in response to detected threat."""
+
+    LOGGED = "logged"
+    BLOCKED = "blocked"
+
+
+@dataclass
+class RequestData:
+    """Normalized HTTP request data for analysis."""
+
+    method: str
+    path: str
+    query_params: dict[str, str] = field(default_factory=dict)
+    headers: dict[str, str] = field(default_factory=dict)
+    body: Optional[str] = None
+    source_ip: str = "unknown"
+    request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+
+@dataclass
+class MatchedPattern:
+    """Details about a matched attack pattern."""
+
+    pattern: str
+    location: str  # "path", "query", "body", "header"
+    field: Optional[str] = None  # Specific field name if applicable
+    matched_value: Optional[str] = None
+
+
+@dataclass
+class SecurityEvent:
+    """Represents a detected security event."""
+
+    event_type: AttackType
+    severity: str  # "CRITICAL", "HIGH", "MEDIUM", "LOW"
+    timestamp: datetime
+    source_ip: str
+    path: str
+    method: str
+    matched_pattern: MatchedPattern
+    request_headers: dict[str, str] = field(default_factory=dict)
+    request_body: Optional[str] = None
+    request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    confidence: float = 0.9
+    description: str = ""
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "event_type": self.event_type.value,
+            "severity": self.severity,
+            "timestamp": self.timestamp.isoformat(),
+            "source_ip": self.source_ip,
+            "path": self.path,
+            "method": self.method,
+            "matched_pattern": {
+                "pattern": self.matched_pattern.pattern,
+                "location": self.matched_pattern.location,
+                "field": self.matched_pattern.field,
+                "matched_value": self.matched_pattern.matched_value,
+            },
+            "request_id": self.request_id,
+            "confidence": self.confidence,
+            "description": self.description,
+        }
+
+
+@dataclass
+class AlertPayload:
+    """Webhook alert payload format."""
+
+    version: str = "1.0"
+    event_id: str = field(default_factory=lambda: f"evt_{uuid.uuid4().hex[:12]}")
+    event_type: str = "security_alert"
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    alert: Optional[SecurityEvent] = None
+    action_taken: ActionTaken = ActionTaken.LOGGED
+
+    def to_dict(self) -> dict:
+        """Convert to webhook payload format."""
+        if self.alert is None:
+            raise ValueError("Alert cannot be None")
+
+        return {
+            "version": self.version,
+            "event": {
+                "id": self.event_id,
+                "type": self.event_type,
+                "timestamp": self.timestamp.isoformat() + "Z",
+            },
+            "alert": {
+                "type": self.alert.event_type.value,
+                "severity": self.alert.severity,
+                "confidence": self.alert.confidence,
+                "description": self.alert.description,
+            },
+            "request": {
+                "method": self.alert.method,
+                "path": self.alert.path,
+                "source_ip": self.alert.source_ip,
+                "headers": self.alert.request_headers,
+            },
+            "matched": {
+                "pattern": self.alert.matched_pattern.pattern,
+                "location": self.alert.matched_pattern.location,
+                "field": self.alert.matched_pattern.field,
+            },
+            "action_taken": self.action_taken.value,
+        }
+
+
+@dataclass
+class AlertResponse:
+    """Response from webhook alert attempt."""
+
+    success: bool
+    webhook_status: int
+    retry_count: int
+    error_message: Optional[str] = None