# 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，统一接入