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

apisec_code_bolt/frameworks/python/prefect_plugin.py

@@ -0,0 +1,251 @@
+"""
+Prefect workflow framework plugin.
+
+Detects flow and task entry points from Prefect 3.x decorator patterns.
+
+Supported:
+- @flow / @flow(name="...") — Prefect flow definitions
+- @task / @task(name="...") — Prefect task definitions
+- @prefect.flow / @prefect.task — qualified forms
+- Function parameter extraction as task arguments
+- Type annotation preservation (used by Prefect for Pydantic validation)
+
+Not supported (yet):
+- serve() / deploy() lifecycle methods
+- Prefect blocks (Secret, etc.) as data sources
+- Subflow detection (flow calling flow)
+- Task result caching semantics
+- Prefect events and automations
+- Work pool / worker configuration analysis
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from ...core.types import (
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+)
+from ...parsing.base import ParsedDecorator, ParsedFile, ParsedFunction
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+# ── Import detection ────────────────────────────────────────────────────────
+
+PREFECT_IMPORTS = frozenset({"prefect"})
+
+
+# ── Decorator name sets ─────────────────────────────────────────────────────
+
+FLOW_DECORATORS: set[str] = {
+    "flow",  # @flow (bare import)
+    "prefect.flow",  # @prefect.flow (qualified)
+}
+
+TASK_DECORATORS: set[str] = {
+    "task",  # @task (bare import)
+    "prefect.task",  # @prefect.task (qualified)
+}
+
+ALL_PREFECT_DECORATORS = FLOW_DECORATORS | TASK_DECORATORS
+
+
+# ── Plugin ──────────────────────────────────────────────────────────────────
+
+
+class PrefectPlugin(BaseFrameworkPlugin):
+    """Plugin for Prefect 3.x flow and task framework extraction."""
+
+    FRAMEWORK: ClassVar[Framework] = Framework.PREFECT
+    LANGUAGE: ClassVar[Language] = Language.PYTHON
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = PREFECT_IMPORTS
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        for imp in parsed_file.imports:
+            mod = (imp.module or "").split(".")[0]
+            if mod == "prefect":
+                return True
+            for name in imp.names:
+                if name in ("prefect", "flow", "task") and (
+                    imp.module is None or imp.module.split(".")[0] == "prefect"
+                ):
+                    return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Route (flow/task) extraction
+    # ------------------------------------------------------------------
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: Any = None,
+    ) -> list[ExtractedRoute]:
+        routes: list[ExtractedRoute] = []
+
+        for func in parsed_file.functions:
+            route = self._try_extract_entry_point(func)
+            if route:
+                routes.append(route)
+
+        for cls in parsed_file.classes:
+            for method in cls.methods:
+                route = self._try_extract_entry_point(method)
+                if route:
+                    routes.append(route)
+
+        return routes
+
+    # ------------------------------------------------------------------
+    # Stubs — Prefect has no HTTP auth/deps/middleware
+    # ------------------------------------------------------------------
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        return []
+
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        **kwargs: Any,
+    ) -> list[ExtractedAuthDependency]:
+        return []
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _try_extract_entry_point(
+        self,
+        func: ParsedFunction,
+    ) -> ExtractedRoute | None:
+        """If *func* has a @flow or @task decorator, return an ExtractedRoute."""
+        dec, is_flow = self._find_prefect_decorator(func)
+        if dec is None:
+            return None
+
+        entry_name = self._resolve_name(dec, func)
+        params = self._extract_parameters(func)
+
+        return ExtractedRoute(
+            kind="task",
+            method=HttpMethod.POST,
+            path=entry_name,
+            handler_function=func.qualified_name,
+            handler_location=func.location,
+            path_params=[],
+            query_params=params,
+            header_params=[],
+            cookie_params=[],
+            body=None,
+            response=ExtractedResponse(),
+            confidence=Confidence.HIGH,
+        )
+
+    def _find_prefect_decorator(
+        self,
+        func: ParsedFunction,
+    ) -> tuple[ParsedDecorator | None, bool]:
+        """Return (decorator, is_flow) if a Prefect decorator is found.
+
+        ``is_flow`` is True for @flow, False for @task.
+        """
+        for dec in func.decorators:
+            base = self._decorator_base_name(dec)
+            if base in FLOW_DECORATORS:
+                return dec, True
+            if base in TASK_DECORATORS:
+                return dec, False
+        return None, False
+
+    def _resolve_name(
+        self,
+        dec: ParsedDecorator,
+        func: ParsedFunction,
+    ) -> str:
+        """Derive the canonical flow/task name.
+
+        Priority: explicit ``name=`` kwarg > function name (no dash conversion).
+        """
+        explicit = self._extract_decorator_arg(dec, "name")
+        if explicit and isinstance(explicit, str):
+            return explicit
+        return func.qualified_name.full
+
+    def _extract_parameters(
+        self,
+        func: ParsedFunction,
+    ) -> list[ExtractedParameter]:
+        """Extract task/flow argument parameters from the function signature."""
+        params: list[ExtractedParameter] = []
+
+        for p in func.parameters:
+            if p.name in ("self", "cls"):
+                continue
+            if p.is_variadic or p.is_keyword_variadic:
+                continue
+
+            params.append(
+                ExtractedParameter(
+                    name=p.name,
+                    location=ParameterLocation.TASK_ARGUMENT,
+                    type_annotation=p.type_annotation,
+                    required=p.default_value is None,
+                    default_value=p.default_value,
+                )
+            )
+
+        return params
+
+    @staticmethod
+    def _decorator_base_name(dec: ParsedDecorator) -> str:
+        """Normalise a decorator to a lookup key.
+
+        Handles:
+        - ``prefect.flow`` / ``prefect.task`` (qualified)
+        - ``flow`` / ``task`` (bare import)
+        """
+        if dec.qualified_name:
+            qn = dec.qualified_name.full
+            parts = qn.rsplit(".", 1)
+            if len(parts) == 2:
+                mod, attr = parts
+                if mod == "prefect":
+                    return f"prefect.{attr}"
+                if attr in ("flow", "task"):
+                    return attr
+            return qn
+
+        name = dec.name
+        if "." in name:
+            _obj, _, attr = name.rpartition(".")
+            if attr in ("flow", "task"):
+                return attr
+        return name
+
+
+_prefect_plugin = PrefectPlugin()
+FrameworkPluginRegistry.register(_prefect_plugin)

apisec_code_bolt/frameworks/python/webhook_plugin.py

@@ -0,0 +1,255 @@
+"""
+Generic webhook and event handler plugin.
+
+Detects event-driven entry points across multiple frameworks and patterns.
+
+Supported constructs:
+- FastAPI/Starlette @app.on_event("startup") / @app.on_event("shutdown")
+- Django signals: @receiver(post_save, ...) — from django.dispatch
+- Generic webhook handlers: @app.webhook, @webhook_handler
+- Flask-SocketIO @socketio.on("event_name")
+- gidgethub Router: @router.register("event_type", action="...") — GitHub webhook bots
+- asyncio event loop callbacks (limited)
+
+Not supported (yet):
+- Django Channels consumers
+- AWS Lambda handler convention (def handler(event, context))
+- Cloud Functions / Azure Functions triggers
+- Pub/Sub subscription callbacks
+- Custom event bus implementations
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from ...core.types import (
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+)
+from ...parsing.base import ParsedDecorator, ParsedFile, ParsedFunction
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+# ── Decorator sets ──────────────────────────────────────────────────────────
+
+EVENT_DECORATORS: set[str] = {
+    "on_event",  # @app.on_event("startup")
+    "on",  # @socketio.on("message")
+    "receiver",  # Django signal: @receiver(post_save, ...)
+    "on_event_handler",
+}
+
+WEBHOOK_DECORATORS: set[str] = {
+    "webhook",  # @app.webhook(...)
+    "webhook_handler",
+}
+
+ALL_EVENT_DECORATORS = EVENT_DECORATORS | WEBHOOK_DECORATORS
+
+# FastAPI/Starlette lifecycle event names. These are not HTTP endpoints: they
+# run only during application startup/shutdown and cannot receive external
+# requests. They should be classified as kind="lifecycle" so downstream rules
+# (missing_auth, rate_limiting, etc.) can skip them.
+LIFECYCLE_EVENT_NAMES: set[str] = {
+    "startup",
+    "shutdown",
+    "lifespan",
+}
+
+
+class WebhookEventPlugin(BaseFrameworkPlugin):
+    """Generic plugin for webhook and event handler entry points."""
+
+    FRAMEWORK: ClassVar[Framework] = Framework.GENERIC
+    LANGUAGE: ClassVar[Language] = Language.PYTHON
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "django.dispatch",
+            "flask_socketio",
+            "gidgethub",
+        }
+    )
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        is_gidgethub = self._has_gidgethub_import(parsed_file)
+        for func in parsed_file.functions:
+            for dec in func.decorators:
+                base = self._decorator_base_name(dec)
+                if base in ALL_EVENT_DECORATORS:
+                    return True
+                if is_gidgethub and base == "register":
+                    return True
+        return False
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: Any = None,
+    ) -> list[ExtractedRoute]:
+        routes: list[ExtractedRoute] = []
+        is_gidgethub = self._has_gidgethub_import(parsed_file)
+
+        for func in parsed_file.functions:
+            route = self._try_extract_event(func, is_gidgethub=is_gidgethub)
+            if route:
+                routes.append(route)
+
+        for cls in parsed_file.classes:
+            for method in cls.methods:
+                route = self._try_extract_event(method, is_gidgethub=is_gidgethub)
+                if route:
+                    routes.append(route)
+
+        return routes
+
+    @staticmethod
+    def _has_gidgethub_import(parsed_file: ParsedFile) -> bool:
+        return any((imp.module or "").startswith("gidgethub") for imp in parsed_file.imports)
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        return []
+
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        **kwargs: Any,
+    ) -> list[ExtractedAuthDependency]:
+        return []
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+    def _try_extract_event(
+        self, func: ParsedFunction, *, is_gidgethub: bool = False
+    ) -> ExtractedRoute | None:
+        dec = self._find_event_decorator(func, is_gidgethub=is_gidgethub)
+        if dec is None:
+            return None
+
+        base = self._decorator_base_name(dec)
+        is_webhook = base in WEBHOOK_DECORATORS
+        is_gh_register = is_gidgethub and base == "register"
+        event_name = self._resolve_event_name(dec, func, is_gh_register=is_gh_register)
+        params = self._extract_parameters(func)
+
+        if is_webhook or is_gh_register:
+            kind = "webhook"
+        elif base == "on_event" and event_name in LIFECYCLE_EVENT_NAMES:
+            # FastAPI @app.on_event("startup"|"shutdown") — not an HTTP endpoint.
+            # The engine's missing_auth / rate_limiting rules must skip entry
+            # points with kind="lifecycle" since they cannot receive external
+            # requests.
+            kind = "lifecycle"
+        else:
+            kind = "event"
+
+        return ExtractedRoute(
+            kind=kind,
+            method=HttpMethod.POST,
+            path=event_name,
+            handler_function=func.qualified_name,
+            handler_location=func.location,
+            path_params=[],
+            query_params=params,
+            header_params=[],
+            cookie_params=[],
+            body=None,
+            response=ExtractedResponse(),
+            confidence=Confidence.MEDIUM,
+        )
+
+    def _find_event_decorator(
+        self, func: ParsedFunction, *, is_gidgethub: bool = False
+    ) -> ParsedDecorator | None:
+        for dec in func.decorators:
+            base = self._decorator_base_name(dec)
+            if base in ALL_EVENT_DECORATORS:
+                return dec
+            if is_gidgethub and base == "register":
+                return dec
+        return None
+
+    def _resolve_event_name(
+        self,
+        dec: ParsedDecorator,
+        func: ParsedFunction,
+        *,
+        is_gh_register: bool = False,
+    ) -> str:
+        if dec.positional_args:
+            first = dec.positional_args[0]
+            if isinstance(first, str):
+                event = first
+                if is_gh_register:
+                    # @router.register("pull_request", action="opened") →
+                    # emit "pull_request:opened" so distinct actions are separate routes.
+                    action = dec.arguments.get("action")
+                    if action and isinstance(action, str):
+                        event = f"{event}:{action}"
+                return event
+        explicit = self._extract_decorator_arg(dec, "name")
+        if explicit and isinstance(explicit, str):
+            return explicit
+        signal_arg = self._extract_decorator_arg(dec, "signal")
+        if signal_arg and isinstance(signal_arg, str):
+            return signal_arg
+        return func.name
+
+    def _extract_parameters(self, func: ParsedFunction) -> list[ExtractedParameter]:
+        params: list[ExtractedParameter] = []
+        for p in func.parameters:
+            if p.name in ("self", "cls", "sender", "signal", "**kwargs"):
+                continue
+            if p.is_variadic or p.is_keyword_variadic:
+                continue
+            params.append(
+                ExtractedParameter(
+                    name=p.name,
+                    location=ParameterLocation.TASK_ARGUMENT,
+                    type_annotation=p.type_annotation,
+                    required=p.default_value is None,
+                    default_value=p.default_value,
+                )
+            )
+        return params
+
+    @staticmethod
+    def _decorator_base_name(dec: ParsedDecorator) -> str:
+        if dec.qualified_name:
+            qn = dec.qualified_name.full
+            parts = qn.rsplit(".", 1)
+            if len(parts) == 2:
+                _, attr = parts
+                # Return the attribute name for known decorators and for
+                # `register` (gidgethub Router pattern).
+                if attr in ALL_EVENT_DECORATORS or attr == "register":
+                    return attr
+            return qn
+
+        name = dec.name
+        if "." in name:
+            _obj, _, attr = name.rpartition(".")
+            if attr in ALL_EVENT_DECORATORS or attr == "register":
+                return attr
+        return name
+
+
+_webhook_plugin = WebhookEventPlugin()
+FrameworkPluginRegistry.register(_webhook_plugin)

apisec_code_bolt/parsing/__init__.py

@@ -0,0 +1,62 @@
+"""Language-specific parsing modules."""
+
+from .base import (
+    BaseParser,
+    ParsedArgument,
+    ParsedAssignment,
+    ParsedCallSite,
+    ParsedClass,
+    ParsedDecorator,
+    ParsedFile,
+    ParsedFunction,
+    ParsedImport,
+    ParsedParameter,
+    ParsedSymbol,
+    ParserRegistry,
+)
+from .services import (
+    # Data types
+    AnalysisContext,
+    ConstantResolver,
+    # Abstract base
+    LanguageServices,
+    PathResolver,
+    ResolvedConstant,
+    ResolvedField,
+    ResolvedPath,
+    ResolvedType,
+    RouterInfo,
+    RouterRegistry,
+    # Protocols
+    TypeResolver,
+)
+
+__all__ = [
+    # Base parsing
+    "BaseParser",
+    "ParserRegistry",
+    "ParsedFile",
+    "ParsedFunction",
+    "ParsedClass",
+    "ParsedImport",
+    "ParsedCallSite",
+    "ParsedArgument",
+    "ParsedAssignment",
+    "ParsedSymbol",
+    "ParsedParameter",
+    "ParsedDecorator",
+    # Service protocols
+    "TypeResolver",
+    "ConstantResolver",
+    "PathResolver",
+    "RouterRegistry",
+    # Service data types
+    "AnalysisContext",
+    "ResolvedType",
+    "ResolvedField",
+    "ResolvedConstant",
+    "ResolvedPath",
+    "RouterInfo",
+    # Language services
+    "LanguageServices",
+]