blackbird/docs/security/BotOps_SECURITY_AUDIT_20260801.md

BotOps 模块安全审计报告

审计日期: 2026-08-01
审计范围: app.py、ws_client.py、commands.py、widgets/
代码版本: dev_qing 分支

---

代码验证记录

验证日期: 2026-08-03
验证方式: 逐条对照审计报告与当前代码（app.py、ws_client.py、commands.py）

验证结果汇总

等级	总数	已修复	未修复	修复率
P0	1	0	1	0%
P1	1	0	0	0%（不适用）
合计	2	0	1	0%

逐条验证

编号	状态	代码位置	验证说明
P0-1	❌ 未修复	ws_client.py L45, L141	websockets.connect(uri) 无 TLS 证书验证、无 token 认证；默认 localhost 风险低，但远程连接时无防护
P1-1	❌ 不适用	整个模块	审计报告声称 BotOps 可执行系统命令，实际代码是纯 TUI 客户端，仅作消息收发，不执行系统命令。此问题不成立

注意: P1-1 在审计报告中被描述为"命令执行权限"问题，经代码验证，BotOps 是 Textual TUI 前端客户端，本地命令仅限 /connect /disconnect /clear /status /help /quit，其余 / 命令透传给 aibox 服务器，模块本身不执行任何系统命令。

---

模块性质

BotOps 是 本地桌面 TUI 客户端（基于 Textual 框架），而非服务端模块。其安全面与服务器模块不同：

• 默认连接 ws://localhost:8765（本机 aibox）
• 所有操作在用户本地桌面环境运行
• 不监听任何端口，不对外提供服务

---

🔴 P0 — 严重问题

P0-1: WebSocket 客户端无认证机制 ❌

• 位置: ws_client.py L45, L141
• 问题: websockets.connect(uri) 直接连接，无 TLS 证书验证、无 token 认证
• 影响分析:
  • 默认 ws://localhost:8765：风险低，仅本机访问
  • 远程连接场景（如 ws://remote-server:8765）：无 MITM 防护，无身份认证
• 修复建议:
  1. 远程连接时启用 WSS（wss://），配置 SSL context
  2. 支持 token 认证（URL query 参数或 Authorization header），与 gateway 认证机制对齐

---

🟠 P1 — 高危问题

P1-1: 命令执行权限（不适用）

• 审计报告原描述: "BotOps 作为运维工具，可执行系统命令"
• 代码验证结论: 不成立。BotOps 是纯 TUI 客户端，本地命令仅限 UI 操作（连接/断开/清屏/状态/帮助/退出），不执行系统命令。所有 / 命令透传给 aibox 服务器处理。

---

✅ 已有安全机制

1. ✅ 桌面客户端架构: 本地运行，不监听端口，不对外提供服务
2. ✅ WebSocket 通信: 与后端通过 JSON 消息交互
3. ✅ 断线自动重连: 指数退避 2s→30s，手动断开抑制重连（ws_client.py L129-148）
4. ✅ CancelledError 正确处理: _listen 中 CancelledError 向上传播（ws_client.py L111-112）
5. ✅ 连接关闭异常安全: _close_ws 捕获所有异常（ws_client.py L68-72）
6. ✅ JSON 解析容错: 非法 JSON 作为 chunk 处理（ws_client.py L105-106）
7. ✅ 未知消息类型隔离: 不认识的 type 仅记入侧栏，不污染 AI 聊天区（app.py L255-257）

---

修复路线图

短期

• 远程连接场景添加 WSS 支持和 token 认证

中期

• 支持从 gateway 获取认证 token，统一接入