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

apisec_code_bolt/frameworks/js/nestjs_plugin.py

@@ -0,0 +1,423 @@
+"""
+NestJS framework plugin.
+
+Extracts HTTP routes from NestJS @Controller + @Get/@Post/@Put/@Patch/@Delete
+decorator patterns. Supports:
+- @Controller('prefix') and @Controller({ path: 'prefix' })
+- Verb decorators: @Get, @Post, @Put, @Patch, @Delete, @Options, @Head, @All
+- Path params: :id → {id}
+- Auth: @UseGuards, @ApiBearerAuth, etc.
+- Versioned controllers
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING, Any
+
+from ...core.types import (
+    AuthDependencyType,
+    AuthSchemeType,
+    CodeLocation,
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+    QualifiedName,
+)
+from ...parsing.base import ParsedDecorator, ParsedFile
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+if TYPE_CHECKING:
+    from ...parsing.services import AnalysisContext
+
+logger = logging.getLogger(__name__)
+
+# NestJS HTTP verb decorators → HttpMethod
+_VERB_DECORATORS: dict[str, HttpMethod] = {
+    "Get": HttpMethod.GET,
+    "Post": HttpMethod.POST,
+    "Put": HttpMethod.PUT,
+    "Patch": HttpMethod.PATCH,
+    "Delete": HttpMethod.DELETE,
+    "Options": HttpMethod.OPTIONS,
+    "Head": HttpMethod.HEAD,
+    "All": HttpMethod.GET,
+}
+
+# Auth-related decorators
+_AUTH_DECORATORS: frozenset[str] = frozenset(
+    {
+        "UseGuards",
+        "Roles",
+        "Public",
+        "ApiBearerAuth",
+        "ApiSecurity",
+        "Auth",
+        "Authorize",
+    }
+)
+
+# Regex to convert NestJS :param to {param}
+_PARAM_RE = re.compile(r":([A-Za-z_]\w*)")
+# Regex to extract 'path' from object literal { path: 'xxx' }
+_OBJ_PATH_RE = re.compile(r"path\s*:\s*['\"]([^'\"]+)['\"]")
+
+
+def _colon_to_curly(path: str) -> str:
+    return _PARAM_RE.sub(r"{\1}", path)
+
+
+def _extract_path_params(path: str) -> list[ExtractedParameter]:
+    return [
+        ExtractedParameter(name=m.group(1), location=ParameterLocation.PATH)
+        for m in _PARAM_RE.finditer(path)
+    ]
+
+
+def _get_decorator_path(dec: ParsedDecorator) -> str:
+    """Extract the path string from a decorator (string arg or { path: '...' } object)."""
+    if not dec.positional_args:
+        return ""
+
+    value = dec.positional_args[0]
+    if not isinstance(value, str):
+        return ""
+
+    # Check if it looks like an object literal
+    if value.strip().startswith("{"):
+        m = _OBJ_PATH_RE.search(value)
+        if m:
+            return m.group(1)
+        return ""
+
+    return value
+
+
+class NestJSPlugin(BaseFrameworkPlugin):
+    """
+    Framework plugin for NestJS.
+
+    Detects NestJS usage via @nestjs/* imports and extracts routes
+    from @Controller + @Get/@Post etc. decorator patterns.
+    """
+
+    FRAMEWORK = Framework.NESTJS
+    LANGUAGE = Language.JAVASCRIPT
+    DETECTION_IMPORTS: frozenset[str] = frozenset(
+        {
+            "@nestjs/common",
+            "@nestjs/core",
+            "@nestjs/swagger",
+        }
+    )
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        """Detect NestJS by looking for @nestjs/* imports."""
+        return any(imp.module.startswith("@nestjs/") for imp in parsed_file.imports)
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        """Extract routes from @Controller + @Get/@Post etc. patterns."""
+        routes: list[ExtractedRoute] = []
+
+        for cls in parsed_file.classes:
+            # Find @Controller decorator
+            controller_dec = _find_decorator(cls.decorators, "Controller")
+            if controller_dec is None:
+                continue
+
+            # Extract controller prefix
+            prefix = _get_decorator_path(controller_dec)
+
+            # Process each method
+            for method in cls.methods:
+                # Find a verb decorator
+                verb_dec = _find_verb_decorator(method.decorators)
+                if verb_dec is None:
+                    continue
+
+                http_method = _VERB_DECORATORS[verb_dec.name]
+
+                # Get route path from decorator
+                method_path = _get_decorator_path(verb_dec)
+
+                # Build full path
+                if prefix and method_path:
+                    full_path = prefix.rstrip("/") + "/" + method_path.lstrip("/")
+                elif prefix:
+                    full_path = "/" + prefix.lstrip("/")
+                elif method_path:
+                    full_path = "/" + method_path.lstrip("/")
+                else:
+                    full_path = "/"
+
+                # Convert :param to {param}
+                full_path = _colon_to_curly(full_path)
+                if not full_path.startswith("/"):
+                    full_path = "/" + full_path
+                full_path = re.sub(r"/+", "/", full_path)
+
+                # Extract path params from combined path
+                path_params = _extract_path_params(prefix + "/" + method_path)
+
+                # Auth: check for @UseGuards or similar
+                auth_guard: str | None = None
+                for auth_dec in method.decorators + cls.decorators:
+                    if auth_dec.name in _AUTH_DECORATORS:
+                        guard_val = (
+                            auth_dec.positional_args[0]
+                            if auth_dec.positional_args
+                            else auth_dec.name
+                        )
+                        auth_guard = str(guard_val)
+                        break
+
+                # Handler name: ClassName.methodName
+                handler_name = f"{cls.name}.{method.name}"
+
+                # Use decorator's location (line number) for benchmark accuracy
+                handler_location = verb_dec.location or method.location
+
+                routes.append(
+                    ExtractedRoute(
+                        method=http_method,
+                        path=full_path,
+                        handler_function=QualifiedName(
+                            module=parsed_file.path.stem,
+                            name=handler_name,
+                        ),
+                        handler_location=handler_location,
+                        path_params=path_params,
+                        router_name=auth_guard,
+                    )
+                )
+
+        return routes
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        """
+        Detect NestJS auth scheme definitions.
+
+        Covers:
+        - @ApiBearerAuth() import/usage → JWT_BEARER scheme
+        - AuthGuard('strategy') references → named Passport strategies
+        - Passport strategy class definitions (extends PassportStrategy)
+        """
+        schemes: list[ExtractedAuthScheme] = []
+        seen_names: set[str] = set()
+
+        def _add(name: str, scheme_type: AuthSchemeType, line: int) -> None:
+            if name not in seen_names:
+                seen_names.add(name)
+                schemes.append(
+                    ExtractedAuthScheme(
+                        scheme_type=scheme_type,
+                        name=name,
+                        location=CodeLocation(file=parsed_file.path, line=line),
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+        # ── Import-based: @ApiBearerAuth / AuthGuard ─────────────────────────
+        for imp in parsed_file.imports:
+            for name in imp.names:
+                if name == "ApiBearerAuth":
+                    _add("BearerAuth", AuthSchemeType.JWT_BEARER, 1)
+                elif name == "AuthGuard":
+                    _add("AuthGuard", AuthSchemeType.JWT_BEARER, 1)
+                elif name in ("JwtAuthGuard", "JwtGuard"):
+                    _add(name, AuthSchemeType.JWT_BEARER, 1)
+
+        # ── Class-based: Passport strategy definitions ───────────────────────
+        for cls in parsed_file.classes:
+            base_names_lower = {b.lower() for b in cls.base_classes}
+            if "passportstrategy" in base_names_lower or any(
+                "strategy" in b for b in base_names_lower
+            ):
+                hint = cls.name.lower()
+                scheme_type = AuthSchemeType.JWT_BEARER if "jwt" in hint else AuthSchemeType.CUSTOM
+                line = cls.location.line if cls.location else 1
+                _add(cls.name, scheme_type, line)
+
+        # ── Usage-based: AuthGuard('strategy-name') call sites ───────────────
+        for call in parsed_file.call_sites:
+            if call.callee_name != "AuthGuard":
+                continue
+            if call.arguments and call.arguments[0].is_literal:
+                strategy = str(call.arguments[0].literal_value)
+                scheme_type = (
+                    AuthSchemeType.JWT_BEARER
+                    if "jwt" in strategy.lower()
+                    else AuthSchemeType.CUSTOM
+                )
+                line = call.location.line if call.location else 1
+                _add(f"AuthGuard({strategy})", scheme_type, line)
+
+        return schemes
+
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        **kwargs: Any,
+    ) -> list[ExtractedAuthDependency]:
+        """
+        Detect NestJS auth requirements from decorator patterns.
+
+        Covers:
+        - @UseGuards(AuthGuard('jwt'), RolesGuard) — class or method level
+        - @Roles(RoleEnum.admin) / @Roles('admin') — role requirements
+        - @ApiBearerAuth() — marks route as requiring Bearer token
+        - Class-level decorators apply to all methods in the controller
+
+        For each controller class with auth decorators, emits one dependency
+        capturing the guards and roles. Method-level overrides are also captured.
+        """
+        deps: list[ExtractedAuthDependency] = []
+
+        for cls in parsed_file.classes:
+            # Class-level guards and roles (apply to all methods)
+            class_guards = _extract_guards(cls.decorators)
+            class_roles = _extract_roles(cls.decorators)
+            class_bearer = any(d.name == "ApiBearerAuth" for d in cls.decorators)
+
+            if class_guards or class_roles or class_bearer:
+                uses_schemes = _guards_to_scheme_names(class_guards)
+                if class_bearer and "BearerAuth" not in uses_schemes:
+                    uses_schemes.append("BearerAuth")
+                line = cls.location.line if cls.location else 1
+                deps.append(
+                    ExtractedAuthDependency(
+                        name=cls.name,
+                        qualified_name=QualifiedName(
+                            module=parsed_file.path.stem,
+                            name=cls.name,
+                        ),
+                        location=CodeLocation(file=parsed_file.path, line=line),
+                        dependency_type=AuthDependencyType.DECORATOR,
+                        uses_schemes=uses_schemes,
+                        requires_roles=class_roles,
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+            # Method-level guards/roles that differ from class-level
+            for method in cls.methods:
+                method_guards = _extract_guards(method.decorators)
+                method_roles = _extract_roles(method.decorators)
+                method_bearer = any(d.name == "ApiBearerAuth" for d in method.decorators)
+
+                if not method_guards and not method_roles and not method_bearer:
+                    continue
+                # Only emit if method has guards/roles not already covered by class
+                if method_guards == class_guards and method_roles == class_roles:
+                    continue
+
+                uses_schemes = _guards_to_scheme_names(method_guards)
+                if method_bearer and "BearerAuth" not in uses_schemes:
+                    uses_schemes.append("BearerAuth")
+                line = method.location.line if method.location else 1
+                handler_name = f"{cls.name}.{method.name}"
+                deps.append(
+                    ExtractedAuthDependency(
+                        name=handler_name,
+                        qualified_name=QualifiedName(
+                            module=parsed_file.path.stem,
+                            name=handler_name,
+                        ),
+                        location=CodeLocation(file=parsed_file.path, line=line),
+                        dependency_type=AuthDependencyType.DECORATOR,
+                        uses_schemes=uses_schemes,
+                        requires_roles=method_roles,
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+        return deps
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+
+def _find_decorator(
+    decorators: list[ParsedDecorator],
+    name: str,
+) -> ParsedDecorator | None:
+    """Find a decorator by name in a list."""
+    for dec in decorators:
+        if dec.name == name:
+            return dec
+    return None
+
+
+def _find_verb_decorator(
+    decorators: list[ParsedDecorator],
+) -> ParsedDecorator | None:
+    """Find the first HTTP verb decorator in a list."""
+    for dec in decorators:
+        if dec.name in _VERB_DECORATORS:
+            return dec
+    return None
+
+
+def _extract_guards(decorators: list[ParsedDecorator]) -> list[str]:
+    """Extract guard names from @UseGuards(...) decorators."""
+    guards: list[str] = []
+    for dec in decorators:
+        if dec.name != "UseGuards":
+            continue
+        for arg in dec.positional_args:
+            arg_str = str(arg).strip()
+            if arg_str:
+                guards.append(arg_str)
+    return guards
+
+
+def _extract_roles(decorators: list[ParsedDecorator]) -> list[str]:
+    """Extract role names from @Roles(...) decorators."""
+    roles: list[str] = []
+    for dec in decorators:
+        if dec.name not in ("Roles", "Role"):
+            continue
+        for arg in dec.positional_args:
+            arg_str = str(arg).strip().strip("'\"")
+            if arg_str:
+                # Strip enum prefix: RoleEnum.admin → admin
+                if "." in arg_str:
+                    arg_str = arg_str.split(".")[-1]
+                roles.append(arg_str)
+    return roles
+
+
+def _guards_to_scheme_names(guards: list[str]) -> list[str]:
+    """Map guard names to auth scheme names."""
+    schemes: list[str] = []
+    for guard in guards:
+        low = guard.lower()
+        if "jwt" in low or "bearer" in low or "auth" in low:
+            if "BearerAuth" not in schemes:
+                schemes.append("BearerAuth")
+        elif guard not in schemes:
+            schemes.append(guard)
+    return schemes
+
+
+FrameworkPluginRegistry.register(NestJSPlugin())

apisec_code_bolt/frameworks/python/__init__.py

@@ -0,0 +1,19 @@
+"""Python framework plugins."""
+
+from .celery_plugin import CeleryPlugin
+from .click_plugin import ClickPlugin
+from .django_plugin import DjangoPlugin
+from .fastapi import FastAPIPlugin
+from .graphql_plugin import GraphQLPythonPlugin
+from .prefect_plugin import PrefectPlugin
+from .webhook_plugin import WebhookEventPlugin
+
+__all__ = [
+    "FastAPIPlugin",
+    "ClickPlugin",
+    "CeleryPlugin",
+    "DjangoPlugin",
+    "GraphQLPythonPlugin",
+    "PrefectPlugin",
+    "WebhookEventPlugin",
+]