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

apisec_code_bolt/frameworks/base.py

@@ -0,0 +1,608 @@
+"""
+Base classes and protocols for framework-specific plugins.
+
+Each framework (FastAPI, Spring Boot, etc.) implements the FrameworkPlugin
+protocol to provide specialized extraction of routes, dependencies, auth,
+and middleware.
+"""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from ..core.types import (
+    AuthDependencyType,
+    AuthSchemeType,
+    CodeLocation,
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+    QualifiedName,
+)
+
+if TYPE_CHECKING:
+    from ..parsing.base import ParsedDecorator, ParsedFile, ParsedFunction
+    from ..parsing.services import AnalysisContext
+
+
+# =============================================================================
+# Route Extraction Types
+# =============================================================================
+
+
+@dataclass
+class ExtractedParameter:
+    """A parameter extracted from a route definition."""
+
+    name: str
+    location: ParameterLocation
+
+    type_annotation: str | None = None
+    required: bool = True
+    default_value: str | None = None
+
+    # Framework-specific details
+    alias: str | None = None  # Alternative name in request
+    description: str | None = None
+
+    # Validation constraints
+    constraints: dict[str, Any] = field(default_factory=dict)
+
+    # Source location
+    code_location: CodeLocation | None = None
+
+
+@dataclass
+class ExtractedBody:
+    """Request body extracted from a route definition."""
+
+    content_type: str | None = None
+    model_name: str | None = None
+    model_qualified_name: QualifiedName | None = None
+    model_fields: list[str] = field(default_factory=list)
+    required: bool = True
+
+    code_location: CodeLocation | None = None
+
+
+@dataclass
+class ExtractedResponse:
+    """Response model extracted from a route definition."""
+
+    status_code: int = 200
+    model_name: str | None = None
+    model_qualified_name: QualifiedName | None = None
+    content_type: str | None = None
+    description: str | None = None
+
+
+@dataclass
+class ExtractedRoute:
+    """
+    An entry point extracted from framework code.
+
+    This is the framework plugin's output for each detected entry point.
+    Covers HTTP routes, CLI commands, task definitions, message consumers, etc.
+    """
+
+    method: HttpMethod
+    path: str
+
+    # Handler
+    handler_function: QualifiedName
+    handler_location: CodeLocation
+
+    # Parameters by location
+    path_params: list[ExtractedParameter] = field(default_factory=list)
+    query_params: list[ExtractedParameter] = field(default_factory=list)
+    header_params: list[ExtractedParameter] = field(default_factory=list)
+    cookie_params: list[ExtractedParameter] = field(default_factory=list)
+
+    # Body
+    body: ExtractedBody | None = None
+
+    # Response
+    response: ExtractedResponse = field(default_factory=ExtractedResponse)
+
+    # Framework metadata
+    router_name: str | None = None
+    tags: list[str] = field(default_factory=list)
+    operation_id: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    deprecated: bool = False
+
+    # Dependencies used by this route
+    dependency_refs: list[str] = field(default_factory=list)
+
+    # Analysis metadata
+    confidence: Confidence = Confidence.HIGH
+
+    # Entry point transport category (language-agnostic).
+    # "http" for web routes, "cli" for CLI commands, "task" for async tasks, etc.
+    kind: str = "http"
+
+
+# =============================================================================
+# Dependency Injection Types
+# =============================================================================
+
+
+@dataclass
+class ExtractedDependency:
+    """
+    A dependency injection definition extracted from framework code.
+
+    This captures FastAPI's Depends(), Spring's @Autowired, etc.
+    """
+
+    name: str
+    qualified_name: QualifiedName
+    location: CodeLocation
+
+    # Type of dependency
+    dependency_type: str  # "function", "class", "provider", etc.
+
+    # What does this dependency provide?
+    provides_type: str | None = None
+    provides_qualified_name: QualifiedName | None = None
+
+    # Dependencies this depends on (chain)
+    depends_on: list[QualifiedName] = field(default_factory=list)
+
+    # Is this auth-related?
+    is_auth_related: bool = False
+    auth_scheme_ref: str | None = None
+
+    # Scope (singleton, request, etc.)
+    scope: str | None = None
+
+    # Analysis metadata
+    confidence: Confidence = Confidence.HIGH
+
+
+# =============================================================================
+# Authentication Types
+# =============================================================================
+
+
+@dataclass
+class ExtractedAuthScheme:
+    """
+    An authentication scheme extracted from framework code.
+
+    This captures OAuth2 schemes, API key definitions, etc.
+    """
+
+    scheme_type: AuthSchemeType
+    name: str
+    location: CodeLocation
+
+    # Scheme configuration
+    config: dict[str, Any] = field(default_factory=dict)
+
+    # For OAuth2
+    token_url: str | None = None
+    authorization_url: str | None = None
+    scopes: dict[str, str] = field(default_factory=dict)  # scope -> description
+
+    # For API keys
+    header_name: str | None = None
+    query_param_name: str | None = None
+    cookie_name: str | None = None
+
+    # Analysis metadata
+    confidence: Confidence = Confidence.HIGH
+
+
+@dataclass
+class ExtractedAuthDependency:
+    """
+    An authentication dependency/guard extracted from framework code.
+
+    This captures functions/classes that perform authentication.
+    """
+
+    name: str
+    qualified_name: QualifiedName
+    location: CodeLocation
+
+    dependency_type: AuthDependencyType
+
+    # What scheme(s) does this use?
+    uses_schemes: list[str] = field(default_factory=list)
+
+    # What other auth dependencies does this depend on?
+    depends_on: list[QualifiedName] = field(default_factory=list)
+
+    # What does this extract/validate?
+    extracts_fields: list[str] = field(default_factory=list)
+    validates: list[str] = field(default_factory=list)
+
+    # Role/scope requirements
+    requires_roles: list[str] = field(default_factory=list)
+    requires_scopes: list[str] = field(default_factory=list)
+
+    # JWT-specific operations
+    jwt_operations: list[str] = field(default_factory=list)
+
+    # Analysis metadata
+    confidence: Confidence = Confidence.HIGH
+
+
+@dataclass
+class ExtractedJwtConfig:
+    """JWT configuration extracted from code."""
+
+    library: str
+
+    detected: bool = False
+    locations: list[CodeLocation] = field(default_factory=list)
+
+    algorithms: list[str] = field(default_factory=list)
+
+    validates_signature: bool = False
+    validates_expiry: bool = False
+    validates_issuer: bool = False
+    validates_audience: bool = False
+
+    secret_source: str | None = None  # "env", "config", "hardcoded"
+    secret_name: str | None = None
+
+    confidence: Confidence = Confidence.HIGH
+
+
+# =============================================================================
+# Middleware Types
+# =============================================================================
+
+
+@dataclass
+class ExtractedMiddleware:
+    """
+    Middleware/interceptor extracted from framework code.
+
+    This captures FastAPI middleware, Spring filters/interceptors, etc.
+    """
+
+    name: str
+    location: CodeLocation
+
+    # Type
+    middleware_type: str  # "middleware", "filter", "interceptor"
+
+    # Optional fields
+    qualified_name: QualifiedName | None = None
+
+    # Ordering
+    order: int | None = None
+
+    # What routes does this apply to?
+    applies_to_patterns: list[str] = field(default_factory=list)
+    applies_to_all: bool = False
+
+    # Detected operations
+    operations: list[str] = field(default_factory=list)  # "auth", "cors", "logging", etc.
+
+    # Analysis metadata
+    confidence: Confidence = Confidence.HIGH
+
+
+# =============================================================================
+# Shared helpers (used by plugins across languages)
+# =============================================================================
+
+
+# Matches ``{name}`` and ``{name:constraint}`` route-template segments.
+# Captures the parameter name only — the optional ``:constraint`` suffix is
+# stripped.  Works for Spring/Micronaut path variables and ASP.NET route
+# templates ({id:int} → id, {slug:regex(...)} → slug).
+_PATH_TEMPLATE_NAME_RE = re.compile(r"\{([^}:]+)(?::[^}]+)?\}")
+
+
+def extract_path_template_names(path: str) -> set[str]:
+    """Return the set of parameter names embedded in a route template.
+
+    Strips any ``:constraint`` suffix on each segment::
+
+        "/api/users/{id}/orders/{orderId:int}"
+            → {"id", "orderId"}
+    """
+    return set(_PATH_TEMPLATE_NAME_RE.findall(path))
+
+
+# Common middleware/filter "what does it do" keyword classifier.
+# Maps an operation tag → list of substrings to look for in the lowercased
+# (class-name + " " + base-class-names) combination.  All three of Spring,
+# Micronaut, and ASP.NET Core had their own near-identical version of this.
+_MIDDLEWARE_OP_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "auth": ("auth", "jwt", "token", "security", "login"),
+    "cors": ("cors",),
+    "logging": ("log",),
+    "rate_limiting": ("rate", "throttl"),
+}
+
+
+def infer_middleware_operations(
+    class_name: str,
+    base_classes: list[str] | tuple[str, ...] = (),
+    extra: dict[str, tuple[str, ...]] | None = None,
+) -> list[str]:
+    """Infer what a middleware/filter class does from its name and base classes.
+
+    Returns the matching operation tags (``["auth"]``, ``["cors", "logging"]``,
+    etc.), or ``["custom"]`` if nothing matches.  Pass ``extra`` to add
+    framework-specific keywords (e.g. ``{"compression": ("compress", "gzip")}``
+    for Spring).
+    """
+    combined = class_name.lower() + " " + " ".join(b.lower() for b in base_classes)
+    keywords = {**_MIDDLEWARE_OP_KEYWORDS, **(extra or {})}
+    ops = [op for op, kws in keywords.items() if any(kw in combined for kw in kws)]
+    return ops or ["custom"]
+
+
+# Class/symbol name heuristics for "is this auth-related?" — used by
+# dependency extraction to flag service classes that handle authentication.
+# This is the union of what Spring/Micronaut/.NET previously each carried
+# their own copy of.  ``identity`` and ``middleware`` are .NET-flavoured
+# but harmless on Java code (Spring rarely names things "Middleware").
+AUTH_NAME_KEYWORDS: frozenset[str] = frozenset(
+    {
+        "auth",
+        "authentication",
+        "authorization",
+        "security",
+        "jwt",
+        "token",
+        "user",
+        "identity",
+        "principal",
+        "credential",
+        "login",
+        "filter",
+        "middleware",
+    }
+)
+
+
+def is_auth_related_name(name: str) -> bool:
+    """True if a class/file/symbol name contains common auth-related substrings."""
+    name_lower = name.lower()
+    return any(kw in name_lower for kw in AUTH_NAME_KEYWORDS)
+
+
+# =============================================================================
+# Abstract Framework Plugin Base
+# =============================================================================
+
+
+class BaseFrameworkPlugin(ABC):
+    """
+    Abstract base class for framework-specific plugins.
+
+    Each framework (FastAPI, Spring Boot, etc.) extends this
+    to provide specialized extraction logic.
+    """
+
+    # Class-level constants to be overridden
+    FRAMEWORK: ClassVar[Framework]
+    LANGUAGE: ClassVar[Language]
+
+    # Import patterns that indicate this framework is used.
+    #
+    # - ``DETECTION_IMPORTS`` matches full module paths or ``module.symbol`` forms exactly.
+    # - ``DETECTION_IMPORT_PREFIXES`` matches the start of a module path — useful for
+    #   namespace-rooted libraries where any subpackage import counts as detection
+    #   (e.g. ``"org.springframework"``, ``"io.micronaut"``, ``"Microsoft.AspNetCore"``).
+    #
+    # Subclasses set at least one of the two; both are checked by the default
+    # ``detect()`` implementation.  Subclasses with extra detection signals
+    # (e.g. attribute-only detection when imports are missing) override ``detect()``.
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = frozenset()
+    DETECTION_IMPORT_PREFIXES: ClassVar[tuple[str, ...]] = ()
+
+    @property
+    def framework(self) -> Framework:
+        """The framework this plugin handles."""
+        return self.FRAMEWORK
+
+    @property
+    def language(self) -> Language:
+        """The language this framework is for."""
+        return self.LANGUAGE
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        """
+        Detect if this framework is used in the parsed file.
+
+        Default implementation checks each import against ``DETECTION_IMPORTS``
+        (exact match) and ``DETECTION_IMPORT_PREFIXES`` (prefix match).
+        Subclasses override only if they need extra signals beyond imports.
+        """
+        prefixes = self.DETECTION_IMPORT_PREFIXES
+        for imp in parsed_file.imports:
+            module = imp.module or ""
+            if module in self.DETECTION_IMPORTS:
+                return True
+            if prefixes and module.startswith(prefixes):
+                return True
+            for name in imp.names:
+                full_name = f"{module}.{name}" if module else name
+                if full_name in self.DETECTION_IMPORTS:
+                    return True
+        return False
+
+    @abstractmethod
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        """
+        Extract HTTP route definitions from the file.
+
+        Args:
+            parsed_file: The parsed source file
+            context: Optional analysis context with services
+
+        Returns:
+            List of extracted route definitions
+        """
+        ...
+
+    @abstractmethod
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        """
+        Extract dependency injection definitions.
+
+        Args:
+            parsed_file: The parsed source file
+
+        Returns:
+            List of extracted dependency definitions
+        """
+        ...
+
+    @abstractmethod
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        """
+        Extract authentication scheme definitions.
+
+        Args:
+            parsed_file: The parsed source file
+
+        Returns:
+            List of extracted auth scheme definitions
+        """
+        ...
+
+    @abstractmethod
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        **kwargs: Any,
+    ) -> list[ExtractedAuthDependency]:
+        """
+        Extract authentication dependencies/guards.
+
+        Args:
+            parsed_file: The parsed source file
+            known_scheme_names: Optional set of auth scheme variable names
+                already extracted for this file, used to populate
+                ``uses_schemes`` on returned dependencies.
+
+        Returns:
+            List of extracted auth dependency definitions
+        """
+        ...
+
+    def extract_jwt_config(self, parsed_file: ParsedFile) -> ExtractedJwtConfig | None:
+        """
+        Extract JWT configuration.
+
+        Default implementation returns None. Override if the
+        framework has specific JWT patterns.
+        """
+        return None
+
+    @abstractmethod
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        """
+        Extract middleware/interceptor definitions.
+
+        Args:
+            parsed_file: The parsed source file
+
+        Returns:
+            List of extracted middleware definitions
+        """
+        ...
+
+    # ==========================================================================
+    # Helper Methods
+    # ==========================================================================
+
+    def _find_decorator(
+        self, function: ParsedFunction, decorator_names: set[str]
+    ) -> ParsedDecorator | None:
+        """Find a decorator by name on a function."""
+        for dec in function.decorators:
+            if dec.name in decorator_names:
+                return dec
+            # Check qualified name
+            if dec.qualified_name and dec.qualified_name.name in decorator_names:
+                return dec
+        return None
+
+    def _has_decorator(self, function: ParsedFunction, decorator_names: set[str]) -> bool:
+        """Check if function has any of the given decorators."""
+        return self._find_decorator(function, decorator_names) is not None
+
+    def _extract_decorator_arg(
+        self, decorator: ParsedDecorator, arg_name: str, default: Any = None
+    ) -> Any:
+        """Extract an argument value from a decorator."""
+        return decorator.arguments.get(arg_name, default)
+
+
+# =============================================================================
+# Framework Plugin Registry
+# =============================================================================
+
+
+class FrameworkPluginRegistry:
+    """
+    Registry of available framework plugins.
+
+    Plugins register themselves and the registry provides
+    lookup and detection capabilities.
+    """
+
+    _plugins: dict[Framework, BaseFrameworkPlugin] = {}
+    _by_language: dict[Language, list[BaseFrameworkPlugin]] = {}
+
+    @classmethod
+    def register(cls, plugin: BaseFrameworkPlugin) -> None:
+        """Register a framework plugin."""
+        cls._plugins[plugin.framework] = plugin
+
+        if plugin.language not in cls._by_language:
+            cls._by_language[plugin.language] = []
+        cls._by_language[plugin.language].append(plugin)
+
+    @classmethod
+    def get_plugin(cls, framework: Framework) -> BaseFrameworkPlugin | None:
+        """Get plugin for a specific framework."""
+        return cls._plugins.get(framework)
+
+    @classmethod
+    def get_plugins_for_language(cls, language: Language) -> list[BaseFrameworkPlugin]:
+        """Get all plugins for a language."""
+        return cls._by_language.get(language, [])
+
+    @classmethod
+    def detect_frameworks(cls, parsed_file: ParsedFile) -> list[Framework]:
+        """
+        Detect which frameworks are used in a parsed file.
+
+        Returns list of detected frameworks, may be empty.
+        """
+        detected = []
+        plugins = cls.get_plugins_for_language(parsed_file.language)
+
+        for plugin in plugins:
+            if plugin.detect(parsed_file):
+                detected.append(plugin.framework)
+
+        return detected
+
+    @classmethod
+    def supported_frameworks(cls) -> frozenset[Framework]:
+        """Get set of supported frameworks."""
+        return frozenset(cls._plugins.keys())

apisec_code_bolt/frameworks/dotnet/__init__.py

@@ -0,0 +1,17 @@
+"""ASP.NET framework plugins — auto-registers on import."""
+
+from .aspnet_plugin import AspNetCorePlugin
+from .grpc_plugin import GrpcPlugin
+from .jwt_config_extractor import DotNetJwtConfigExtractor
+from .legacy_aspnet_plugin import LegacyAspNetPlugin
+from .refit_plugin import RefitPlugin
+from .wcf_plugin import WcfPlugin
+
+__all__ = [
+    "AspNetCorePlugin",
+    "DotNetJwtConfigExtractor",
+    "GrpcPlugin",
+    "LegacyAspNetPlugin",
+    "RefitPlugin",
+    "WcfPlugin",
+]

apisec_code_bolt/frameworks/dotnet/_path_helpers.py

@@ -0,0 +1,43 @@
+"""
+Shared .NET routing-path helpers.
+
+Both AspNetCorePlugin and RefitPlugin need to:
+- Extract the path string from a `[Route("...")]`-style attribute, supporting
+  positional and named arguments
+- Strip ASP.NET-style route-template constraints (e.g. `{id:int}` → `{id}`)
+
+Previously RefitPlugin instantiated an AspNetCorePlugin just to reach these
+helpers — that's an architectural smell since Refit is *not* an MVC plugin.
+Promoting both functions to module-level removes the indirection.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ...parsing.base import ParsedDecorator
+
+
+def dec_path(dec: ParsedDecorator) -> str | None:
+    """Extract the path string from a routing attribute.
+
+    Tries positional arg 0 first, then the named keys ASP.NET attribute
+    routing accepts (`template` / `Template` / `name` / `Name`).
+    """
+    if dec.positional_args:
+        val = dec.positional_args[0]
+        if isinstance(val, str):
+            return val
+    for key in ("template", "Template", "name", "Name"):
+        val = dec.arguments.get(key)
+        if val and isinstance(val, str):
+            return val
+    return None
+
+
+_ROUTE_CONSTRAINT_RE = re.compile(r"\{([^}:]+):[^}]+\}")
+
+
+def normalize_path(path: str) -> str:
+    """Strip ASP.NET route-constraint suffixes: `{id:int}` → `{id}`, `{slug:regex(...)}` → `{slug}`."""
+    return _ROUTE_CONSTRAINT_RE.sub(r"{\1}", path)