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。

六、审计重点关注项(逐条核实)

脚本执行无沙箱(最高优先级) —— 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;单管理员私有部署则属设计使然,但仍建议在报告中明确标注。
仓库内硬编码密钥 —— node/deploy/docker-compose.yml:10:NODE_KEY=18036c... 为未注释的真实样例值,随仓库分发。若该 key 曾用于生产,需轮换。
节点认证强度 —— node-auth.ts 为普通字符串比较(非常量时间);timingSafeEqual 仅在 admin/src/api/routes/webdesk.ts:181(HMAC 比较)使用。未配置 NODE_KEY 时节点 API 完全开放(依赖网络隔离)。
登录无防爆破 —— 全库未发现 rate limit / 登录失败锁定;无独立 CSRF token,依赖会话 Cookie 的 SameSite=Lax 兜底(session.ts:144-151,已核实)。
CORS 通配 —— admin/src/api/routes/webdesk.ts:25:access-control-allow-origin: *,仅作用于两条 WebDesk 免登录路由(已核实仅此文件),该组路由用 HMAC 节点密钥保护。
查询参数携带凭证 —— VNC/WebDesk WS 鉴权使用 ?token= / ?ticket=(SDK 限制),凭证会进代理/访问日志;票据为 5 分钟一次性(direct.ts)。
节点本身高权限 —— Docker privileged 容器内跑 Xvfb/x11vnc/CRIU dump-restore/impersonate MITM(共享本地 CA 私钥);节点被攻破=宿主机被攻破,节点与管理面间是 NODE_KEY 单因素。
execute_js(MCP 工具) —— 在 Profile 页面上下文执行任意 JS;单看是低危页面脚本,但结合第 1 条(脚本系统)即构成完整 RCE 面;MCP Token 与用户 API Token 同一凭证,泄露即获得该用户全部 54 个工具能力。
多用户边界 —— 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 管线)。

12 KiB Raw Blame History