synapse-orch-ai 1.9.1 → 1.9.3

package/backend/core/browser_automation.py

@@ -0,0 +1,91 @@
+"""What the Browser Automation server may be asked to do.
+
+The server is Playwright's MCP server (`@playwright/mcp`), started by `core/server.py`, on by default, and called
+by agents that read web pages, so what a page says can steer it. Its tools are offered through `gated()`:
+
+* **Only the tools reviewed for the pinned version.** None that run code in the server's own process
+  (`browser_run_code_unsafe`; Playwright's own description calls it RCE-equivalent), run a model's script in the
+  page (`browser_evaluate`), or read local files into a page (`browser_file_upload`, `browser_drop`). A tool a
+  later version adds is not offered until someone reviews it and adds it here.
+* **A `url` is http(s)**, or `about:blank`: never `file:`, `chrome:`, `data:` and the like.
+* **A `filename` stays in the server's folder**: relative, no `..`. The server is started with that folder as its
+  working directory and output directory, so it is where its own files land.
+
+Where the browser may connect is not decided here: its network goes through the egress proxy
+(`core.egress_proxy`). BRW1's browser component replaces this server and its gate (`core/browser/gate.py`).
+"""
+from __future__ import annotations
+
+from pathlib import PurePosixPath, PureWindowsPath
+from typing import Any
+from urllib.parse import urlsplit
+
+#: The server's name in `core/server.py`'s list, and the package it runs, pinned: `npx -y @playwright/mcp` ran
+#: whatever was newest the first time, and a new version's new tools reached agents unreviewed.
+BROWSER_AUTOMATION = "Browser Automation"
+PLAYWRIGHT_MCP = "@playwright/mcp@0.0.83"
+
+#: The tools of the pinned version that are offered. Reviewed 2026-10-28 against what 0.0.83 lists.
+OFFERED = frozenset({
+    "browser_navigate", "browser_navigate_back", "browser_tabs", "browser_snapshot", "browser_find",
+    "browser_wait_for", "browser_take_screenshot", "browser_console_messages", "browser_network_requests",
+    "browser_network_request", "browser_click", "browser_type", "browser_fill_form", "browser_select_option",
+    "browser_press_key", "browser_hover", "browser_drag", "browser_handle_dialog", "browser_resize",
+    "browser_emulate_media", "browser_close",
+})
+
+_URL_ARGS = ("url",)
+_FILE_ARGS = ("filename",)
+
+
+def refusal(name: str, arguments: dict | None) -> str | None:
+    """Why this call is not made, or None when it may be."""
+    if name not in OFFERED:
+        return f"{name} is not available in Synapse's browser."
+    args = arguments or {}
+    for key in _URL_ARGS:
+        url = args.get(key)
+        if url is None:
+            continue
+        scheme = urlsplit(str(url)).scheme.lower()
+        if scheme not in ("http", "https") and str(url) != "about:blank":
+            return f"{name} opens http and https addresses only."
+    for key in _FILE_ARGS:
+        filename = args.get(key)
+        if filename is None:
+            continue
+        text = str(filename)
+        if (text.startswith(("/", "\\", "~")) or PureWindowsPath(text).drive
+                or ".." in PurePosixPath(text.replace("\\", "/")).parts):
+            return f"{name} saves only inside its own folder: give a file name, not a path."
+    return None
+
+
+class _Gated:
+    """The server's session, offering only `OFFERED` and refusing what `refusal` refuses. Anything else (a ping,
+    initialize) is the session's own."""
+
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._session, name)
+
+    async def list_tools(self, *args: Any, **kwargs: Any) -> Any:
+        result = await self._session.list_tools(*args, **kwargs)
+        return result.model_copy(update={"tools": [t for t in result.tools if t.name in OFFERED]})
+
+    async def call_tool(self, name: str, arguments: dict | None = None, *args: Any, **kwargs: Any) -> Any:
+        reason = refusal(name, arguments)
+        if reason is not None:
+            import mcp.types as types
+
+            return types.CallToolResult(content=[types.TextContent(type="text", text=reason)], isError=True)
+        return await self._session.call_tool(name, arguments, *args, **kwargs)
+
+
+def gated(server_name: str, session: Any) -> Any:
+    """`session`, gated when it is the Browser Automation server's; any other server's as it is."""
+    if server_name != BROWSER_AUTOMATION or isinstance(session, _Gated):
+        return session
+    return _Gated(session)

package/backend/core/egress_guard.py

@@ -0,0 +1,223 @@
+"""Egress policy for tools that fetch user- or model-supplied URLs.
+
+A tool's URLs are data, not configuration: they arrive from a prompt, and a
+prompt can be steered by whatever the last scraped page said. A fetcher that
+goes wherever it is pointed will sooner or later be pointed at the network
+the process itself runs on — the cloud metadata endpoints (169.254.169.254,
+169.254.170.2), loopback services on its own host, or anything else the
+subnet can reach. On a cloud runtime the metadata endpoint alone turns one
+injected URL into live credentials.
+
+The policy: http(s) only, and only to addresses that are actually on the
+public internet. Every address a hostname resolves to is checked, not just
+the first — a name with one public and one private record must not pass.
+
+`EGRESS_ALLOW_HOSTS` (comma-separated hostnames) exempts specific hosts from
+the address checks, for installs that genuinely scrape an intranet or a
+localhost dev server, and for tests dialing loopback stand-ins. Empty —
+deny — is the default.
+
+The DNS-rebinding window (resolution here vs. resolution at connect time) is
+deliberately not closed: closing it means owning socket creation and TLS SNI
+handling in every fetch path. Network-level egress control is the layer for
+that; this module is the in-process guard in front of it.
+
+Deliberately stdlib-only, and deliberately not a Settings consumer: it is
+imported by tool subprocesses that must construct in any environment.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import os
+import socket
+import time
+from urllib.parse import urlparse
+
+#: Carrier-grade NAT. Not covered by `is_private`, and it is where several
+#: managed-Kubernetes overlays put internal services.
+_CGNAT = ipaddress.ip_network("100.64.0.0/10")
+
+#: One resolution per host per window is enough for a page's subresources;
+#: short enough that the cache is not itself a rebinding aid.
+_RESOLVE_TTL_SECONDS = 60.0
+_RESOLVE_CACHE_MAX = 512
+
+_resolve_cache: dict[str, tuple[float, list[str]]] = {}
+
+
+class BlockedEgress(ValueError):
+    """A URL that must not be fetched. The message is safe to echo to the model."""
+
+
+class MalformedUrl(BlockedEgress):
+    """Not a URL with a scheme, so it names no destination to check.
+
+    A subclass for the same reason `UnresolvedHost` is: the scraper should
+    refuse what it cannot evaluate. A custom HTTP tool should not, because the
+    commonest way to get here is an unrendered `{{global.api_base}}` — a missing
+    variable, whose own error message names the variable and is worth more than
+    this one. Nothing is conceded: a string with no scheme is one httpx refuses
+    to send anywhere. A URL with a scheme that is simply not http stays a plain
+    `BlockedEgress`.
+    """
+
+
+class UnresolvedHost(BlockedEgress):
+    """The host could not be resolved, so nothing is known about where it points.
+
+    A subclass, so every existing caller keeps failing closed: for the scraper,
+    which is handed URLs a model invented, "unknown" is the right thing to
+    refuse. A *saved* custom HTTP tool is the other case — the host may be an
+    internal API, a service not yet deployed, or a DNS blip, and refusing it is
+    a guess about somebody else's network. `core/builder_tools.py` already says
+    so in as many words about the same URLs at creation time.
+
+    Letting it through concedes nothing: httpx resolves through the same stack
+    a moment later and fails the same lookup. What is not conceded is an
+    address — an IP literal always "resolves", so `169.254.169.254` is still
+    refused by the check below.
+    """
+
+
+def allowed_hosts() -> frozenset[str]:
+    raw = os.environ.get("EGRESS_ALLOW_HOSTS", "")
+    return frozenset(h.strip().lower() for h in raw.split(",") if h.strip())
+
+
+def reject_address(address: str) -> str | None:
+    """Return a reason to refuse this IP, or None to allow it.
+
+    Grouped by what each range would reach, because the point is not that the
+    addresses are unusual but that they are *ours*.
+    """
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        return f"{address} is not an IP address"
+
+    # An IPv4-mapped IPv6 address (`::ffff:169.254.170.2`) reaches the IPv4
+    # host while failing every IPv4 range check, so unwrap before testing.
+    if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
+        ip = ip.ipv4_mapped
+
+    if ip.is_loopback:
+        return "loopback"
+    if ip.is_link_local:
+        # 169.254.0.0/16 and fe80::/10 — the cloud metadata range.
+        return "link-local, including the cloud metadata endpoint"
+    # Before `is_private`, which also covers 0.0.0.0/8 and would report the
+    # unspecified address as "private" — true, and unhelpful to whoever typed it.
+    if ip.is_unspecified:
+        return "the unspecified address"
+    if ip.is_private:
+        return "private network"
+    if ip.is_multicast or ip.is_reserved:
+        return "multicast or reserved"
+    if ip.version == 4 and ip in _CGNAT:
+        return "shared address space"
+    return None
+
+
+async def resolve(host: str) -> list[str]:
+    """All addresses `host` resolves to, via the event loop's resolver, cached briefly."""
+    now = time.monotonic()
+    hit = _resolve_cache.get(host)
+    if hit is not None and now - hit[0] < _RESOLVE_TTL_SECONDS:
+        return hit[1]
+
+    loop = asyncio.get_running_loop()
+    try:
+        infos = await loop.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
+    except socket.gaierror as exc:
+        raise UnresolvedHost(f"could not resolve {host}") from exc
+    # sockaddr[0] is typed `str | int` because the tuple shape differs by
+    # address family; for AF_INET and AF_INET6 it is always the address.
+    addresses = sorted({str(info[4][0]) for info in infos})
+
+    if len(_resolve_cache) >= _RESOLVE_CACHE_MAX:
+        _resolve_cache.clear()
+    _resolve_cache[host] = (now, addresses)
+    return addresses
+
+
+async def check_host(host: str) -> None:
+    """Raise `BlockedEgress` unless every address behind `host` is public."""
+    host = host.strip().lower().strip("[]")
+    if not host:
+        raise BlockedEgress("that URL has no host")
+    if host in allowed_hosts():
+        return
+    _check_addresses(host, await _addresses(host))
+
+
+async def checked_addresses(host: str) -> list[str]:
+    """The addresses behind `host`, every one of them public, or raise `BlockedEgress`.
+
+    For a caller that opens the connection itself (`core.egress_proxy`): it dials
+    one of these and never the name again, so the address it checked is the
+    address it reaches. A host in `EGRESS_ALLOW_HOSTS` is resolved, not checked.
+    """
+    host = host.strip().lower().strip("[]")
+    if not host:
+        raise BlockedEgress("that URL has no host")
+    addresses = await _addresses(host)
+    if host not in allowed_hosts():
+        _check_addresses(host, addresses)
+    return addresses
+
+
+async def _addresses(host: str) -> list[str]:
+    try:
+        ipaddress.ip_address(host)
+        return [host]
+    except ValueError:
+        return await resolve(host)
+
+
+def _check_addresses(host: str, addresses: list[str]) -> None:
+    for address in addresses:
+        reason = reject_address(address)
+        if reason is not None:
+            # `host` is echoed because the caller supplied it. The addresses
+            # it resolved to are not: that is internal topology, and reading
+            # it back is exactly what an attacker is probing for.
+            raise BlockedEgress(f"{host} resolves to a blocked range: {reason}")
+
+
+async def check_tool_url(url: str) -> None:
+    """`check_url`, with the posture a *saved* custom tool needs.
+
+    The scraper is handed URLs a model invented, so refusing whatever it cannot
+    evaluate is right for it. A custom HTTP tool is different: its URL was
+    written by a person, saved, and may name an internal API, a service not yet
+    deployed, or a host this machine simply cannot resolve. Refusing those is a
+    guess about somebody else's network, and it concedes nothing to allow them —
+    httpx resolves through the same stack a moment later and fails the same
+    lookup, and a string with no scheme is one httpx will not send anywhere.
+
+    What is *not* conceded is an address: an IP literal always resolves, so the
+    cloud metadata endpoint and loopback are refused here exactly as they are
+    for the scraper.
+
+    One function because there are two call sites — the ReAct loop and the
+    orchestration TOOL step — and a control written twice is a control that
+    drifts. That is the lesson the stdio-MCP gate had to be moved for.
+    """
+    try:
+        await check_url(url)
+    except (UnresolvedHost, MalformedUrl):
+        return
+
+
+async def check_url(url: str) -> None:
+    """Check one URL, or raise `BlockedEgress`."""
+    parsed = urlparse(url)
+    if not parsed.scheme:
+        raise MalformedUrl("that is not a URL; it has no http:// or https:// scheme")
+    if parsed.scheme not in {"http", "https"}:
+        raise BlockedEgress(
+            f"{parsed.scheme} URLs are not supported; use http or https"
+        )
+    await check_host(parsed.hostname or "")

package/backend/core/egress_proxy.py

@@ -0,0 +1,229 @@
+"""One egress proxy for every browser Synapse starts.
+
+`core/egress_guard.py` decides where a fetch may go. A browser makes its own
+requests — redirects, a page's scripts, in-page fetches, WebSockets, service
+workers — and a hook inside the browser does not see every one of them. A
+proxy does: the browser is started with this one as its proxy, Playwright puts
+loopback through it too (`<-loopback>` in Chromium's bypass list), and it opens
+no connection the guard refuses.
+
+It also closes the window the guard leaves open on purpose. The guard resolves
+a name, and the fetch it guards resolves it again; here the address that was
+checked (`egress_guard.checked_addresses`) is the address dialled, and the name
+is never looked up a second time.
+
+What it speaks is the least a browser needs: `CONNECT host:port` for TLS and
+WebSockets, and an absolute-form `http://` request for plain HTTP, sent on as
+one request per connection (`Connection: close`) so a second request on the
+same connection cannot name another host. A refusal is a `403` whose body is
+the guard's message (it names the host asked for, never an address it
+resolved to); anything that is not a proxy request is a `400`.
+
+It listens on loopback and needs no credentials: what it reaches is the public
+internet, which anything on the machine reaches already.
+
+Deliberately stdlib-only, like the guard: the scraper's subprocess starts its own.
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+from urllib.parse import urlsplit
+
+from core import egress_guard
+
+#: What a Chromium behind this proxy is started with. UDP never goes through a proxy: WebRTC takes the proxied path
+#: or none, and QUIC, which WebTransport rides with no route in its way, is off.
+CHROMIUM_ARGS = ("--force-webrtc-ip-handling-policy=disable_non_proxied_udp", "--disable-quic")
+
+#: A request head larger than this is not one a browser sends.
+_HEAD_LIMIT = 64 * 1024
+_HEAD_TIMEOUT_SECONDS = 30.0
+CONNECT_TIMEOUT_SECONDS = 10.0
+#: After the browser closes its side, how long the other side has to finish.
+_DRAIN_SECONDS = 30.0
+
+_REASONS = {400: "Bad Request", 403: "Forbidden", 502: "Bad Gateway"}
+
+#: Headers meant for the proxy itself, never sent on.
+_FOR_THE_PROXY = {"proxy-connection", "proxy-authorization", "proxy-authenticate"}
+
+
+class _BadRequest(ValueError):
+    pass
+
+
+class _Request:
+    def __init__(self, head: bytes):
+        lines = head[:-4].decode("latin-1").split("\r\n")
+        parts = lines[0].split(" ")
+        if len(parts) != 3 or not parts[2].startswith("HTTP/"):
+            raise _BadRequest("not an HTTP request")
+        self.method, target, version = parts
+        self.tunnel = self.method.upper() == "CONNECT"
+        try:
+            if self.tunnel:
+                url = urlsplit(f"//{target}")
+                self.host, self.port = url.hostname, url.port
+                if not self.host or not self.port:
+                    raise _BadRequest("CONNECT needs host:port")
+                self.forward = b""
+                return
+            url = urlsplit(target)
+            self.host, self.port = url.hostname, url.port or 80
+        except ValueError as exc:
+            raise _BadRequest(f"not an address: {exc}") from None
+        if url.scheme != "http" or not self.host:
+            raise _BadRequest("a proxy request is CONNECT host:port or an absolute http:// URL")
+
+        headers = []
+        for line in lines[1:]:
+            name, _, value = line.partition(":")
+            if name.strip().lower() not in _FOR_THE_PROXY:
+                headers.append((name.strip(), value.strip()))
+        connection = {v.strip().lower() for n, value in headers if n.lower() == "connection"
+                      for v in value.split(",")}
+        upgrade = "upgrade" in connection and any(n.lower() == "upgrade" for n, _ in headers)
+        if not upgrade:
+            headers = [(n, v) for n, v in headers if n.lower() not in ("connection", "keep-alive")]
+            headers.append(("Connection", "close"))
+        path = (url.path or "/") + (f"?{url.query}" if url.query else "")
+        self.forward = "".join([f"{self.method} {path} {version}\r\n",
+                                *(f"{n}: {v}\r\n" for n, v in headers), "\r\n"]).encode("latin-1")
+
+
+class EgressProxy:
+    """A loopback proxy that dials only what `core.egress_guard` allows. `start()` once, `close()` when done."""
+
+    host = "127.0.0.1"
+
+    def __init__(self) -> None:
+        self.port = 0
+        self.loop: asyncio.AbstractEventLoop | None = None
+        self._server: asyncio.base_events.Server | None = None
+        self._starting: asyncio.Future | None = None
+        self._writers: set[asyncio.StreamWriter] = set()
+        self._closed = False
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    async def start(self) -> str:
+        """Listen, once; every caller waits for the same start."""
+        if self._starting is None:
+            self.loop = asyncio.get_running_loop()
+            self._starting = asyncio.ensure_future(self._listen())
+        await asyncio.shield(self._starting)
+        return self.url
+
+    async def _listen(self) -> None:
+        self._server = await asyncio.start_server(self._serve, self.host, 0, limit=_HEAD_LIMIT)
+        self.port = self._server.sockets[0].getsockname()[1]
+
+    async def close(self) -> None:
+        self._closed = True
+        if self._server is not None:
+            self._server.close()
+        for writer in list(self._writers):
+            writer.close()
+        if self._server is not None:
+            await self._server.wait_closed()
+
+    async def _serve(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        self._writers.add(writer)
+        upstream: asyncio.StreamWriter | None = None
+        host = ""
+        try:
+            try:
+                head = await asyncio.wait_for(reader.readuntil(b"\r\n\r\n"), _HEAD_TIMEOUT_SECONDS)
+            except (asyncio.IncompleteReadError, asyncio.LimitOverrunError, TimeoutError, ConnectionError):
+                return
+            request = _Request(head)
+            host = request.host
+            addresses = await egress_guard.checked_addresses(host)
+            up_reader, upstream = await _dial(addresses, request.port)
+            self._writers.add(upstream)
+            if request.tunnel:
+                writer.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
+            else:
+                upstream.write(request.forward)
+            await _relay(reader, writer, up_reader, upstream)
+        except _BadRequest as exc:
+            _answer(writer, 400, str(exc))
+        except egress_guard.BlockedEgress as exc:
+            print(f"egress proxy: refused {host}: {exc}", file=sys.stderr)
+            _answer(writer, 403, str(exc))
+        except (OSError, TimeoutError):
+            _answer(writer, 502, f"could not reach {host}")
+        finally:
+            for w in (upstream, writer):
+                if w is not None:
+                    self._writers.discard(w)
+                    w.close()
+
+
+async def _dial(addresses: list[str], port: int):
+    """A connection to the first of `addresses` that answers. Never the name: the addresses are what was checked."""
+    last: BaseException = OSError("no address")
+    for address in addresses:
+        try:
+            return await asyncio.wait_for(asyncio.open_connection(address, port), CONNECT_TIMEOUT_SECONDS)
+        except (OSError, TimeoutError) as exc:
+            last = exc
+    raise last
+
+
+async def _pipe(src: asyncio.StreamReader, dst: asyncio.StreamWriter) -> None:
+    try:
+        while data := await src.read(65536):
+            dst.write(data)
+            await dst.drain()
+    except ConnectionError:
+        pass
+
+
+async def _relay(client_r, client_w, up_r, up_w) -> None:
+    """Both ways until the far side is done. The browser closing its side gives the far side a moment to finish."""
+    outbound = asyncio.ensure_future(_pipe(client_r, up_w))
+    inbound = asyncio.ensure_future(_pipe(up_r, client_w))
+    try:
+        done, _ = await asyncio.wait({outbound, inbound}, return_when=asyncio.FIRST_COMPLETED)
+        if inbound not in done:
+            if up_w.can_write_eof():
+                try:
+                    up_w.write_eof()
+                except OSError:
+                    pass
+            await asyncio.wait({inbound}, timeout=_DRAIN_SECONDS)
+    finally:
+        for task in (outbound, inbound):
+            task.cancel()
+
+
+def _answer(writer: asyncio.StreamWriter, status: int, reason: str) -> None:
+    body = f"{reason}\n".encode()
+    try:
+        writer.write(f"HTTP/1.1 {status} {_REASONS[status]}\r\nContent-Type: text/plain; charset=utf-8\r\n"
+                     f"Content-Length: {len(body)}\r\nX-Synapse-Egress: refused\r\nConnection: close\r\n\r\n"
+                     .encode() + body)
+    except (OSError, RuntimeError):
+        pass
+
+
+_shared: EgressProxy | None = None
+
+
+async def shared() -> EgressProxy:
+    """This event loop's proxy, started on first use. A closed one, or one from another loop, is replaced."""
+    global _shared
+    loop = asyncio.get_running_loop()
+    proxy = _shared
+    if proxy is None or proxy.closed or (proxy.loop is not None and proxy.loop is not loop):
+        proxy = _shared = EgressProxy()
+    await proxy.start()
+    return proxy