Skip to content

Automate browser based workflows with AI

Support org-level CDP operation denylists (SKY-12538) (#7542)

Aaron Perez8e96fdae92ac
diff --git a/skyvern/proxy/__main__.py b/skyvern/proxy/__main__.py
index 600f1aa16..821212a08 100644
--- a/skyvern/proxy/__main__.py
+++ b/skyvern/proxy/__main__.py
@@ -16,11 +16,13 @@ from skyvern.proxy.adapters.memory import (
)
from skyvern.proxy.adapters.websocket_server import CdpProxyServer
from skyvern.proxy.adapters.websocket_upstream import WebSocketUpstreamBrowser
+from skyvern.proxy.core.denylist import MethodPatternSet, org_denylist_interceptor
from skyvern.proxy.core.interception_demo import demo_get_version_interceptor
from skyvern.proxy.core.pipeline import CommandInterceptor, MiddlewarePipeline
from skyvern.proxy.core.policy import EventPolicyEngine
from skyvern.proxy.core.policy_pack import NOISY_EVENT_PACK_V1
from skyvern.proxy.core.screencast import SCREENCAST_PACK_V1, screencast_pipeline
+from skyvern.proxy.core.session import ProxySession
from skyvern.proxy.ports import EventPolicyPort, UpstreamBrowserPort
LOG = structlog.get_logger(__name__)
@@ -54,17 +56,33 @@ def build_event_policy(kind: str) -> EventPolicyPort:
raise ValueError(f"unknown CDP_PROXY_EVENT_POLICY: {kind!r}")
-def build_interceptors(kind: str) -> tuple[CommandInterceptor, ...]:
+def build_interceptors(kind: str, denylist: str = "") -> tuple[CommandInterceptor, ...]:
"""Config-only interceptor switch (SKY-12535). The default is none: with
- interception disabled the command path is exactly the pre-seam pass-through."""
- if kind == "":
- return ()
+ interception disabled the command path is exactly the pre-seam pass-through.
+
+ `denylist` (CDP_PROXY_DENYLIST, comma-separated method patterns) is the
+ generic wiring for SKY-12538: one static list applied to every session this
+ proxy serves, compiled at startup so a bad pattern fails the boot rather than
+ a command. The per-organization source (cloud/cdp_proxy/denylist.py) replaces
+ the lookup in the cloud composition root. The denylist runs FIRST: a denied
+ method is denied before any other interceptor can see or rewrite it.
+ """
+ interceptors: list[CommandInterceptor] = []
+ if denylist:
+ patterns = MethodPatternSet.compile([part.strip() for part in denylist.split(",") if part.strip()])
+
+ async def deny_all_sessions(session: ProxySession) -> MethodPatternSet | None:
+ return patterns
+
+ interceptors.append(org_denylist_interceptor(deny_all_sessions))
if kind == "demo-get-version":
- return (demo_get_version_interceptor,)
- raise ValueError(f"unknown CDP_PROXY_INTERCEPTORS: {kind!r}")
+ interceptors.append(demo_get_version_interceptor)
+ elif kind:
+ raise ValueError(f"unknown CDP_PROXY_INTERCEPTORS: {kind!r}")
+ return tuple(interceptors)
-def build_pipeline(kind: str, interceptors_kind: str = "") -> MiddlewarePipeline:
+def build_pipeline(kind: str, interceptors_kind: str = "", denylist: str = "") -> MiddlewarePipeline:
"""The command half of the selected policy, keyed off the same switch.
Only the screencast policy has one: bounding what a client asks Page.startScreencast
@@ -75,7 +93,7 @@ def build_pipeline(kind: str, interceptors_kind: str = "") -> MiddlewarePipeline
Interceptors are orthogonal to the policy pack and compose into the same pipeline.
"""
- interceptors = build_interceptors(interceptors_kind)
+ interceptors = build_interceptors(interceptors_kind, denylist)
if kind == "screencast-v1":
return screencast_pipeline(interceptors)
return MiddlewarePipeline(interceptors=interceptors)
@@ -87,17 +105,24 @@ def main() -> None:
upstream_kind = os.environ.get("CDP_PROXY_UPSTREAM", "websocket")
policy_kind = os.environ.get("CDP_PROXY_EVENT_POLICY", "forward-all")
interceptors_kind = os.environ.get("CDP_PROXY_INTERCEPTORS", "")
+ denylist = os.environ.get("CDP_PROXY_DENYLIST", "")
server = CdpProxyServer(
upstream=build_upstream(upstream_kind),
sessions=InMemorySessionRegistry(),
auth=AllowAllAuth(),
metrics=NoOpMetrics(),
event_policy=build_event_policy(policy_kind),
- pipeline=build_pipeline(policy_kind, interceptors_kind),
+ pipeline=build_pipeline(policy_kind, interceptors_kind, denylist),
host=os.environ.get("CDP_PROXY_HOST", "0.0.0.0"),
port=int(os.environ.get("CDP_PROXY_PORT", "9223")),
)
- LOG.info("starting CDP proxy", upstream=upstream_kind, event_policy=policy_kind, interceptors=interceptors_kind)
+ LOG.info(
+ "starting CDP proxy",
+ upstream=upstream_kind,
+ event_policy=policy_kind,
+ interceptors=interceptors_kind,
+ denylist_patterns=len([part for part in denylist.split(",") if part.strip()]),
+ )
asyncio.run(server.serve_forever())
diff --git a/skyvern/proxy/adapters/websocket_server.py b/skyvern/proxy/adapters/websocket_server.py
index 78076c38a..f3bb8e6a1 100644
--- a/skyvern/proxy/adapters/websocket_server.py
+++ b/skyvern/proxy/adapters/websocket_server.py
@@ -1361,6 +1361,20 @@ class CdpProxyServer:
self._event_policy.observe_command(processed, session)
_track_command(command_starts, upstream_command.id, processed.method)
processed = upstream_command
+ elif isinstance(processed, (CdpEvent, CdpResponse)):
+ # A CDP client only ever sends COMMANDS (method + id) to the browser;
+ # events and responses flow the other way. A method-bearing frame
+ # sent without an id decodes as an event (frames.py), so forwarding a
+ # client event raw would let a client smuggle a command past command
+ # interception — e.g. a denied Target.sendMessageToTarget stripped of
+ # its id would tunnel a denied inner method past the denylist. Dropped,
+ # never forwarded: closing the bypass here rather than trusting the
+ # browser to reject an id-less command.
+ self._metrics.increment(
+ _METRIC_FRAMES_DROPPED,
+ tags={**_org_tag(session), "direction": direction.value, "reason": "non_command_upstream"},
+ )
+ continue
wire = encode_frame(processed)
await connection.send(wire)
self._record_relayed(session, direction, wire)
@@ -1404,14 +1418,20 @@ class CdpProxyServer:
self._record_intercepted(session, command, INTERCEPTOR_FAILURE_REASON)
return interceptor_failure_response(command)
if isinstance(outcome, SynthesizedResponse):
- self._record_intercepted(session, command, outcome.reason)
+ self._record_intercepted(session, command, outcome.reason, audit_method=outcome.audit_method)
return outcome.to_response(command)
return outcome
- def _record_intercepted(self, session: ProxySession, command: CdpCommand, reason: str) -> None:
+ def _record_intercepted(
+ self, session: ProxySession, command: CdpCommand, reason: str, audit_method: str | None = None
+ ) -> None:
"""The audit trail for a command answered at the proxy (SKY-12538): a counter
- under bounded labels plus one structured line naming the exact method."""
- cdp_method, cdp_domain = _cdp_method_tags(command.method)
+ under bounded labels plus one structured line naming the exact method. The
+ synthesis's audit_method wins over the wrapper it arrived in, so a denial
+ tunneled through Target.sendMessageToTarget is recorded against the method
+ actually blocked."""
+ method = audit_method or command.method
+ cdp_method, cdp_domain = _cdp_method_tags(method)
self._metrics.increment(
_METRIC_COMMANDS_INTERCEPTED,
tags={**_org_tag(session), "reason": reason, "cdp_method": cdp_method, "cdp_domain": cdp_domain},
@@ -1419,7 +1439,7 @@ class CdpProxyServer:
LOG.info(
"CDP command intercepted",
session_id=session.session_id,
- cdp_method=command.method,
+ cdp_method=method,
reason=reason,
**_org_tag(session),
)
diff --git a/skyvern/proxy/core/denylist.py b/skyvern/proxy/core/denylist.py
new file mode 100644
index 000000000..35cef8b19
--- /dev/null
+++ b/skyvern/proxy/core/denylist.py
@@ -0,0 +1,157 @@
+"""Org-level CDP operation denylists (SKY-12538), as an interceptor on the
+command-interception seam (SKY-12535).
+
+A denied command is answered with a deterministic synthesized CDP error under the
+client's own request id — never a silent drop, which would hang the client, and
+never a forward, which would defeat the policy. Running as an interceptor keeps
+the denylist inside the policy engine's decision path rather than a bypass: the
+audit trail (the commands_intercepted counter plus the adapter's structured log)
+comes with the seam.
+
+Matching covers the legacy `Target.sendMessageToTarget` tunnel: the inner
+serialized command's method is matched too (see `denied_method`), so wrapping a
+denied method does not bypass the policy. A tunneled denial surfaces as an error
+on the WRAPPER id — the same in-protocol outcome as Chrome refusing the send
+itself (invalid or closed session), which legacy clients must and do handle by
+failing the inner call (pre-flat puppeteer rejects the inner callback on a
+wrapper error). Synthesizing the target-side `Target.receivedMessageFromTarget`
+reply instead would need an event-synthesis verb the interception seam
+deliberately does not have (SKY-12535 v1), for a client shape no worse off than
+against a real browser refusing the send.
+
+The METHOD-PATTERN GRAMMAR is a strict superset of the policy packs' exact method
+names, so any method string a pack rule names is a valid pattern here:
+
+- exact: ``Page.navigate`` matches only that method;
+- trailing ``*``: a prefix wildcard — ``Network.*`` denies a domain, ``*`` denies
+ everything. ``*`` anywhere else is rejected at compile time, not silently
+ ignored: a pattern that quietly matched nothing would read as protection.
+
+WHO IS DENIED comes from `DenylistLookup`: the session's organization resolves to
+its compiled pattern set (the cloud ConfigStore-backed source lives in
+cloud/cdp_proxy/denylist.py; its cache TTL is the propagation window). A lookup
+returning None means no denylist — the source absorbs config-infrastructure
+failures by failing OPEN, matching the event policy's forwarding-is-the-safe
+default, while a lookup that raises fails the command CLOSED via the seam's rule.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from skyvern.proxy.core.frames import CdpCommand
+from skyvern.proxy.core.pipeline import CommandInterceptor, InterceptContext, InterceptOutcome, SynthesizedResponse
+from skyvern.proxy.core.session import ProxySession
+
+DENYLIST_REASON = "org_denylist"
+
+# JSON-RPC generic server error; distinct from CDP's -32001 session-not-found and
+# the seam's -32603 interceptor failure, so a denial is tellable from both.
+DENIED_ERROR_CODE = -32000
+
+
+class MethodPatternError(ValueError):
+ pass
+
+
+def denied_error(method: str) -> dict[str, Any]:
+ return {"code": DENIED_ERROR_CODE, "message": f"'{method}' is not allowed by organization policy"}
+
+
+@dataclass(frozen=True)
+class MethodPatternSet:
+ """A compiled denylist: exact methods plus '*'-terminated prefixes."""
+
+ exact: frozenset[str]
+ prefixes: tuple[str, ...]
+
+ @classmethod
+ def compile(cls, patterns: Iterable[str]) -> MethodPatternSet:
+ exact: set[str] = set()
+ prefixes: list[str] = []
+ for pattern in patterns:
+ if not isinstance(pattern, str) or not pattern or any(c.isspace() for c in pattern):
+ raise MethodPatternError(f"invalid method pattern: {pattern!r}")
+ star = pattern.find("*")
+ if star == -1:
+ exact.add(pattern)
+ elif star == len(pattern) - 1:
+ prefixes.append(pattern[:-1])
+ else:
+ raise MethodPatternError(f"'*' is only valid as the final character: {pattern!r}")
+ return cls(frozenset(exact), tuple(prefixes))
+
+ def matches(self, method: str) -> bool:
+ return method in self.exact or any(method.startswith(prefix) for prefix in self.prefixes)
+
+ def __bool__(self) -> bool:
+ return bool(self.exact or self.prefixes)
+
+
+DenylistLookup = Callable[[ProxySession], Awaitable["MethodPatternSet | None"]]
+
+_SEND_MESSAGE_METHOD = "Target.sendMessageToTarget"
+# Legitimate clients do not nest the legacy tunnel at all; a chain deeper than
+# this is denied outright rather than left unverifiable.
+_MAX_TUNNEL_DEPTH = 8
+
+
+def denied_method(patterns: MethodPatternSet, command: CdpCommand) -> str | None:
+ """The method this command would run that the denylist matches, or None.
+
+ Target.sendMessageToTarget is the legacy non-flat tunnel: its `message` param
+ carries a serialized inner command that Chrome unwraps and dispatches, so the
+ inner method must be matched too — recursively, since the tunnel can wrap
+ itself — or denying a method is bypassed by wrapping it. An undecodable
+ message passes (Chrome cannot dispatch it either, so there is nothing to
+ deny); a chain past the depth cap is denied as-is.
+ """
+ method = command.method
+ params: dict[str, Any] = command.params or {}
+ for _ in range(_MAX_TUNNEL_DEPTH + 1):
+ if patterns.matches(method):
+ return method
+ if method != _SEND_MESSAGE_METHOD:
+ return None
+ message = params.get("message")
+ if not isinstance(message, str):
+ return None
+ try:
+ inner = json.loads(message)
+ except ValueError:
+ return None
+ if not isinstance(inner, dict) or not isinstance(inner.get("method"), str):
+ return None
+ method = inner["method"]
+ inner_params = inner.get("params")
+ params = inner_params if isinstance(inner_params, dict) else {}
+ return method
+
+
+def org_denylist_interceptor(lookup: DenylistLookup) -> CommandInterceptor:
+ async def intercept(command: CdpCommand, session: ProxySession, context: InterceptContext) -> InterceptOutcome:
+ patterns = await lookup(session)
+ if patterns is not None:
+ matched = denied_method(patterns, command)
+ if matched is not None:
+ # audit_method: a tunneled denial is audited against the method it
+ # blocked, not the Target.sendMessageToTarget wrapper it rode in.
+ return SynthesizedResponse(error=denied_error(matched), reason=DENYLIST_REASON, audit_method=matched)
+ return command
+
+ return intercept
+
+
+__all__ = [
+ "DENIED_ERROR_CODE",
+ "DENYLIST_REASON",
+ "DenylistLookup",
+ "MethodPatternError",
+ "MethodPatternSet",
+ "denied_error",
+ "denied_method",
+ "org_denylist_interceptor",
+]
diff --git a/skyvern/proxy/core/pipeline.py b/skyvern/proxy/core/pipeline.py
index b64f5f9ba..e4b7aa141 100644
--- a/skyvern/proxy/core/pipeline.py
+++ b/skyvern/proxy/core/pipeline.py
@@ -106,12 +106,16 @@ class SynthesizedResponse:
relay down instead of answering the client.
`reason` is the audit tag for the decision trace — a label-safe identifier,
- since it becomes a metric label.
+ since it becomes a metric label. `audit_method` names the method the decision
+ was actually about when that differs from the intercepted command's own — a
+ denied method tunneled inside Target.sendMessageToTarget (SKY-12538) — so the
+ audit trail records the blocked method, not the wrapper it arrived in.
"""
result: dict[str, Any] | None = None
error: dict[str, Any] | None = None
reason: str = "intercepted"
+ audit_method: str | None = None
def __post_init__(self) -> None:
if (self.result is None) == (self.error is None):
@@ -125,6 +129,12 @@ class SynthesizedResponse:
raise ValueError(f"synthesized response is not CDP-encodable: {exc}") from exc
if not isinstance(self.reason, str) or not _REASON_PATTERN.fullmatch(self.reason):
raise ValueError("reason must be a short lowercase identifier ([a-z0-9_]{1,64})")
+ if self.audit_method is not None and (
+ not isinstance(self.audit_method, str)
+ or not self.audit_method
+ or any(c.isspace() for c in self.audit_method)
+ ):
+ raise ValueError("audit_method must be a non-empty method name")
def to_response(self, command: CdpCommand) -> CdpResponse:
"""Stamp the synthesis with the intercepted command's own id and session
diff --git a/tests/unit/proxy/test_denylist.py b/tests/unit/proxy/test_denylist.py
new file mode 100644
index 000000000..d052b9927
--- /dev/null
+++ b/tests/unit/proxy/test_denylist.py
@@ -0,0 +1,368 @@
+"""Org-level CDP operation denylists (SKY-12538) on the interception seam.
+
+A denied command is answered with a deterministic synthesized CDP error under the
+client's own request id — never a silent drop — and never reaches the browser.
+The pattern grammar is a superset of the policy packs' exact method names: exact
+("Page.navigate") or trailing-'*' prefix ("Network.*", "*").
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+
+from skyvern.proxy.__main__ import build_interceptors, build_pipeline
+from skyvern.proxy.adapters.memory import ForwardAllEventPolicy, InMemorySessionRegistry, StaticKeyAuth
+from skyvern.proxy.adapters.websocket_server import CdpProxyServer
+from skyvern.proxy.core.denylist import (
+ DENIED_ERROR_CODE,
+ DENYLIST_REASON,
+ MethodPatternError,
+ MethodPatternSet,
+ denied_error,
+ denied_method,
+ org_denylist_interceptor,
+)
+from skyvern.proxy.core.frames import CdpCommand, CdpEvent, decode_frame
+from skyvern.proxy.core.pipeline import InterceptContext, MiddlewarePipeline, SynthesizedResponse
+from skyvern.proxy.core.session import Principal, ProxySession, ResolvedSession
+from tests.unit.proxy.test_interception import _responses, _upstream_methods
+from tests.unit.proxy.test_metrics_contract import _RecordingMetrics
+from tests.unit.proxy.test_shared_connection import (
+ UPSTREAM_URL,
+ _command,
+ _ControllableUpstream,
+ _ScriptClient,
+ _SharedBrowser,
+ _until,
+)
+
+
+def test_exact_patterns_match_only_their_method() -> None:
+ patterns = MethodPatternSet.compile(["Page.navigate"])
+
+ assert patterns.matches("Page.navigate")
+ assert not patterns.matches("Page.navigateToHistoryEntry")
+ assert not patterns.matches("Page.enable")
+ assert bool(patterns)
+
+
+def test_trailing_star_is_a_prefix_wildcard() -> None:
+ patterns = MethodPatternSet.compile(["Network.*", "Page.nav*"])
+
+ assert patterns.matches("Network.enable")
+ assert patterns.matches("Network.setCookie")
+ assert patterns.matches("Page.navigate")
+ assert patterns.matches("Page.navigateToHistoryEntry")
+ assert not patterns.matches("Page.enable")
+ assert not patterns.matches("Runtime.evaluate")
+
+
+def test_bare_star_matches_every_method() -> None:
+ patterns = MethodPatternSet.compile(["*"])
+
+ assert patterns.matches("Page.enable")
+ assert patterns.matches("anything")
+
+
+def test_empty_pattern_set_matches_nothing() -> None:
+ patterns = MethodPatternSet.compile([])
+
+ assert not patterns.matches("Page.enable")
+ assert not bool(patterns)
+
+
[email protected]("bad", ["", " ", "Page .navigate", "Page.*.x", "*.enable", "Pa*ge", "**", None, 7])
+def test_invalid_patterns_are_rejected(bad: object) -> None:
+ with pytest.raises(MethodPatternError):
+ MethodPatternSet.compile([bad]) # type: ignore[list-item]
+
+
+def test_denied_error_is_deterministic() -> None:
+ # Exact on purpose: the AC promises a deterministic error, so the message is
+ # contract, not prose.
+ assert denied_error("Page.navigate") == {
+ "code": DENIED_ERROR_CODE,
+ "message": "'Page.navigate' is not allowed by organization policy",
+ }
+
+
+def _session(organization_id: str | None = "org-a") -> ProxySession:
+ principal = Principal(principal_id="p", organization_id=organization_id) if organization_id else None
+ return ProxySession(session_id="s1", upstream_ws_url="ws://x/y", principal=principal)
+
+
+def _context() -> InterceptContext:
+ async def send_proxy_command(command: CdpCommand) -> None:
+ raise AssertionError("a denylist never issues upstream traffic")
+
+ return InterceptContext(send_proxy_command=send_proxy_command)
+
+
+async def test_denied_method_synthesizes_the_deterministic_error() -> None:
+ async def lookup(session: ProxySession) -> MethodPatternSet | None:
+ return MethodPatternSet.compile(["Network.*"])
+
+ interceptor = org_denylist_interceptor(lookup)
+
+ outcome = await interceptor(CdpCommand(id=1, method="Network.enable"), _session(), _context())
+
+ assert isinstance(outcome, SynthesizedResponse)
+ assert outcome.error == denied_error("Network.enable")
+ assert outcome.reason == DENYLIST_REASON
+
+
+async def test_unmatched_and_unconfigured_commands_pass_through() -> None:
+ async def some(session: ProxySession) -> MethodPatternSet | None:
+ return MethodPatternSet.compile(["Network.*"])
+
+ async def none(session: ProxySession) -> MethodPatternSet | None:
+ return None
+
+ command = CdpCommand(id=1, method="Page.enable")
+
+ assert await org_denylist_interceptor(some)(command, _session(), _context()) is command
+ assert await org_denylist_interceptor(none)(command, _session(), _context()) is command
+
+
+def _tunneled(method: str, params: dict | None = None, depth: int = 1) -> CdpCommand:
+ inner: dict = {"id": 1, "method": method, "params": params or {}}
+ for _ in range(depth):
+ inner = {"id": 1, "method": "Target.sendMessageToTarget", "params": {"message": json.dumps(inner)}}
+ return CdpCommand(id=1, method=inner["method"], params=inner["params"])
+
+
+def test_the_legacy_send_message_tunnel_cannot_bypass_the_denylist() -> None:
+ patterns = MethodPatternSet.compile(["Page.navigate"])
+
+ # The inner method is what Chrome dispatches, so it is what gets matched.
+ assert denied_method(patterns, _tunneled("Page.navigate")) == "Page.navigate"
+ assert denied_method(patterns, _tunneled("Page.navigate", depth=3)) == "Page.navigate"
+ assert denied_method(patterns, _tunneled("Page.enable")) is None
+ # Denying the tunnel itself still works by pattern.
+ assert denied_method(MethodPatternSet.compile(["Target.*"]), _tunneled("Page.enable")) == (
+ "Target.sendMessageToTarget"
+ )
+
+
+def test_an_undispatchable_tunnel_message_passes() -> None:
+ patterns = MethodPatternSet.compile(["Page.navigate"])
+ for params in (
+ None,
+ {},
+ {"message": 7},
+ {"message": "not json"},
+ {"message": json.dumps(["not", "an", "object"])},
+ {"message": json.dumps({"id": 1})},
+ ):
+ command = CdpCommand(id=1, method="Target.sendMessageToTarget", params=params)
+ # Chrome cannot dispatch any of these either, so there is nothing to deny.
+ assert denied_method(patterns, command) is None
+
+
+def test_a_tunnel_nested_past_the_depth_cap_is_denied() -> None:
+ patterns = MethodPatternSet.compile(["Page.navigate"])
+
+ assert denied_method(patterns, _tunneled("Page.enable", depth=20)) == "Target.sendMessageToTarget"
+
+
+async def test_the_interceptor_denies_the_tunneled_inner_method() -> None:
+ async def lookup(session: ProxySession) -> MethodPatternSet | None:
+ return MethodPatternSet.compile(["Page.navigate"])
+
+ interceptor = org_denylist_interceptor(lookup)
+
+ outcome = await interceptor(_tunneled("Page.navigate"), _session(), _context())
+
+ assert isinstance(outcome, SynthesizedResponse)
+ # The error names the method that was actually denied, not the wrapper.
+ assert outcome.error == denied_error("Page.navigate")
+
+
+async def test_a_tunneled_denial_is_audited_against_the_inner_method() -> None:
+ connection = _ControllableUpstream()
+ sessions = InMemorySessionRegistry()
+ sessions.put(ResolvedSession(session_id="s1", upstream_adapter="memory", upstream_ws_url=UPSTREAM_URL))
+ metrics = _RecordingMetrics()
+ server = CdpProxyServer(
+ upstream=_SharedBrowser(connection), # type: ignore[arg-type]
+ sessions=sessions,
+ auth=StaticKeyAuth({"key": Principal(principal_id="p", organization_id="org")}),
+ metrics=metrics, # type: ignore[arg-type]
+ event_policy=ForwardAllEventPolicy(),
+ pipeline=build_pipeline("forward-all", denylist="Page.navigate"),
+ )
+ tunneled = _tunneled("Page.navigate")
+ client = _ScriptClient([json.dumps({"id": 1, "method": tunneled.method, "params": tunneled.params})])
+ client.request.headers = {"x-api-key": "key"}
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: client.sent)
+
+ [denied] = _responses(client)
+ assert denied.error == denied_error("Page.navigate")
+ # An org monitoring Page.navigate denials sees the tunneled attempt too: the
+ # audit records the blocked method, not the wrapper it rode in.
+ [tags] = [tags for op, name, _, tags in metrics.calls if name.endswith("commands_intercepted")]
+ assert tags["cdp_method"] == "Page.navigate"
+ assert tags["cdp_domain"] == "Page"
+ assert tags["reason"] == DENYLIST_REASON
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_an_id_less_tunnel_cannot_bypass_the_denylist() -> None:
+ # A denied Target.sendMessageToTarget stripped of its top-level id decodes as a
+ # CdpEvent, not a CdpCommand — the interception path is command-only, so without
+ # this guard the frame would be forwarded upstream raw, tunneling the denied
+ # inner method past the denylist. It must be dropped, never forwarded.
+ connection = _ControllableUpstream()
+ sessions = InMemorySessionRegistry()
+ sessions.put(ResolvedSession(session_id="s1", upstream_adapter="memory", upstream_ws_url=UPSTREAM_URL))
+ server = CdpProxyServer(
+ upstream=_SharedBrowser(connection), # type: ignore[arg-type]
+ sessions=sessions,
+ auth=StaticKeyAuth({"key": Principal(principal_id="p", organization_id="org")}),
+ metrics=_RecordingMetrics(), # type: ignore[arg-type]
+ event_policy=ForwardAllEventPolicy(),
+ pipeline=build_pipeline("forward-all", denylist="Page.navigate"),
+ )
+ inner = json.dumps({"id": 1, "method": "Page.navigate", "params": {"url": "about:blank"}})
+ # No top-level "id": this frame decodes as an event and skips command interception.
+ id_less_tunnel = json.dumps({"method": "Target.sendMessageToTarget", "params": {"message": inner}})
+ # A following command with an id proves the connection stayed usable.
+ client = _ScriptClient([id_less_tunnel, _command(2, "Runtime.enable")])
+ client.request.headers = {"x-api-key": "key"}
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: client.echoes())
+
+ # The id-less tunnel never reached the browser (checked over ALL forwarded
+ # frames, since the tunnel decodes as an event, not a command); only the
+ # legitimate command did. Without the guard this frame is forwarded raw and
+ # "Target.sendMessageToTarget" appears here.
+ upstream = [decode_frame(wire) for wire in connection.sent]
+ upstream_methods = [f.method for f in upstream if isinstance(f, (CdpCommand, CdpEvent))]
+ assert "Target.sendMessageToTarget" not in upstream_methods
+ assert upstream_methods == ["Runtime.enable"]
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_the_static_env_denylist_wiring_denies_through_a_live_server() -> None:
+ pipeline = build_pipeline("forward-all", denylist="Network.*, Page.navigate")
+ assert pipeline.has_interceptors
+
+ connection = _ControllableUpstream()
+ sessions = InMemorySessionRegistry()
+ sessions.put(ResolvedSession(session_id="s1", upstream_adapter="memory", upstream_ws_url=UPSTREAM_URL))
+ server = CdpProxyServer(
+ upstream=_SharedBrowser(connection), # type: ignore[arg-type]
+ sessions=sessions,
+ auth=StaticKeyAuth({"key": Principal(principal_id="p", organization_id="org")}),
+ metrics=_RecordingMetrics(), # type: ignore[arg-type]
+ event_policy=ForwardAllEventPolicy(),
+ pipeline=pipeline,
+ )
+ client = _ScriptClient([_command(1, "Network.enable"), _command(2, "Runtime.enable")])
+ client.request.headers = {"x-api-key": "key"}
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: len(client.sent) >= 2)
+
+ [denied] = [r for r in _responses(client) if r.error is not None]
+ assert denied.id == 1
+ assert denied.error == denied_error("Network.enable")
+ assert _upstream_methods(connection) == ["Runtime.enable"]
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+def test_a_bad_env_denylist_pattern_fails_the_boot_not_a_command() -> None:
+ with pytest.raises(MethodPatternError):
+ build_interceptors("", "Network.*,bad*pattern")
+ assert build_interceptors("", "") == ()
+
+
+async def test_denylists_apply_per_organization_across_all_its_sessions() -> None:
+ """AC: an org with a denylist gets deterministic errors on banned methods on
+ every session it owns, while another org's identical command passes."""
+ denylists = {"org-a": MethodPatternSet.compile(["Runtime.*"])}
+
+ async def lookup(session: ProxySession) -> MethodPatternSet | None:
+ organization_id = session.principal.organization_id if session.principal else None
+ return denylists.get(organization_id) if organization_id else None
+
+ connection_a, connection_b = _ControllableUpstream(), _ControllableUpstream()
+
+ class _TwoBrowsers:
+ async def connect(self, session: ProxySession) -> _ControllableUpstream:
+ return connection_a if "org-a" in session.upstream_ws_url else connection_b
+
+ sessions = InMemorySessionRegistry()
+ sessions.put(
+ ResolvedSession(
+ session_id="sa", upstream_adapter="memory", upstream_ws_url="ws://org-a/b", organization_id="org-a"
+ )
+ )
+ sessions.put(
+ ResolvedSession(
+ session_id="sb", upstream_adapter="memory", upstream_ws_url="ws://org-b/b", organization_id="org-b"
+ )
+ )
+ metrics = _RecordingMetrics()
+ server = CdpProxyServer(
+ upstream=_TwoBrowsers(), # type: ignore[arg-type]
+ sessions=sessions,
+ auth=StaticKeyAuth(
+ {
+ "key-a": Principal(principal_id="a", organization_id="org-a"),
+ "key-b": Principal(principal_id="b", organization_id="org-b"),
+ }
+ ),
+ metrics=metrics, # type: ignore[arg-type]
+ event_policy=ForwardAllEventPolicy(),
+ pipeline=MiddlewarePipeline(interceptors=[org_denylist_interceptor(lookup)]),
+ )
+
+ client_a = _ScriptClient([_command(1, "Runtime.evaluate"), _command(2, "Page.enable")])
+ client_a.request.path = "/sa"
+ client_a.request.headers = {"x-api-key": "key-a"}
+ client_b = _ScriptClient([_command(1, "Runtime.evaluate")])
+ client_b.request.path = "/sb"
+ client_b.request.headers = {"x-api-key": "key-b"}
+
+ task_a = asyncio.create_task(server._handle_client(client_a)) # type: ignore[arg-type]
+ task_b = asyncio.create_task(server._handle_client(client_b)) # type: ignore[arg-type]
+ assert await _until(lambda: len(client_a.sent) >= 2 and client_b.sent)
+
+ # org-a: the banned method is answered with the deterministic error, its other
+ # command still reaches the browser; the banned one never does.
+ [denied] = [r for r in _responses(client_a) if r.error is not None]
+ assert denied.id == 1
+ assert denied.error == denied_error("Runtime.evaluate")
+ assert _upstream_methods(connection_a) == ["Page.enable"]
+ # org-b: the same method sails through.
+ assert client_b.echoes() == {"Runtime.evaluate"}
+ assert _upstream_methods(connection_b) == ["Runtime.evaluate"]
+ # AC: denied attempts are visible in the audit trail, attributed to the org.
+ audits = [tags for op, name, _, tags in metrics.calls if name.endswith("commands_intercepted")]
+ assert audits == [
+ {"org_id": "org-a", "reason": DENYLIST_REASON, "cdp_method": "Runtime.evaluate", "cdp_domain": "Runtime"}
+ ]
+
+ client_a.release()
+ client_b.release()
+ await asyncio.wait_for(asyncio.gather(task_a, task_b), timeout=5)