aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/copier-aegis-project/{{ project_slug }}/app/services/backend/middleware_inspector.py.jinja

@@ -0,0 +1,223 @@
+"""
+FastAPI Middleware Introspection Service
+
+Utility functions for extracting comprehensive middleware information from FastAPI
+applications for security auditing and dashboard display.
+"""
+
+from typing import Any
+
+import fastapi
+
+__all__ = ["MiddlewareMetadata", "FastAPIMiddlewareInspector"]
+
+from app.core.log import logger
+from app.services.backend.models import MiddlewareInfo, MiddlewareMetadata
+
+
+class FastAPIMiddlewareInspector:
+    """Utility class for extracting middleware information from FastAPI apps."""
+
+    def __init__(self, app: fastapi.FastAPI) -> None:
+        """Initialize with FastAPI application instance."""
+        self.app = app
+
+    def get_middleware_metadata(self) -> MiddlewareMetadata:
+        """
+        Extract comprehensive middleware information from FastAPI app.
+
+        Returns:
+            MiddlewareMetadata containing middleware stack, security info, and stats
+        """
+        try:
+            middleware_stack = []
+
+            # Inspect middleware stack using FastAPI's user_middleware attribute
+            if hasattr(self.app, 'user_middleware'):
+                for idx, middleware_item in enumerate(self.app.user_middleware):
+                    middleware_info = (
+                        self._extract_middleware_info_from_middleware_item(
+                            middleware_item, idx
+                        )
+                    )
+                    if middleware_info:
+                        middleware_stack.append(middleware_info)
+
+            # Calculate statistics
+            total_middleware = len(middleware_stack)
+            security_middleware = self._identify_security_middleware(middleware_stack)
+            security_count = len(security_middleware)
+            
+            return MiddlewareMetadata(
+                middleware_stack=middleware_stack,
+                total_middleware=total_middleware,
+                security_middleware=security_middleware,
+                security_count=security_count,
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to extract middleware metadata: {e}")
+            return self._get_fallback_metadata(str(e))
+    
+    def _extract_middleware_info_from_middleware_item(
+        self, middleware_item: Any, order: int
+    ) -> MiddlewareInfo | None:
+        """Extract information from a FastAPI Middleware item."""
+        try:
+            # FastAPI stores middleware as Middleware(cls, **kwargs) objects
+            middleware_cls = middleware_item.cls
+            middleware_kwargs = (
+                middleware_item.kwargs 
+                if hasattr(middleware_item, 'kwargs') 
+                else {}
+            )
+            
+            middleware_type = middleware_cls.__name__
+            middleware_module = middleware_cls.__module__
+
+            # Use kwargs as configuration
+            config = dict(middleware_kwargs)
+
+            # Determine if this is security-related middleware
+            is_security = self._is_security_middleware(
+                middleware_type, middleware_module
+            )
+            
+            return MiddlewareInfo(
+                type=middleware_type,
+                module=middleware_module,
+                order=order,
+                config=config,
+                is_security=is_security,
+            )
+        except Exception as e:
+            logger.warning(
+                f"Failed to extract middleware info for {middleware_item}: {e}"
+            )
+            return None
+
+    def _extract_middleware_info(
+        self, middleware: Any, order: int
+    ) -> MiddlewareInfo | None:
+        """Extract information from a single middleware instance (legacy method).
+
+        This method is kept for backward compatibility and is still used in tests.
+        For production use, _extract_middleware_info_from_middleware_item is preferred.
+        """
+        try:
+            middleware_type = type(middleware).__name__
+            middleware_module = type(middleware).__module__
+
+            # Extract middleware-specific configuration
+            config = self._extract_middleware_config(middleware)
+
+            # Determine if this is security-related middleware
+            is_security = self._is_security_middleware(
+                middleware_type, middleware_module
+            )
+            
+            return MiddlewareInfo(
+                type=middleware_type,
+                module=middleware_module,
+                order=order,
+                config=config,
+                is_security=is_security,
+            )
+        except Exception as e:
+            logger.warning(
+                f"Failed to extract middleware info for {type(middleware)}: {e}"
+            )
+            return None
+
+    def _extract_middleware_config(self, middleware: Any) -> dict[str, Any]:
+        """Extract configuration from middleware where possible."""
+        config = {}
+
+        try:
+            # CORS Middleware configuration
+            if hasattr(middleware, 'allow_origins'):
+                config.update({
+                    "allow_origins": getattr(middleware, 'allow_origins', []),
+                    "allow_methods": getattr(middleware, 'allow_methods', []),
+                    "allow_headers": getattr(middleware, 'allow_headers', []),
+                    "allow_credentials": getattr(
+                        middleware, 'allow_credentials', False
+                    ),
+                })
+
+            # JWT/Auth middleware configuration
+            elif hasattr(middleware, 'algorithm'):
+                config.update({
+                    "algorithm": getattr(middleware, 'algorithm', 'Unknown'),
+                })
+
+            # Rate limiting middleware
+            elif hasattr(middleware, 'calls') and hasattr(middleware, 'period'):
+                config.update({
+                    "calls": getattr(middleware, 'calls', 0),
+                    "period": getattr(middleware, 'period', 0),
+                })
+
+            # Security headers middleware
+            elif hasattr(middleware, 'csp'):
+                config.update({
+                    "csp": getattr(middleware, 'csp', {}),
+                })
+            
+        except Exception as e:
+            logger.debug(f"Could not extract config from {type(middleware)}: {e}")
+
+        return config
+
+    def _is_security_middleware(
+        self, middleware_type: str, middleware_module: str
+    ) -> bool:
+        """Determine if middleware is security-related based on type and module."""
+        security_keywords = [
+            'cors', 'auth', 'jwt', 'rate', 'security', 'limit', 'csrf', 'xss'
+        ]
+        security_modules = ['starlette.middleware.cors', 'fastapi.middleware.cors']
+        
+        # Check type name for security keywords
+        type_lower = middleware_type.lower()
+        if any(keyword in type_lower for keyword in security_keywords):
+            return True
+        
+        # Check module name for security patterns
+        module_lower = middleware_module.lower()
+        if any(keyword in module_lower for keyword in security_keywords):
+            return True
+        
+        # Check for known security middleware modules
+        if middleware_module in security_modules:
+            return True
+
+        return False
+
+    def _identify_security_middleware(self, stack: list[MiddlewareInfo]) -> list[str]:
+        """Identify security-related middleware types."""
+        return [mw.type for mw in stack if mw.is_security]
+    
+    def _get_fallback_metadata(self, error: str) -> MiddlewareMetadata:
+        """Return fallback metadata when introspection fails."""
+        return MiddlewareMetadata(
+            middleware_stack=[],
+            total_middleware=0,
+            security_middleware=[],
+            security_count=0,
+            error=error,
+            fallback=True,
+        )
+
+
+def get_fastapi_middleware_metadata(app: fastapi.FastAPI) -> MiddlewareMetadata:
+    """
+    Convenience function to get middleware metadata from FastAPI app.
+
+    Args:
+        app: FastAPI application instance
+    Returns:
+        MiddlewareMetadata containing middleware stack and security information
+    """
+    inspector = FastAPIMiddlewareInspector(app)
+    return inspector.get_middleware_metadata()

aegis/templates/copier-aegis-project/{{ project_slug }}/app/services/backend/models.py.jinja

@@ -0,0 +1,70 @@
+"""
+Backend service models using Pydantic for type safety and validation.
+
+These models define the structure for route introspection data and middleware
+detection data for backend service metadata.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class RouteInfo(BaseModel):
+    """Information about a single FastAPI route."""
+    
+    path: str
+    methods: list[str]
+    name: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    tags: list[str] = []
+    deprecated: bool = False
+    path_params: list[str] = []
+    dependencies: int = 0
+    response_model: str | None = None
+
+
+class RouteMetadata(BaseModel):
+    """Comprehensive route metadata for FastAPI application."""
+    
+    routes: list[RouteInfo]
+    total_routes: int
+    total_endpoints: int
+    method_counts: dict[str, int] = {}
+    route_groups: dict[str, int] = {}
+    tag_groups: dict[str, int] = {}
+    has_docs: bool = False
+    has_health: bool = False
+    deprecated_count: int = 0
+    error: str | None = None
+    fallback: bool = False
+    
+    def model_dump_for_metadata(self) -> dict[str, Any]:
+        """Convert to dict format suitable for ComponentStatus metadata."""
+        return self.model_dump(mode='json')
+
+
+class MiddlewareInfo(BaseModel):
+    """Information about a single middleware in the stack."""
+    
+    type: str
+    module: str
+    order: int
+    config: dict[str, Any] = {}
+    is_security: bool = False
+
+
+class MiddlewareMetadata(BaseModel):
+    """Comprehensive middleware metadata for FastAPI application."""
+    
+    middleware_stack: list[MiddlewareInfo]
+    total_middleware: int
+    security_middleware: list[str] = []
+    security_count: int = 0
+    error: str | None = None
+    fallback: bool = False
+    
+    def model_dump_for_metadata(self) -> dict[str, Any]:
+        """Convert to dict format suitable for ComponentStatus metadata."""
+        return self.model_dump(mode='json')

aegis/templates/copier-aegis-project/{{ project_slug }}/app/services/backend/route_inspector.py.jinja

@@ -0,0 +1,155 @@
+"""
+FastAPI Route Introspection Service
+
+Utility functions for extracting comprehensive route information from FastAPI
+applications for health monitoring and dashboard display.
+"""
+
+import fastapi
+from fastapi.routing import APIRoute
+
+__all__ = ["RouteMetadata", "FastAPIRouteInspector"]
+
+from app.core.log import logger
+from app.services.backend.models import RouteInfo, RouteMetadata
+
+
+class FastAPIRouteInspector:
+    """Utility class for extracting route information from FastAPI apps."""
+    
+    def __init__(self, app: fastapi.FastAPI) -> None:
+        """Initialize with FastAPI application instance."""
+        self.app = app
+    
+    def get_routes_metadata(self) -> RouteMetadata:
+        """
+        Extract comprehensive route information from FastAPI app.
+
+        Returns:
+            RouteMetadata containing route data, statistics, and groupings
+        """
+        try:
+            routes_data = []
+            
+            # Extract route information
+            for route in self.app.routes:
+                if isinstance(route, APIRoute):
+                    route_info = RouteInfo(
+                        path=route.path,
+                        methods=sorted(list(route.methods)),
+                        name=route.name,
+                        summary=getattr(route, "summary", "") or None,
+                        description=getattr(route, "description", "") or None,
+                        tags=getattr(route, "tags", []) or [],
+                        deprecated=bool(getattr(route, "deprecated", False)),
+                        path_params=self._extract_path_params(route.path),
+                        dependencies=(
+                            len(route.dependencies) if route.dependencies else 0
+                        ),
+                        response_model=(
+                            str(route.response_model) if route.response_model else None
+                        ),
+                    )
+                    routes_data.append(route_info)
+            
+            # Calculate statistics
+            total_routes = len(routes_data)
+            total_endpoints = sum(len(r.methods) for r in routes_data)
+            method_counts = self._count_methods(routes_data)
+            route_groups = self._group_routes_by_prefix(routes_data)
+            tag_groups = self._group_routes_by_tags(routes_data)
+            
+            return RouteMetadata(
+                routes=routes_data,
+                total_routes=total_routes,
+                total_endpoints=total_endpoints,
+                method_counts=method_counts,
+                route_groups=route_groups,
+                tag_groups=tag_groups,
+                has_docs=any(
+                    "/docs" in r.path or "/redoc" in r.path for r in routes_data
+                ),
+                has_health=any("/health" in r.path for r in routes_data),
+                deprecated_count=sum(1 for r in routes_data if r.deprecated),
+            )
+            
+        except Exception as e:
+            logger.error(f"Failed to extract route metadata: {e}")
+            return self._get_fallback_metadata(str(e))
+    
+    def _extract_path_params(self, path: str) -> list[str]:
+        """Extract path parameters from route path."""
+        import re
+        return re.findall(r'\{([^}]+)\}', path)
+    
+    def _count_methods(self, routes: list[RouteInfo]) -> dict[str, int]:
+        """Count routes by HTTP method."""
+        method_counts: dict[str, int] = {}
+        for route in routes:
+            for method in route.methods:
+                if method != "HEAD":  # Skip HEAD methods as they're automatic
+                    method_counts[method] = method_counts.get(method, 0) + 1
+        return method_counts
+    
+    def _group_routes_by_prefix(self, routes: list[RouteInfo]) -> dict[str, int]:
+        """Group routes by path prefix for organization."""
+        groups: dict[str, int] = {}
+        for route in routes:
+            path_parts = route.path.strip("/").split("/")
+            prefix = path_parts[0] if path_parts[0] else "root"
+            
+            # Special handling for common patterns
+            if prefix in ["health", "docs", "redoc", "openapi.json"]:
+                groups[prefix] = groups.get(prefix, 0) + 1
+            elif prefix == "api" and len(path_parts) > 2:
+                # Skip API version prefix, group by actual resource
+                # /api/v1/users -> group as "users"
+                resource = path_parts[2]
+                groups[resource] = groups.get(resource, 0) + 1
+            elif prefix.startswith("api"):
+                # Fallback for other API patterns
+                groups[prefix] = groups.get(prefix, 0) + 1
+            else:
+                groups[prefix] = groups.get(prefix, 0) + 1
+        
+        return groups
+    
+    def _group_routes_by_tags(self, routes: list[RouteInfo]) -> dict[str, int]:
+        """Group routes by OpenAPI tags."""
+        tag_counts: dict[str, int] = {}
+        for route in routes:
+            if not route.tags:
+                tag_counts["untagged"] = tag_counts.get("untagged", 0) + 1
+            else:
+                for tag in route.tags:
+                    tag_counts[tag] = tag_counts.get(tag, 0) + 1
+        return tag_counts
+    
+    def _get_fallback_metadata(self, error: str) -> RouteMetadata:
+        """Return fallback metadata when introspection fails."""
+        return RouteMetadata(
+            routes=[],
+            total_routes=0,
+            total_endpoints=0,
+            method_counts={},
+            route_groups={},
+            tag_groups={},
+            has_docs=False,
+            has_health=False,
+            deprecated_count=0,
+            error=error,
+            fallback=True,
+        )
+
+
+def get_fastapi_route_metadata(app: fastapi.FastAPI) -> RouteMetadata:
+    """
+    Convenience function to get route metadata from FastAPI app.
+
+    Args:
+        app: FastAPI application instance
+    Returns:
+        RouteMetadata containing route metadata and statistics
+    """
+    inspector = FastAPIRouteInspector(app)
+    return inspector.get_routes_metadata()