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

apisec_code_bolt/frameworks/dotnet/grpc_plugin.py

@@ -0,0 +1,559 @@
+"""
+gRPC framework plugin (server-side).
+
+Detects gRPC service implementations built on top of:
+- `Grpc.Core`            — classic gRPC for .NET (Grpc.Core.Server)
+- `Grpc.AspNetCore.Server` — ASP.NET Core integration (AddGrpc / MapGrpcService)
+
+A gRPC service is a class that inherits from a `.proto`-generated
+abstract base whose name ends in `Base` (e.g. `Greeter.GreeterBase`).
+Each RPC is an `override` method that accepts a `ServerCallContext`.
+
+Routes are emitted with:
+- `method = POST`                 — gRPC is always POST over HTTP/2
+- `path   = /{package}.{Service}/{Method}` (wire path)
+- `kind   = grpc_unary | grpc_server_stream | grpc_client_stream | grpc_bidi_stream`
+- `tags   = ["grpc"]`
+
+Streaming is inferred from parameter types:
+- `IAsyncStreamReader<TReq>`  parameter → client streaming
+- `IServerStreamWriter<TRes>` parameter → server streaming
+- Both → bidirectional streaming
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import ClassVar
+
+from ...core.types import (
+    AuthDependencyType,
+    AuthSchemeType,
+    CodeLocation,
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    QualifiedName,
+)
+from ...parsing.base import ParsedClass, ParsedDecorator, ParsedFile, ParsedFunction
+from ...parsing.services import AnalysisContext
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedBody,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+_GRPC_IMPORTS: frozenset[str] = frozenset(
+    {
+        "Grpc.Core",
+        "Grpc.Core.Interceptors",
+        "Grpc.AspNetCore.Server",
+        "Grpc.AspNetCore.Server.ClientFactory",
+        "Google.Protobuf",
+    }
+)
+
+# Parameter type names that mark a method as a gRPC RPC override.
+_SERVER_CALL_CONTEXT = "ServerCallContext"
+
+# Generic-typed streaming parameter base names (before `<...>`).
+_CLIENT_STREAM_READER = "IAsyncStreamReader"
+_SERVER_STREAM_WRITER = "IServerStreamWriter"
+
+# Methods inherited from Object that may also be `override` — never RPCs.
+_OBJECT_METHOD_NAMES: frozenset[str] = frozenset(
+    {
+        "Equals",
+        "GetHashCode",
+        "ToString",
+        "Finalize",
+    }
+)
+
+_GENERIC_INNER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_\.]*<(.+)>\??$")
+
+
+def _extract_authorize_roles(dec: ParsedDecorator) -> list[str]:
+    """Extract comma-separated role names from [Authorize(Roles = "Admin,User")].
+
+    The C# parser stores named arguments in dec.arguments (a dict), not in
+    dec.positional_args.  Mirrors aspnet_plugin._extract_roles().
+    """
+    roles_val = dec.arguments.get("Roles", dec.arguments.get("roles", ""))
+    if not roles_val or not isinstance(roles_val, str):
+        return []
+    return [r.strip() for r in roles_val.split(",") if r.strip()]
+
+
+# Parsing `package foo.bar;` and `service Greeter { ... }` from .proto files.
+_PROTO_PACKAGE_RE = re.compile(r"^\s*package\s+([\w\.]+)\s*;", re.MULTILINE)
+_PROTO_SERVICE_RE = re.compile(r"^\s*service\s+(\w+)\s*\{", re.MULTILINE)
+
+
+# =============================================================================
+# GrpcPlugin
+# =============================================================================
+
+
+class GrpcPlugin(BaseFrameworkPlugin):
+    """Framework plugin for server-side gRPC services in C#."""
+
+    FRAMEWORK: ClassVar[Framework] = Framework.GRPC
+    LANGUAGE: ClassVar[Language] = Language.CSHARP
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = _GRPC_IMPORTS
+    DETECTION_IMPORT_PREFIXES: ClassVar[tuple[str, ...]] = ("Grpc.",)
+
+    def __init__(self) -> None:
+        # Maps str(project_root) → {service_name: proto_package}.
+        # Populated lazily on first extract_routes call per project, so
+        # back-to-back scans don't re-read every .proto file.
+        self._proto_packages_cache: dict[str, dict[str, str]] = {}
+
+    # -------------------------------------------------------------------------
+    # Detection
+    # -------------------------------------------------------------------------
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        for imp in parsed_file.imports:
+            module = imp.module or ""
+            if module.startswith("Grpc."):
+                return True
+        # Attribute-free fallback: a class extending *Base with an override
+        # method accepting ServerCallContext is almost certainly a gRPC service.
+        return any(self._is_grpc_service_by_shape(cls) for cls in parsed_file.classes)
+
+    # -------------------------------------------------------------------------
+    # Route extraction
+    # -------------------------------------------------------------------------
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        routes: list[ExtractedRoute] = []
+        proto_map = self._load_proto_packages(context)
+
+        for cls in parsed_file.classes:
+            if not self._is_grpc_service(cls):
+                continue
+
+            package, service = self._extract_service_id(cls, parsed_file, proto_map)
+
+            for method in cls.methods:
+                if not self._is_rpc_method(method):
+                    continue
+                route = self._extract_rpc_route(method, cls, package, service)
+                if route is not None:
+                    routes.append(route)
+
+        return routes
+
+    # -------------------------------------------------------------------------
+    # .proto-file discovery
+    # -------------------------------------------------------------------------
+
+    def _load_proto_packages(self, context: AnalysisContext | None) -> dict[str, str]:
+        """
+        Build `{service_name: proto_package}` by scanning the project for
+        `.proto` files.  Cached per project_root because extract_routes is
+        called once per C# file but the proto layout is shared across them.
+        """
+        if context is None or context.project_root is None:
+            return {}
+        key = str(context.project_root)
+        if key not in self._proto_packages_cache:
+            self._proto_packages_cache[key] = _scan_proto_files(context.project_root)
+        return self._proto_packages_cache[key]
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        """
+        Detect gRPC auth schemes.
+
+        gRPC services on ASP.NET Core use the same [Authorize] attribute as
+        regular controllers:
+        - AddJwtBearer calls → JWT_BEARER
+        - AddAuthentication / AddBearerToken calls → CUSTOM
+        - [Authorize] on service classes → CUSTOM
+        """
+        schemes: list[ExtractedAuthScheme] = []
+        seen: set[str] = set()
+
+        for call in parsed_file.call_sites:
+            name_lower = call.callee_name.lower()
+            line = call.location.line if call.location else 1
+            if name_lower == "addjwtbearer":
+                if "JwtBearer" not in seen:
+                    seen.add("JwtBearer")
+                    schemes.append(
+                        ExtractedAuthScheme(
+                            scheme_type=AuthSchemeType.JWT_BEARER,
+                            name="JwtBearer",
+                            location=CodeLocation(file=parsed_file.path, line=line),
+                            confidence=Confidence.HIGH,
+                        )
+                    )
+            elif name_lower in ("addauthentication", "addbearertoken"):
+                # AddBearerToken is the .NET 8 opaque bearer-token API, not JWT
+                if "Authentication" not in seen:
+                    seen.add("Authentication")
+                    schemes.append(
+                        ExtractedAuthScheme(
+                            scheme_type=AuthSchemeType.CUSTOM,
+                            name="GrpcAuthentication",
+                            location=CodeLocation(file=parsed_file.path, line=line),
+                            confidence=Confidence.MEDIUM,
+                        )
+                    )
+
+        # [Authorize] on gRPC service class → auth is active
+        for cls in parsed_file.classes:
+            if self._is_grpc_service(cls):
+                if any(d.name == "Authorize" for d in cls.decorators):
+                    if "Authorize" not in seen:
+                        seen.add("Authorize")
+                        schemes.append(
+                            ExtractedAuthScheme(
+                                scheme_type=AuthSchemeType.CUSTOM,
+                                name="GrpcAuthorize",
+                                location=cls.location
+                                or CodeLocation(file=parsed_file.path, line=1),
+                                confidence=Confidence.HIGH,
+                            )
+                        )
+
+        return schemes
+
+    def extract_auth_dependencies(
+        self, parsed_file: ParsedFile, known_scheme_names: set[str] | None = None, **kwargs
+    ) -> list[ExtractedAuthDependency]:
+        """
+        Extract [Authorize] and [AllowAnonymous] on gRPC service RPC methods.
+
+        Uses dec.arguments (named dict) not positional_args — the C# parser
+        stores [Authorize(Roles = "Admin,User")] as arguments["Roles"], not as
+        a positional arg. Mirrors the pattern in aspnet_plugin._extract_roles().
+        Only emits deps for methods that pass _is_rpc_method() to exclude
+        lifecycle / helper overrides.
+        """
+        deps: list[ExtractedAuthDependency] = []
+
+        for cls in parsed_file.classes:
+            if not self._is_grpc_service(cls):
+                continue
+
+            # Class-level [Authorize] / [AllowAnonymous]
+            class_roles: list[str] = []
+            class_has_authorize = False
+            class_is_anonymous = any(d.name == "AllowAnonymous" for d in cls.decorators)
+            if not class_is_anonymous:
+                for dec in cls.decorators:
+                    if dec.name == "Authorize":
+                        class_has_authorize = True
+                        class_roles.extend(_extract_authorize_roles(dec))
+
+            for method in cls.methods:
+                # Only RPC methods, not lifecycle overrides
+                if not self._is_rpc_method(method):
+                    continue
+
+                # Method-level [AllowAnonymous] takes precedence over class [Authorize]
+                if any(d.name == "AllowAnonymous" for d in method.decorators):
+                    continue
+
+                method_roles = list(class_roles)
+                has_method_authorize = False
+                for dec in method.decorators:
+                    if dec.name == "Authorize":
+                        has_method_authorize = True
+                        method_roles.extend(_extract_authorize_roles(dec))
+
+                # Skip if neither class nor method has any [Authorize]
+                if not class_has_authorize and not has_method_authorize:
+                    continue
+
+                handler = f"{cls.name}.{method.name}"
+                deps.append(
+                    ExtractedAuthDependency(
+                        name=handler,
+                        qualified_name=QualifiedName(module=parsed_file.path.stem, name=handler),
+                        location=method.location or CodeLocation(file=parsed_file.path, line=1),
+                        dependency_type=AuthDependencyType.ANNOTATION,
+                        uses_schemes=["GrpcAuthorize"],
+                        requires_roles=method_roles,
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+        return deps
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+    # -------------------------------------------------------------------------
+    # Service-class detection
+    # -------------------------------------------------------------------------
+
+    def _is_grpc_service(self, cls: ParsedClass) -> bool:
+        """A non-abstract class inheriting from a `*Base` parent."""
+        if not cls.base_classes:
+            return False
+        for base in cls.base_classes:
+            simple = base.rsplit(".", 1)[-1]
+            if simple.endswith("Base") and simple != "Base":
+                return True
+        return False
+
+    def _is_grpc_service_by_shape(self, cls: ParsedClass) -> bool:
+        """Detection fallback used when no `using Grpc.*` is present."""
+        if not self._is_grpc_service(cls):
+            return False
+        return any(self._is_rpc_method(m) for m in cls.methods)
+
+    def _is_rpc_method(self, method: ParsedFunction) -> bool:
+        if method.name in _OBJECT_METHOD_NAMES:
+            return False
+        # gRPC overrides always take ServerCallContext as their final parameter.
+        for param in method.parameters:
+            base = (param.type_annotation or "").split("<")[0].strip().rstrip("?")
+            if base.rsplit(".", 1)[-1] == _SERVER_CALL_CONTEXT:
+                return True
+        return False
+
+    # -------------------------------------------------------------------------
+    # Service-ID extraction
+    # -------------------------------------------------------------------------
+
+    def _extract_service_id(
+        self,
+        cls: ParsedClass,
+        parsed_file: ParsedFile,
+        proto_map: dict[str, str] | None = None,
+    ) -> tuple[str, str]:
+        """
+        Derive (proto_package, service_name) for emission of the wire path.
+
+        Strategy:
+        1. Inspect the base-class spelling.  `Helloworld.Greeter.GreeterBase`
+           → package=Helloworld, service=Greeter.
+           `Greeter.GreeterBase` (no package) → package="", service=Greeter.
+        2. Fall back to a service-name lookup in the `.proto`-derived package
+           map: that's where the *actual* wire-path package lives whenever
+           the .proto uses `option csharp_namespace = "...";` to decouple
+           C# from the proto package.
+        3. Last resort: file's C# namespace.
+        """
+        for base in cls.base_classes:
+            parts = base.split(".")
+            if not parts[-1].endswith("Base") or parts[-1] == "Base":
+                continue
+
+            # The conventional shape is `<Package>.<Service>.<Service>Base` or
+            # `<Service>.<Service>Base`.  Strip the trailing `Base` from the
+            # last part to recover the service name; everything before the
+            # second-to-last part is the package.
+            service_with_base = parts[-1]
+            service = service_with_base[: -len("Base")]
+
+            if len(parts) >= 2:
+                # `...<Service>.<Service>Base` (canonical) — strip both the
+                # trailing `*Base` and its preceding `<Service>` segment.
+                # Anything else keeps whatever's before the Base part.
+                preceding = parts[-2]
+                package = ".".join(parts[:-2]) if preceding == service else ".".join(parts[:-1])
+            else:
+                package = ""
+
+            if not package and proto_map:
+                package = proto_map.get(service, "")
+
+            if not package:
+                package = self._csharp_namespace(parsed_file) or ""
+
+            return package, service
+
+        return "", cls.name
+
+    def _csharp_namespace(self, parsed_file: ParsedFile) -> str | None:
+        ns = getattr(parsed_file, "namespace", None)
+        if isinstance(ns, str) and ns:
+            return ns
+        return None
+
+    # -------------------------------------------------------------------------
+    # Per-RPC emission
+    # -------------------------------------------------------------------------
+
+    def _extract_rpc_route(
+        self,
+        method: ParsedFunction,
+        cls: ParsedClass,
+        package: str,
+        service: str,
+    ) -> ExtractedRoute | None:
+        request_type, response_type, kind = self._classify_streaming(method)
+
+        path = f"/{package}.{service}/{method.name}" if package else f"/{service}/{method.name}"
+
+        body: ExtractedBody | None = None
+        if request_type:
+            body = ExtractedBody(
+                content_type="application/grpc",
+                model_name=request_type,
+                required=True,
+            )
+
+        response = ExtractedResponse(
+            status_code=200,
+            model_name=response_type,
+        )
+
+        handler_qname = method.qualified_name or QualifiedName(
+            module=cls.qualified_name.module if cls.qualified_name else "",
+            name=f"{cls.name}.{method.name}",
+        )
+
+        return ExtractedRoute(
+            method=HttpMethod.POST,
+            path=path,
+            handler_function=handler_qname,
+            handler_location=method.location,
+            path_params=[],
+            query_params=[],
+            header_params=[],
+            cookie_params=[],
+            body=body,
+            response=response,
+            tags=["grpc"],
+            dependency_refs=[],
+            confidence=Confidence.HIGH,
+            kind=kind,
+        )
+
+    def _classify_streaming(self, method: ParsedFunction) -> tuple[str | None, str | None, str]:
+        """
+        Return (request_model, response_model, kind) from method signature.
+
+        The four gRPC method shapes:
+        - Unary:               TRes Method(TReq req, ServerCallContext ctx)
+        - Server streaming:    Task  Method(TReq req, IServerStreamWriter<TRes> rs, ServerCallContext ctx)
+        - Client streaming:    Task<TRes> Method(IAsyncStreamReader<TReq> rs, ServerCallContext ctx)
+        - Bidi streaming:      Task  Method(IAsyncStreamReader<TReq> rr, IServerStreamWriter<TRes> rw, ServerCallContext ctx)
+        """
+        client_stream_req: str | None = None
+        server_stream_res: str | None = None
+        first_data_param_type: str | None = None
+
+        for param in method.parameters:
+            ty = (param.type_annotation or "").strip()
+            if not ty:
+                continue
+            base = ty.split("<")[0].strip()
+            simple = base.rsplit(".", 1)[-1]
+
+            if simple == _SERVER_CALL_CONTEXT:
+                continue
+            if simple == _CLIENT_STREAM_READER:
+                client_stream_req = _generic_inner(ty)
+                continue
+            if simple == _SERVER_STREAM_WRITER:
+                server_stream_res = _generic_inner(ty)
+                continue
+            if first_data_param_type is None:
+                first_data_param_type = ty
+
+        # Response: prefer the stream writer's type; otherwise unwrap Task<T>.
+        response_type = server_stream_res or _unwrap_task(method.return_type)
+
+        # Request: streaming reader's type wins; otherwise the first non-context param.
+        request_type = client_stream_req or first_data_param_type
+
+        if client_stream_req is not None and server_stream_res is not None:
+            kind = "grpc_bidi_stream"
+        elif client_stream_req is not None:
+            kind = "grpc_client_stream"
+        elif server_stream_res is not None:
+            kind = "grpc_server_stream"
+        else:
+            kind = "grpc_unary"
+
+        return request_type, response_type, kind
+
+
+# =============================================================================
+# Module-level helpers
+# =============================================================================
+
+
+def _scan_proto_files(root: Path) -> dict[str, str]:
+    """
+    Walk `root` for `*.proto` files and return `{service_name: package}`.
+
+    A service name is the identifier in `service Foo { ... }`; the
+    package is the value of the first `package …;` declaration in the
+    same file (or empty if none).  When a service name appears in more
+    than one proto, the first match wins — duplicates are rare in
+    practice (the canonical case is a `.proto` checked into both the
+    server and a client project; the package matches either way).
+    """
+    mapping: dict[str, str] = {}
+    try:
+        proto_paths = sorted(root.rglob("*.proto"))
+    except (OSError, ValueError):
+        return mapping
+
+    for proto in proto_paths:
+        try:
+            text = proto.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        pkg_match = _PROTO_PACKAGE_RE.search(text)
+        package = pkg_match.group(1) if pkg_match else ""
+        for service in _PROTO_SERVICE_RE.findall(text):
+            if service not in mapping:
+                mapping[service] = package
+    return mapping
+
+
+def _generic_inner(type_annotation: str) -> str | None:
+    """Return `T` from `Foo<T>` (handles trailing nullable `?`)."""
+    m = _GENERIC_INNER_RE.match(type_annotation.strip())
+    if m:
+        return m.group(1).strip()
+    return None
+
+
+def _unwrap_task(return_type: str | None) -> str | None:
+    """`Task<T>` / `ValueTask<T>` → `T`; `Task` / `void` → None."""
+    if not return_type:
+        return None
+    ret = return_type.strip()
+    for wrapper in ("Task<", "ValueTask<"):
+        if ret.startswith(wrapper) and ret.endswith(">"):
+            return ret[len(wrapper) : -1].strip() or None
+    if ret in ("Task", "ValueTask", "void"):
+        return None
+    return ret
+
+
+# =============================================================================
+# Self-registration
+# =============================================================================
+
+_grpc_plugin = GrpcPlugin()
+FrameworkPluginRegistry.register(_grpc_plugin)