Files
2026-11-02 22:54:14 +08:00

100 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# universal-web-api 代码审查报告
> 审查日期:2026-09-25 · 项目:[lumingya/universal-web-api](https://github.com/lumingya/universal-web-api) · 审查分支:`main` · 审查代码基准:`9c1b53b`(此前提交仅新增/更新审查日志,未修改业务逻辑)。
>
> 范围:按“下载项目、详细寻找可优化之处与 Bug、汇报”的要求,审查配置、API、认证、命令/工作流、标签页池、媒体、前端与测试。**本轮只审查和报告,没有修复业务代码。** 更细的证据和阶段过程见同目录的 `DEVLOG-code-review-2026-09.md`。
## 一、结论先行
**不建议以当前默认配置将控制面板/API 暴露到公网或不可信局域网。** 最紧迫的是:默认关闭的管理认证与开放 CORS(S1),叠加一个会原样导出 `.env` 的只读备份接口(S13);其次是将上游媒体保存为可在应用同源访问的活动格式(S8、S9)。此外,配置模板具有误导性,命令文件热加载可在配置暂时损坏时清空全部命令,后台调试捕获可能持久化聊天响应。
共记录 **38 条**:P1 高优先级 **6**、P2 中优先级 **15**、P3 低优先级 **17**;其中安全/隐私类 `S` 14 条、功能问题 `B` 8 条、优化/仓库卫生 `H` 14 条、测试可复现性 `T` 2 条。**数量不等于 38 个独立可利用漏洞**:例如 S13 是 S1 在备份接口上的高价值具体表现,S3 与 S2 的信任边界相连;标记“条件性/静态”的条目尚无真实浏览器或网络攻击验证。
### 现在就做的部署缓解
1. **隔离服务**:在完成修复前仅绑定可信回环/内网,经防火墙或可信反向代理收紧访问;显式启用服务和仪表板认证,使用不同的强令牌;CORS 限制为必要的准确来源。对 `/api/settings/backup` 单独强制认证,不能仅依赖默认关闭的全局开关。
2. **保护凭据**:若曾把服务暴露给不可信主体,检查访问日志、已导出的备份和 `logs/network_parser_debug`,按实际暴露范围轮换 `.env` 中的令牌/密钥。不要把完整备份文件直接分享、提交或发送给第三方。
3. **关闭高风险输出**:将 `NETWORK_DEBUG_CAPTURE_ENABLED` 显式设为 `false` 并确认运行时值;暂时限制 `/media`、`/download_images` 外部访问,不允许以同源内联方式打开未验证的 SVG/HTML。
4. **限制自定义代码**:只有可信管理员才能安装解析器、配置 Python/JS 命令。AST 过滤不能替代 OS 级隔离。
## 二、证据口径与验证范围
- **[实测]**:合成数据、无网络 mock、`httpx.ASGITransport` 进程内 HTTP、Node VM 或短小临时文件/桩;**不是**真实浏览器或公网攻击验证。
- **[静态/条件]**:代码路径足以说明前置条件和风险,但没有在真实部署、CDP、DNS 重绑定、恶意第三方页面或用户点击场景完成利用验证。
- **[优化]**:容量、可维护性和坏输入健壮性建议;不表示已发生生产故障。
轻量基线:226 个 Python 文件语法检查通过;33 个项目 JS 文件 `node --check` 通过;Ruff 的选定语法/未定义名规则有 5 个 F821。剔除依赖本机私有配置/浏览器的用例后,独立子集 **544 passed、30 deselected**。更宽的首轮为 **548 passed、74 failed、9 deselected**:64 个失败归因缺失/过期的本地 fixture,9 个为站点自动发现断言(B1),1 个为缺失的开发依赖 `httpx`(T2);不能声称“全套测试通过”。**没有**安装 Playwright/Chromium、运行重度浏览器 E2E、截屏、加载大文件或做高并发压力测试。
## 三、高优先级:安全边界与默认配置(P1)
| ID | 问题、证据与条件 | 建议 |
| --- | --- | --- |
| **S13 · 备份泄露密钥** | `app/api/system.py:79-113,293-315,948-952`:`GET /api/settings/backup` 返回 `.env` 所有解析到的键值;默认仪表板认证关闭且 CORS 允许 `*`。进程内**用合成密钥**模拟后,外来源、无授权的 GET 为 200、允许跨源,响应含合成值。另 `static/js/dashboard-methods.js:1602-1648` 把浏览器本地面板令牌以 `dashboard_token` 和 `api_token` 两字段写入明文下载包;Node VM 合成令牌验证。**前提**:服务可达、`.env` 中实际有敏感值;文件导出风险即使启用认证也存在。 | 备份接口始终强制管理鉴权/最小权限,收紧 CORS;默认备份剔除或遮蔽秘密,敏感备份采用明确提示、加密和短生命周期;浏览器本地令牌默认不导出。增加无授权 401 与无密钥回显的回归测试。 |
| **S1 · 控制面默认开放** | `app/core/config_parts/env_config.py:159-188`, `main.py:603-616`:认证默认关闭,CORS 默认为 `*`。ASGITransport 验证第三方 Origin 能读取 `/api/commands`;仅启用管理认证后,无令牌 401、带合成令牌 200。S13 是特别危险的只读示例;管理写接口同样需要保护。真实浏览器私网策略、代理拓扑尚未验证。 | 默认 fail-closed;非回环绑定必须设认证令牌,限定 Host/Origin;管理操作考虑 CSRF/来源约束和角色权限。 |
| **S8 · SVG 同源活动内容** | `app/core/browser/media.py:2432-2440,2644-2677,2693-2734,2829-2836`, `main.py:839-841`:后台下载拒绝 SVG,但前台回退接受 `image/svg+xml` 并原样保存 `.svg` 到公开目录。[实测] mock 产出文件,ASGI GET 返回 `image/svg+xml`,没有强制下载/CSP。**须攻击者可影响上游媒体,且受害者直接导航打开该本地 SVG**;不能把作为 `<img>` 展示等同于脚本执行。 | 前后台统一拒绝 SVG 或转换成安全位图;媒体使用隔离域、附件下载和严格 CSP、`nosniff`。 |
| **S9 · 音视频 HTML 落盘** | `app/core/browser/media.py:2101-2215`, `app/core/extractors/media_extractor.py:929-945,1006-1080`, `main.py:728-742,804-825`:仅检验响应头含 `video`/`audio`,可从远端 URL 取得 `.html` 后缀并写出该内容。[实测] mock `clip.html` + `video/custom` 落盘后,同源 GET 为 `text/html`、`inline`、无 CSP。**须控制上游地址及响应,受害者访问生成链接**;尚未在浏览器执行脚本。 | 限定扩展名与实际媒体魔数,拒绝 HTML/SVG,媒体统一强制下载或放隔离源;加针对不一致 MIME/后缀的测试。 |
| **S2 · 自定义代码非安全沙箱** | `app/services/command_engine_actions.py:2427-2590,3054-3106`:Python 命令仅按 AST 规则限制部分直接调用,还可接触高权限对象;JS 命令可操作浏览器。解析器动态 import(S3)也执行用户代码。此项为**静态信任边界审查**,未运行攻击代码,不能声称某一具体逃逸已利用。 | 禁止不可信主体编写/安装代码;若确有多租户需求,在低权限独立进程/容器内执行并剥离浏览器/配置等高权限对象,限制出网和资源。 |
| **H1 · 模板诱导不安全部署** | `.env.example:7-69,100-138`:重复项与 `AUTH_ENABLED=your-secret-here` / `DASHBOARD_AUTH_ENABLED=your-secret-here`;布尔解析只接受真值,复制模板实际上关闭认证,还示例开放监听、CORS `*` 等。环境路径与地址包含个人部署痕迹。 | 改成安全、可直接复制的示例;在启动时对非布尔值、无令牌的公开绑定给出错误而非静默回退。 |
> **注意**:S8/S9 证明的是落盘与 HTTP 提供活动格式的链路,不是已经在真实浏览器完成 XSS 利用;S13 的示例密钥纯属合成测试,不涉及任何真实凭据。
## 四、中优先级:功能缺陷与条件性风险(P2)
| ID | 位置与实际影响 / 前提 | 修复方向 |
| --- | --- | --- |
| **B8 · 命令配置损坏清空运行缓存 [实测]** | `app/services/command_engine.py:1352-1378,1654-1674`。真实 `CommandEngine` 加载 1 条命令,再将**临时** `commands.json` 置为错误 JSON:热加载得到 0 条,推进 mtime,并产生 1 条 `run_js_file` 清理动作;仅 mock 清理,未操作在线标签页。 | 将“读失败”与合法空命令分开,保留 last-known-good;只有明确有效的新配置才清理预注入脚本。 |
| **B5 · 解冻失败却交付标签 [桩复现]** | `app/core/tab_pool_parts/idle_maintenance.py:346-384`, `session.py:258-278`。假 CDP 抛错后冻结标志在 `finally` 被清除,`acquire()` 仍返回 true、状态 BUSY;真实浏览器后果未测。 | 解冻失败标记异常,不交付会话;保留待确认冻结态并增加失败恢复测试。 |
| **B2 · 旧版历史丢失 [实测]** | `app/services/request_manager.py:545-573`。顶层数组历史在兼容分支前被 `.get()` 抛错,合成文件恢复 0 条;对象格式恢复 1 条。 | 先分支检查 `list`/`dict` 再读取,补升级兼容测试。 |
| **B3 · Responses 内存历史无字节预算 [小样本+静态]** | `app/api/chat.py:93-99,539-608,1030-1076,1950-1955,2420-2425`。默认存整个对话和多模态内容,只有 1h/1024 条数量上限;两轮微型数据储存文本 137→274 字符。状态仅按 response ID 索引,不按认证主体隔离;跨用户访问**须先获得 ID**。 | 限单项/总字节及媒体体积,清理过期状态,按主体绑定续接,并明确默认 `store` 语义。 |
| **S12 · 默认响应调试抓取隐私 [配置实测]** | `config/browser_config.json:371-376`, `app/core/network_monitor.py:1699-1804,1975-1980`。受跟踪配置将抓取设为 `true` 且不过滤解析器,可将响应正文片段写入 `logs/network_parser_debug`;合成普通聊天文本经脱敏器仍保留;字符串 `"false"` 被 `bool()` 判为 true。未触发真实会话落盘。 | 出厂默认关闭、严格解析布尔值;需要开启时明确提示、限制内容与保留期、使用强脱敏,清理历史快照。 |
| **S10 · 图片比对/C2PA 直接取外部 URL [条件性]** | `app/utils/image_validation.py:37-121,151-175,272-370`。从第三方页面提取的图片地址交给 `requests.get`,未统一做私网/重定向检查与流式大小限制;mock 回环 URL 到达请求调用点,未连接真实内网。常规**上传输入图片**另有校验,不能一概而论。 | 复用受限抓取器,检查每次解析/跳转、限制下载字节、data URI 和像素大小。 |
| **S11 · DNS 校验后连接重解析 [条件性]** | `app/utils/remote_resource.py:141-185,206-245`。预先解析并检查地址,HTTP 层仍收到原主机名;若攻击者可控制 DNS,连接时可能换到私网。已有逐跳重定向检查/跨域去凭据,未验证真实重绑定。 | 固定连接到已检查 IP,保持正确 SNI/Host;或通过可信出网代理拦截私网。 |
| **S4 · 回环 IP 当作授权 [条件性]** | `app/api/browser_routes.py:119-129`, `start.py:836-844,905-922`。`open-profile-url` 只认连接来源为回环,无令牌;本机反代或隧道可能使外来调用被视作本机。 | 单独强制管理认证,核实真实代理链,限制可打开的目标 URL。 |
| **S5 · 定时重启代理容量/协议 [静态]** | `start.py:836-892,905-961,1400-1405`。启用 handoff proxy 后单连接缓冲上限 64MB,无总并发约束;仅按 Content-Length 处理请求,chunked/Expect 兼容性不完整。 | 设总连接/缓冲预算、端到端超时;优先使用成熟反向代理组件并明确源地址传递。 |
| **S6 · 媒体路由及转码资源 [静态]** | `main.py:728-737,804-825,839-841`。`/media`、`/download_images` 无认证;请求可触发最长约 60s 转码,无全局并发/同键去重;路径边界校验已存在。 | 对私有媒体鉴权、限制并发和资源消耗;不可把路径穿越误报为本条。 |
| **S3 · 解析器安装立即 import [静态]** | `app/services/parser_manager.py:162-227,331-345`。检查语法/类名后导入源文件即执行代码;未发现直接暴露安装 API,主要与 S2 传入对象/管理员配置相连。 | 可信管理员专用;隔离加载与权限、资源和依赖。 |
| **B1 · 站点自动发现误判 [测试复现]** | `app/utils/site_discovery.py:9-18`, `config/site_rules.json:1-22`。搜索引擎主域默认允许自动发现,9 个纯逻辑断言失败;可能将搜索页当聊天站点。 | 补精确主域禁用规则,并保留 `gemini.google.com` 等所需子域的独立规则。 |
| **T1 · 干净克隆测试资源不全 [测试复现]** | `tests/test_arena_auto_battle_command.py`, `tests/test_media_stream_image_precedence.py` 等依赖未跟踪 `config/commands*.json`、本地 JS 示例,另引用不存在的 `js/arena-conversation-image-window.user.js`;首轮约 64 项失败属 fixture 依赖,**不能推为产品回归**。 | 增加可分发小 fixture,或标为需本地环境的集成测试;CI 运行纯逻辑子集。 |
| **H9 · 标签页等待队列无总量上限 [优化]** | `app/core/tab_pool_parts/manager.py:151-155,2882-2905,3436-3483`。32 个 acquire 工作者限制的是并行线程,不是待执行/等待请求总数;只做静态容量分析,未压测。 | 请求入口限流,设置任务和等待上限,队列过满明确 429/503;监控等待时间。 |
| **H12 · 网络事件 URL 正则可能回溯 [短样本]** | `app/services/command_engine_results.py:637-663`。标准库 `re.search` 无超时,嵌套量词模式在 12→16→19 字符的合成 URL 上约 0.0005→0.0057→0.046s,未进行长串压力测试。 | 限制模式/URL 大小,使用支持超时的匹配器;可参考工作流现有 25ms 正则预算。 |
## 五、低优先级:一致性与可维护性(P3)
| ID | 位置与现象 | 建议 |
| --- | --- | --- |
| **B4** | `app/api/chat.py:469-475,2514-2517,2804-2813`:接受 `n=3` 却只返回 1 个 OpenAI choice(微型模型与格式化器验证)。 | 明确只支持 `n=1` 并拒绝其他值,或实现多路输出。 |
| **B6** | `app/core/tab_pool_parts/idle_maintenance.py:69-103`:`BROWSER_CDP_RECYCLE_AFTER_REQUESTS=inf` 通过浮点解析后 `int(inf)` 抛 `OverflowError`(临时环境复现)。 | 检查 `math.isfinite` 并给出配置错误/默认值。 |
| **B7** | `app/core/workflow/script_loader.py:173-194`:mtime 相同但内容被替换时热加载仍返回旧脚本(临时文件 `first`→`later` 实测)。 | 采用纳秒时间/大小或 hash,配置写入时主动失效缓存。 |
| **S14** | `static/tutorial/index.html:1534-1540`:仍可打开的遗留教程将搜索框原值拼接到 `innerHTML`;Node VM 证明恶意 `<img onerror>` **字符串**进入 HTML sink。只发现自输入路径,没有 URL 自动传播,也没有浏览器执行验证。 | 对搜索词做 HTML 编码或使用 `textContent`,统一教程页面。 |
| **S7** | `main.py:376-406,689-698`, `app/api/system.py:789-815`:开放引导/健康接口暴露站点目录、版本、浏览器/池状态,可能触发浏览器连接。 | 公开健康响应最小化,详细诊断仅对管理员开放。 |
| **H2** | README 三种语言写 2.9.8 且指向缺失 CHANGELOG_CURRENT.md,`VERSION` 为 3.0.0。 | 同步版本、链接和发布校验。 |
| **H3** | `.gitignore` 仍忽略已跟踪 marketplace 缓存;tests 白名单覆盖不一致,scripts 规则重叠。 | 清理规则、审查是否取消跟踪缓存。 |
| **H4** | Python/JS 中约 40 个文件 EOL 混用,无 `.gitattributes`。 | 统一换行约定,分独立提交减小审查噪音。 |
| **H5** | 图片资源存在字节重复,`static/images/logo.svg` 约 792KB。 | 去重和优化 SVG/截图资产,不修改视觉效果。 |
| **H6** | `requirements.txt` 的 FastAPI/Uvicorn 约束偏旧;**未证实特定 CVE 适用于当前依赖范围**。 | 使用锁定依赖与回归测试制定升级计划。 |
| **T2** | `requirements-dev.txt` 未列 `httpx`,依赖 ASGITransport 的纯逻辑测试缺包后报导入错;补装后通过。 | 补 dev 测试依赖或拆出不含浏览器的 tests extra。 |
| **H7** | `app/utils/model_routing.py`, `start.py`:5 处类型注解 `Optional`/`Any` 未导入,Ruff F821;`typing.get_type_hints` 实测 NameError。 | 显式导入、加入静态检查。 |
| **H8** | `app/api/chat.py:157-193,217-249`:6 个 Arena 辅助函数重复定义,前一版被覆盖。 | 删除死代码并保留行为单测。 |
| **H10** | `app/core/stream_monitor.py:1706-1732,1768-1779`:两项 Arena 判定方法重复,后定义覆盖前定义;当前有效的是边界较严版本。 | 保留有效版本,清理旧方法;**不**误报当前主机校验失效。 |
| **H11** | `config/browser_config.json:320-369`:受跟踪配置含具体 Arena 会话 URL/标签页编号;只证明标识存在,未验证链接权限。 | 用示例占位符和本地覆盖;按需评估历史清理。 |
| **H13** | `app/services/command_engine_storage.py:22-335` 的存储 mixin 未被实际 `CommandEngine` 继承/引用,多个方法与主类重复。 | 删除/合并或明确废弃,防止修补错误文件。 |
| **H14** | `static/js/dashboard-methods.js:1173-1207,1583-1599`:站点/完整备份导入无 `file.size` 判断;其他预设/流程导入设了 4MiB/1MiB。未进行大文件压力测试。 | 增加一致的大小上限和用户提示,必要时异步/流式解析。 |
## 六、已核实的保护与不要误报的事项
- `updater.py` 校验 SHA-256,并限制 ZIP 路径、符号链接、成员数量、展开体积和压缩比;覆盖前会备份,提取失败/异常有恢复处理。**不**报告“没有校验/没有备份回滚”。
- 公共资源抓取器已有逐跳重定向校验和跨域凭据剥离;S11 只针对 DNS 校验与实际连接地址之间的窗口。普通上传输入图片亦有格式/大小校验;S10 指不同的第三方页面图片比对路径。
- 工作流有限制节点数/深度/数据量/转换次数/运行时间的预算,内部正则有 25ms 限时;S12 是默认调试内容落盘,不是说没有任何空间上限。
- 请求链已有流式断连关闭、部分线程工作队列背压与执行超时;标签页获取已有取消轮询和迟到会话回收。H9 是**另一处 acquire 等待任务的总量边界**。
- Vue 组件的显式 `v-html` 核对后为自带图标 SVG;新教程和浏览器引导页在动态 `innerHTML` 插值前多数已有实体编码。S14 限定在仍可访问的遗留教程搜索框,不作“全站可远程 XSS”主张。
## 七、建议的修复顺序与验收条件
**第一批:阻断凭据与同源脚本风险。** S13/S1/H1:无授权备份必须返回 401/403;非可信 Origin 不得读管理数据;默认下载文件不包含服务端秘密和浏览器本地令牌;公开绑定缺认证应拒绝启动。S8/S9:恶意 SVG 与 `video/custom` + `.html` 的 mock 样例不得成为可同源内联访问的活动文档。S12:全新克隆默认不产生响应调试明文,配置字符串 `"false"` 解析为禁用。
**第二批:修复确定性功能错误。** B8:短暂无效命令 JSON 不清空上一版命令/预注入状态,恢复有效文件后可正常切换;B5:CDP 解冻失败不交付 BUSY 标签;B2:顶层数组历史能恢复;B1:搜索引擎主域禁自动发现、指定 AI 子域仍可用;B3:超限历史/媒体有可预测的拒绝/截断策略和隔离测试。
**第三批:边界和工程优化。** 统一远端媒体/图片抓取策略(S10/S11),限制 URL 正则与队列(H12/H9),为导入文件加大小预算(H14),移除重复/未使用代码(H8/H10/H13),并让无需浏览器的 CI 依赖/fixture 自足(T1/T2)。
如需我继续实施修复,应按上述批次逐项提交;**本报告仅提供审查建议,没有改动上述业务代码**。