apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/frameworks/java/spring_plugin.py

@@ -0,0 +1,1293 @@
+"""
+Spring Boot framework plugin.
+
+Extracts HTTP routes, auth schemes, dependencies, and middleware from
+Spring Boot applications using annotation-based detection.
+
+Supports:
+- @RestController / @Controller with @RequestMapping
+- @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping
+- Multi-value path arrays: @GetMapping({"/v1/users", "/v2/users"})
+- @RequestMapping at method level with or without method=
+- @PathVariable, @RequestParam, @RequestBody, @RequestHeader, @CookieValue,
+  @RequestPart, @MatrixVariable
+- produces= / consumes= content-type negotiation on mapping annotations
+- @ResponseStatus for custom response codes
+- Bean Validation: @NotNull, @Size, @Min, @Max, @Pattern, @Email, @Valid
+- Spring Security: @PreAuthorize, @Secured, @RolesAllowed
+- @EnableWebSecurity / @EnableMethodSecurity / JWT / OAuth2 bean detection
+- SecurityFilterChain bean (structural detection)
+- @Component, @Service, @Repository, @Bean dependency detection
+- Filter / HandlerInterceptor middleware detection
+- @CrossOrigin CORS policy detection (class and method level)
+- @ControllerAdvice global exception handler detection
+- @FeignClient declarative HTTP client (outbound call surface, kind="feign")
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from ...core.types import (
+    AuthDependencyType,
+    AuthSchemeType,
+    CodeLocation,
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+)
+from ...parsing.base import ParsedClass, ParsedDecorator, ParsedFile, ParsedFunction
+from ...parsing.services import AnalysisContext
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedBody,
+    ExtractedDependency,
+    ExtractedJwtConfig,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+    extract_path_template_names,
+    infer_middleware_operations,
+    is_auth_related_name,
+)
+from . import _annotations
+from ._constraints import extract_constraints as _extract_bean_constraints
+from ._constraints import is_complex_type as _is_complex_java_type
+from .jwt_config_extractor import JavaJwtConfigExtractor
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+# Spring annotation → HTTP method (for convenience aliases)
+_MAPPING_TO_METHOD: dict[str, HttpMethod] = {
+    "GetMapping": HttpMethod.GET,
+    "PostMapping": HttpMethod.POST,
+    "PutMapping": HttpMethod.PUT,
+    "DeleteMapping": HttpMethod.DELETE,
+    "PatchMapping": HttpMethod.PATCH,
+    "HeadMapping": HttpMethod.HEAD,
+    "OptionsMapping": HttpMethod.OPTIONS,
+}
+
+# RequestMethod enum values
+_REQUEST_METHOD_MAP: dict[str, HttpMethod] = {
+    "GET": HttpMethod.GET,
+    "POST": HttpMethod.POST,
+    "PUT": HttpMethod.PUT,
+    "DELETE": HttpMethod.DELETE,
+    "PATCH": HttpMethod.PATCH,
+    "HEAD": HttpMethod.HEAD,
+    "OPTIONS": HttpMethod.OPTIONS,
+    "TRACE": HttpMethod.TRACE,
+}
+
+_CONTROLLER_ANNOTATIONS: frozenset[str] = frozenset(
+    {
+        "RestController",
+        "Controller",
+    }
+)
+
+_SECURITY_ANNOTATIONS: frozenset[str] = frozenset(
+    {
+        "PreAuthorize",
+        "Secured",
+        "RolesAllowed",
+        "PermitAll",
+        "DenyAll",
+        "RequiresAuthentication",
+    }
+)
+
+_BEAN_ANNOTATIONS: frozenset[str] = frozenset(
+    {
+        "Component",
+        "Service",
+        "Repository",
+        "Bean",
+        "Configuration",
+    }
+)
+
+# Auth-related-name heuristic now lives in ``frameworks.base.AUTH_NAME_KEYWORDS``
+# (imported as ``is_auth_related_name``).
+
+_SPRING_IMPORTS: frozenset[str] = frozenset(
+    {
+        "org.springframework.web.bind.annotation",
+        "org.springframework.boot",
+        "org.springframework.stereotype",
+        "org.springframework.security",
+        "org.springframework.context.annotation",
+        "org.springframework.web.filter",
+    }
+)
+
+# HttpStatus enum name → numeric code (covers the common Spring subset)
+_HTTP_STATUS_MAP: dict[str, int] = {
+    "CONTINUE": 100,
+    "SWITCHING_PROTOCOLS": 101,
+    "OK": 200,
+    "CREATED": 201,
+    "ACCEPTED": 202,
+    "NON_AUTHORITATIVE_INFORMATION": 203,
+    "NO_CONTENT": 204,
+    "RESET_CONTENT": 205,
+    "PARTIAL_CONTENT": 206,
+    "MULTIPLE_CHOICES": 300,
+    "MOVED_PERMANENTLY": 301,
+    "FOUND": 302,
+    "SEE_OTHER": 303,
+    "NOT_MODIFIED": 304,
+    "TEMPORARY_REDIRECT": 307,
+    "PERMANENT_REDIRECT": 308,
+    "BAD_REQUEST": 400,
+    "UNAUTHORIZED": 401,
+    "PAYMENT_REQUIRED": 402,
+    "FORBIDDEN": 403,
+    "NOT_FOUND": 404,
+    "METHOD_NOT_ALLOWED": 405,
+    "NOT_ACCEPTABLE": 406,
+    "REQUEST_TIMEOUT": 408,
+    "CONFLICT": 409,
+    "GONE": 410,
+    "LENGTH_REQUIRED": 411,
+    "PRECONDITION_FAILED": 412,
+    "PAYLOAD_TOO_LARGE": 413,
+    "URI_TOO_LONG": 414,
+    "UNSUPPORTED_MEDIA_TYPE": 415,
+    "UNPROCESSABLE_ENTITY": 422,
+    "LOCKED": 423,
+    "TOO_MANY_REQUESTS": 429,
+    "INTERNAL_SERVER_ERROR": 500,
+    "NOT_IMPLEMENTED": 501,
+    "BAD_GATEWAY": 502,
+    "SERVICE_UNAVAILABLE": 503,
+    "GATEWAY_TIMEOUT": 504,
+}
+
+# Bean Validation (JSR-303/380) annotation names
+_CONSTRAINT_ANNOTATIONS: frozenset[str] = frozenset(
+    {
+        "NotNull",
+        "NonNull",
+        "NotEmpty",
+        "NotBlank",
+        "Null",
+        "Size",
+        "Length",
+        "Min",
+        "Max",
+        "DecimalMin",
+        "DecimalMax",
+        "Digits",
+        "Pattern",
+        "Email",
+        "URL",
+        "Positive",
+        "PositiveOrZero",
+        "Negative",
+        "NegativeOrZero",
+        "AssertTrue",
+        "AssertFalse",
+        "Past",
+        "PastOrPresent",
+        "Future",
+        "FutureOrPresent",
+        "Valid",  # cascade validation
+    }
+)
+
+
+@dataclass
+class FilterChainPolicy:
+    """Global Spring Security filter-chain auth policy extracted from a SecurityFilterChain bean.
+
+    any_request_auth=True means .anyRequest().authenticated() (or equivalent) is present,
+    so every route NOT matching a permit_all_patterns entry requires authentication.
+    """
+
+    any_request_auth: bool = False
+    permit_all_patterns: list[str] = field(default_factory=list)
+
+    def requires_auth(self, route_path: str) -> bool:
+        """Return True if this policy requires auth for route_path."""
+        if not self.any_request_auth:
+            return False
+        # Strip GraphQL operation suffix for matching: /graphql:Query.x → /graphql
+        normalized = route_path.split(":")[0] if ":" in route_path else route_path
+        for pattern in self.permit_all_patterns:
+            if "**" in pattern:
+                prefix = pattern.split("**")[0].rstrip("/")
+                if normalized == prefix or normalized.startswith(prefix + "/"):
+                    return False
+            elif fnmatch.fnmatch(normalized, pattern):
+                return False
+        return True
+
+
+# =============================================================================
+# SpringBootPlugin
+# =============================================================================
+
+
+class SpringBootPlugin(BaseFrameworkPlugin):
+    """
+    Framework plugin for Spring Boot applications.
+
+    Extracts routes, auth schemes, dependencies, and middleware
+    from Spring Boot annotation patterns.
+    """
+
+    FRAMEWORK: ClassVar[Framework] = Framework.SPRING_BOOT
+    LANGUAGE: ClassVar[Language] = Language.JAVA
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = _SPRING_IMPORTS
+    DETECTION_IMPORT_PREFIXES: ClassVar[tuple[str, ...]] = ("org.springframework",)
+
+    # `detect()` inherited from BaseFrameworkPlugin — prefix match on
+    # ``org.springframework`` plus exact match against `_SPRING_IMPORTS`.
+
+    # -------------------------------------------------------------------------
+    # Route extraction
+    # -------------------------------------------------------------------------
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        routes: list[ExtractedRoute] = []
+
+        # Build a simple name → prefix map for base-class @RequestMapping inheritance.
+        # Only covers same-file parent classes (cross-file inheritance requires type
+        # resolution and is handled separately when a full context is available).
+        prefix_by_class: dict[str, str] = {}
+        for cls in parsed_file.classes:
+            p = self._get_class_prefix(cls)
+            if p:
+                prefix_by_class[cls.name] = p
+
+        for cls in parsed_file.classes:
+            if not self._is_controller(cls):
+                continue
+
+            class_prefix = self._get_class_prefix(cls)
+            # Inherit @RequestMapping prefix from a same-file parent class when the
+            # subclass doesn't declare its own.
+            if not class_prefix:
+                for base in cls.base_classes:
+                    simple = base.rsplit(".", 1)[-1]
+                    if simple in prefix_by_class:
+                        class_prefix = prefix_by_class[simple]
+                        break
+            # Collect @PathVariable params from @ModelAttribute methods.  These
+            # run before every handler and implicitly bind path variables that
+            # don't appear in the handler's own parameter list.
+            model_attr_params = self._collect_model_attr_path_params(cls)
+
+            for method in cls.methods:
+                results = self._extract_routes_from_method(
+                    method, class_prefix, cls, parsed_file, context, model_attr_params
+                )
+                routes.extend(results)
+
+        # --- @FeignClient interfaces (outbound HTTP call surface) ---
+        for cls in parsed_file.classes:
+            if not any(dec.name == "FeignClient" for dec in cls.decorators):
+                continue
+
+            feign_prefix = self._get_feign_prefix(cls)
+
+            for method in cls.methods:
+                feign_routes = self._extract_routes_from_method(
+                    method, feign_prefix, cls, parsed_file, context
+                )
+                for route in feign_routes:
+                    # Re-emit with kind="feign" and lower confidence
+                    routes.append(
+                        ExtractedRoute(
+                            method=route.method,
+                            path=route.path,
+                            handler_function=route.handler_function,
+                            handler_location=route.handler_location,
+                            path_params=route.path_params,
+                            query_params=route.query_params,
+                            header_params=route.header_params,
+                            cookie_params=route.cookie_params,
+                            body=route.body,
+                            response=route.response,
+                            tags=route.tags,
+                            dependency_refs=route.dependency_refs,
+                            confidence=Confidence.MEDIUM,
+                            kind="feign",
+                        )
+                    )
+
+        return routes
+
+    def _is_controller(self, cls: ParsedClass) -> bool:
+        """Check if class is annotated as a Spring controller."""
+        return any(dec.name in _CONTROLLER_ANNOTATIONS for dec in cls.decorators)
+
+    def _get_class_prefix(self, cls: ParsedClass) -> str:
+        """Get class-level @RequestMapping path prefix."""
+        for dec in cls.decorators:
+            if dec.name == "RequestMapping":
+                path = self._annotation_path(dec)
+                if path:
+                    return path.rstrip("/")
+        return ""
+
+    def _get_feign_prefix(self, cls: ParsedClass) -> str:
+        """Get URL prefix from @FeignClient(path=) or @RequestMapping on the interface."""
+        for dec in cls.decorators:
+            if dec.name == "FeignClient":
+                path = self._annotation_str(dec, "path") or self._annotation_str(dec, "url") or ""
+                if path and path.startswith("/"):
+                    return path.rstrip("/")
+            if dec.name == "RequestMapping":
+                p = self._annotation_path(dec)
+                if p:
+                    return p.rstrip("/")
+        return ""
+
+    def _collect_model_attr_path_params(self, cls: ParsedClass) -> list[tuple[str, str | None]]:
+        """Return (name, type) for every @PathVariable on a @ModelAttribute method.
+
+        Spring calls @ModelAttribute methods before every handler in the same
+        controller.  Any @PathVariable they declare is therefore implicitly
+        bound on every route, even if the handler method itself does not list
+        that parameter.  We collect them here so they can be merged into the
+        per-route path_params list.
+        """
+        params: list[tuple[str, str | None]] = []
+        seen: set[str] = set()
+        for method in cls.methods:
+            if not any(dec.name == "ModelAttribute" for dec in method.decorators):
+                continue
+            for param in method.parameters:
+                metadata = param.metadata or {}
+                if "PathVariable" not in metadata:
+                    continue
+                alias = metadata["PathVariable"]
+                name, _required, _default = self._unpack_annotation_alias(alias, param.name)
+                if name and name not in seen:
+                    seen.add(name)
+                    params.append((name, param.type_annotation))
+        return params
+
+    @staticmethod
+    def _unpack_annotation_alias(val: Any, param_name: str) -> tuple[str, bool, Any]:
+        return _annotations.unpack_annotation_alias(val, param_name)
+
+    def _extract_routes_from_method(
+        self,
+        method: ParsedFunction,
+        class_prefix: str,
+        cls: ParsedClass,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None,
+        model_attr_params: list[tuple[str, str | None]] | None = None,
+    ) -> list[ExtractedRoute]:
+        """Extract all routes from a single handler method.
+
+        Returns a list because:
+        - @GetMapping({"/v1/users", "/v2/users"}) → 2 routes
+        - @RequestMapping (no method=) → one route per HTTP verb
+        - normally returns a single-element list
+        """
+        routes: list[ExtractedRoute] = []
+
+        # Collect cross-cutting annotations once (shared across all paths)
+        response_status = self._method_response_status(method)
+        auth_refs = self._method_auth_refs(cls, method)
+
+        for dec in method.decorators:
+            http_method = _MAPPING_TO_METHOD.get(dec.name)
+
+            if dec.name == "RequestMapping":
+                explicit_methods = self._get_request_methods(dec)
+                # Spring's actual default when no method= is ALL methods.
+                # Surface all common verbs so no attack surface is hidden.
+                http_methods_to_emit = (
+                    explicit_methods
+                    if explicit_methods
+                    else [
+                        HttpMethod.GET,
+                        HttpMethod.POST,
+                        HttpMethod.PUT,
+                        HttpMethod.DELETE,
+                        HttpMethod.PATCH,
+                    ]
+                )
+            elif http_method is not None:
+                http_methods_to_emit = [http_method]
+            else:
+                continue
+
+            local_paths = self._annotation_paths(dec)
+            if not local_paths:
+                local_paths = [""]
+
+            # Content-type negotiation from annotation
+            consumes = self._annotation_str(dec, "consumes")
+            produces = self._annotation_str(dec, "produces")
+
+            for local_path in local_paths:
+                full_path = self._join_paths(class_prefix, local_path)
+
+                path_params, query_params, header_params, cookie_params, body = (
+                    self._extract_method_params(method, full_path, context, parsed_file)
+                )
+
+                # Merge implicit @PathVariables from @ModelAttribute methods.
+                # Only add a param if (a) the name appears in the path template
+                # and (b) it wasn't already captured from the handler itself.
+                if model_attr_params:
+                    existing_path_names = {p.name for p in path_params}
+                    path_tpl_names = extract_path_template_names(full_path)
+                    for ma_name, ma_type in model_attr_params:
+                        if ma_name not in existing_path_names and ma_name in path_tpl_names:
+                            path_params.append(
+                                ExtractedParameter(
+                                    name=ma_name,
+                                    location=ParameterLocation.PATH,
+                                    type_annotation=ma_type,
+                                    required=True,
+                                )
+                            )
+
+                # Apply consumes= override to body content type
+                if consumes:
+                    if body is not None:
+                        body = ExtractedBody(
+                            content_type=consumes,
+                            model_name=body.model_name,
+                            model_fields=body.model_fields,
+                            required=body.required,
+                        )
+                    else:
+                        body = ExtractedBody(content_type=consumes)
+
+                response = ExtractedResponse(
+                    model_name=method.return_type,
+                    status_code=response_status,
+                    content_type=produces if produces else None,
+                )
+
+                for hm in http_methods_to_emit:
+                    routes.append(
+                        ExtractedRoute(
+                            method=hm,
+                            path=full_path,
+                            handler_function=method.qualified_name,
+                            handler_location=method.location,
+                            path_params=list(path_params),
+                            query_params=list(query_params),
+                            header_params=list(header_params),
+                            cookie_params=list(cookie_params),
+                            body=body,
+                            response=response,
+                            tags=[cls.name],
+                            dependency_refs=list(auth_refs),
+                            confidence=Confidence.HIGH,
+                            kind="http",
+                        )
+                    )
+
+        return routes
+
+    def _method_response_status(self, method: ParsedFunction) -> int:
+        """Extract HTTP response status from @ResponseStatus on a method."""
+        for ann in method.decorators:
+            if ann.name == "ResponseStatus":
+                return self._extract_status_code(ann)
+        return 200
+
+    def _method_auth_refs(self, cls: ParsedClass, method: ParsedFunction) -> list[str]:
+        """Collect auth dependency refs from security annotations on a method.
+
+        Falls back to class-level security annotations when the method itself
+        carries none — Spring's @PreAuthorize / @Secured at the class level
+        applies to every handler in the controller.  A method-level @PermitAll
+        opens the method back up and clears the inherited guard.
+        """
+        method_ann_names = {ann.name for ann in method.decorators}
+        # @PermitAll on a method explicitly disables class-level guards.
+        if "PermitAll" in method_ann_names:
+            return []
+        for ann in method.decorators:
+            if ann.name in _SECURITY_ANNOTATIONS:
+                return [f"{cls.name}.{method.name}"]
+        # No method-level guard — fall back to the class.
+        for dec in cls.decorators:
+            if dec.name in _SECURITY_ANNOTATIONS:
+                return [cls.name]
+        return []
+
+    # -------------------------------------------------------------------------
+    # Parameter extraction
+    # -------------------------------------------------------------------------
+
+    def _extract_method_params(
+        self,
+        method: ParsedFunction,
+        path: str,
+        context: AnalysisContext | None,
+        parsed_file: ParsedFile,
+    ) -> tuple[
+        list[ExtractedParameter],  # path_params
+        list[ExtractedParameter],  # query_params
+        list[ExtractedParameter],  # header_params
+        list[ExtractedParameter],  # cookie_params
+        ExtractedBody | None,
+    ]:
+        path_params: list[ExtractedParameter] = []
+        query_params: list[ExtractedParameter] = []
+        header_params: list[ExtractedParameter] = []
+        cookie_params: list[ExtractedParameter] = []
+        body: ExtractedBody | None = None
+
+        # Extract {param} names from the path template
+        path_template_names = extract_path_template_names(path)
+
+        for param in method.parameters:
+            metadata = param.metadata or {}
+            constraints = self._extract_constraints(metadata)
+
+            # @PathVariable
+            if "PathVariable" in metadata:
+                alias = metadata["PathVariable"]
+                name, _required, _default = self._unpack_annotation_alias(alias, param.name)
+                path_params.append(
+                    ExtractedParameter(
+                        name=name,
+                        location=ParameterLocation.PATH,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        constraints=constraints,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # @RequestParam
+            if "RequestParam" in metadata:
+                val = metadata["RequestParam"]
+                name, required, _default = self._unpack_annotation_alias(val, param.name)
+                # @NotNull / @NonNull implies required
+                if constraints.get("not_null"):
+                    required = True
+                query_params.append(
+                    ExtractedParameter(
+                        name=name,
+                        location=ParameterLocation.QUERY,
+                        type_annotation=param.type_annotation,
+                        required=required,
+                        constraints=constraints,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # @RequestHeader
+            if "RequestHeader" in metadata:
+                val = metadata["RequestHeader"]
+                name, _required, _default = self._unpack_annotation_alias(val, param.name)
+                header_params.append(
+                    ExtractedParameter(
+                        name=name,
+                        location=ParameterLocation.HEADER,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        constraints=constraints,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # @RequestBody
+            if "RequestBody" in metadata:
+                model_name = param.type_annotation
+                model_fields: list[str] = []
+                _has_valid = "Valid" in metadata  # noqa: F841 — reserved for future manifest field
+
+                if context and context.type_resolver and model_name:
+                    resolved_fields = context.type_resolver.get_model_fields(
+                        model_name, parsed_file.path
+                    )
+                    model_fields = [f.name for f in resolved_fields]
+
+                body = ExtractedBody(
+                    content_type="application/json",
+                    model_name=model_name,
+                    model_fields=model_fields,
+                    required=True,
+                )
+                # @Valid marks the body for bean-validation; no dedicated manifest
+                # field yet — noted here for future extension.
+                continue
+
+            # @CookieValue
+            if "CookieValue" in metadata:
+                val = metadata["CookieValue"]
+                name, _required, _default = self._unpack_annotation_alias(val, param.name)
+                cookie_params.append(
+                    ExtractedParameter(
+                        name=name,
+                        location=ParameterLocation.COOKIE,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        constraints=constraints,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # @RequestPart (multipart form file/field)
+            if "RequestPart" in metadata:
+                val = metadata["RequestPart"]
+                name, _required, _default = self._unpack_annotation_alias(val, param.name)
+                # Represent multipart parts as query params with FORM location;
+                # treat as body if it's the only complex param.
+                if body is None:
+                    body = ExtractedBody(
+                        content_type="multipart/form-data",
+                        model_name=param.type_annotation,
+                        required=True,
+                    )
+                else:
+                    query_params.append(
+                        ExtractedParameter(
+                            name=name,
+                            location=ParameterLocation.QUERY,
+                            type_annotation=param.type_annotation,
+                            required=True,
+                            constraints=constraints,
+                            code_location=param.location,
+                        )
+                    )
+                continue
+
+            # @MatrixVariable
+            if "MatrixVariable" in metadata:
+                val = metadata["MatrixVariable"]
+                name, _required, _default = self._unpack_annotation_alias(val, param.name)
+                path_params.append(
+                    ExtractedParameter(
+                        name=name,
+                        location=ParameterLocation.PATH,
+                        type_annotation=param.type_annotation,
+                        required=False,
+                        alias=f";{name}",
+                        constraints=constraints,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # No annotation — infer from path template
+            if param.name in path_template_names:
+                path_params.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=ParameterLocation.PATH,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        constraints=constraints,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # Default: skip framework-injected types (HttpServletRequest, etc.)
+            skip_types = {
+                "HttpServletRequest",
+                "HttpServletResponse",
+                "HttpSession",
+                "Principal",
+                "Authentication",
+                "Model",
+                "ModelAndView",
+                "BindingResult",
+                "Errors",
+            }
+            if param.type_annotation in skip_types:
+                continue
+
+            # Treat remaining scalar params as query params (Spring default)
+            if param.type_annotation and not self._is_complex_type(param.type_annotation):
+                query_params.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=ParameterLocation.QUERY,
+                        type_annotation=param.type_annotation,
+                        required=False,
+                        constraints=constraints,
+                        code_location=param.location,
+                    )
+                )
+
+        return path_params, query_params, header_params, cookie_params, body
+
+    def _extract_constraints(self, metadata: dict[str, Any]) -> dict[str, Any]:
+        return _extract_bean_constraints(metadata)
+
+    def _is_complex_type(self, type_name: str) -> bool:
+        return _is_complex_java_type(type_name)
+
+    # -------------------------------------------------------------------------
+    # Dependency extraction
+    # -------------------------------------------------------------------------
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        """Extract Spring-managed bean definitions."""
+        deps: list[ExtractedDependency] = []
+
+        for cls in parsed_file.classes:
+            ann_names = {d.name for d in cls.decorators}
+
+            if not ann_names & _BEAN_ANNOTATIONS:
+                continue
+
+            # Detect auth-related beans
+            is_auth = is_auth_related_name(cls.name)
+
+            deps.append(
+                ExtractedDependency(
+                    name=cls.name,
+                    qualified_name=cls.qualified_name,
+                    location=cls.location,
+                    dependency_type="class",
+                    provides_type=cls.name,
+                    is_auth_related=is_auth,
+                    confidence=Confidence.HIGH,
+                )
+            )
+
+            # Also extract @Bean methods
+            for method in cls.methods:
+                if any(d.name == "Bean" for d in method.decorators):
+                    method_is_auth = is_auth_related_name(method.name)
+                    deps.append(
+                        ExtractedDependency(
+                            name=method.name,
+                            qualified_name=method.qualified_name,
+                            location=method.location,
+                            dependency_type="function",
+                            provides_type=method.return_type,
+                            is_auth_related=method_is_auth,
+                            confidence=Confidence.HIGH,
+                        )
+                    )
+
+        # --- @FeignClient interfaces ---
+        for cls in parsed_file.classes:
+            if not any(d.name == "FeignClient" for d in cls.decorators):
+                continue
+            deps.append(
+                ExtractedDependency(
+                    name=cls.name,
+                    qualified_name=cls.qualified_name,
+                    location=cls.location,
+                    dependency_type="feign_client",
+                    provides_type=cls.name,
+                    is_auth_related=False,
+                    confidence=Confidence.HIGH,
+                )
+            )
+
+        return deps
+
+    # -------------------------------------------------------------------------
+    # Auth scheme extraction
+    # -------------------------------------------------------------------------
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        """Detect Spring Security configuration and JWT setup."""
+        schemes: list[ExtractedAuthScheme] = []
+
+        for cls in parsed_file.classes:
+            ann_names = {d.name for d in cls.decorators}
+
+            # @EnableWebSecurity or class name contains "SecurityConfig"
+            if (
+                "EnableWebSecurity" in ann_names
+                or "EnableMethodSecurity" in ann_names
+                or "EnableGlobalMethodSecurity" in ann_names
+                or "SecurityConfig" in cls.name
+                or "WebSecurityConfig" in cls.name
+                or "SecurityConfiguration" in cls.name
+            ):
+                schemes.append(
+                    ExtractedAuthScheme(
+                        scheme_type=AuthSchemeType.SPRING_SECURITY,
+                        name=cls.name,
+                        location=cls.location,
+                        config={"class": cls.name},
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+            # @Bean SecurityFilterChain — detects security config in any @Configuration class
+            for method in cls.methods:
+                if any(d.name == "Bean" for d in method.decorators):
+                    if "SecurityFilterChain" in (method.return_type or ""):
+                        schemes.append(
+                            ExtractedAuthScheme(
+                                scheme_type=AuthSchemeType.SPRING_SECURITY,
+                                name=method.name,
+                                location=method.location,
+                                config={"bean": method.name, "return_type": method.return_type},
+                                confidence=Confidence.HIGH,
+                            )
+                        )
+
+            # Scan for JWT-related method names / return types
+            for method in cls.methods:
+                if any(d.name == "Bean" for d in method.decorators):
+                    name_lower = method.name.lower()
+                    ret = (method.return_type or "").lower()
+
+                    if "jwt" in name_lower or "jwt" in ret:
+                        schemes.append(
+                            ExtractedAuthScheme(
+                                scheme_type=AuthSchemeType.JWT_BEARER,
+                                name=method.name,
+                                location=method.location,
+                                config={"bean": method.name, "return_type": method.return_type},
+                                confidence=Confidence.MEDIUM,
+                            )
+                        )
+                    elif "oauth" in name_lower or "oauth" in ret:
+                        schemes.append(
+                            ExtractedAuthScheme(
+                                scheme_type=AuthSchemeType.OAUTH2_AUTHORIZATION_CODE,
+                                name=method.name,
+                                location=method.location,
+                                config={"bean": method.name},
+                                confidence=Confidence.MEDIUM,
+                            )
+                        )
+
+        # Scan for bearer token / API key patterns in imports
+        import_names = {n for imp in parsed_file.imports for n in imp.names}
+        if any("JwtDecoder" in n or "JwtEncoder" in n for n in import_names):
+            if not any(s.scheme_type == AuthSchemeType.JWT_BEARER for s in schemes):
+                schemes.append(
+                    ExtractedAuthScheme(
+                        scheme_type=AuthSchemeType.JWT_BEARER,
+                        name="jwt_from_imports",
+                        location=CodeLocation(file=parsed_file.path, line=0),
+                        config={"detected_via": "import"},
+                        confidence=Confidence.MEDIUM,
+                    )
+                )
+
+        return schemes
+
+    # -------------------------------------------------------------------------
+    # Filter-chain policy extraction (global, cross-file)
+    # -------------------------------------------------------------------------
+
+    def get_filter_chain_policy(
+        self, all_parsed_files: list[ParsedFile]
+    ) -> FilterChainPolicy | None:
+        """Scan all project files for a SecurityFilterChain @Bean and extract
+        its permit-all URL patterns plus the anyRequest() auth requirement.
+
+        Returns None if no SecurityFilterChain bean is found.
+        """
+        for parsed_file in all_parsed_files:
+            for cls in parsed_file.classes:
+                for method in cls.methods:
+                    if not any(d.name == "Bean" for d in method.decorators):
+                        continue
+                    if "SecurityFilterChain" not in (method.return_type or ""):
+                        continue
+                    return self._parse_filter_chain_method(parsed_file.path, method.location.line)
+        return None
+
+    def _parse_filter_chain_method(
+        self, file_path: str | Path, start_line: int
+    ) -> FilterChainPolicy:
+        """Read the SecurityFilterChain bean body and extract security rules."""
+        try:
+            source_lines = Path(file_path).read_text(errors="replace").splitlines()
+        except OSError:
+            return FilterChainPolicy()
+
+        # Grab from the method's start line up to a reasonable window (150 lines).
+        body = "\n".join(source_lines[max(0, start_line - 1) : start_line + 150])
+
+        # Patterns like: .requestMatchers("/api/login/**", "/api/public/**").permitAll()
+        # or:            .requestMatchers(antMatcher("/actuator/**")).permitAll()
+        permit_all_patterns: list[str] = []
+        for m in re.finditer(
+            r"requestMatchers\s*\(([^)]+)\)\s*(?:\.[^.]+)*?\.\s*permitAll\s*\(\s*\)",
+            body,
+        ):
+            args_text = m.group(1)
+            for pattern in re.findall(r'"([^"]+)"', args_text):
+                permit_all_patterns.append(pattern)
+
+        # Also capture PathRequest.toStaticResources() / toH2Console() idioms
+        if re.search(r"PathRequest\s*\.", body) and re.search(r"permitAll", body):
+            permit_all_patterns.append("/h2-console/**")
+            permit_all_patterns.append("/static/**")
+
+        any_request_auth = bool(
+            re.search(
+                r"anyRequest\s*\(\s*\)\s*(?:\.[^.]+)*?\.\s*"
+                r"(authenticated|fullyAuthenticated|hasRole|hasAuthority)\s*\(",
+                body,
+            )
+        )
+
+        return FilterChainPolicy(
+            any_request_auth=any_request_auth,
+            permit_all_patterns=permit_all_patterns,
+        )
+
+    # -------------------------------------------------------------------------
+    # Auth dependency extraction
+    # -------------------------------------------------------------------------
+
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        **kwargs: Any,
+    ) -> list[ExtractedAuthDependency]:
+        """Extract auth guards: @PreAuthorize, @Secured, auth filter/service classes."""
+        auth_deps: list[ExtractedAuthDependency] = []
+
+        for cls in parsed_file.classes:
+            # Auth-related classes (filter, service, guard)
+            if self._is_auth_class(cls):
+                auth_deps.append(
+                    ExtractedAuthDependency(
+                        name=cls.name,
+                        qualified_name=cls.qualified_name,
+                        location=cls.location,
+                        dependency_type=AuthDependencyType.FILTER
+                        if "filter" in cls.name.lower()
+                        else AuthDependencyType.CLASS,
+                        confidence=Confidence.MEDIUM,
+                    )
+                )
+
+            # Class-level @PreAuthorize / @Secured / @RolesAllowed.
+            # Applies to every handler in the controller, so emit a single
+            # dependency keyed by the class name.  Routes whose methods
+            # carry no method-level guard reference this entry via
+            # `_method_auth_refs`.
+            class_roles: list[str] = []
+            class_has_security = False
+            for dec in cls.decorators:
+                if dec.name in _SECURITY_ANNOTATIONS:
+                    class_has_security = True
+                    class_roles.extend(self._extract_roles_from_security_ann(dec))
+            if class_has_security:
+                auth_deps.append(
+                    ExtractedAuthDependency(
+                        name=cls.name,
+                        qualified_name=cls.qualified_name,
+                        location=cls.location,
+                        dependency_type=AuthDependencyType.ANNOTATION,
+                        requires_roles=class_roles,
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+            # Methods with @PreAuthorize / @Secured.
+            # Collect ALL security annotations on a method (a method may have
+            # both @PreAuthorize and @Secured simultaneously) and merge their
+            # roles rather than stopping at the first match.
+            for method in cls.methods:
+                all_roles: list[str] = []
+                has_security_ann = False
+                for dec in method.decorators:
+                    if dec.name in _SECURITY_ANNOTATIONS:
+                        has_security_ann = True
+                        all_roles.extend(self._extract_roles_from_security_ann(dec))
+                if has_security_ann:
+                    auth_deps.append(
+                        ExtractedAuthDependency(
+                            name=f"{cls.name}.{method.name}",
+                            qualified_name=method.qualified_name,
+                            location=method.location,
+                            dependency_type=AuthDependencyType.ANNOTATION,
+                            requires_roles=all_roles,
+                            confidence=Confidence.HIGH,
+                        )
+                    )
+
+        return auth_deps
+
+    def _is_auth_class(self, cls: ParsedClass) -> bool:
+        if is_auth_related_name(cls.name):
+            return True
+        # Implements Spring Security interfaces
+        for base in cls.base_classes:
+            if any(
+                iface in base
+                for iface in [
+                    "UserDetailsService",
+                    "AuthenticationProvider",
+                    "OncePerRequestFilter",
+                    "GenericFilterBean",
+                    "BasicAuthenticationFilter",
+                    "UsernamePasswordAuthenticationFilter",
+                ]
+            ):
+                return True
+        return False
+
+    def _extract_roles_from_security_ann(self, dec: ParsedDecorator) -> list[str]:
+        """Extract role names from @PreAuthorize / @Secured values.
+
+        For @PreAuthorize SpEL expressions, only emit a role when the
+        expression contains ``hasRole(...)`` / ``hasAuthority(...)``.  Other
+        guard expressions (``isAuthenticated()``, ``principal != null``, …)
+        are still protective — the route's non-empty ``dependency_refs``
+        captures that — but they don't translate to a role name, so we
+        return nothing for them rather than leak the raw SpEL string
+        downstream as if it were a role.
+        """
+        roles: list[str] = []
+        is_pre_authorize = dec.name == "PreAuthorize"
+
+        def _collect_from_string(val: str) -> None:
+            found = re.findall(r"hasRole\(['\"]([^'\"]+)['\"]\)", val)
+            found += re.findall(r"hasAuthority\(['\"]([^'\"]+)['\"]\)", val)
+            if found:
+                roles.extend(found)
+            elif not is_pre_authorize:
+                # @Secured / @RolesAllowed values are plain role strings.
+                roles.append(val)
+            # else: SpEL expression with no role/authority — emit nothing.
+
+        # @Secured({"ROLE_ADMIN", "ROLE_USER"}) or @PreAuthorize("hasRole(...)")
+        for val in dec.positional_args:
+            if isinstance(val, list):
+                for v in val:
+                    if isinstance(v, str):
+                        _collect_from_string(v)
+                    else:
+                        roles.append(str(v))
+            elif isinstance(val, str):
+                _collect_from_string(val)
+
+        val = dec.arguments.get("value")
+        if val:
+            if isinstance(val, list):
+                for v in val:
+                    if isinstance(v, str):
+                        _collect_from_string(v)
+                    else:
+                        roles.append(str(v))
+            elif isinstance(val, str):
+                _collect_from_string(val)
+
+        return roles
+
+    # -------------------------------------------------------------------------
+    # Middleware extraction
+    # -------------------------------------------------------------------------
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        """Detect Spring filters, interceptors, CORS policies, and exception handlers."""
+        middleware: list[ExtractedMiddleware] = []
+
+        for cls in parsed_file.classes:
+            ann_names = {d.name for d in cls.decorators}
+
+            # Standard filter / interceptor detection
+            mw_type = self._classify_middleware(cls)
+            if mw_type is not None:
+                operations = self._infer_middleware_operations(cls)
+                middleware.append(
+                    ExtractedMiddleware(
+                        name=cls.name,
+                        qualified_name=cls.qualified_name,
+                        location=cls.location,
+                        middleware_type=mw_type,
+                        applies_to_all=True,
+                        operations=operations,
+                        confidence=Confidence.MEDIUM,
+                    )
+                )
+                continue  # Don't double-count as CORS / ControllerAdvice
+
+            # @CrossOrigin on a @RestController / @Controller class
+            # Emitted as a dedicated "cors" middleware scoped to that controller.
+            if "CrossOrigin" in ann_names and any(a in ann_names for a in _CONTROLLER_ANNOTATIONS):
+                cors_dec = next(d for d in cls.decorators if d.name == "CrossOrigin")
+                origins = self._annotation_str_list(cors_dec, "origins") or ["*"]
+                middleware.append(
+                    ExtractedMiddleware(
+                        name=f"CrossOrigin({cls.name})",
+                        qualified_name=cls.qualified_name,
+                        location=cls.location,
+                        middleware_type="cors",
+                        applies_to_all=False,
+                        applies_to_patterns=[f"{cls.name}.*"],
+                        operations=["cors"],
+                        confidence=Confidence.HIGH,
+                    )
+                )
+                logger.debug("CORS policy on %s: origins=%s", cls.name, origins)
+
+            # @ControllerAdvice — global exception handler
+            if "ControllerAdvice" in ann_names or "RestControllerAdvice" in ann_names:
+                middleware.append(
+                    ExtractedMiddleware(
+                        name=cls.name,
+                        qualified_name=cls.qualified_name,
+                        location=cls.location,
+                        middleware_type="exception_handler",
+                        applies_to_all=True,
+                        operations=["error_handling"],
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+        return middleware
+
+    def _classify_middleware(self, cls: ParsedClass) -> str | None:
+        """Return middleware type string or None if not a middleware class."""
+        for base in cls.base_classes:
+            # Use exact Spring class names to avoid false positives from
+            # unrelated classes whose names happen to contain "Filter"
+            # (e.g. ImageFilter, ColorFilter, StreamFilter).
+            if any(
+                base == pattern or base.endswith("." + pattern)
+                for pattern in [
+                    "OncePerRequestFilter",
+                    "GenericFilterBean",
+                    "BasicAuthenticationFilter",
+                    "UsernamePasswordAuthenticationFilter",
+                    "GenericFilter",
+                    "HttpFilter",
+                ]
+            ):
+                return "filter"
+            # Also accept any base whose simple name ends in "Filter" and
+            # starts with a Spring-related prefix to avoid over-matching.
+            if base.startswith("org.springframework") and base.endswith("Filter"):
+                return "filter"
+            if "HandlerInterceptor" in base or base.endswith("Interceptor"):
+                return "interceptor"
+
+        # @Component class that looks like a filter by name
+        ann_names = {d.name for d in cls.decorators}
+        if "Component" in ann_names:
+            name_lower = cls.name.lower()
+            if "filter" in name_lower:
+                return "filter"
+            if "interceptor" in name_lower:
+                return "interceptor"
+
+        return None
+
+    def _infer_middleware_operations(self, cls: ParsedClass) -> list[str]:
+        """Infer middleware operations from class name + base classes.
+
+        Spring extends the cross-framework keyword set with ``compression``,
+        which only really shows up in Spring's compression-filter ecosystem.
+        """
+        return infer_middleware_operations(
+            cls.name,
+            cls.base_classes,
+            extra={"compression": ("compress", "gzip")},
+        )
+
+    # -------------------------------------------------------------------------
+    # Annotation helpers
+    # -------------------------------------------------------------------------
+
+    def _annotation_paths(self, dec: ParsedDecorator) -> list[str]:
+        return _annotations.annotation_paths(dec)
+
+    def _annotation_path(self, dec: ParsedDecorator) -> str | None:
+        return _annotations.annotation_path(dec)
+
+    def _annotation_str(self, dec: ParsedDecorator, key: str) -> str | None:
+        return _annotations.annotation_str(dec, key)
+
+    def _annotation_str_list(self, dec: ParsedDecorator, key: str) -> list[str]:
+        return _annotations.annotation_str_list(dec, key)
+
+    def _extract_status_code(self, dec: ParsedDecorator) -> int:
+        return _annotations.extract_status_code(dec, _HTTP_STATUS_MAP)
+
+    def _get_request_methods(self, dec: ParsedDecorator) -> list[HttpMethod]:
+        """Extract HTTP method(s) from @RequestMapping(method = ...).
+
+        Supports both the single-value form (``method = RequestMethod.GET``)
+        and the array form (``method = {RequestMethod.GET, RequestMethod.POST}``).
+        Returns an empty list when ``method=`` was not specified at all.
+        """
+        method_val = dec.arguments.get("method")
+        if method_val is None:
+            return []
+
+        if isinstance(method_val, str):
+            raw = method_val.split(".")[-1].upper()
+            mapped = _REQUEST_METHOD_MAP.get(raw)
+            return [mapped] if mapped is not None else []
+
+        if isinstance(method_val, list):
+            result: list[HttpMethod] = []
+            for entry in method_val:
+                raw = str(entry).split(".")[-1].upper()
+                mapped = _REQUEST_METHOD_MAP.get(raw)
+                if mapped is not None and mapped not in result:
+                    result.append(mapped)
+            return result
+
+        return []
+
+    def _join_paths(self, prefix: str, path: str) -> str:
+        return _annotations.join_paths(prefix, path)
+
+    # -------------------------------------------------------------------------
+    # JWT config extraction
+    # -------------------------------------------------------------------------
+
+    _jwt_extractor = JavaJwtConfigExtractor()
+
+    def extract_jwt_config(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> ExtractedJwtConfig | None:
+        """Extract JWT library, algorithms, validation flags, and secret source."""
+        return self._jwt_extractor.extract(parsed_file)
+
+
+# =============================================================================
+# Registration
+# =============================================================================
+
+_spring_plugin = SpringBootPlugin()
+FrameworkPluginRegistry.register(_spring_plugin)