#!/usr/bin/env python3 """chv-browser：浏览器子代理（客机侧、单元外独立进程）。 对齐 Muse P4（见 docs/chv-muse-p4-gap.md）：本文件源自 P2 的 chv-browser.py（c61484a），P4 在此基础上重构——子代理不再直连 Playwright/Chromium，Chromium 的所有权在单元外 CDP broker （chv-cdp-broker.py）手里；本进程只是 broker 的客户端。 子代理只向单元返回页面无障碍树快照（Playwright accessibility.snapshot，经 broker 取回），不见原始 DOM，不能 在页面上下文跑 JS，不暴露交互操作，不开 DevTools。 操作（Unix socket /run/chv/browser.sock，JSON 行）： open {url} -> 经 broker 导航并返回 {title, url, a11y, truncated, untrusted_input, injection_flags, form_risk} snapshot {} -> 当前页同上 screenshot {} -> 截图落盘，返回 {path} close {} -> 关当前页 pause {} -> 暂停（用户接管/填表/自动暂停的统一状态） resume {} -> 解除暂停 status {} -> {paused, url, form_risk} list_asks {} -> 待审批 ask 列表 resolve_ask {ask_id, decision} -> 写回 allow/denied ping {} -> {"ok": true} 暂停时除 ping/resume/status/list_asks/resolve_ask 外一切操作 拒绝——用户接管或凭证注入填表时，代理完全不能行动。 URL 校验、快照截断、错误消毒、禁用操作表都在 chv_browser_guard.py（纯函数模块，两脚本共用）。本层再做一次 validate_url 与 truncate_a11y（纵深防御），回包先过泄露检查。 只用标准库。运行身份：系统用户 chv-browser，socket 0600 （broker 以 root 连，不受模式限制）。 """ import importlib.util import json import os import socket import sys BROWSER_SOCK = "/run/chv/browser.sock" CDP_SOCK = "/run/chv/cdp-broker.sock" MAX_REQUEST_BYTES = 65536 _GUARD = None def _load_guard(): """加载同目录的 chv_browser_guard（纯函数模块）。""" global _GUARD if _GUARD is not None: return _GUARD here = os.path.dirname(os.path.abspath(__file__)) path = os.path.join(here, "chv_browser_guard.py") spec = importlib.util.spec_from_file_location( "chv_browser_guard", path) module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) _GUARD = module return module class BrowserAgent: """浏览器子代理：CDP broker 的客户端。broker_call 供单测注入 假 broker（收到 req dict 返回 resp dict）；正常运行时走 Unix socket 直连 broker。""" def __init__(self, cdp_sock_path=CDP_SOCK, broker_call=None): self._guard = _load_guard() self._cdp_sock_path = cdp_sock_path self._broker_call = broker_call self._paused = False def _call(self, req): if self._broker_call is not None: return self._broker_call(req) try: conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) conn.settimeout(120) conn.connect(self._cdp_sock_path) except OSError as e: return {"ok": False, "error": "CDP broker 未就绪：%s" % e} try: conn.sendall((json.dumps(req, ensure_ascii=False) + "\n").encode()) data = b"" while len(data) < MAX_REQUEST_BYTES: chunk = conn.recv(4096) if not chunk: break data += chunk if data.endswith(b"\n"): break except OSError as e: return {"ok": False, "error": "CDP broker 通信失败：%s" % e} finally: conn.close() try: resp = json.loads(data.decode()) except (ValueError, UnicodeDecodeError): return {"ok": False, "error": "CDP broker 回包不是 JSON"} if not isinstance(resp, dict) or "ok" not in resp: return {"ok": False, "error": "CDP broker 回包格式不对"} return resp def _sync_paused(self, resp): """从回包同步暂停镜像状态（broker 暂停时本层同样拒绝）。""" if isinstance(resp, dict) and "已暂停" in str( resp.get("error", "")): self._paused = True return resp def _blocked_while_paused(self): return {"ok": False, "error": "浏览器已暂停（用户接管/填表/自动暂停）"} def open(self, url): if self._paused: return self._blocked_while_paused() ok, err = self._guard.validate_url(url) if not ok: return {"ok": False, "error": err} resp = self._call({"op": "open", "url": url}) if resp.get("ok") and isinstance(resp.get("a11y"), dict): tree, truncated = self._guard.truncate_a11y(resp["a11y"]) resp = dict(resp) resp["a11y"] = tree resp["truncated"] = bool(resp.get("truncated") or truncated) return self._sync_paused(resp) def snapshot(self): if self._paused: return self._blocked_while_paused() resp = self._call({"op": "snapshot"}) if resp.get("ok") and isinstance(resp.get("a11y"), dict): tree, truncated = self._guard.truncate_a11y(resp["a11y"]) resp = dict(resp) resp["a11y"] = tree resp["truncated"] = bool(resp.get("truncated") or truncated) return self._sync_paused(resp) def screenshot(self): if self._paused: return self._blocked_while_paused() return self._sync_paused(self._call({"op": "screenshot"})) def close(self): if self._paused: return self._blocked_while_paused() resp = self._call({"op": "close"}) return self._sync_paused(resp) def pause(self): resp = self._call({"op": "pause"}) if resp.get("ok"): self._paused = True return resp def resume(self): resp = self._call({"op": "resume"}) if resp.get("ok"): self._paused = False return resp def status(self): resp = self._call({"op": "status"}) if isinstance(resp, dict) and "paused" in resp: self._paused = bool(resp["paused"]) return resp def list_asks(self): return self._call({"op": "list_asks"}) def resolve_ask(self, ask_id, decision): resp = self._call({"op": "resolve_ask", "ask_id": ask_id, "decision": decision}) if resp.get("ok") and resp.get("decision") == "allowed": self._paused = False return resp def handle_request(agent, req): """处理一个请求 dict，返回响应 dict（纯逻辑，可单测）。""" guard = _load_guard() if not isinstance(req, dict): return {"ok": False, "error": "请求须是 JSON 对象"} op = req.get("op") if op in guard.FORBIDDEN_OPS: return {"ok": False, "error": "操作 %r 不暴露（无 JS/无原始 DOM/无交互）" % op} if op == "ping": return {"ok": True, "browser": True} if op == "open": return agent.open(req.get("url")) if op == "snapshot": return agent.snapshot() if op == "screenshot": return agent.screenshot() if op == "close": return agent.close() if op == "pause": return agent.pause() if op == "resume": return agent.resume() if op == "status": return agent.status() if op == "list_asks": return agent.list_asks() if op == "resolve_ask": return agent.resolve_ask(req.get("ask_id"), req.get("decision")) return {"ok": False, "error": "未知操作：%r（白名单：open/snapshot/screenshot/" "close/pause/resume/status/list_asks/resolve_ask/" "ping）" % (op,)} def _handle_conn(agent, conn): """一个连接一请求一响应；回包先过泄露检查，不过即换通用错； 错误信息过消毒，绝不把页面原文原样放进回包。""" guard = _load_guard() conn.settimeout(120) data = b"" while len(data) < MAX_REQUEST_BYTES: chunk = conn.recv(4096) if not chunk: break data += chunk if data.endswith(b"\n"): break try: req = json.loads(data.decode()) except (ValueError, UnicodeDecodeError): resp = {"ok": False, "error": "请求不是合法 JSON"} else: try: resp = handle_request(agent, req) except Exception as e: resp = {"ok": False, "error": guard.sanitize_error(e)} if guard.response_leaks(resp): resp = {"ok": False, "error": "响应泄露检查未通过（已拦截）"} conn.sendall((json.dumps(resp, ensure_ascii=False) + "\n").encode()) def serve(sock_path=BROWSER_SOCK, cdp_sock_path=CDP_SOCK): """监听 Unix socket，逐连接处理。socket 0600。建不起来即抛错， 不要静默带病跑。""" if os.path.exists(sock_path): os.remove(sock_path) os.makedirs(os.path.dirname(sock_path), exist_ok=True) srv = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) srv.bind(sock_path) srv.listen(16) os.chmod(sock_path, 0o600) print("chv-browser: 监听 %s" % sock_path, file=sys.stderr, flush=True) agent = BrowserAgent(cdp_sock_path=cdp_sock_path) try: while True: try: conn, _ = srv.accept() except OSError: continue try: _handle_conn(agent, conn) except OSError as e: print("chv-browser: 连接处理异常：%s" % _load_guard().sanitize_error(e), file=sys.stderr, flush=True) finally: try: conn.close() except OSError: pass finally: pass def main(argv): sock_path = BROWSER_SOCK cdp_sock_path = CDP_SOCK i = 0 while i < len(argv): if argv[i] == "--socket" and i + 1 < len(argv): sock_path = argv[i + 1] i += 2 elif argv[i] == "--cdp-socket" and i + 1 < len(argv): cdp_sock_path = argv[i + 1] i += 2 else: print("chv-browser: 未知参数：%s" % argv[i], file=sys.stderr) return 2 serve(sock_path, cdp_sock_path) return 0 if __name__ == "__main__": raise SystemExit(main(sys.argv[1:]))