agent-capmap 0.1.0__py3-none-any.whl

agentcapmap/enumerate/hashing.py

@@ -0,0 +1,37 @@
+"""Canonical tool-definition hashing.
+
+The hash identifies a tool definition independent of JSON key order or whitespace, so
+it can key the classifier cache and detect rug pulls (definition changed after review).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable
+from typing import Any
+
+
+def canonical_tool_definition(
+    name: str, description: str | None, input_schema: dict[str, Any] | None
+) -> bytes:
+    payload = {
+        "name": name,
+        "description": description or "",
+        "inputSchema": input_schema or {},
+    }
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+
+
+def tool_definition_hash(
+    name: str, description: str | None, input_schema: dict[str, Any] | None
+) -> str:
+    """Hex SHA-256 of the canonical (name, description, inputSchema) JSON."""
+    return hashlib.sha256(canonical_tool_definition(name, description, input_schema)).hexdigest()
+
+
+def server_definition_hash(tool_hashes: Iterable[str]) -> str:
+    """Order-independent hash over a server's tool hashes."""
+    return hashlib.sha256("\n".join(sorted(tool_hashes)).encode("ascii")).hexdigest()

agentcapmap/enumerate/http.py

@@ -0,0 +1,313 @@
+"""HTTP transports: Streamable HTTP (current spec) and legacy HTTP+SSE.
+
+Security properties:
+- Redirects are never followed, so configured credentials (Authorization, API-key
+  headers) cannot be forwarded to another host.
+- The legacy SSE `endpoint` must be same-origin as the configured URL, for the same
+  reason.
+- Response bodies, lines and SSE events are size-bounded.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import queue
+import threading
+import time
+from collections.abc import Iterable, Iterator
+from typing import Any
+from urllib.parse import urljoin, urlsplit
+
+import httpx
+
+from agentcapmap import __version__
+from agentcapmap.enumerate.transport import (
+    AuthRequired,
+    IdCounter,
+    RequestTimeout,
+    TransportError,
+    check_allowed,
+    is_response_to,
+    unwrap_response,
+)
+from agentcapmap.limits import MAX_MESSAGE_BYTES, MAX_QUEUED_MESSAGES, loads_untrusted
+from agentcapmap.limits import UntrustedJSONError as _BadJSON
+from agentcapmap.redact import get_logger, redact_url
+
+log = get_logger(__name__)
+
+_USER_AGENT = f"agent-capmap/{__version__}"
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+def iter_sse(lines: Iterable[str], max_event_chars: int | None = None) -> Iterator[tuple[str, str]]:
+    """Yield (event, data) pairs from a text/event-stream line iterator."""
+    max_event_chars = max_event_chars or MAX_MESSAGE_BYTES
+    event, data, size = "message", list[str](), 0
+    for line in lines:
+        if line == "":
+            if data:
+                yield event, "\n".join(data)
+            event, data, size = "message", [], 0
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        value = value.removeprefix(" ")
+        if field == "event":
+            event = value
+        elif field == "data":
+            size += len(value) + 1
+            if size > max_event_chars:
+                raise TransportError(f"SSE event larger than {max_event_chars} bytes")
+            data.append(value)
+    if data:
+        yield event, "\n".join(data)
+
+
+def _bounded_lines(response: httpx.Response) -> Iterator[str]:
+    """Decode a streamed body into lines, refusing any line longer than the limit."""
+    max_line = MAX_MESSAGE_BYTES
+    buffer = ""
+    for chunk in response.iter_text():
+        buffer += chunk
+        while (newline := buffer.find("\n")) != -1:
+            yield buffer[:newline].removesuffix("\r")
+            buffer = buffer[newline + 1 :]
+        if len(buffer) > max_line:
+            raise TransportError(f"response line longer than {max_line} bytes")
+    if buffer:
+        yield buffer.removesuffix("\r")
+
+
+def _read_body(response: httpx.Response) -> bytes:
+    limit = MAX_MESSAGE_BYTES
+    declared = response.headers.get("content-length")
+    if declared and declared.isdigit() and int(declared) > limit:
+        raise TransportError(f"response body larger than {limit} bytes")
+    body = bytearray()
+    for chunk in response.iter_bytes():
+        body += chunk
+        if len(body) > limit:
+            raise TransportError(f"response body larger than {limit} bytes")
+    return bytes(body)
+
+
+def _raise_for_status(response: httpx.Response, url: str) -> None:
+    status = response.status_code
+    if status == 401:
+        raise AuthRequired(
+            f"HTTP 401 from {redact_url(url)}: authentication required",
+            response.headers.get("www-authenticate"),
+        )
+    if 300 <= status < 400:
+        raise TransportError(
+            f"HTTP {status} redirect from {redact_url(url)} refused "
+            "(credentials are never forwarded to another location)"
+        )
+    if status >= 400:
+        raise TransportError(f"HTTP {status} from {redact_url(url)}")
+
+
+def _http_error(url: str, exc: httpx.HTTPError) -> TransportError:
+    # The exception text can embed the full URL (including secrets); report only its type.
+    return TransportError(f"HTTP error contacting {redact_url(url)}: {type(exc).__name__}")
+
+
+def _parse_json_messages(body: bytes) -> list[Any]:
+    try:
+        parsed = loads_untrusted(body)
+    except _BadJSON as exc:
+        raise TransportError(f"server returned invalid JSON ({exc})") from None
+    return parsed if isinstance(parsed, list) else [parsed]
+
+
+def _origin(url: str) -> tuple[str, str, int | None]:
+    parts = urlsplit(url)
+    scheme = parts.scheme.lower()
+    return scheme, (parts.hostname or "").lower(), parts.port or _DEFAULT_PORTS.get(scheme)
+
+
+def _client(headers: dict[str, str], timeout: float) -> httpx.Client:
+    return httpx.Client(
+        headers={"User-Agent": _USER_AGENT, **headers},
+        timeout=httpx.Timeout(timeout),
+        follow_redirects=False,
+    )
+
+
+class StreamableHttpTransport:
+    """POST each JSON-RPC message; responses come back as JSON or as an SSE stream."""
+
+    def __init__(self, url: str, headers: dict[str, str], timeout: float) -> None:
+        self._url = url
+        self._http = _client(headers, timeout)
+        self._ids = IdCounter()
+        self._session_id: str | None = None
+        self._protocol_version: str | None = None
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json, text/event-stream",
+            "Content-Type": "application/json",
+        }
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        if self._protocol_version:
+            headers["MCP-Protocol-Version"] = self._protocol_version
+        return headers
+
+    def _find_response(
+        self, response: httpx.Response, method: str, request_id: int, deadline: float
+    ) -> dict[str, Any]:
+        content_type = response.headers.get("content-type", "").split(";")[0].strip()
+        if content_type == "text/event-stream":
+            for _event, data in iter_sse(_bounded_lines(response)):
+                if time.monotonic() > deadline:
+                    raise RequestTimeout(f"{method} timed out")
+                try:
+                    message = loads_untrusted(data)
+                except _BadJSON:
+                    continue
+                if is_response_to(message, request_id):
+                    return unwrap_response(message)
+            raise TransportError(f"SSE stream ended without a response to {method}")
+        for message in _parse_json_messages(_read_body(response)):
+            if is_response_to(message, request_id):
+                return unwrap_response(message)
+        raise TransportError(f"no response to {method} in HTTP body")
+
+    def request(self, method: str, params: dict[str, Any], timeout: float) -> dict[str, Any]:
+        check_allowed(method)
+        request_id = self._ids.next()
+        body = {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params}
+        deadline = time.monotonic() + timeout
+        try:
+            with self._http.stream(
+                "POST", self._url, json=body, headers=self._headers(), timeout=timeout
+            ) as response:
+                _raise_for_status(response, self._url)
+                if session_id := response.headers.get("mcp-session-id"):
+                    self._session_id = session_id
+                result = self._find_response(response, method, request_id, deadline)
+        except httpx.TimeoutException:
+            raise RequestTimeout(f"{method} timed out after {timeout:.0f}s") from None
+        except httpx.HTTPError as exc:
+            raise _http_error(self._url, exc) from None
+
+        if method == "initialize":
+            version = result.get("protocolVersion")
+            self._protocol_version = version if isinstance(version, str) else None
+        return result
+
+    def notify(self, method: str, params: dict[str, Any] | None = None) -> None:
+        check_allowed(method, notification=True)
+        body: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            body["params"] = params
+        try:
+            response = self._http.post(self._url, json=body, headers=self._headers())
+        except httpx.HTTPError as exc:
+            raise _http_error(self._url, exc) from None
+        _raise_for_status(response, self._url)
+
+    def close(self) -> None:
+        if self._session_id:
+            with contextlib.suppress(httpx.HTTPError):
+                self._http.delete(self._url, headers=self._headers(), timeout=5)
+        self._http.close()
+
+
+class LegacySseTransport:
+    """Deprecated 2024-11-05 transport: GET an SSE stream, POST to the advertised endpoint."""
+
+    def __init__(self, url: str, headers: dict[str, str], timeout: float) -> None:
+        self._url = url
+        self._http = _client(headers, timeout)
+        self._ids = IdCounter()
+        self._messages: queue.Queue[Any] = queue.Queue(maxsize=MAX_QUEUED_MESSAGES)
+        self._endpoint: queue.Queue[str | BaseException] = queue.Queue()
+        self._closed = threading.Event()
+        threading.Thread(target=self._listen, daemon=True).start()
+        try:
+            item = self._endpoint.get(timeout=timeout)
+        except queue.Empty:
+            self.close()
+            raise RequestTimeout(f"no SSE endpoint event within {timeout:.0f}s") from None
+        if isinstance(item, BaseException):
+            self.close()
+            raise item
+        self._post_url: str = item
+
+    def _endpoint_url(self, data: str) -> str:
+        endpoint = urljoin(self._url, data.strip())
+        if _origin(endpoint) != _origin(self._url):
+            raise TransportError(
+                "SSE endpoint is on a different origin than the configured URL; refusing to "
+                "send requests (and credentials) there"
+            )
+        return endpoint
+
+    def _listen(self) -> None:
+        try:
+            with self._http.stream(
+                "GET",
+                self._url,
+                headers={"Accept": "text/event-stream"},
+                timeout=httpx.Timeout(10.0, read=None),
+            ) as response:
+                _raise_for_status(response, self._url)
+                for event, data in iter_sse(_bounded_lines(response)):
+                    if self._closed.is_set():
+                        return
+                    if event == "endpoint":
+                        self._endpoint.put(self._endpoint_url(data))
+                    elif event == "message":
+                        with contextlib.suppress(_BadJSON):
+                            self._messages.put(loads_untrusted(data))
+        except TransportError as exc:
+            self._endpoint.put(exc)
+        except httpx.HTTPError as exc:
+            if not self._closed.is_set():
+                self._endpoint.put(_http_error(self._url, exc))
+        finally:
+            with contextlib.suppress(queue.Full):
+                self._messages.put_nowait(None)
+
+    def _post(self, body: dict[str, Any]) -> None:
+        try:
+            response = self._http.post(
+                self._post_url, json=body, headers={"Content-Type": "application/json"}
+            )
+        except httpx.HTTPError as exc:
+            raise _http_error(self._url, exc) from None
+        _raise_for_status(response, self._post_url)
+
+    def request(self, method: str, params: dict[str, Any], timeout: float) -> dict[str, Any]:
+        check_allowed(method)
+        request_id = self._ids.next()
+        self._post({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise RequestTimeout(f"{method} timed out after {timeout:.0f}s")
+            try:
+                message = self._messages.get(timeout=remaining)
+            except queue.Empty:
+                continue
+            if message is None:
+                raise TransportError("SSE stream closed before response")
+            if is_response_to(message, request_id):
+                return unwrap_response(message)
+
+    def notify(self, method: str, params: dict[str, Any] | None = None) -> None:
+        check_allowed(method, notification=True)
+        body: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            body["params"] = params
+        self._post(body)
+
+    def close(self) -> None:
+        self._closed.set()
+        self._http.close()

agentcapmap/enumerate/netguard.py

@@ -0,0 +1,60 @@
+"""Refuse remote MCP URLs that point at link-local or cloud-metadata addresses.
+
+Loopback and private ranges are deliberately allowed: local MCP servers commonly
+listen on localhost, and a config the user chose to enumerate may name a LAN host.
+Link-local space (169.254.0.0/16, fe80::/10) holds the cloud instance-metadata
+services, which hand out credentials and are never an MCP server.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from urllib.parse import urlsplit
+
+from agentcapmap.enumerate.transport import TransportError
+
+_BLOCKED_NETWORKS = (
+    ipaddress.ip_network("169.254.0.0/16"),  # AWS/Azure/GCP/OpenStack metadata, link-local
+    ipaddress.ip_network("fe80::/10"),  # IPv6 link-local
+    ipaddress.ip_network("fd00:ec2::/32"),  # AWS IPv6 metadata
+    ipaddress.ip_network("100.100.100.200/32"),  # Alibaba Cloud metadata
+)
+_BLOCKED_HOSTS = frozenset({"metadata.google.internal", "metadata", "instance-data"})
+
+
+def _blocked(address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped:
+        address = address.ipv4_mapped
+    return any(address in network for network in _BLOCKED_NETWORKS)
+
+
+def check_remote_url(url: str) -> None:
+    """Raise TransportError if the URL's host is, or resolves to, a blocked address."""
+    host = (urlsplit(url).hostname or "").lower().rstrip(".")
+    if not host:
+        raise TransportError("remote server URL has no host")
+    if host in _BLOCKED_HOSTS:
+        raise TransportError("remote server host is a cloud metadata name; refusing to connect")
+    try:
+        literal = ipaddress.ip_address(host)
+    except ValueError:
+        pass
+    else:
+        if _blocked(literal):
+            raise TransportError("remote server address is link-local/metadata; refusing")
+        return
+    try:
+        infos = socket.getaddrinfo(host, None, type=socket.SOCK_STREAM)
+    except OSError:
+        return  # unresolvable: the connection attempt will fail with its own error
+    # SECURITY-REVIEW: this resolves the name once to check it, then httpx resolves it
+    # again to connect, so a DNS-rebinding server could still switch to a blocked
+    # address in between. Pinning the checked IP needs a custom httpx transport.
+    for info in infos:
+        try:
+            resolved = ipaddress.ip_address(info[4][0])
+        except ValueError:
+            continue
+        if _blocked(resolved):
+            raise TransportError("remote server host resolves to a link-local/metadata address")

agentcapmap/enumerate/stdio.py

@@ -0,0 +1,273 @@
+"""stdio transport: launch the server as a subprocess, newline-delimited JSON-RPC.
+
+Launching the configured server command is this module's purpose, which is why it
+imports `subprocess` (bandit B404). It is reached only through the warned, opt-in
+`--enumerate` flag.
+"""
+
+from __future__ import annotations
+
+import collections
+import contextlib
+import json
+import os
+import queue
+import shutil
+import signal
+import subprocess  # nosec B404
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import IO, Any
+
+from agentcapmap.enumerate.transport import (
+    JSONRPC_METHOD_NOT_FOUND,
+    IdCounter,
+    RequestTimeout,
+    TransportError,
+    check_allowed,
+    is_response_to,
+    unwrap_response,
+)
+from agentcapmap.limits import (
+    MAX_MESSAGE_BYTES,
+    MAX_QUEUED_MESSAGES,
+    MAX_STDERR_LINE_CHARS,
+    UntrustedJSONError,
+    loads_untrusted,
+)
+from agentcapmap.redact import get_logger, redact_text
+
+log = get_logger(__name__)
+
+_EOF = object()
+_OVERLONG = object()
+_STDERR_TAIL_LINES = 20
+
+# Only these variables are inherited from our own environment, mirroring the official
+# MCP SDK. Everything else (ANTHROPIC_API_KEY, cloud credentials, tokens) stays with us;
+# a server gets extra variables only if its config sets them explicitly.
+_INHERITED_ENV_WINDOWS = frozenset(
+    {
+        "APPDATA",
+        "COMSPEC",
+        "HOMEDRIVE",
+        "HOMEPATH",
+        "LOCALAPPDATA",
+        "PATH",
+        "PATHEXT",
+        "PROCESSOR_ARCHITECTURE",
+        "PROGRAMDATA",
+        "PROGRAMFILES",
+        "PROGRAMFILES(X86)",
+        "SYSTEMDRIVE",
+        "SYSTEMROOT",
+        "TEMP",
+        "TMP",
+        "USERNAME",
+        "USERPROFILE",
+        "WINDIR",
+    }
+)
+_INHERITED_ENV_POSIX = frozenset(
+    {"HOME", "LANG", "LC_ALL", "LOGNAME", "PATH", "SHELL", "TERM", "TMPDIR", "USER"}
+)
+
+
+def default_environment() -> dict[str, str]:
+    """The minimal environment a launched server inherits from agent-capmap."""
+    allowed = _INHERITED_ENV_WINDOWS if sys.platform == "win32" else _INHERITED_ENV_POSIX
+    return {
+        key: value
+        for key, value in os.environ.items()
+        # Skip exported shell functions ("() { ...") as the MCP SDK does.
+        if key.upper() in allowed and not value.startswith("()")
+    }
+
+
+def _read_bounded_line(stream: IO[bytes], limit: int) -> bytes | object | None:
+    """Next line (None at EOF), or _OVERLONG after discarding a line longer than `limit`."""
+    chunk = stream.readline(limit)
+    if not chunk:
+        return None
+    if chunk.endswith(b"\n") or len(chunk) < limit:
+        return chunk
+    while True:  # discard the rest of the oversized line
+        more = stream.readline(limit)
+        if not more or more.endswith(b"\n"):
+            return _OVERLONG
+
+
+class StdioTransport:
+    def __init__(
+        self,
+        command: str,
+        args: list[str],
+        env: dict[str, str],
+        cwd: str | None = None,
+    ) -> None:
+        full_env = {**default_environment(), **env}
+        executable = shutil.which(command, path=full_env.get("PATH")) or command
+        kwargs: dict[str, Any] = {}
+        if sys.platform == "win32":
+            kwargs["creationflags"] = (
+                subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW
+            )
+        else:
+            kwargs["start_new_session"] = True
+        try:
+            # Launching the configured server command is this transport's purpose, and is
+            # only reached via the explicit, warned --enumerate opt-in. The command comes
+            # from a config the user chose to enumerate; no shell is involved (argv list,
+            # shell=False), so arguments cannot be reinterpreted as shell syntax.
+            self._proc = subprocess.Popen(  # noqa: S603  # nosec B603
+                [executable, *args],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=full_env,
+                cwd=cwd,
+                shell=False,
+                **kwargs,
+            )
+        except OSError as exc:
+            raise TransportError(f"failed to start {command!r}: {exc.strerror or exc}") from None
+
+        if self._proc.stdin is None or self._proc.stdout is None or self._proc.stderr is None:
+            _kill_tree(self._proc)
+            raise TransportError("failed to open pipes to the server process")
+        self._stdin = self._proc.stdin
+        self._ids = IdCounter()
+        self._messages: queue.Queue[Any] = queue.Queue(maxsize=MAX_QUEUED_MESSAGES)
+        self._stderr_tail: collections.deque[str] = collections.deque(maxlen=_STDERR_TAIL_LINES)
+        threading.Thread(target=self._read_stdout, args=(self._proc.stdout,), daemon=True).start()
+        threading.Thread(target=self._read_stderr, args=(self._proc.stderr,), daemon=True).start()
+
+    def _read_stdout(self, stream: IO[bytes]) -> None:
+        try:
+            while (raw := _read_bounded_line(stream, MAX_MESSAGE_BYTES)) is not None:
+                if not isinstance(raw, bytes):  # _OVERLONG
+                    log.debug("dropping stdout line longer than %d bytes", MAX_MESSAGE_BYTES)
+                    continue
+                line = raw.decode("utf-8", errors="replace").strip()
+                if not line:
+                    continue
+                try:
+                    message = loads_untrusted(line)
+                except UntrustedJSONError:
+                    log.debug("ignoring non-JSON stdout line: %s", line[:200])
+                    continue
+                self._messages.put(message)
+        except (OSError, ValueError):
+            pass  # pipe closed underneath us
+        finally:
+            self._messages.put(_EOF)
+
+    def _read_stderr(self, stream: IO[bytes]) -> None:
+        try:
+            while (raw := _read_bounded_line(stream, MAX_MESSAGE_BYTES)) is not None:
+                if not isinstance(raw, bytes):  # _OVERLONG
+                    continue
+                text = raw.decode("utf-8", errors="replace").rstrip()[:MAX_STDERR_LINE_CHARS]
+                line = redact_text(text)
+                if line:
+                    self._stderr_tail.append(line)
+                    log.debug("server stderr: %s", line)
+        except (OSError, ValueError):
+            pass  # pipe closed underneath us; stderr is diagnostic only
+
+    def _write(self, message: dict[str, Any]) -> None:
+        data = (json.dumps(message, separators=(",", ":")) + "\n").encode("utf-8")
+        try:
+            self._stdin.write(data)
+            self._stdin.flush()
+        except OSError:
+            raise self._exited_error() from None
+
+    def _exited_error(self) -> TransportError:
+        with contextlib.suppress(subprocess.TimeoutExpired):
+            self._proc.wait(timeout=1)
+        code = self._proc.returncode
+        detail = f"server exited (code {code})" if code is not None else "server closed stdout"
+        if self._stderr_tail:
+            detail += "; stderr: " + " | ".join(list(self._stderr_tail)[-5:])
+        return TransportError(redact_text(detail))
+
+    def _reply_to_server_request(self, message: dict[str, Any]) -> None:
+        # Servers may ping or ask for roots/sampling. We answer pings, decline the rest.
+        if message.get("method") == "ping":
+            self._write({"jsonrpc": "2.0", "id": message["id"], "result": {}})
+        else:
+            self._write(
+                {
+                    "jsonrpc": "2.0",
+                    "id": message["id"],
+                    "error": {"code": JSONRPC_METHOD_NOT_FOUND, "message": "not supported"},
+                }
+            )
+
+    def request(self, method: str, params: dict[str, Any], timeout: float) -> dict[str, Any]:
+        check_allowed(method)
+        request_id = self._ids.next()
+        self._write({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise RequestTimeout(f"{method} timed out after {timeout:.0f}s")
+            try:
+                message = self._messages.get(timeout=remaining)
+            except queue.Empty:
+                continue
+            if message is _EOF:
+                raise self._exited_error()
+            if is_response_to(message, request_id):
+                return unwrap_response(message)
+            if isinstance(message, dict) and "method" in message and "id" in message:
+                self._reply_to_server_request(message)
+            # Anything else (notifications, stray responses) is ignored.
+
+    def notify(self, method: str, params: dict[str, Any] | None = None) -> None:
+        check_allowed(method, notification=True)
+        message: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            message["params"] = params
+        self._write(message)
+
+    def close(self) -> None:
+        # Spec shutdown: close stdin, give the server a moment, then terminate the tree.
+        with contextlib.suppress(OSError):
+            self._stdin.close()
+        with contextlib.suppress(subprocess.TimeoutExpired):
+            self._proc.wait(timeout=2)
+        # Always kill the tree: children (e.g. npx -> node) may outlive the parent.
+        _kill_tree(self._proc)
+
+
+def _taskkill_path() -> str:
+    system_root = os.environ.get("SYSTEMROOT") or r"C:\Windows"
+    return str(Path(system_root) / "System32" / "taskkill.exe")
+
+
+def _kill_tree(proc: subprocess.Popen[bytes]) -> None:
+    if sys.platform == "win32":
+        # Fixed system binary by absolute path; the only variable argument is our own
+        # child's integer PID.
+        subprocess.run(  # noqa: S603  # nosec B603
+            [_taskkill_path(), "/F", "/T", "/PID", str(int(proc.pid))],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            shell=False,
+        )
+    else:
+        with contextlib.suppress(ProcessLookupError, PermissionError):
+            os.killpg(proc.pid, signal.SIGTERM)
+        try:
+            proc.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.killpg(proc.pid, signal.SIGKILL)
+    with contextlib.suppress(subprocess.TimeoutExpired):
+        proc.wait(timeout=2)