dopesecurity-mcp-server 0.1.0__py3-none-any.whl

dopesecurity/__init__.py

@@ -0,0 +1 @@
+"""dope.security Python packages."""

dopesecurity/mcp_server/__init__.py

@@ -0,0 +1,5 @@
+"""dope.security MCP server."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

dopesecurity/mcp_server/__main__.py

@@ -0,0 +1,135 @@
+"""Console entry point for the dope.security MCP server."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+import structlog
+
+from dopesecurity.mcp_server.config import (
+    CliConfigOverrides,
+    configure_logging,
+    load_settings,
+)
+
+LOG_LEVEL_CHOICES = ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dopesecurity-mcp-server",
+        description=(
+            "Local MCP server for the dope.security Flightdeck partner API. "
+            "Reads credentials from DOPE_CLIENT_ID and DOPE_CLIENT_SECRET."
+        ),
+    )
+    parser.add_argument(
+        "--enable-mutations",
+        action="store_true",
+        default=None,
+        help="Expose write tools that modify tenant state.",
+    )
+    parser.add_argument(
+        "--enable-destructive",
+        action="store_true",
+        default=None,
+        help=(
+            "Additionally expose destructive tools that drop a whole policy or "
+            "custom category, or reset whole sections to base. Requires "
+            "--enable-mutations."
+        ),
+    )
+    parser.add_argument(
+        "--timeout-seconds",
+        type=float,
+        default=None,
+        metavar="FLOAT",
+        help="HTTP timeout for Flightdeck calls in seconds.",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=LOG_LEVEL_CHOICES,
+        default=None,
+        help="Logging verbosity. Logs are written to stderr.",
+    )
+    parser.add_argument(
+        "--log-file",
+        type=str,
+        default=None,
+        metavar="PATH",
+        help=(
+            "If set, also append JSON logs to this file (handy when running "
+            "under MCP Inspector, which hides server stderr)."
+        ),
+    )
+    parser.add_argument(
+        "--token-refresh-skew-seconds",
+        type=float,
+        default=None,
+        metavar="FLOAT",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--base-url",
+        type=str,
+        default=None,
+        metavar="URL",
+        help=argparse.SUPPRESS,
+    )
+    return parser
+
+
+def _overrides_from_args(args: argparse.Namespace) -> CliConfigOverrides:
+    return CliConfigOverrides(
+        enable_mutations=args.enable_mutations,
+        enable_destructive=args.enable_destructive,
+        timeout_seconds=args.timeout_seconds,
+        log_level=args.log_level,
+        token_refresh_skew_seconds=args.token_refresh_skew_seconds,
+        base_url=args.base_url,
+        log_file=args.log_file,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    overrides = _overrides_from_args(args)
+    settings = load_settings(overrides)
+    configure_logging(settings.log_level, log_file=settings.log_file)
+
+    log = structlog.get_logger("dopesecurity.mcp_server.main")
+    # WARNING: client_id and base url logged in clear text on purpose for
+    # debugging credential issues; tighten before production.
+    log.info(
+        "main.startup",
+        log_level=settings.log_level,
+        api_base_url=settings.api_base_url,
+        enable_mutations=settings.enable_mutations,
+        enable_destructive=settings.enable_destructive,
+        timeout_seconds=settings.timeout_seconds,
+        token_refresh_skew_seconds=settings.token_refresh_skew_seconds,
+        client_id=settings.client_id,
+        client_secret_set=bool(settings.client_secret.get_secret_value()),
+        client_secret_length=len(settings.client_secret.get_secret_value()),
+    )
+
+    # Imported lazily so --help does not require constructing FastMCP.
+    from dopesecurity.mcp_server.server import create_server
+
+    try:
+        mcp = create_server(settings)
+        mcp.run()
+    except Exception as exc:
+        log.exception(
+            "main.fatal",
+            exc_type=type(exc).__name__,
+            exc_message=str(exc),
+        )
+        raise
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised via console script
+    raise SystemExit(main())

dopesecurity/mcp_server/auth.py

@@ -0,0 +1,209 @@
+"""Flightdeck OAuth client-credentials token manager."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import structlog
+
+from dopesecurity.mcp_server.config import Settings
+from dopesecurity.mcp_server.errors import (
+    FlightdeckAuthenticationError,
+    FlightdeckServerError,
+    FlightdeckTransportError,
+)
+from dopesecurity.mcp_server.flightdeck.models import TokenResponse  # noqa: TID252
+
+TOKEN_PATH = "/partner/oauth/token"
+
+
+@dataclass
+class CachedToken:
+    access_token: str
+    expires_at_monotonic: float
+
+    def is_expired(self, *, now: float) -> bool:
+        return now >= self.expires_at_monotonic
+
+
+class FlightdeckTokenManager:
+    """Caches a Flightdeck bearer token and refreshes it before expiry."""
+
+    def __init__(
+        self,
+        http: httpx.AsyncClient,
+        settings: Settings,
+        logger: structlog.stdlib.BoundLogger | None = None,
+    ) -> None:
+        self._http = http
+        self._settings = settings
+        self._logger = logger or structlog.get_logger("dopesecurity.mcp_server.auth")
+        self._lock = asyncio.Lock()
+        self._cached: CachedToken | None = None
+
+    def invalidate(self) -> None:
+        """Discard the cached token so the next call exchanges credentials again."""
+
+        self._logger.info("auth.token.invalidate", had_cached=self._cached is not None)
+        self._cached = None
+
+    async def get_token(self, *, force_refresh: bool = False) -> str:
+        if not force_refresh:
+            current = self._cached
+            if current is not None and not current.is_expired(now=time.monotonic()):
+                self._logger.debug(
+                    "auth.token.cache_hit",
+                    expires_in=max(current.expires_at_monotonic - time.monotonic(), 0.0),
+                )
+                return current.access_token
+
+        async with self._lock:
+            if not force_refresh:
+                current = self._cached
+                if current is not None and not current.is_expired(now=time.monotonic()):
+                    self._logger.debug("auth.token.cache_hit_after_lock")
+                    return current.access_token
+            self._logger.info(
+                "auth.token.exchange_start",
+                force_refresh=force_refresh,
+                base_url=str(self._http.base_url),
+                token_path=TOKEN_PATH,
+                client_id=self._settings.client_id,
+            )
+            token = await self._exchange()
+            self._cached = token
+            self._logger.info(
+                "auth.token.exchange_success",
+                expires_at_monotonic=token.expires_at_monotonic,
+                seconds_until_expiry=max(
+                    token.expires_at_monotonic - time.monotonic(), 0.0
+                ),
+            )
+            return token.access_token
+
+    async def _exchange(self) -> CachedToken:
+        body = {
+            "grant_type": "client_credentials",
+            "client_id": self._settings.client_id,
+            "client_secret": self._settings.client_secret.get_secret_value(),
+        }
+        # WARNING: logging the full body (including the client_secret) is
+        # intentional for credential debugging; remove before production.
+        self._logger.debug(
+            "auth.token.request",
+            url=str(httpx.URL(self._http.base_url).join(TOKEN_PATH)),
+            body=body,
+        )
+        try:
+            response = await self._http.post(TOKEN_PATH, json=body)
+        except httpx.TransportError as exc:
+            self._logger.exception(
+                "auth.token.transport_error",
+                exc_type=type(exc).__name__,
+                exc_message=str(exc),
+                request_url=str(getattr(exc, "request", None) and exc.request.url),
+            )
+            raise FlightdeckTransportError(
+                f"Failed to reach Flightdeck token endpoint: {type(exc).__name__}: {exc}"
+            ) from exc
+        except Exception as exc:  # noqa: BLE001 - log everything else too
+            self._logger.exception(
+                "auth.token.unexpected_request_error",
+                exc_type=type(exc).__name__,
+                exc_message=str(exc),
+            )
+            raise
+
+        # WARNING: response body and headers may contain tokens or hints
+        # about credential failures; logged on purpose for debugging.
+        self._logger.info(
+            "auth.token.response",
+            status=response.status_code,
+            headers=dict(response.headers),
+            body_text=response.text,
+            body_json=_safe_json(response),
+        )
+
+        if response.status_code in (400, 401, 403):
+            details = _safe_json(response)
+            self._logger.error(
+                "auth.token.rejected",
+                status=response.status_code,
+                details=details,
+                body_text=response.text,
+            )
+            raise FlightdeckAuthenticationError(
+                f"Flightdeck rejected the client credentials (status {response.status_code}): "
+                f"{response.text}",
+                details=details,
+            )
+        if response.status_code >= 500:
+            details = _safe_json(response)
+            self._logger.error(
+                "auth.token.server_error",
+                status=response.status_code,
+                details=details,
+                body_text=response.text,
+            )
+            raise FlightdeckServerError(
+                f"Flightdeck token endpoint returned a server error (status "
+                f"{response.status_code}): {response.text}",
+                details=details,
+            )
+        if response.status_code != 200:
+            details = _safe_json(response)
+            self._logger.error(
+                "auth.token.unexpected_status",
+                status=response.status_code,
+                details=details,
+                body_text=response.text,
+            )
+            raise FlightdeckAuthenticationError(
+                f"Unexpected token response status {response.status_code}: {response.text}",
+                details=details,
+            )
+
+        try:
+            parsed = TokenResponse.model_validate(response.json())
+        except Exception as exc:  # noqa: BLE001 - normalize parse failures
+            self._logger.exception(
+                "auth.token.parse_failed",
+                exc_type=type(exc).__name__,
+                exc_message=str(exc),
+                body_text=response.text,
+            )
+            raise FlightdeckAuthenticationError(
+                f"Token response could not be parsed: {type(exc).__name__}: {exc}",
+            ) from exc
+
+        if parsed.token_type.lower() != "bearer":
+            self._logger.error(
+                "auth.token.unsupported_token_type",
+                token_type=parsed.token_type,
+            )
+            raise FlightdeckAuthenticationError(
+                f"Unsupported token_type {parsed.token_type!r}",
+            )
+
+        skew = self._settings.token_refresh_skew_seconds
+        expires_at = time.monotonic() + max(parsed.expires_in - skew, 0.0)
+        # WARNING: full access token logged for debugging.
+        self._logger.debug(
+            "auth.token.parsed",
+            token_type=parsed.token_type,
+            expires_in=parsed.expires_in,
+            skew=skew,
+            access_token=parsed.access_token,
+        )
+        return CachedToken(access_token=parsed.access_token, expires_at_monotonic=expires_at)
+
+
+def _safe_json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None

dopesecurity/mcp_server/config.py

@@ -0,0 +1,172 @@
+"""Runtime configuration and logging setup."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import structlog
+from pydantic import Field, SecretStr, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+DEFAULT_BASE_URL = "https://api.flightdeck.dope.security/v1"
+
+
+@dataclass(frozen=True)
+class CliConfigOverrides:
+    """CLI overrides for non-secret settings."""
+
+    enable_mutations: bool | None = None
+    enable_destructive: bool | None = None
+    timeout_seconds: float | None = None
+    log_level: str | None = None
+    token_refresh_skew_seconds: float | None = None
+    base_url: str | None = None
+    log_file: str | None = None
+
+
+class Settings(BaseSettings):
+    """Process-wide settings sourced from the environment with optional overrides."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="DOPE_",
+        env_ignore_empty=True,
+        extra="forbid",
+        case_sensitive=False,
+    )
+
+    client_id: str = Field(validation_alias="DOPE_CLIENT_ID")
+    client_secret: SecretStr = Field(validation_alias="DOPE_CLIENT_SECRET")
+    enable_mutations: bool = Field(default=False, validation_alias="DOPE_ENABLE_MUTATIONS")
+    enable_destructive: bool = Field(
+        default=False, validation_alias="DOPE_ENABLE_DESTRUCTIVE"
+    )
+    timeout_seconds: float = Field(default=30.0, validation_alias="DOPE_TIMEOUT_SECONDS", gt=0)
+    log_level: LogLevel = Field(default="INFO", validation_alias="DOPE_LOG_LEVEL")
+    token_refresh_skew_seconds: float = Field(
+        default=60.0, validation_alias="DOPE_TOKEN_REFRESH_SKEW_SECONDS", ge=0
+    )
+    api_base_url: str = Field(default=DEFAULT_BASE_URL, validation_alias="DOPE_BASE_URL")
+    log_file: str | None = Field(default=None, validation_alias="DOPE_LOG_FILE")
+
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def _normalize_log_level(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.upper()
+        return value
+
+    @model_validator(mode="after")
+    def _destructive_requires_mutations(self) -> Settings:
+        if self.enable_destructive and not self.enable_mutations:
+            raise ValueError(
+                "DOPE_ENABLE_DESTRUCTIVE requires DOPE_ENABLE_MUTATIONS to also "
+                "be enabled (destructive tools are a subset of write tools)."
+            )
+        return self
+
+
+def load_settings(overrides: CliConfigOverrides | None = None) -> Settings:
+    """Load settings from environment, then apply non-secret CLI overrides."""
+
+    settings = Settings()  # type: ignore[call-arg]
+    if overrides is None:
+        return settings
+
+    update: dict[str, Any] = {}
+    if overrides.enable_mutations is not None:
+        update["enable_mutations"] = overrides.enable_mutations
+    if overrides.enable_destructive is not None:
+        update["enable_destructive"] = overrides.enable_destructive
+    if overrides.timeout_seconds is not None:
+        update["timeout_seconds"] = overrides.timeout_seconds
+    if overrides.log_level is not None:
+        update["log_level"] = overrides.log_level.upper()
+    if overrides.token_refresh_skew_seconds is not None:
+        update["token_refresh_skew_seconds"] = overrides.token_refresh_skew_seconds
+    if overrides.base_url is not None:
+        update["api_base_url"] = overrides.base_url
+    if overrides.log_file is not None:
+        update["log_file"] = overrides.log_file
+
+    if not update:
+        return settings
+    merged = settings.model_copy(update=update)
+    # model_copy bypasses validators; re-check the destructive invariant
+    # so CLI flags like `--enable-destructive` (without --enable-mutations)
+    # fail loudly at startup instead of silently registering nothing.
+    if merged.enable_destructive and not merged.enable_mutations:
+        raise ValueError(
+            "--enable-destructive requires --enable-mutations to also be "
+            "enabled (destructive tools are a subset of write tools)."
+        )
+    return merged
+
+
+class _TeeWriter:
+    """File-like sink that writes/flushes to multiple underlying streams."""
+
+    def __init__(self, *streams: Any) -> None:
+        self._streams = streams
+
+    def write(self, data: str) -> int:
+        last = 0
+        for stream in self._streams:
+            try:
+                last = stream.write(data)
+            except Exception:  # noqa: BLE001 - never let logging break the app
+                pass
+        return last
+
+    def flush(self) -> None:
+        for stream in self._streams:
+            try:
+                stream.flush()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+def configure_logging(log_level: str, log_file: str | None = None) -> None:
+    """Configure stdlib logging and structlog to write to stderr (and optional file)."""
+
+    level_name = log_level.upper()
+    level = logging.getLevelNamesMapping().get(level_name, logging.INFO)
+
+    handler = logging.StreamHandler(stream=sys.stderr)
+    handler.setLevel(level)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+
+    root = logging.getLogger()
+    for existing in list(root.handlers):
+        root.removeHandler(existing)
+    root.addHandler(handler)
+    root.setLevel(level)
+
+    sink: Any = sys.stderr
+    if log_file:
+        # Line-buffered so `tail -f` shows entries as they happen.
+        file_stream = open(log_file, "a", buffering=1, encoding="utf-8")  # noqa: SIM115
+        sink = _TeeWriter(sys.stderr, file_stream)
+        # Surface the path so users know where to tail.
+        print(f"dopesecurity-mcp-server: logging to {log_file}", file=sys.stderr)
+
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            # NOTE: `dict_tracebacks` includes full traceback frames, locals, and
+            # the exception chain. This is intentionally verbose for debugging
+            # auth/credential issues and may leak sensitive data; tighten before
+            # production hardening.
+            structlog.processors.dict_tracebacks,
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        logger_factory=structlog.PrintLoggerFactory(file=sink),
+        cache_logger_on_first_use=True,
+    )