blackbird/docs/security/pymsg_SECURITY_AUDIT_20260801.md

# pymsg 模块安全审计报告

**审计日期**: 2026-08-01  
**审计范围**: `pymsg/__init__.py`、`pymsg/rpc.py`、`pymsg/async_queue.py`  
**代码版本**: dev_qing 分支

---

## ⚠️ 合并追溯说明（2026-08-10）

原始审计报告共 16 条发现（P0×3 / P1×5 / P2×4 / P3×4）。其中 **6 条已修复项**
（P0-1、P0-2、P1-1、P1-2、P1-3、P1-5）的修复代码已落地并经 2026-08-03 验证，
现已作为 `[SECURITY AUDIT ... ✅ 已修复]` 注释合并进源文件对应位置：

| 编号 | 已合并位置 |
|------|------------|
| P0-1 | `pymsg/__init__.py` — `recv()`、`_recv_exact()` |
| P0-2 | `pymsg/__init__.py` — `recv()`、`_handle_client()` |
| P1-1 | `pymsg/__init__.py` — `MsgServer.__init__`、`_accept_client()` |
| P1-2 | `pymsg/__init__.py` — `_BoundedThreadPoolExecutor` 类、`MsgServer.__init__`、`_handle_client()` |
| P1-3 | `pymsg/rpc.py` — `_sanitize_error()` |
| P1-5 | `pymsg/rpc.py` — 模块顶部 `_MAX_NUM_DIGITS` 注释、`_dispatch()` |

**本报告以下章节仅保留尚未修复（未合并）的 10 条发现作为待办跟踪**，已修复条目
已从「逐条验证」「修复进度」及详细问题章节中删除，其完整描述见源代码注释。

---

## 剩余未修复条目（待跟踪）

### 汇总

| 等级 | 剩余总数 | 说明 |
|------|----------|------|
| P0 | 1 | 无认证/鉴权机制 |
| P1 | 1 | 明文 TCP，无 TLS |
| P2 | 4 | 健壮性/配置问题 |
| P3 | 4 | 优化建议 |
| **合计** | **10** | |

### 逐条验证（仅未合并项）

| 编号 | 状态 | 代码位置 | 说明 |
|------|------|----------|------|
| P0-3 | ❌ 未修复 | `rpc.py` L80-171 | 无认证机制，仅依赖 127.0.0.1 网络层隔离 |
| P1-4 | ❌ 未修复 | 全模块 | 明文 TCP，无 TLS 支持 |
| P2-1 | ❌ 未修复 | `__init__.py` L106-111 | length=0 空消息无特殊处理 |
| P2-2 | ❌ 未修复 | `__init__.py` L395-418 | `broadcast()` 无频率/权限控制 |
| P2-3 | ❌ 未修复 | `__init__.py` L377-378 | `except (ValueError, OSError): break` 仍捕获所有 OSError（含 EINTR） |
| P2-4 | ❌ 未修复 | `__init__.py` L196-203 | `MsgClient.send()` 短连接模式，高频调用导致 TIME_WAIT 堆积 |
| P3-1 | ❌ 未修复 | - | 安全事件（超大消息、超时、JSON 解析失败）无日志 |
| P3-2 | ❌ 未修复 | `__init__.py` L182 | `name` 参数未过滤控制字符 |
| P3-3 | ❌ 未修复 | `__init__.py` L359 | `listen(10)` backlog 在高并发下偏小 |
| P3-4 | ❌ 未修复 | `__init__.py` L520-527 | `_shutdown` 直接 `close()` 所有 socket，可能发送 RST |

---

## 问题严重等级

| 等级 | 说明 | 响应时间 |
|------|------|----------|
| P0 🔴 | 可导致服务崩溃、DoS 或远程接管 | 立即修复 |
| P1 🟠 | 可导致资源耗尽、信息泄露 | 72小时内 |
| P2 🟡 | 健壮性/配置问题 | 一周内 |
| P3 🟢 | 优化建议 | 版本迭代 |

---

## 修复进度（剩余）

| 优先级 | 剩余待修复 |
|--------|------------|
| P0 | 1（无认证） |
| P1 | 1（无 TLS） |
| P2 | 4 |
| P3 | 4 |

---

## 🔴 P0 — 严重问题

### P0-3: 无认证/鉴权机制
- **位置**: `rpc.py:80-171` 整个 RpcServer
- **问题**: RPC 服务完全没有身份验证，任何能连接到端口的客户端都能调用所有路由
- **当前缓解**: 所有服务均绑定 127.0.0.1，依赖网络层隔离
- **修复建议**:
  1. 添加基于预共享 token 的认证（如 `_auth` 字段）
  2. 支持路由级权限控制
  3. 文档明确警告不要暴露到公网

---

## 🟠 P1 — 高危问题

| # | 问题 | 位置 | 状态 |
|---|------|------|------|
| P1-4 | 无 TLS/加密传输，内网流量可被窃听 | 全模块明文 TCP | ❌ 未修复 |

---

## 🟡 P2 — 中危问题

| # | 问题 |
|---|------|
| P2-1 | length=0 空消息未特殊处理，可用于心跳攻击 |
| P2-2 | broadcast() 无频率/权限控制，可被用于放大攻击 |
| P2-3 | select 异常处理过于宽泛，EINTR 临时错误直接退出循环 |
| P2-4 | MsgClient 短连接模式导致 TIME_WAIT 堆积 |

---

## 🟢 P3 — 低危/建议

| # | 建议 |
|---|------|
| P3-1 | 安全事件（超大消息、超时、JSON解析失败）无日志 |
| P3-2 | `name` 参数未过滤控制字符，可导致日志注入 |
| P3-3 | listen backlog=10 在高并发下偏小 |
| P3-4 | 无优雅关闭（直接 close() 可能发送 RST） |

---

## ✅ 已有安全机制

1. ✅ 64 MiB 消息大小上限（`_MAX_MSG_SIZE`），防止 OOM
2. ✅ send/recv 双端都检查消息大小
3. ✅ 线程池模式下同一连接串行处理，避免帧交错
4. ✅ 使用 `sendmsg` 散射-聚集 I/O 减少内存拷贝
5. ✅ 使用 `recv_into` 预分配 buffer
6. ✅ 线程安全的发送锁
7. ✅ 回调异常隔离（线程池模式）
8. ✅ 单元测试覆盖消息大小边界

> 注：P0-1（recv 总超时）、P0-2（UnicodeDecodeError 防护）、P1-1（连接数限制）、
> P1-2（有界队列）、P1-3（异常脱敏）、P1-5（JSON 解析限制）等已修复机制均已合并进
> 源代码注释，见开头「合并追溯说明」。

---

## 修复路线图（剩余）

### 中期
- [ ] 统一认证机制（P0-3）
- [ ] TLS 支持选项（P1-4）
- [ ] 安全事件日志（P3-1）