docs: add full security review

This commit is contained in:
Your Name committed 2026-06-23 11:15:57 +08:00
1 parent aeeabd8ba2
commit 77413fa7d1
1 file changed
+228
@@ -0,0 +1,228 @@
# 全量安全审查报告
日期:2026-06-23
审查方式:结合 `security-best-practices`、`security-threat-model`、`code-review-and-quality` 思路,对客户端、本地 Web GUI、卡密服务端、自动更新、打包分发和 Git/配置暴露面做静态审查与最小运行验证。
## 结论
当前版本已经具备一批关键安全地基:客户端默认走 `https://dy.absfan.cn`,自动更新 manifest 有签名和安装包 sha256 校验;卡密服务使用服务端时间和 SQLite 参数化查询;后台登录使用 HttpOnly 会话 cookie 与 CSRF;本地 Web GUI 默认只监听 `127.0.0.1`;当前 tracked 文件未发现服务器真实 IP、私钥或管理员 token 明文。
但仍有 5 个需要优先处理的风险:
- P0:Git 历史提交里仍可检索到服务器源站 IP 字面量,若仓库外发或公开,历史会继续泄露源站。
- P1:服务端限流信任客户端传入的 `x-forwarded-for`,可能被绕过并造成 rate-limit bucket 增长。
- P1:后台登录未接入限流/锁定;同时仍保留 Bearer/Basic token 后门入口,公网后台暴露时爆破面偏大。
- P1:后台发布更新时一次性 `await installer.read()` 读取上传文件,缺少上传大小限制,可能导致内存或磁盘 DoS。
- P1:本地 Web GUI 虽默认本机监听,但一旦配置成 `0.0.0.0`,WiFi ADB、启动/停止、日志读取等接口没有二次认证。
## 范围与资产
核心资产:
- 卡密数据库、激活记录、审计记录。
- 服务端私钥、管理员 token、更新安装包、更新 manifest。
- 客户端内置公钥、授权文件、本地配置。
- 本地 Web GUI 对 ADB、设备、日志和运行进程的控制能力。
主要入口:
- 公网:`/api/v1/activate`、`/api/v1/verify_license`、`/api/v1/update/manifest`、`/api/v1/update/download/{filename}`、`/admin/*`。
- 本机:`/api/wifi/*`、`/api/config`、日志/运行控制相关 Web GUI 接口。
- 分发:PyInstaller/安装包、自动更新下载的 EXE。
## 已有安全控制
- 客户端默认更新地址是 `https://dy.absfan.cn/api/v1/update/manifest`。
- 自动更新默认要求 manifest 签名,安装包 URL 默认同源,安装包下载后做 sha256 校验。
- 服务端 license 和 update manifest 使用 Ed25519 签名。
- SQLite 操作使用参数化 SQL,未看到直接字符串拼接 SQL 的主路径。
- 后台登录成功后写入 HttpOnly、SameSite=Lax 的 session cookie,后台写操作有 CSRF token。
- 卡密校验以服务器端激活记录和服务端时间为准,客户端本地时间不能直接绕过在线校验。
- 本地 Web GUI 默认监听 `127.0.0.1:8000`,不是默认公网暴露。
- 当前 tracked 文件扫描未发现真实源站 IP、服务器密码、管理员 token、私钥 PEM。
## 发现与建议
### P0-1 Git 历史仍包含源站 IP
证据:
- 当前 tracked 文件未命中真实源站 IP、管理员 token 或私钥。
- `git log --all -S` 仍能在历史提交中找到源站 IP 字面量,涉及提交包括 `25876bd`、`0efdc83`、`5c7d341`、`cb74a23` 等。
影响:
- 即使当前代码改成域名,仓库被发给别人或推到公开仓库时,历史仍会暴露源站。
- 攻击者可绕过域名层防护,直接打源站端口或做扫描。
建议:
- 若仓库已经外发或公开:立即做 Git 历史改写,清除源站 IP、旧 server 默认值和任何敏感片段,然后 force push。
- 同步轮换公网源站或至少限制源站只接受可信代理/防火墙来源。
- 报告、文档、提交信息里后续只写域名或 `[REDACTED_ORIGIN]`。
### P1-1 限流信任 `x-forwarded-for`
证据:
- `license_server/api.py:182-185` 使用请求头 `x-forwarded-for` 第一段作为限流 key。
- `_rate_limited` 对 activate、verify_license 生效,但 bucket key 由该 header 决定。
影响:
- 如果反代/CDN 未强制覆盖该 header,客户端可以伪造不同 IP 绕过限流。
- 大量伪造 header 会让 `rate_limit_buckets` 增长,形成内存型 DoS。
建议:
- 只在请求来自可信代理 IP 时读取 `x-forwarded-for`,否则使用 `request.client.host`。
- 增加 bucket 总量上限和周期性清理。
- 部署层确保反代覆盖而不是透传用户自带的 XFF。
### P1-2 后台登录缺少限流/锁定,且保留多种 token 入口
证据:
- `/admin/login` 在 `license_server/api.py:492-497` 直接比较 token,失败返回 403,未调用 `_rate_limited`。
- `_admin_allowed` 在 `license_server/api.py:88-109` 同时接受 session cookie、Bearer token、Basic auth。
影响:
- 公网后台可被持续爆破或撞库,尤其管理员 token 如果不够长会变成高风险。
- Bearer/Basic 让 token 更容易出现在代理日志、浏览器插件、命令历史或误贴日志中。
建议:
- 给 `/admin/login` 加 IP + 用户维度限流、指数退避和失败审计。
- 默认禁用 Basic auth;Bearer token 仅保留给受控 CLI,或通过环境变量显式开启。
- 管理员 token 要求至少 32 字节随机值,并增加启动时弱 token 检查。
### P1-3 更新发布上传无大小限制
证据:
- `license_server/api.py:586-606` 中 `UploadFile` 直接 `await installer.read()`,随后写入发布目录。
- 未见文件大小、后缀白名单、Content-Length 上限或流式落盘控制。
影响:
- 管理员误操作、token 泄露或 CSRF 以外的后台入口被利用时,可以上传超大文件导致内存、磁盘或进程不可用。
- 更新发布链路是高权限供应链入口,风险高于普通文件上传。
建议:
- 增加最大上传大小,例如 300 MB 或按实际安装包体积上限配置。
- 使用流式写临时文件,边读边计算 sha256,超限立即中断并删除临时文件。
- 限制后缀为 `.exe`,发布前校验 Windows Authenticode 签名或至少校验内部版本号。
### P1-4 本地 Web GUI 非 localhost 暴露时缺少认证
证据:
- 默认监听 `127.0.0.1`:`douyin/core/path_config.py:31`。
- 环境变量或配置可覆盖 host:`douyin/core/path_config.py:96-103`。
- Web GUI 暴露 WiFi ADB 启用、连接、断开、扫描和自动重连:`gui/web_gui_pkg/routes.py:717-824`、`863-940`。
影响:
- 默认本机使用问题不大。
- 如果用户为了局域网访问改成 `0.0.0.0`,同网段其他人可未授权控制 ADB 连接、扫描局域网、读取部分状态或影响挂机运行。
建议:
- 当 host 不是 localhost 时强制启用 Web GUI token。
- 对 `/api/wifi/*`、运行控制、配置写入、日志读取加认证。
- UI 上显示“当前监听地址”和“局域网暴露风险”。
### P2-1 HTTPS 开关默认逻辑不够稳
证据:
- 默认 manifest URL 是 HTTPS:`douyin/updater/force_update.py:31`。
- frozen 默认 manifest 下 `require_https` 默认值为 `not using_default_manifest`,即默认 false:`douyin/updater/force_update.py:192-195`。
- 同时默认签名是开启的。
影响:
- 当前域名是 HTTPS,实际链路可用。
- 但“默认 manifest 不强制 HTTPS”的逻辑容易在以后改默认地址时退化,签名不能完全替代传输层保护。
建议:
- `require_https` 默认始终为 true,除非显式开发环境关闭。
- 对自动更新增加环境分层:dev 可放宽,release 必须 HTTPS + signed manifest + sha256。
### P2-2 license 和 update manifest 共用签名密钥
证据:
- `license_server/core.py:444-446` 提供通用 `sign_payload`。
- license 文档签名在 `license_server/core.py:626-644`,update manifest 也由同一服务私钥签名。
影响:
- 单一私钥泄露会同时影响授权文件与更新供应链。
- 后续密钥轮换时两个系统耦合,恢复复杂。
建议:
- 分离 license signing key 与 update signing key。
- 客户端分别内置 license public key 和 update public key,支持 key id 与滚动轮换。
### P2-3 依赖版本没有锁定
证据:
- `requirements.txt` 多数依赖使用 `>=`,例如 `Pillow>=9.0.0`、`opencv-python>=4.5.0`、`cryptography>=41.0.0`。
影响:
- 构建复现性弱,新版本依赖可能引入兼容问题或供应链风险。
建议:
- 为 release 打包生成锁定文件,例如 `requirements-lock.txt` 或 `pip-tools` 输出。
- CI/打包只使用锁定依赖,开发环境可继续宽松。
### P2-4 shell 调用需要继续收敛
证据:
- 聚焦扫描显示存在若干 `subprocess.run`/`Popen`,多数 ADB 调用为列表参数。
- 仍存在少量 `shell=True` 或 `/bin/sh -c` 用法,主要用于平台命令探测或 ADB 降级路径。
影响:
- 如果参数未来从 UI 或配置直通,可能扩大命令注入风险。
建议:
- 对所有 `shell=True` 建立 allowlist,逐个替换成 list 参数。
- 对确实需要 shell 的命令增加注释和单元测试覆盖。
## 验证
已执行:
- `python -m pytest tests/test_license_server_api.py tests/test_license_server_core.py tests/test_license_manager.py tests/test_auto_update.py tests/test_web_gui_routes_logic.py -q`
- 结果:PASS。
- 日志:`artifacts/security_audit_tests.log`。
公网最小验证:
- `https://dy.absfan.cn/api/v1/health` 返回 `{"ok": true, "service": "douyin-license-server"}`。
- `https://dy.absfan.cn/api/v1/update/manifest` 返回 `enabled=false`、`version=0.0.0`,并包含签名字段。
当前 secret 扫描:
- tracked 文件未发现真实源站 IP、私钥 PEM、管理员 token、服务器密码明文。
- Git 历史仍包含源站 IP,需要单独处理。
## 建议修复顺序
1. 先修服务端 P1:可信代理 IP/XFF、后台登录限流、上传大小限制、Secure cookie。
2. 再修本地 P1:Web GUI 非 localhost 强制 token,敏感接口鉴权。
3. 然后做 P0 历史清理:确认仓库是否已外发/公开,必要时 history rewrite + force push + 源站访问限制。
4. 最后做供应链增强:分离签名密钥、release 依赖锁定、自动更新 HTTPS 强制。