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

security_use/sbom/models.py

@@ -0,0 +1,40 @@
+"""Data models for SBOM generation."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+
+class SBOMFormat(Enum):
+    """Supported SBOM output formats."""
+
+    CYCLONEDX_JSON = "cyclonedx-json"
+    CYCLONEDX_XML = "cyclonedx-xml"
+    SPDX_JSON = "spdx-json"
+    SPDX_TV = "spdx-tv"  # Tag-value format
+
+
+@dataclass
+class SBOMComponent:
+    """Represents a component in the SBOM."""
+
+    name: str
+    version: str
+    ecosystem: str
+    purl: Optional[str] = None
+    licenses: list[str] = field(default_factory=list)
+    hashes: dict[str, str] = field(default_factory=dict)
+    supplier: Optional[str] = None
+    description: Optional[str] = None
+    vulnerabilities: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SBOMOutput:
+    """Result of SBOM generation."""
+
+    format: SBOMFormat
+    content: str
+    component_count: int
+    generated_at: datetime = field(default_factory=datetime.utcnow)

security_use/scanner.py

@@ -42,7 +42,7 @@ def scan_iac(
     Args:
         path: Path to scan (file or directory). Defaults to current directory.
         file_content: Direct content to scan (alternative to path).
-        file_type: Type of IaC file when using file_content.
+        file_type: Type of IaC file when using file_content (e.g., "terraform", "cloudformation").
 
     Returns:
         ScanResult containing any IaC findings.
@@ -52,7 +52,20 @@ def scan_iac(
     scanner = IaCScanner()
 
     if file_content is not None:
-        return scanner.scan_content(file_content, file_type or "terraform")
+        # Map file_type to a synthetic file path with correct extension
+        # so the parser can be selected correctly
+        file_type_to_extension = {
+            "terraform": "inline.tf",
+            "tf": "inline.tf",
+            "cloudformation": "inline.yaml",
+            "cfn": "inline.yaml",
+            "yaml": "inline.yaml",
+            "yml": "inline.yml",
+            "json": "inline.json",
+        }
+        file_type_lower = (file_type or "terraform").lower()
+        synthetic_path = file_type_to_extension.get(file_type_lower, f"inline.{file_type_lower}")
+        return scanner.scan_content(file_content, synthetic_path)
 
     scan_path = Path(path) if path else Path.cwd()
     return scanner.scan_path(scan_path)

security_use/sensor/__init__.py

@@ -0,0 +1,125 @@
+"""Security sensor for runtime attack detection and alerting.
+
+This module provides middleware for FastAPI and Flask applications that
+detects malicious patterns in HTTP requests and sends alerts to the
+SecurityUse dashboard or custom webhooks.
+
+Example 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,
+    )
+
+Example with auto-detection of vulnerable endpoints:
+    app.add_middleware(
+        SecurityMiddleware,
+        auto_detect_vulnerable=True,
+        project_path="./",
+    )
+
+Example with selective monitoring:
+    app.add_middleware(
+        SecurityMiddleware,
+        watch_paths=["/api/users", "/api/search", "/admin/*"],
+    )
+
+Example usage with Flask:
+    from flask import Flask
+    from security_use.sensor import FlaskSecurityMiddleware
+
+    app = Flask(__name__)
+    app.wsgi_app = FlaskSecurityMiddleware(
+        app.wsgi_app,
+        api_key="su_...",
+    )
+
+Legacy usage with webhook:
+    app.add_middleware(
+        SecurityMiddleware,
+        webhook_url="https://your-webhook.com/alerts",
+    )
+
+Programmatic usage:
+    from security_use.sensor import AttackDetector, DashboardAlerter, RequestData
+
+    detector = AttackDetector()
+    alerter = DashboardAlerter(api_key="su_...")
+
+    request = RequestData(
+        method="POST",
+        path="/api/users",
+        body="username=admin' OR 1=1--",
+        source_ip="192.168.1.100",
+    )
+
+    events = detector.analyze_request(request)
+    for event in events:
+        await alerter.send_alert(event)
+
+Endpoint analysis:
+    from security_use.sensor import VulnerableEndpointDetector
+
+    detector = VulnerableEndpointDetector()
+    result = detector.analyze("./my-project")
+
+    # Get paths that use vulnerable packages
+    for endpoint in result.vulnerable_endpoints:
+        print(f"{endpoint.path} - risk: {endpoint.risk_score}")
+"""
+
+from .alert_queue import AlertQueue, get_alert_queue
+from .config import SensorConfig, create_config
+from .dashboard_alerter import DashboardAlerter
+from .detector import AttackDetector, RateLimiter
+from .endpoint_analyzer import (
+    AnalysisResult,
+    EndpointInfo,
+    VulnerableEndpointDetector,
+    detect_vulnerable_endpoints,
+)
+from .middleware import FlaskSecurityMiddleware, SecurityMiddleware
+from .models import (
+    ActionTaken,
+    AlertPayload,
+    AlertResponse,
+    AttackType,
+    MatchedPattern,
+    RequestData,
+    SecurityEvent,
+)
+from .webhook import WebhookAlerter
+
+__all__ = [
+    # Middleware
+    "SecurityMiddleware",
+    "FlaskSecurityMiddleware",
+    # Detection
+    "AttackDetector",
+    "RateLimiter",
+    # Alerting
+    "AlertQueue",
+    "get_alert_queue",
+    "DashboardAlerter",
+    "WebhookAlerter",
+    # Endpoint Analysis
+    "VulnerableEndpointDetector",
+    "detect_vulnerable_endpoints",
+    "EndpointInfo",
+    "AnalysisResult",
+    # Configuration
+    "SensorConfig",
+    "create_config",
+    # Models
+    "SecurityEvent",
+    "RequestData",
+    "MatchedPattern",
+    "AlertPayload",
+    "AlertResponse",
+    "AttackType",
+    "ActionTaken",
+]

security_use/sensor/alert_queue.py

@@ -0,0 +1,207 @@
+"""Background alert queue for non-blocking alert delivery."""
+
+import atexit
+import logging
+import queue
+import threading
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional, Protocol
+
+if TYPE_CHECKING:
+    from .models import ActionTaken, SecurityEvent
+
+logger = logging.getLogger(__name__)
+
+
+class Alerter(Protocol):
+    """Protocol for alerters."""
+
+    def send_alert_sync(self, event: "SecurityEvent", action: "ActionTaken") -> bool:
+        ...
+
+
+@dataclass
+class AlertItem:
+    """An alert to be sent."""
+
+    event: "SecurityEvent"
+    action: "ActionTaken"
+    alerter: Alerter
+
+
+class AlertQueue:
+    """Background queue for sending alerts without blocking requests.
+
+    Usage:
+        queue = AlertQueue(max_size=1000)
+        queue.start()
+
+        # In request handler:
+        queue.enqueue(event, action, alerter)
+
+        # On shutdown:
+        queue.stop()
+    """
+
+    def __init__(
+        self,
+        max_size: int = 1000,
+        num_workers: int = 2,
+        drain_timeout: float = 5.0,
+    ):
+        """Initialize the alert queue.
+
+        Args:
+            max_size: Maximum queue size. Alerts dropped if full.
+            num_workers: Number of worker threads.
+            drain_timeout: Seconds to wait for queue drain on shutdown.
+        """
+        self.max_size = max_size
+        self.num_workers = num_workers
+        self.drain_timeout = drain_timeout
+
+        self._queue: queue.Queue[Optional[AlertItem]] = queue.Queue(maxsize=max_size)
+        self._workers: list[threading.Thread] = []
+        self._running = False
+        self._started = False
+        self._lock = threading.Lock()
+
+        # Stats
+        self.alerts_sent = 0
+        self.alerts_failed = 0
+        self.alerts_dropped = 0
+
+    def start(self) -> None:
+        """Start the worker threads."""
+        with self._lock:
+            if self._started:
+                return
+
+            self._running = True
+            self._started = True
+
+            for i in range(self.num_workers):
+                worker = threading.Thread(
+                    target=self._worker_loop,
+                    name=f"security-use-alert-worker-{i}",
+                    daemon=True,
+                )
+                worker.start()
+                self._workers.append(worker)
+
+            # Register shutdown handler
+            atexit.register(self.stop)
+
+            logger.debug(f"Alert queue started with {self.num_workers} workers")
+
+    def stop(self, timeout: Optional[float] = None) -> None:
+        """Stop the worker threads and drain the queue.
+
+        Args:
+            timeout: Max seconds to wait. Uses drain_timeout if None.
+        """
+        with self._lock:
+            if not self._running:
+                return
+
+            self._running = False
+            timeout = timeout or self.drain_timeout
+
+            # Send stop signals
+            for _ in self._workers:
+                try:
+                    self._queue.put_nowait(None)
+                except queue.Full:
+                    pass
+
+        # Wait for workers (outside lock to avoid deadlock)
+        for worker in self._workers:
+            worker.join(timeout=timeout / max(1, len(self._workers)))
+
+        with self._lock:
+            self._workers.clear()
+
+        logger.debug(
+            f"Alert queue stopped. Sent: {self.alerts_sent}, "
+            f"Failed: {self.alerts_failed}, Dropped: {self.alerts_dropped}"
+        )
+
+    def enqueue(
+        self,
+        event: "SecurityEvent",
+        action: "ActionTaken",
+        alerter: Alerter,
+    ) -> bool:
+        """Add an alert to the queue.
+
+        Returns:
+            True if queued, False if dropped (queue full).
+        """
+        if not self._running:
+            self.start()  # Auto-start on first use
+
+        item = AlertItem(event=event, action=action, alerter=alerter)
+
+        try:
+            self._queue.put_nowait(item)
+            return True
+        except queue.Full:
+            self.alerts_dropped += 1
+            logger.warning(
+                f"Alert queue full, dropping alert: {event.event_type}"
+            )
+            return False
+
+    def _worker_loop(self) -> None:
+        """Worker thread main loop."""
+        while self._running or not self._queue.empty():
+            try:
+                item = self._queue.get(timeout=0.5)
+
+                if item is None:  # Stop signal
+                    self._queue.task_done()
+                    break
+
+                try:
+                    success = item.alerter.send_alert_sync(item.event, item.action)
+                    if success:
+                        self.alerts_sent += 1
+                    else:
+                        self.alerts_failed += 1
+                except Exception as e:
+                    self.alerts_failed += 1
+                    logger.error(f"Alert worker error: {e}")
+                finally:
+                    self._queue.task_done()
+
+            except queue.Empty:
+                continue
+
+    @property
+    def pending_count(self) -> int:
+        """Number of alerts waiting to be sent."""
+        return self._queue.qsize()
+
+    @property
+    def stats(self) -> dict:
+        """Get queue statistics."""
+        return {
+            "pending": self.pending_count,
+            "sent": self.alerts_sent,
+            "failed": self.alerts_failed,
+            "dropped": self.alerts_dropped,
+        }
+
+
+# Global singleton for easy access
+_default_queue: Optional[AlertQueue] = None
+_queue_lock = threading.Lock()
+
+
+def get_alert_queue() -> AlertQueue:
+    """Get the default alert queue singleton."""
+    global _default_queue
+    with _queue_lock:
+        if _default_queue is None:
+            _default_queue = AlertQueue()
+        return _default_queue

security_use/sensor/config.py

@@ -0,0 +1,217 @@
+"""Configuration for the security sensor."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class SensorConfig:
+    """Configuration for the security sensor middleware."""
+
+    # Alerting mode: "dashboard", "webhook", or "both"
+    alert_mode: str = "dashboard"
+
+    # Dashboard settings (preferred)
+    api_key: Optional[str] = None
+    dashboard_url: Optional[str] = None
+
+    # Webhook settings (legacy/fallback)
+    webhook_url: Optional[str] = None
+    webhook_headers: dict[str, str] = field(default_factory=dict)
+    webhook_retry_count: int = 3
+    webhook_timeout: float = 10.0
+
+    # Detection settings
+    enabled_detectors: list[str] = field(
+        default_factory=lambda: [
+            "sqli",
+            "xss",
+            "path_traversal",
+            "command_injection",
+            "rate_limit",
+            "suspicious_headers",
+        ]
+    )
+
+    # Rate limiting
+    rate_limit_threshold: int = 100  # requests per window per IP
+    rate_limit_window: int = 60  # seconds
+    rate_limit_cleanup_interval: int = 300  # seconds between cleanup runs
+    rate_limit_max_ips: int = 100000  # max tracked IPs to prevent memory leak
+
+    # Alert queue settings (for non-blocking alert delivery in Flask)
+    alert_queue_size: int = 1000  # max queued alerts
+    alert_queue_workers: int = 2  # number of worker threads
+    alert_queue_drain_timeout: float = 5.0  # seconds to wait on shutdown
+
+    # Body handling
+    max_body_size: int = 1024 * 1024  # 1MB max body for analysis
+
+    # Behavior
+    block_on_detection: bool = True  # Return 403 on attack detection (default True now)
+    excluded_paths: list[str] = field(default_factory=list)  # Paths to skip
+
+    # Selective monitoring
+    watch_paths: Optional[list[str]] = None  # Only monitor these paths (None = all)
+    auto_detect_vulnerable: bool = False  # Auto-detect vulnerable endpoints
+    project_path: Optional[str] = None  # Project path for auto-detection
+
+    # Logging
+    log_requests: bool = False  # Log all requests (not just attacks)
+    log_level: str = "WARNING"
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SensorConfig":
+        """Create config from dictionary."""
+        return cls(
+            alert_mode=data.get("alert_mode", "dashboard"),
+            api_key=data.get("api_key") or os.environ.get("SECURITY_USE_API_KEY"),
+            dashboard_url=data.get("dashboard_url") or os.environ.get("SECURITY_USE_DASHBOARD_URL"),
+            webhook_url=data.get("webhook_url"),
+            webhook_headers=data.get("webhook_headers", {}),
+            webhook_retry_count=data.get("webhook_retry_count", 3),
+            webhook_timeout=data.get("webhook_timeout", 10.0),
+            enabled_detectors=data.get(
+                "enabled_detectors",
+                [
+                    "sqli",
+                    "xss",
+                    "path_traversal",
+                    "command_injection",
+                    "rate_limit",
+                    "suspicious_headers",
+                ],
+            ),
+            rate_limit_threshold=data.get("rate_limit_threshold", 100),
+            rate_limit_window=data.get("rate_limit_window", 60),
+            rate_limit_cleanup_interval=data.get("rate_limit_cleanup_interval", 300),
+            rate_limit_max_ips=data.get("rate_limit_max_ips", 100000),
+            alert_queue_size=data.get("alert_queue_size", 1000),
+            alert_queue_workers=data.get("alert_queue_workers", 2),
+            alert_queue_drain_timeout=data.get("alert_queue_drain_timeout", 5.0),
+            max_body_size=data.get("max_body_size", 1024 * 1024),
+            block_on_detection=data.get("block_on_detection", True),
+            excluded_paths=data.get("excluded_paths", []),
+            watch_paths=data.get("watch_paths"),
+            auto_detect_vulnerable=data.get("auto_detect_vulnerable", False),
+            project_path=data.get("project_path"),
+            log_requests=data.get("log_requests", False),
+            log_level=data.get("log_level", "WARNING"),
+        )
+
+    def to_dict(self) -> dict:
+        """Convert config to dictionary."""
+        return {
+            "alert_mode": self.alert_mode,
+            "api_key": self.api_key,
+            "dashboard_url": self.dashboard_url,
+            "webhook_url": self.webhook_url,
+            "webhook_headers": self.webhook_headers,
+            "webhook_retry_count": self.webhook_retry_count,
+            "webhook_timeout": self.webhook_timeout,
+            "enabled_detectors": self.enabled_detectors,
+            "rate_limit_threshold": self.rate_limit_threshold,
+            "rate_limit_window": self.rate_limit_window,
+            "rate_limit_cleanup_interval": self.rate_limit_cleanup_interval,
+            "rate_limit_max_ips": self.rate_limit_max_ips,
+            "alert_queue_size": self.alert_queue_size,
+            "alert_queue_workers": self.alert_queue_workers,
+            "alert_queue_drain_timeout": self.alert_queue_drain_timeout,
+            "max_body_size": self.max_body_size,
+            "block_on_detection": self.block_on_detection,
+            "excluded_paths": self.excluded_paths,
+            "watch_paths": self.watch_paths,
+            "auto_detect_vulnerable": self.auto_detect_vulnerable,
+            "project_path": self.project_path,
+            "log_requests": self.log_requests,
+            "log_level": self.log_level,
+        }
+
+    def is_path_excluded(self, path: str) -> bool:
+        """Check if a path should be excluded from monitoring."""
+        for excluded in self.excluded_paths:
+            if excluded.endswith("*"):
+                if path.startswith(excluded[:-1]):
+                    return True
+            elif path == excluded:
+                return True
+        return False
+
+    def should_monitor_path(self, path: str) -> bool:
+        """Check if a path should be monitored.
+
+        Returns True if:
+        - Path is not in excluded_paths AND
+        - Either watch_paths is None (monitor all) OR path is in watch_paths
+        """
+        if self.is_path_excluded(path):
+            return False
+
+        if self.watch_paths is None:
+            return True
+
+        # Check watch_paths with wildcard support
+        for watch_path in self.watch_paths:
+            if watch_path.endswith("*"):
+                if path.startswith(watch_path[:-1]):
+                    return True
+            elif path == watch_path or path.startswith(watch_path + "/"):
+                return True
+
+        return False
+
+
+def create_config(
+    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,
+    **kwargs,
+) -> SensorConfig:
+    """Convenience function to create a sensor configuration.
+
+    Args:
+        api_key: SecurityUse API key for dashboard alerting.
+        webhook_url: URL to send alerts to (legacy, use api_key instead).
+        block_on_detection: Whether to return 403 on attack detection.
+        excluded_paths: List of paths to exclude from monitoring.
+        watch_paths: List of paths to monitor (None = all paths).
+        auto_detect_vulnerable: Auto-detect vulnerable endpoints to monitor.
+        project_path: Project path for auto-detection.
+        enabled_detectors: List of detector types to enable.
+        rate_limit_threshold: Requests per minute per IP before rate limiting.
+        **kwargs: Additional configuration options.
+
+    Returns:
+        SensorConfig instance.
+    """
+    # Determine alert mode
+    alert_mode = "dashboard"
+    if api_key or os.environ.get("SECURITY_USE_API_KEY"):
+        alert_mode = "dashboard"
+    elif webhook_url:
+        alert_mode = "webhook"
+
+    config_dict = {
+        "alert_mode": alert_mode,
+        "api_key": api_key,
+        "webhook_url": webhook_url,
+        "block_on_detection": block_on_detection,
+        "excluded_paths": excluded_paths or [],
+        "watch_paths": watch_paths,
+        "auto_detect_vulnerable": auto_detect_vulnerable,
+        "project_path": project_path,
+        "rate_limit_threshold": rate_limit_threshold,
+        **kwargs,
+    }
+
+    if enabled_detectors is not None:
+        config_dict["enabled_detectors"] = enabled_detectors
+
+    return SensorConfig.from_dict(config_dict)