bubble-analysis 0.2.0__py3-none-any.whl

bubble/integrations/fastapi/detector.py

@@ -0,0 +1,176 @@
+"""FastAPI route and exception handler detection."""
+
+import libcst as cst
+from libcst.metadata import MetadataWrapper, PositionProvider
+
+from bubble.enums import EntrypointKind, Framework
+from bubble.integrations.base import Entrypoint, GlobalHandler
+
+
+class FastAPIRouteVisitor(cst.CSTVisitor):
+    """Detects FastAPI route decorators (@router.get, @router.post, etc.)."""
+
+    METADATA_DEPENDENCIES = (PositionProvider,)
+
+    HTTP_METHODS = {"get", "post", "put", "delete", "patch", "options", "head"}
+
+    def __init__(self, file_path: str) -> None:
+        self.file_path = file_path
+        self.entrypoints: list[Entrypoint] = []
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:
+        for decorator in node.decorators:
+            route_info = self._parse_route_decorator(decorator)
+            if route_info:
+                pos = self.get_metadata(PositionProvider, node)
+                self.entrypoints.append(
+                    Entrypoint(
+                        file=self.file_path,
+                        function=node.name.value,
+                        line=pos.start.line,
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        metadata={
+                            "http_method": route_info["method"],
+                            "http_path": route_info["path"],
+                            "framework": Framework.FASTAPI,
+                        },
+                    )
+                )
+        return True
+
+    def _parse_route_decorator(self, decorator: cst.Decorator) -> dict[str, str] | None:
+        if not isinstance(decorator.decorator, cst.Call):
+            return None
+
+        call = decorator.decorator
+
+        if not isinstance(call.func, cst.Attribute):
+            return None
+
+        method_name = call.func.attr.value.lower()
+        if method_name not in self.HTTP_METHODS:
+            return None
+
+        path = None
+        if call.args:
+            first_arg = call.args[0]
+            if isinstance(first_arg.value, cst.SimpleString):
+                path = first_arg.value.evaluated_value
+
+        if path:
+            return {"path": path, "method": method_name.upper()}
+        return None
+
+
+class FastAPIExceptionHandlerVisitor(cst.CSTVisitor):
+    """Detects FastAPI exception handlers.
+
+    Detects both patterns:
+    - app.add_exception_handler(ExceptionType, handler_func)
+    - @app.exception_handler(ExceptionType) decorator
+    """
+
+    METADATA_DEPENDENCIES = (PositionProvider,)
+
+    def __init__(self, file_path: str) -> None:
+        self.file_path = file_path
+        self.handlers: list[GlobalHandler] = []
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:
+        for decorator in node.decorators:
+            handler_info = self._parse_exception_handler_decorator(decorator)
+            if handler_info:
+                pos = self.get_metadata(PositionProvider, node)
+                self.handlers.append(
+                    GlobalHandler(
+                        file=self.file_path,
+                        line=pos.start.line,
+                        function=node.name.value,
+                        handled_type=handler_info,
+                    )
+                )
+        return True
+
+    def _parse_exception_handler_decorator(self, decorator: cst.Decorator) -> str | None:
+        if not isinstance(decorator.decorator, cst.Call):
+            return None
+
+        call = decorator.decorator
+        if not isinstance(call.func, cst.Attribute):
+            return None
+
+        if call.func.attr.value != "exception_handler":
+            return None
+
+        if not call.args:
+            return None
+
+        return self._get_name_from_expr(call.args[0].value)
+
+    def visit_Call(self, node: cst.Call) -> bool:
+        if not isinstance(node.func, cst.Attribute):
+            return True
+        if node.func.attr.value != "add_exception_handler":
+            return True
+        if len(node.args) < 2:
+            return True
+
+        exception_type = self._get_name_from_expr(node.args[0].value)
+        handler_name = self._get_name_from_expr(node.args[1].value)
+
+        if exception_type and handler_name:
+            pos = self.get_metadata(PositionProvider, node)
+            self.handlers.append(
+                GlobalHandler(
+                    file=self.file_path,
+                    line=pos.start.line,
+                    function=handler_name,
+                    handled_type=exception_type,
+                )
+            )
+
+        return True
+
+    def _get_name_from_expr(self, expr: cst.BaseExpression) -> str:
+        if isinstance(expr, cst.Name):
+            return expr.value
+        elif isinstance(expr, cst.Attribute):
+            base = self._get_name_from_expr(expr.value)
+            if base:
+                return f"{base}.{expr.attr.value}"
+            return expr.attr.value
+        return ""
+
+
+def detect_fastapi_entrypoints(source: str, file_path: str) -> list[Entrypoint]:
+    """Detect FastAPI route entrypoints in a Python source file."""
+    try:
+        module = cst.parse_module(source)
+    except Exception:
+        return []
+
+    wrapper = MetadataWrapper(module)
+    visitor = FastAPIRouteVisitor(file_path)
+
+    try:
+        wrapper.visit(visitor)
+        return visitor.entrypoints
+    except Exception:
+        return []
+
+
+def detect_fastapi_global_handlers(source: str, file_path: str) -> list[GlobalHandler]:
+    """Detect FastAPI exception handlers in a Python source file."""
+    try:
+        module = cst.parse_module(source)
+    except Exception:
+        return []
+
+    wrapper = MetadataWrapper(module)
+    visitor = FastAPIExceptionHandlerVisitor(file_path)
+
+    try:
+        wrapper.visit(visitor)
+        return visitor.handlers
+    except Exception:
+        return []

bubble/integrations/fastapi/semantics.py

@@ -0,0 +1,14 @@
+"""FastAPI exception-to-HTTP-response mappings.
+
+Defines which exceptions FastAPI converts to HTTP responses automatically.
+"""
+
+EXCEPTION_RESPONSES: dict[str, str] = {
+    "fastapi.HTTPException": "HTTP {status_code}",
+    "HTTPException": "HTTP {status_code}",
+    "starlette.exceptions.HTTPException": "HTTP {status_code}",
+    "pydantic.ValidationError": "HTTP 422",
+    "pydantic_core.ValidationError": "HTTP 422",
+    "ValidationError": "HTTP 422",
+    "RequestValidationError": "HTTP 422",
+}

bubble/integrations/flask/__init__.py

@@ -0,0 +1,57 @@
+"""Flask framework integration for flow analysis."""
+
+import typer
+
+from bubble.integrations.base import Entrypoint, GlobalHandler
+from bubble.integrations.flask.detector import (
+    FlaskErrorHandlerVisitor,
+    FlaskRouteVisitor,
+    detect_flask_entrypoints,
+    detect_flask_global_handlers,
+)
+from bubble.integrations.flask.semantics import EXCEPTION_RESPONSES
+from bubble.integrations.models import IntegrationData
+
+
+class FlaskIntegration:
+    """Flask framework integration."""
+
+    @property
+    def name(self) -> str:
+        return "flask"
+
+    @property
+    def cli_app(self) -> typer.Typer:
+        from bubble.integrations.flask.cli import app
+
+        return app
+
+    def detect_entrypoints(self, source: str, file_path: str) -> list[Entrypoint]:
+        return detect_flask_entrypoints(source, file_path)
+
+    def detect_global_handlers(self, source: str, file_path: str) -> list[GlobalHandler]:
+        return detect_flask_global_handlers(source, file_path)
+
+    def get_exception_response(self, exception_type: str) -> str | None:
+        exc_simple = exception_type.split(".")[-1]
+        for handled_type, response in EXCEPTION_RESPONSES.items():
+            handled_simple = handled_type.split(".")[-1]
+            if exc_simple == handled_simple or exception_type == handled_type:
+                return response
+        return None
+
+    def extract_integration_data(self, source: str, file_path: str) -> IntegrationData:
+        return IntegrationData(
+            entrypoints=self.detect_entrypoints(source, file_path),
+            global_handlers=self.detect_global_handlers(source, file_path),
+        )
+
+
+__all__ = [
+    "FlaskIntegration",
+    "FlaskRouteVisitor",
+    "FlaskErrorHandlerVisitor",
+    "EXCEPTION_RESPONSES",
+    "detect_flask_entrypoints",
+    "detect_flask_global_handlers",
+]

bubble/integrations/flask/cli.py

@@ -0,0 +1,110 @@
+"""CLI commands for Flask integration (flow flask ...)."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from bubble.enums import Framework, OutputFormat
+from bubble.extractor import extract_from_directory
+from bubble.integrations import formatters
+from bubble.integrations.flask import FlaskIntegration
+from bubble.integrations.queries import (
+    audit_integration,
+    list_integration_entrypoints,
+    trace_routes_to_exception,
+)
+from bubble.models import ProgramModel
+
+app = typer.Typer(
+    name="flask",
+    help="Flask framework-specific commands.",
+    no_args_is_help=True,
+)
+
+console = Console()
+integration = FlaskIntegration()
+
+
+def _build_model(directory: Path, use_cache: bool = True) -> ProgramModel:
+    """Build the program model from a directory."""
+    with console.status(f"[bold blue]Analyzing[/bold blue] {directory.name}/..."):
+        return extract_from_directory(directory, use_cache=use_cache)
+
+
+def _get_flask_entrypoints_and_handlers(model: ProgramModel) -> tuple[list, list]:
+    """Get Flask entrypoints and global handlers from the model."""
+    entrypoints = [e for e in model.entrypoints if e.metadata.get("framework") == Framework.FLASK]
+    handlers = model.global_handlers
+    return entrypoints, handlers
+
+
+@app.command()
+def audit(
+    directory: Annotated[
+        Path, typer.Option("--directory", "-d", help="Directory to analyze")
+    ] = Path("."),
+    output_format: Annotated[str, typer.Option("--format", "-f", help="Output format")] = "text",
+    no_cache: Annotated[bool, typer.Option("--no-cache", help="Disable caching")] = False,
+) -> None:
+    """Check Flask routes for escaping exceptions.
+
+    Scans every Flask HTTP route, reports which have uncaught exceptions.
+
+    Example:
+        flow flask audit
+        flow flask audit -d /path/to/project
+    """
+    directory = directory.resolve()
+    model = _build_model(directory, use_cache=not no_cache)
+    entrypoints, handlers = _get_flask_entrypoints_and_handlers(model)
+    result = audit_integration(model, integration, entrypoints, handlers)
+    formatters.audit(result, OutputFormat(output_format), directory, console)
+
+
+@app.command(name="entrypoints")
+def list_routes(
+    directory: Annotated[
+        Path, typer.Option("--directory", "-d", help="Directory to analyze")
+    ] = Path("."),
+    output_format: Annotated[str, typer.Option("--format", "-f", help="Output format")] = "text",
+    no_cache: Annotated[bool, typer.Option("--no-cache", help="Disable caching")] = False,
+) -> None:
+    """List Flask HTTP routes.
+
+    Example:
+        flow flask entrypoints
+    """
+    directory = directory.resolve()
+    model = _build_model(directory, use_cache=not no_cache)
+    entrypoints, _ = _get_flask_entrypoints_and_handlers(model)
+    result = list_integration_entrypoints(integration, entrypoints)
+    formatters.entrypoints(result, OutputFormat(output_format), directory, console)
+
+
+@app.command(name="routes-to")
+def routes_to(
+    exception_type: Annotated[str, typer.Argument(help="Exception type to trace")],
+    directory: Annotated[
+        Path, typer.Option("--directory", "-d", help="Directory to analyze")
+    ] = Path("."),
+    include_subclasses: Annotated[
+        bool, typer.Option("--include-subclasses", "-s", help="Include subclasses")
+    ] = False,
+    output_format: Annotated[str, typer.Option("--format", "-f", help="Output format")] = "text",
+    no_cache: Annotated[bool, typer.Option("--no-cache", help="Disable caching")] = False,
+) -> None:
+    """Trace which Flask routes can trigger a given exception.
+
+    Example:
+        flow flask routes-to ValueError
+        flow flask routes-to DatabaseError -s
+    """
+    directory = directory.resolve()
+    model = _build_model(directory, use_cache=not no_cache)
+    entrypoints, _ = _get_flask_entrypoints_and_handlers(model)
+    result = trace_routes_to_exception(
+        model, integration, entrypoints, exception_type, include_subclasses
+    )
+    formatters.routes_to(result, OutputFormat(output_format), directory, console)

bubble/integrations/flask/detector.py

@@ -0,0 +1,191 @@
+"""Flask route and error handler detection."""
+
+import libcst as cst
+from libcst.metadata import MetadataWrapper, PositionProvider
+
+from bubble.enums import EntrypointKind, Framework
+from bubble.integrations.base import Entrypoint, GlobalHandler
+
+
+class FlaskRouteVisitor(cst.CSTVisitor):
+    """
+    Detects Flask route decorators.
+
+    Supports:
+    - @app.route, @blueprint.route (standard Flask)
+    - @expose (Flask-AppBuilder)
+    """
+
+    METADATA_DEPENDENCIES = (PositionProvider,)
+
+    ROUTE_DECORATOR_NAMES = {"route", "expose"}
+
+    def __init__(self, file_path: str) -> None:
+        self.file_path = file_path
+        self.entrypoints: list[Entrypoint] = []
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:
+        for decorator in node.decorators:
+            route_info = self._parse_route_decorator(decorator)
+            if route_info:
+                pos = self.get_metadata(PositionProvider, node)
+                self.entrypoints.append(
+                    Entrypoint(
+                        file=self.file_path,
+                        function=node.name.value,
+                        line=pos.start.line,
+                        kind=EntrypointKind.HTTP_ROUTE,
+                        metadata={
+                            "http_method": route_info["method"],
+                            "http_path": route_info["path"],
+                            "framework": Framework.FLASK,
+                        },
+                    )
+                )
+        return True
+
+    def _parse_route_decorator(self, decorator: cst.Decorator) -> dict[str, str] | None:
+        if not isinstance(decorator.decorator, cst.Call):
+            return None
+
+        call = decorator.decorator
+
+        if isinstance(call.func, cst.Attribute):
+            if call.func.attr.value not in self.ROUTE_DECORATOR_NAMES:
+                return None
+        elif isinstance(call.func, cst.Name):
+            if call.func.value not in self.ROUTE_DECORATOR_NAMES:
+                return None
+        else:
+            return None
+
+        path = None
+        if call.args:
+            first_arg = call.args[0]
+            if isinstance(first_arg.value, cst.SimpleString):
+                path = first_arg.value.evaluated_value
+            elif isinstance(first_arg.value, cst.ConcatenatedString):
+                parts = []
+                for part in first_arg.value.left, first_arg.value.right:
+                    if isinstance(part, cst.SimpleString):
+                        parts.append(part.evaluated_value)
+                path = "".join(parts) if parts else None
+
+        methods = ["GET"]
+        for arg in call.args:
+            if arg.keyword and arg.keyword.value == "methods":
+                methods = self._extract_methods(arg.value)
+
+        if path:
+            return {"path": path, "method": methods[0] if methods else "GET"}
+        return None
+
+    def _extract_methods(self, value: cst.BaseExpression) -> list[str]:
+        """
+        Extract HTTP methods from a list or tuple.
+
+        Handles both Flask-style lists and Flask-AppBuilder-style tuples:
+        - methods=["GET", "POST"]
+        - methods=("GET", "POST")
+        """
+        methods: list[str] = []
+        if isinstance(value, cst.List | cst.Tuple):
+            for el in value.elements:
+                if isinstance(el, cst.Element) and isinstance(el.value, cst.SimpleString):
+                    extracted = el.value.evaluated_value
+                    if extracted:
+                        methods.append(extracted)
+        return methods if methods else ["GET"]
+
+
+class FlaskErrorHandlerVisitor(cst.CSTVisitor):
+    """Detects Flask error handlers (@app.errorhandler, @blueprint.errorhandler)."""
+
+    METADATA_DEPENDENCIES = (PositionProvider,)
+
+    def __init__(self, file_path: str) -> None:
+        self.file_path = file_path
+        self.handlers: list[GlobalHandler] = []
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:
+        for decorator in node.decorators:
+            handler_info = self._parse_errorhandler_decorator(decorator)
+            if handler_info:
+                pos = self.get_metadata(PositionProvider, node)
+                self.handlers.append(
+                    GlobalHandler(
+                        file=self.file_path,
+                        line=pos.start.line,
+                        function=node.name.value,
+                        handled_type=handler_info["exception_type"],
+                    )
+                )
+        return True
+
+    def _parse_errorhandler_decorator(self, decorator: cst.Decorator) -> dict[str, str] | None:
+        if not isinstance(decorator.decorator, cst.Call):
+            return None
+
+        call = decorator.decorator
+
+        if isinstance(call.func, cst.Attribute):
+            if call.func.attr.value != "errorhandler":
+                return None
+        elif isinstance(call.func, cst.Name):
+            if call.func.value != "errorhandler":
+                return None
+        else:
+            return None
+
+        if not call.args:
+            return None
+
+        first_arg = call.args[0].value
+        exception_type = self._get_name_from_expr(first_arg)
+        if exception_type:
+            return {"exception_type": exception_type}
+        return None
+
+    def _get_name_from_expr(self, expr: cst.BaseExpression) -> str:
+        if isinstance(expr, cst.Name):
+            return expr.value
+        elif isinstance(expr, cst.Attribute):
+            base = self._get_name_from_expr(expr.value)
+            if base:
+                return f"{base}.{expr.attr.value}"
+            return expr.attr.value
+        return ""
+
+
+def detect_flask_entrypoints(source: str, file_path: str) -> list[Entrypoint]:
+    """Detect Flask route entrypoints in a Python source file."""
+    try:
+        module = cst.parse_module(source)
+    except Exception:
+        return []
+
+    wrapper = MetadataWrapper(module)
+    visitor = FlaskRouteVisitor(file_path)
+
+    try:
+        wrapper.visit(visitor)
+        return visitor.entrypoints
+    except Exception:
+        return []
+
+
+def detect_flask_global_handlers(source: str, file_path: str) -> list[GlobalHandler]:
+    """Detect Flask error handlers in a Python source file."""
+    try:
+        module = cst.parse_module(source)
+    except Exception:
+        return []
+
+    wrapper = MetadataWrapper(module)
+    visitor = FlaskErrorHandlerVisitor(file_path)
+
+    try:
+        wrapper.visit(visitor)
+        return visitor.handlers
+    except Exception:
+        return []

bubble/integrations/flask/semantics.py

@@ -0,0 +1,19 @@
+"""Flask exception-to-HTTP-response mappings.
+
+Defines which exceptions Flask converts to HTTP responses automatically.
+"""
+
+EXCEPTION_RESPONSES: dict[str, str] = {
+    "werkzeug.exceptions.HTTPException": "HTTP {code}",
+    "HTTPException": "HTTP {code}",
+    "werkzeug.exceptions.NotFound": "HTTP 404",
+    "NotFound": "HTTP 404",
+    "werkzeug.exceptions.BadRequest": "HTTP 400",
+    "BadRequest": "HTTP 400",
+    "werkzeug.exceptions.Unauthorized": "HTTP 401",
+    "Unauthorized": "HTTP 401",
+    "werkzeug.exceptions.Forbidden": "HTTP 403",
+    "Forbidden": "HTTP 403",
+    "werkzeug.exceptions.InternalServerError": "HTTP 500",
+    "InternalServerError": "HTTP 500",
+}