1.77.6: SERP sorry-重定向按验证码语义(不换号+15min冷却);浏览池保温释放跳过+60min持有上限;速率-门壳实验与监控工具

docs/审计-功能清单与技术栈.md

@@ -0,0 +1,113 @@
+# SerpMax(ProfileMax)审计准备:功能清单与技术栈
+
+> 生成日期:2026-10-28。版本以各服务 package.json 为准:admin v1.74.2、node v0.43.0。
+> 本文所有"审计重点"均已逐条核实源码(含 file:line),非推断。
+
+## 一、项目定位与总体架构
+
+SerpMax 是一套**反检测指纹浏览器农场管理平台**:集中管理大量带浏览器指纹的 Profile(指纹、代理、Cookie、插件),在多个远程节点上批量启动 Chromium 并自动化,配套 SERP 采集、Cloudflare/reCAPTCHA 挑战处理、VNC/WebDesk 人工接管,并通过 MCP 接口暴露给 AI Agent。
+
+- **admin**(`admin/`,profilemax-admin v1.74.2):管理后台单进程 Bun 服务(端口 5300),持有 PostgreSQL;React 前端构建产物由 nginx 直出。浏览器操作类 API 大多为**中继**:按 `profile.node → nodes.base_url` 转发到节点并附节点密钥(见 `docs/API.md` 头部)。
+- **node**(`node/`,profilemax-node v0.43.0):运行节点(端口 3100),无 UI、无业务数据库(仅只读 Chrome History 的本地 SQLite);Docker privileged 部署,管理浏览器进程、Xvfb/x11vnc、WebDesk、impersonate MITM 代理、CRIU 快照。
+- **stress/**:并发常驻浏览器压测套件(造号、发射器、/proc PSS 采样、报告)。
+
+## 二、技术栈
+
+| 层 | 技术 |
+|---|---|
+| 运行时 | Bun(oven/bun 1.4)+ TypeScript,裸 `Bun.serve()` routes,无 Express/Hono 等框架 |
+| 浏览器内核 | **双内核**:veil-chromium(自研,ungoogled-chromium 153 + C++ 指纹补丁,指纹由启动旗标驱动)与 cloakbrowser npm 包(包装 Chromium + Playwright API) |
+| 自动化 | playwright-core(CDP 驱动) |
+| admin 数据库 | PostgreSQL(`Bun.sql`),`pgarray.ts` 处理 text[] |
+| admin 前端 | React 19 + antd 6 + Tailwind 4(`bun-plugin-tailwind` + `Bun.build`,无 vite/webpack),lucide-react、flag-icons、**@novnc/novnc**(RFB over WebSocket) |
+| 查看器 | noVNC + 自研 WebDesk(`vendor/webdesk/webdesk-linux-static` 静态二进制:WebP 帧流 + 私有二进制协议 0x10/0x11/0x12/0x13-14/0x16,XTEST 键鼠注入) |
+| 网络伪装 | 自研 impersonate-proxy(Go,本地 MITM:uTLS/JA3/HTTP2/头序伪装)+ socks5 链;`socks-proxy-agent`;mmdb-lib(GeoIP) |
+| 对象存储 | 自研 S3 SigV4 客户端(`admin/src/core/s3.ts`,path-style、Multipart 64MB 分片,零第三方依赖),用于备份上传 |
+| 身份 | 本地账密(Bun.password/bcrypt)+ ZITADEL OIDC(Authorization Code + PKCE,公共客户端) |
+| 打码 | recaptcha-answer 外部识别服务(4x4 宫格远端 AI,其余 ONNX 本地) |
+| 快照 | CRIU checkpoint/restore 整棵 Chromium 进程树(仅 headless,D-Bus 隔离) |
+| 部署 | Docker(privileged,代码挂卷 + `/system/update` 自更新)、systemd 免 Docker 安装包、pg_basebackup/pg_dump 备份 |
+
+## 三、功能清单
+
+### admin 侧(管理后台)
+
+**认证与多用户**:登录/登出/当前用户、改密、API Token 签发与轮换;ZITADEL OIDC 绑定/解绑/JIT 建号;用户 CRUD 与菜单权限分配(仅内置 id=1 为 admin,`session.ts` 强制)。
+
+**Profile 管理**:CRUD、创建时一次生成指纹快照并固化(数字种子/UA/屏幕/时区语言/WebGL/canvas·audio 噪声种子/字体)、批量、复制(duplicate)、转移、分享(`profile_shares`:use=查看运行 / edit=编辑删除分享)、启停、浏览器状态、磁盘软清/硬重置。
+
+**Cookie 与存储**:Cookie Jar 读写/批量删除/导入导出;浏览器运行时 Cookie 与 Jar 双写同步;Profile 存储(IndexedDB/localStorage)与插件自有数据 zip 导出导入。
+
+**代理**:CRUD、批量导入、标签/facets、出口 IP 测试、启停;socks5/socks5h/http/https。
+
+**DNS(替代 hosts)**:host→IP 条目 CRUD、内容检测规则(正则/子串,如 google-serp)、经指定代理探测(google 系取首页匹配+延迟)、通过的条目打标签组并随代理下发到绑定 Profile;节点经 `/api/node/dns/entries.json` 全量同步。
+
+**插件库**:上传 zip、Chrome Web Store 详情页导入、sha256 增量下发节点、静默安装(删 manifest.key+版本加 build 号→浏览器自打 CRX→External Extensions)。
+
+**脚本系统**:两种 kind——`code` 存 JS/TS 源码、`schema` 存 JSON 步骤编排;标签;直接执行(run 需显式 profileRefs)。
+
+**任务系统**:任务=脚本+Profile 标签圈定+并发上限+逐目标错峰+周期+jitter;调度器每 60s tick,SQL 原子认领到期任务;运行记录、取消;`zombieReaper` 收割重启遗留的 RUNNING 僵尸。
+
+**SERP 采集**:Google 搜索,json/html/raw 三形态输出(兼容 Rust serp-api 形状)、温页池(warm→直接在温页上搜索,降低触发风控)、缓存、统计、健康检查。
+
+**挑战处理**:每 Profile 可开关的 CF Turnstile 自动过盾与 reCAPTCHA 自动打码;reCAPTCHA 手动打码会话(前端 CaptchaSolveModal 经中继点格子)。
+
+**浏览器中继**(`routes/browser-relay.ts`,全部转发节点):SSE 事件流(state/动态 FPS 截图)、批量动作、execute、启停/窗口、cf-solver、recaptcha-solver、VNC/WebDesk WS 中继(WS 握手做 Profile 访问控制)、captcha 图块接口、httpcache 统计。
+
+**节点管理**:注册/心跳/自更新(`/api/node-package`、`/node/version`,含 `/api` 别名规避 CF 520)/安装脚本下发/硬件信息。
+
+**MCP Server**(`admin/src/api/mcp.ts`,1033 行):`POST /mcp`,JSON-RPC 2.0 无状态 Streamable HTTP,协议版本 2025-03-26;**54 个工具**(Profile 全生命周期、fetch_url/fetch_by_condition、execute_js、代理/插件/Cookie/节点查询、脚本与任务 CRUD+运行+取消等);认证=Bearer 用户 API Token;工具直接调用内部处理器,自动继承多用户访问控制。
+
+**运维**:事件日志查询/清理、Dashboard 聚合统计、S3 配置(仅 root)与备份(pg_basebackup 全量/增量 + pg_dump 逻辑 + S3 上传,`backup_runs` 表)、settings KV、Prometheus `/metrics`(节点侧)、WebDesk 免登录起始页(HMAC 节点密钥签名)。
+
+### node 侧(运行节点)
+
+- **Profile 运行**:启动/停止/重启、CDP 端点、crash 处理与恢复、空闲回收(reaper)、磁盘配额;快照开关(CRIU dump/restore 保留页面现场)。
+- **Lease**:Acquire/Heartbeat/Release/超时扫描,保证一个 Profile 同一时间一个消费者;超时自动停浏览器回 READY。
+- **Fetch 体系**:Profile 上下文 HTTP fetch(代理+UA+Cookie 三来源合并);`impersonate.fetch` 走本地 impersonate-proxy MITM(uTLS/JA3/HTTP2)再经 socks5 出站,执行体 go-fetch 二进制、curl 回落;每 Profile 一个 impersonate-proxy 进程(独立端口+YAML+共享 CA)。
+- **WebRTC 防泄露**:`--force-webrtc-ip-handling-policy=disable_non_proxied_udp` + init script 改写 SDP/ICE 候选为代理出口 IP。
+- **浏览器控制**:`browser-control.ts` 批量动作 + SSE(state/screenshot 动态 FPS)。
+- **SERP 浏览池**:pool 快照/warm/search/unwarm。
+- **VNC/WebDesk**:每浏览器独立 Xvfb + x11vnc(display≥100、rfbport≥6100);WebDesk 挂同一 Xvfb 提供私有 WS 协议,agent 只听 127.0.0.1+随机 token,node/admin 透明字节管道。
+- **一次性直连票据**(`direct.ts`):VNC/直连 5 分钟有效。
+- **节点系统 API**:`/health` `/ready` `/metrics` `/events`、目录覆盖、自更新、Schema 编排执行器(lease→起浏览器→逐步执行→释放,错误策略 stop/continue/retry)。
+
+## 四、数据层(admin,PostgreSQL,24 张表)
+
+`migrate.ts`(1075 行,幂等 `CREATE TABLE IF NOT EXISTS` + `ALTER TABLE ADD COLUMN IF NOT EXISTS`,启动即跑,无版本表):
+
+`proxies`、`profiles`、`profile_statistics`、`cookies`、`profile_storage`、`logs`、`captcha_events`、`settings`(KV)、`admin_user`、`sessions`、`users`、`scripts`、`tasks`、`profile_task_state`、`task_runs`、`profile_shares`、`dns_rules`、`dns_entries`、`extensions`、`nodes`、`oidc_identities`、`serp_requests`、`goto_cache`、`backup_runs`。
+
+repo 层 `admin/src/repos/*` 每表一文件。
+
+## 五、认证与授权模型(已核实)
+
+- **会话双通道**(`admin/src/api/session.ts`):①Cookie `smax_session`(HttpOnly + **SameSite=Lax** + 可选 Secure,token=两个 uuidv7 拼接,存 sessions 表,TTL 可配);②`Bearer <users.api_token>`(`smax_` 前缀)。
+- **权限阶梯**:`requireUser` → `requireAdmin`(role=admin)→ `requireRoot`(仅 id=1);业务菜单级权限 `requirePerm(req, "tasks" 等)`;Profile 级 `loadProfileFor`(归属者/被分享者/admin),`access.ts` 统一 404/403。
+- **密码**:Bun.password(bcrypt);**默认管理员密码**来自 `config.defaultAdminPassword`。
+- **OIDC**:ZITADEL Auth Code + PKCE(公共客户端);state 一次性消费 10 分钟(注释明示作 CSRF 防护);身份主键 (issuer, subject),绝不以 email 为键;配置存 settings KV。
+- **节点认证**(`node/src/api/middleware/node-auth.ts`):配置 `NODE_KEY` 时要求 `x-node-key` 头或 Bearer;**未配置则全放行**(注释:本机/内网模式)。
+- **MCP**:仅 Bearer 用户 API Token,未认证 401。
+
+## 六、审计重点关注项(逐条核实)
+
+1. **脚本执行无沙箱(最高优先级)** —— `node/src/core/schema/schema.actions.ts:246-257`:用户 JS/TS 先包进 `async function __task__(ctx){...}`,`Bun.Transpiler` 剥 TS 类型后 `new Function(...)` 在**节点服务进程内**执行。`new Function` 作用域是全局,Bun/node API(fs、网络、子进程)全部可达 —— 等于服务器任意代码执行。`ctx` 本身也提供完整 Playwright API 与 task_state 读写。多用户部署下,任何拥有 tasks 菜单权限的普通用户可创建/运行脚本(`handleScriptCreate/Run` 仅 `requirePerm(req,"tasks")`,见 `admin/src/api/routes/tasks.ts:148/779`)→ 等效 RCE;单管理员私有部署则属设计使然,但仍建议在报告中明确标注。
+2. **仓库内硬编码密钥** —— `node/deploy/docker-compose.yml:10`:`NODE_KEY=18036c...` 为未注释的真实样例值,随仓库分发。若该 key 曾用于生产,需轮换。
+3. **节点认证强度** —— `node-auth.ts` 为普通字符串比较(非常量时间);`timingSafeEqual` 仅在 `admin/src/api/routes/webdesk.ts:181`(HMAC 比较)使用。未配置 NODE_KEY 时节点 API 完全开放(依赖网络隔离)。
+4. **登录无防爆破** —— 全库未发现 rate limit / 登录失败锁定;无独立 CSRF token,依赖会话 Cookie 的 SameSite=Lax 兜底(session.ts:144-151,已核实)。
+5. **CORS 通配** —— `admin/src/api/routes/webdesk.ts:25`:`access-control-allow-origin: *`,仅作用于两条 WebDesk 免登录路由(已核实仅此文件),该组路由用 HMAC 节点密钥保护。
+6. **查询参数携带凭证** —— VNC/WebDesk WS 鉴权使用 `?token=` / `?ticket=`(SDK 限制),凭证会进代理/访问日志;票据为 5 分钟一次性(direct.ts)。
+7. **节点本身高权限** —— Docker privileged 容器内跑 Xvfb/x11vnc/CRIU dump-restore/impersonate MITM(共享本地 CA 私钥);节点被攻破=宿主机被攻破,节点与管理面间是 NODE_KEY 单因素。
+8. **execute_js(MCP 工具)** —— 在 Profile 页面上下文执行任意 JS;单看是低危页面脚本,但结合第 1 条(脚本系统)即构成完整 RCE 面;MCP Token 与用户 API Token 同一凭证,泄露即获得该用户全部 54 个工具能力。
+9. **多用户边界** —— Profile 权限模型完善(归属/分享两级+菜单权限),但 admin 强制仅 id=1 为 admin(`session.ts`);历史 admin 角色降级,需在审计中确认用户升级路径的一致性。
+
+## 七、仓库结构与文档地图
+
+- `docs/`:`API.md`(全栈 API:admin 5310 行/node 3100 行+中继架构)、CRIU 快照方案、插件 bind-mount 存档、Google IPv6 列表。
+- `admin/docs/`(AI 可读,经 /docs 免登录直出):overview、rest-api、mcp、schema、scripts、tasks、serp、VNC、API、开发执行文档、验收截图。
+- `node/docs/`:技术开发规范、Browser-Control 协议、webdesk-viewer 协议、动态 FPS 截图模块、veil 内核迁移问题清单。
+- `admin/scripts/`:前端构建、CDP 可视化验收、本地 SOCKS5 开发代理、**keepalive-flow.ts(生产级保活脚本 v3)**、插件恢复。
+- `node/scripts/`:验收(20 步含 crash/lease/schema 超时)、CRIU PoC/基准、各探针、mkcrx.py、systemd 打包。
+- `node/deploy/`:Dockerfile.node、docker-compose.yml(privileged)。
+- `stress/`:造号、压测发射器、PSS 采样、报告(OVH-FR 8C/31G 实测)、清理工具。
+- 根目录 `tests-ka-flow.ts`:保活脚本状态机测试(mock ctx 复刻节点 script.run 管线)。