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

defectdojo_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""MCP server for DefectDojo."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("defectdojo-mcp-server")
+except PackageNotFoundError:  # pragma: no cover - only when running from a raw source tree
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

defectdojo_mcp/__main__.py

@@ -0,0 +1,4 @@
+from defectdojo_mcp.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

defectdojo_mcp/app.py

@@ -0,0 +1,165 @@
+"""Shared state and helpers used by every tool."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from mcp.server.mcpserver import Context
+from mcp.server.mcpserver.exceptions import ToolError
+
+from defectdojo_mcp.client import DojoAPIError, DojoClient
+from defectdojo_mcp.config import Settings
+
+Transport = Literal["stdio", "http"]
+HttpAuth = Literal["token", "passthrough"]
+
+PASSTHROUGH_HEADER = "x-defectdojo-api-key"
+
+# Test type rows can be created through the API, so names from that fallback
+# source are only returned when they look like ordinary parser names.
+_PLAIN_NAME = re.compile(r"^[A-Za-z0-9 ._()/+&:'-]{1,100}$")
+
+
+def key_from_headers(headers: Mapping[str, str] | None) -> str | None:
+    """Pull a caller-supplied DefectDojo key out of request headers."""
+    if not headers:
+        return None
+    lowered = {k.lower(): v for k, v in headers.items()}
+    direct = (lowered.get(PASSTHROUGH_HEADER) or "").strip()
+    if direct:
+        return direct
+    auth = (lowered.get("authorization") or "").strip()
+    scheme, _, value = auth.partition(" ")
+    if scheme.lower() in {"token", "bearer"} and value.strip():
+        return value.strip()
+    return None
+
+
+@dataclass
+class App:
+    settings: Settings
+    client: DojoClient
+    transport: Transport = "stdio"
+    http_auth: HttpAuth | None = None
+    _scan_types: list[str] | None = field(default=None, init=False, repr=False)
+
+    @property
+    def passthrough(self) -> bool:
+        return self.transport == "http" and self.http_auth == "passthrough"
+
+    def api_key(self, ctx: Context | None) -> str:
+        if self.passthrough:
+            key = key_from_headers(ctx.headers if ctx is not None else None)
+            if not key:
+                raise ToolError(
+                    "No DefectDojo API key was sent with this request. In pass-through mode, send it in the "
+                    "X-DefectDojo-Api-Key header or as Authorization: Token <key>."
+                )
+            return key
+        if not self.settings.api_key:
+            raise ToolError("DEFECTDOJO_API_KEY is not configured on this server.")
+        return self.settings.api_key
+
+    async def scan_types(self, ctx: Context | None) -> tuple[list[str], str]:
+        """Scan type names the instance can import, with the source they came from.
+
+        The import endpoint's OpenAPI enum lists every parser. Older instances
+        without that enum fall back to the test_types table, which only holds
+        types that were used before.
+        """
+        if self._scan_types is not None:
+            return self._scan_types, "openapi"
+        api_key = self.api_key(ctx)
+        try:
+            schema = await self.client.openapi_schema(api_key)
+        except DojoAPIError as exc:
+            raise ToolError(exc.message) from exc
+        names = _scan_type_enum(schema)
+        if names:
+            self._scan_types = names
+            return names, "openapi"
+        data = await self.get(ctx, "test_types/", {"limit": 1000}, resource="test types")
+        rows = data.get("results", []) if isinstance(data, dict) else []
+        found = sorted({str(r.get("name")) for r in rows if isinstance(r, dict) and r.get("name")})
+        return [n for n in found if _PLAIN_NAME.match(n)], "test_types"
+
+    async def get(
+        self, ctx: Context | None, path: str, params: Mapping[str, Any] | None = None, resource: str | None = None
+    ) -> Any:
+        try:
+            return await self.client.get(path, api_key=self.api_key(ctx), params=params, resource=resource)
+        except DojoAPIError as exc:
+            raise ToolError(exc.message) from exc
+
+    async def post(self, ctx: Context | None, path: str, body: Any, resource: str | None = None) -> Any:
+        try:
+            return await self.client.post(path, api_key=self.api_key(ctx), json_body=body, resource=resource)
+        except DojoAPIError as exc:
+            raise ToolError(exc.message) from exc
+
+    async def patch(self, ctx: Context | None, path: str, body: Any, resource: str | None = None) -> Any:
+        try:
+            return await self.client.patch(path, api_key=self.api_key(ctx), json_body=body, resource=resource)
+        except DojoAPIError as exc:
+            raise ToolError(exc.message) from exc
+
+    async def multipart(
+        self,
+        ctx: Context | None,
+        path: str,
+        data: Mapping[str, Any],
+        files: list[tuple[str, tuple[str, bytes, str]]],
+        resource: str | None = None,
+    ) -> Any:
+        try:
+            return await self.client.request(
+                "POST", path, api_key=self.api_key(ctx), data=data, files=files, resource=resource
+            )
+        except DojoAPIError as exc:
+            raise ToolError(exc.message) from exc
+
+    async def page(
+        self,
+        ctx: Context | None,
+        path: str,
+        params: Mapping[str, Any],
+        limit: int,
+        offset: int,
+        shaper: Callable[[dict[str, Any]], dict[str, Any]],
+        resource: str,
+    ) -> dict[str, Any]:
+        """Fetch one page of a list endpoint and shape the results."""
+        data = await self.get(ctx, path, {**params, "limit": limit, "offset": offset}, resource=resource)
+        if isinstance(data, list):
+            results, count, has_next = data, len(data), False
+        elif isinstance(data, dict):
+            results = data.get("results") or []
+            count = data.get("count", len(results))
+            has_next = bool(data.get("next"))
+        else:
+            raise ToolError("DefectDojo returned an unexpected response shape for a list request.")
+        shaped = [shaper(r) for r in results if isinstance(r, dict)]
+        return {
+            "count": count,
+            "offset": offset,
+            "limit": limit,
+            "returned": len(shaped),
+            "next_offset": offset + len(results) if has_next else None,
+            "results": shaped,
+        }
+
+
+def _scan_type_enum(schema: dict[str, Any] | None) -> list[str]:
+    if not schema:
+        return []
+    try:
+        prop = schema["components"]["schemas"]["ImportScanRequest"]["properties"]["scan_type"]
+    except (KeyError, TypeError):
+        return []
+    values = prop.get("enum") if isinstance(prop, dict) else None
+    if not isinstance(values, list):
+        return []
+    return sorted({str(v) for v in values if isinstance(v, str) and _PLAIN_NAME.match(v)})

defectdojo_mcp/cli.py

@@ -0,0 +1,200 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import ipaddress
+import logging
+import sys
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from defectdojo_mcp import __version__
+from defectdojo_mcp.config import ConfigError, Settings
+
+if TYPE_CHECKING:
+    from mcp.server.transport_security import TransportSecuritySettings
+
+logger = logging.getLogger("defectdojo_mcp")
+
+LOOPBACK_NAMES = {"localhost"}
+
+EPILOG = """\
+environment:
+  DEFECTDOJO_URL             base URL of your DefectDojo instance (required)
+  DEFECTDOJO_API_KEY         API v2 key (required, except in --http-auth passthrough)
+  DEFECTDOJO_VERIFY_SSL      true (default), false, or a CA bundle path
+  DEFECTDOJO_TIMEOUT         request timeout in seconds (default 30)
+  DEFECTDOJO_ALLOW_WRITES    true to register write tools (default false)
+  DEFECTDOJO_IMPORT_DIRS     folders scan files may be read from (unset = no file path imports)
+  DEFECTDOJO_MAX_UPLOAD_MB   largest scan file to upload (default 25)
+  DEFECTDOJO_MCP_AUTH_TOKEN  bearer token clients must send in HTTP token mode
+  DEFECTDOJO_MCP_ALLOWED_HOSTS  extra Host header values allowed in HTTP mode
+
+docs: https://github.com/DefectDojo/defectdojo-mcp
+"""
+
+
+class RedactingFilter(logging.Filter):
+    """Replace secret values in any log record before it is written."""
+
+    def __init__(self, secrets: Sequence[str]) -> None:
+        super().__init__()
+        self.secrets = [s for s in secrets if s and len(s) >= 4]
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if not self.secrets:
+            return True
+        message = record.getMessage()
+        redacted = message
+        for secret in self.secrets:
+            redacted = redacted.replace(secret, "[REDACTED]")
+        if redacted != message:
+            record.msg = redacted
+            record.args = None
+        return True
+
+
+def configure_logging(level: str, secrets: Sequence[str]) -> None:
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    handler.addFilter(RedactingFilter(secrets))
+    root = logging.getLogger()
+    for existing in list(root.handlers):
+        root.removeHandler(existing)
+    root.addHandler(handler)
+    root.setLevel(level)
+    # httpx logs every request URL at INFO. URLs carry no secrets, but keep the noise down.
+    logging.getLogger("httpx").setLevel(max(logging.WARNING, logging.getLevelName(level)))
+
+
+def is_loopback(host: str) -> bool:
+    if host.lower() in LOOPBACK_NAMES:
+        return True
+    try:
+        return ipaddress.ip_address(host.strip("[]")).is_loopback
+    except ValueError:
+        return False
+
+
+LOOPBACK_HOSTS = ["127.0.0.1:*", "localhost:*", "[::1]:*"]
+LOOPBACK_ORIGINS = ["http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*"]
+
+
+def transport_security(settings: Settings, host: str) -> TransportSecuritySettings | None:
+    """Host and Origin checks against DNS rebinding.
+
+    Always on for a loopback bind, whatever its spelling (the SDK only turns
+    them on by itself for "127.0.0.1", "localhost" and "::1"), and on for any
+    bind once DEFECTDOJO_MCP_ALLOWED_HOSTS is set. Loopback clients such as a
+    local inspector keep working when extra hosts are added.
+    """
+    from mcp.server.transport_security import TransportSecuritySettings
+
+    loopback = is_loopback(host)
+    if not loopback and not settings.allowed_hosts:
+        return None
+    hosts = list(settings.allowed_hosts)
+    origins = [f"https://{h}" for h in settings.allowed_hosts] + [f"http://{h}" for h in settings.allowed_hosts]
+    if loopback:
+        hosts += LOOPBACK_HOSTS
+        origins += LOOPBACK_ORIGINS
+    return TransportSecuritySettings(enable_dns_rebinding_protection=True, allowed_hosts=hosts, allowed_origins=origins)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="defectdojo-mcp",
+        description="MCP server for DefectDojo. Read-only unless DEFECTDOJO_ALLOW_WRITES=true.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--transport", choices=("stdio", "http"), default="stdio", help="stdio (default) or streamable HTTP"
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="HTTP bind address (default 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8000, help="HTTP port (default 8000)")
+    parser.add_argument("--path", default="/mcp", help="HTTP endpoint path (default /mcp)")
+    parser.add_argument(
+        "--http-auth",
+        choices=("token", "passthrough"),
+        default="token",
+        help="HTTP client auth: a shared bearer token (default) or each caller's own DefectDojo key",
+    )
+    parser.add_argument(
+        "--log-level", default="WARNING", choices=("DEBUG", "INFO", "WARNING", "ERROR"), help="log level (stderr)"
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    passthrough = args.transport == "http" and args.http_auth == "passthrough"
+    try:
+        settings = Settings.from_env(require_api_key=not passthrough)
+    except ConfigError as exc:
+        print(f"defectdojo-mcp: {exc}", file=sys.stderr)
+        return 2
+
+    configure_logging(args.log_level, settings.secrets())
+
+    from defectdojo_mcp.server import build_server
+
+    if args.transport == "stdio":
+        mcp, _ = build_server(settings, transport="stdio")
+        mcp.run("stdio")
+        return 0
+
+    return run_http(args, settings)
+
+
+def run_http(args: argparse.Namespace, settings: Settings) -> int:
+    import uvicorn
+
+    from defectdojo_mcp.http_auth import AuthMiddleware
+    from defectdojo_mcp.server import build_server
+
+    if not 1 <= args.port <= 65535:
+        print("defectdojo-mcp: --port must be between 1 and 65535", file=sys.stderr)
+        return 2
+    if args.http_auth == "token" and not settings.http_auth_token:
+        print(
+            "defectdojo-mcp: HTTP mode needs DEFECTDOJO_MCP_AUTH_TOKEN (clients send it as a bearer token), "
+            "or use --http-auth passthrough so each client sends its own DefectDojo API key.\n"
+            'Generate a token with: python -c "import secrets; print(secrets.token_urlsafe(32))"',
+            file=sys.stderr,
+        )
+        return 2
+    if args.http_auth == "token" and settings.http_auth_token and len(settings.http_auth_token) < 16:
+        print("defectdojo-mcp: DEFECTDOJO_MCP_AUTH_TOKEN must be at least 16 characters.", file=sys.stderr)
+        return 2
+    if args.http_auth == "passthrough" and settings.api_key:
+        logger.warning("Pass-through mode ignores DEFECTDOJO_API_KEY. Each client must send its own key.")
+
+    loopback = is_loopback(args.host)
+    security = transport_security(settings, args.host)
+    if not loopback:
+        logger.warning(
+            "Listening on %s, which is not a loopback address. Put the server behind TLS and set "
+            "DEFECTDOJO_MCP_ALLOWED_HOSTS to the public host name.",
+            args.host,
+        )
+
+    mcp, _ = build_server(settings, transport="http", http_auth=args.http_auth)
+    # Leave room for base64 encoded uploads plus the JSON-RPC envelope.
+    body_limit = (settings.max_upload_bytes * 4) // 3 + 1024 * 1024
+    starlette_app = mcp.streamable_http_app(
+        streamable_http_path=args.path,
+        max_request_body_size=body_limit,
+        transport_security=security,
+        host=args.host,
+    )
+    wrapped = AuthMiddleware(starlette_app, args.http_auth, settings.http_auth_token)
+    print(
+        f"defectdojo-mcp {__version__} listening on http://{args.host}:{args.port}{args.path} "
+        f"(auth: {args.http_auth}, writes: {'on' if settings.allow_writes else 'off'})",
+        file=sys.stderr,
+    )
+    uvicorn.run(wrapped, host=args.host, port=args.port, log_level=args.log_level.lower(), access_log=False)
+    return 0

defectdojo_mcp/client.py

@@ -0,0 +1,290 @@
+"""Small async client for the DefectDojo REST API v2."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import anyio
+import httpx
+
+from defectdojo_mcp import __version__
+from defectdojo_mcp.config import Settings
+from defectdojo_mcp.untrusted import wrap
+
+logger = logging.getLogger(__name__)
+
+RETRY_STATUSES = frozenset({429, 502, 503, 504})
+MAX_RETRIES = 2
+MAX_RETRY_WAIT = 5.0
+
+Params = Mapping[str, Any]
+FileTuple = tuple[str, bytes, str]
+
+
+MAYBE_APPLIED = " The change may still have been applied, so check DefectDojo before trying again."
+
+
+class DojoAPIError(Exception):
+    """An error talking to DefectDojo, with a message safe to show to the model."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+def redact(text: str, secrets: Sequence[str]) -> str:
+    for secret in secrets:
+        if secret and len(secret) >= 4:
+            text = text.replace(secret, "[REDACTED]")
+    return text
+
+
+def _clean_params(params: Params | None) -> dict[str, str] | None:
+    """Drop None values and turn booleans and lists into the strings DefectDojo expects."""
+    if not params:
+        return None
+    out: dict[str, str] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        elif isinstance(value, (list, tuple, set)):
+            if not value:
+                continue
+            out[key] = ",".join(str(v) for v in value)
+        else:
+            out[key] = str(value)
+    return out
+
+
+def _error_detail(response: httpx.Response) -> str | None:
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, ValueError):
+        text = response.text.strip()
+        return wrap(text, 500) if text else None
+    if isinstance(body, dict) and set(body) == {"detail"}:
+        return wrap(body["detail"], 500)
+    return wrap(json.dumps(body, ensure_ascii=False), 1500)
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    raw = response.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return None
+
+
+class DojoClient:
+    """Thin wrapper around httpx.AsyncClient.
+
+    The API key is passed per call so that HTTP pass-through mode can use the
+    caller's own DefectDojo key. Redirects are never followed, which keeps the
+    Authorization header from leaking to another host.
+    """
+
+    retry_base_delay = 0.5
+
+    def __init__(self, settings: Settings, transport: httpx.AsyncBaseTransport | None = None) -> None:
+        self.settings = settings
+        self._http = httpx.AsyncClient(
+            base_url=settings.api_base + "/",
+            timeout=httpx.Timeout(settings.timeout),
+            verify=settings.verify_ssl,
+            follow_redirects=False,
+            headers={"Accept": "application/json", "User-Agent": f"defectdojo-mcp/{__version__}"},
+            transport=transport,
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    def _secrets(self, api_key: str | None) -> list[str]:
+        return [*self.settings.secrets(), *([api_key] if api_key else [])]
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        api_key: str | None,
+        params: Params | None = None,
+        json_body: Any = None,
+        data: Mapping[str, Any] | None = None,
+        files: Sequence[tuple[str, FileTuple]] | None = None,
+        resource: str | None = None,
+    ) -> Any:
+        if not api_key:
+            raise DojoAPIError("No DefectDojo API key is available for this request.")
+        path = path.lstrip("/")
+        headers = {"Authorization": f"Token {api_key}"}
+        idempotent = method.upper() == "GET"
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    method,
+                    path,
+                    params=_clean_params(params),
+                    json=json_body,
+                    data=data,
+                    files=files,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as exc:
+                if idempotent and attempt < MAX_RETRIES:
+                    attempt += 1
+                    await anyio.sleep(self.retry_base_delay * attempt)
+                    continue
+                message = f"Timed out after {self.settings.timeout:g}s waiting for DefectDojo."
+                if idempotent or isinstance(exc, httpx.ConnectTimeout):
+                    message += " Try a narrower query or raise DEFECTDOJO_TIMEOUT."
+                else:
+                    # The request was sent, so DefectDojo may have finished the write after we gave up.
+                    message += MAYBE_APPLIED + " Raise DEFECTDOJO_TIMEOUT for large imports."
+                raise DojoAPIError(message) from exc
+            except httpx.HTTPError as exc:
+                if idempotent and attempt < MAX_RETRIES:
+                    attempt += 1
+                    await anyio.sleep(self.retry_base_delay * attempt)
+                    continue
+                message = redact(
+                    f"Could not reach DefectDojo at {self.settings.url} ({type(exc).__name__}). "
+                    "Check DEFECTDOJO_URL, network access and TLS settings.",
+                    self._secrets(api_key),
+                )
+                if not idempotent and not isinstance(exc, httpx.ConnectError):
+                    message += MAYBE_APPLIED
+                raise DojoAPIError(message) from exc
+
+            if response.status_code in RETRY_STATUSES and idempotent and attempt < MAX_RETRIES:
+                attempt += 1
+                wait = _retry_after(response)
+                delay = min(wait if wait is not None else self.retry_base_delay * attempt, MAX_RETRY_WAIT)
+                logger.info("DefectDojo answered %s, retrying in %.1fs", response.status_code, delay)
+                await anyio.sleep(delay)
+                continue
+            return self._handle(response, api_key, resource, idempotent)
+
+    def _handle(self, response: httpx.Response, api_key: str, resource: str | None, idempotent: bool = True) -> Any:
+        status = response.status_code
+        secrets = self._secrets(api_key)
+        if 200 <= status < 300:
+            if status == 204 or not response.content:
+                return None
+            try:
+                return response.json()
+            except (json.JSONDecodeError, ValueError) as exc:
+                raise DojoAPIError(
+                    "DefectDojo returned a response that is not JSON. "
+                    "Check that DEFECTDOJO_URL points at the DefectDojo base URL.",
+                    status,
+                ) from exc
+
+        detail = _error_detail(response)
+        what = resource or "object"
+        if 300 <= status < 400:
+            message = (
+                f"DefectDojo answered with a redirect ({status}). Check that DEFECTDOJO_URL uses the right "
+                "scheme and host, for example https:// instead of http://."
+            )
+        elif status == 400:
+            message = "DefectDojo rejected the request as invalid (400)."
+            if detail:
+                message += f" Details: {detail}"
+        elif status == 401:
+            message = "DefectDojo did not accept the API key (401). It may be wrong, revoked or expired."
+        elif status == 403:
+            message = (
+                "Permission denied (403). The API key is invalid or its user lacks permission for this "
+                f"{what} or action."
+            )
+            if detail:
+                message += f" Details: {detail}"
+        elif status == 404:
+            message = f"Not found (404): the {what} does not exist or the API key's user cannot see it."
+        elif status == 405:
+            message = "This DefectDojo version does not support this operation (405)."
+        elif status == 413:
+            message = "The DefectDojo server rejected the upload as too large (413)."
+        elif status == 429:
+            wait = _retry_after(response)
+            hint = f" Retry after {wait:g} seconds." if wait is not None else " Wait a moment and try again."
+            message = "DefectDojo is rate limiting requests (429)." + hint
+        elif status >= 500:
+            message = (
+                f"DefectDojo had a server error ({status}). Try again later, or check the DefectDojo logs "
+                "if it keeps happening."
+            )
+            if not idempotent:
+                message += MAYBE_APPLIED
+        else:
+            message = f"DefectDojo returned an unexpected status ({status})."
+            if detail:
+                message += f" Details: {detail}"
+        raise DojoAPIError(redact(message, secrets), status)
+
+    async def get(
+        self, path: str, *, api_key: str | None, params: Params | None = None, resource: str | None = None
+    ) -> Any:
+        return await self.request("GET", path, api_key=api_key, params=params, resource=resource)
+
+    async def post(self, path: str, *, api_key: str | None, json_body: Any = None, resource: str | None = None) -> Any:
+        return await self.request("POST", path, api_key=api_key, json_body=json_body, resource=resource)
+
+    async def patch(self, path: str, *, api_key: str | None, json_body: Any = None, resource: str | None = None) -> Any:
+        return await self.request("PATCH", path, api_key=api_key, json_body=json_body, resource=resource)
+
+    async def raw_get(self, url: str, *, headers: Mapping[str, str] | None = None) -> httpx.Response:
+        """Unauthenticated GET used only for best-effort edition detection."""
+        return await self._http.get(url, headers=dict(headers or {}))
+
+    async def openapi_schema(self, api_key: str) -> dict[str, Any] | None:
+        """Download the full OpenAPI schema, or None if the instance does not serve it."""
+        try:
+            data = await self.get("oa3/schema/", api_key=api_key, params={"format": "json"}, resource="API schema")
+        except DojoAPIError as exc:
+            if exc.status in {401, 403}:
+                raise
+            return None
+        return data if isinstance(data, dict) else None
+
+    async def schema_version(self, api_key: str | None) -> str | None:
+        """Read info.version from the OpenAPI schema without downloading all of it.
+
+        drf-spectacular writes "openapi" and "info" first, so the first few
+        kilobytes are enough. Returns None if the schema is unavailable.
+        """
+        if not api_key:
+            return None
+        try:
+            async with self._http.stream(
+                "GET",
+                "oa3/schema/",
+                params={"format": "json"},
+                headers={"Authorization": f"Token {api_key}"},
+            ) as response:
+                if response.status_code != 200:
+                    return None
+                buf = b""
+                async for chunk in response.aiter_bytes():
+                    buf += chunk
+                    if len(buf) >= 16384:
+                        break
+        except httpx.HTTPError:
+            return None
+        return _extract_info_version(buf.decode("utf-8", errors="replace"))
+
+
+def _extract_info_version(text: str) -> str | None:
+    match = re.search(r'"info"\s*:\s*\{.*?"version"\s*:\s*"([^"]{1,64})"', text, re.DOTALL)
+    return match.group(1) if match else None