# db 模块安全审计报告

**审计日期**: 2026-08-01  
**审计范围**: `dbv2.py`、`db_tools.py`、`log_client` 相关  
**代码版本**: dev_qing 分支

---

## 修复进度

| 优先级 | 总数 | 已修复 | 部分修复 | 未修复 |
|--------|------|--------|----------|--------|
| P0 | 1 | 0 | 1 | 0 |
| P1 | 3 | 0 | 1 | 2 |
| P2 | 2 | 1 | 0 | 1 |
| **合计** | **6** | **1** | **2** | **3** |

---

## 🔴 P0 — 严重问题

### P0-1: 零认证对外开放完整 CRUD（依赖 127.0.0.1 网络隔离）
- **位置**: `dbv2.py` L180、L191-196、L323-406
- **当前状态**: ⚠️ 部分修复
  - ✅ 默认监听 `127.0.0.1`（`dbv2.py` L180），Docker 也绑定到 127.0.0.1
  - ✅ 配置通过 confs + 环境变量两层加载，配置完整性校验（`dbv2.py` L118-129）
  - ❌ 仍无任何认证机制（`RpcServer` 无 auth 回调）
  - ❌ SELECT 无默认 LIMIT：`_do_select` (L364-366) limit 参数可选，客户端可省略以获取全表数据
  - ❌ UPDATE/DELETE 不强制要求 WHERE：`_do_update` (L391-394) 和 `_do_delete` (L400-403) 仅在 where_cond 非空时添加 WHERE 子句，可执行无条件全表更新/删除
  - ❌ 无表级/操作级权限控制
- **修复建议**:
  1. ~~确保管理接口仅监听 127.0.0.1~~ ✅ 已实现
  2. 添加 API Token 认证（预共享密钥，所有调用需携带 `_auth` 字段）
  3. SELECT 强制添加 LIMIT 上限（默认 1000 条），防止拖库
  4. 添加操作权限：日志写入只允许 insert，禁止 delete/truncate
  5. 拒绝无条件 UPDATE/DELETE（必须带 where 条件）
  6. DDL 操作仅限本地运维工具，RPC 接口完全禁用

---

## 🟠 P1 — 高危问题

| # | 问题 | 状态 | 说明 |
|---|------|------|------|
| P1-1 | db_tools.py 运维工具存在 SQL 字符串拼接风险 | ⚠️ 部分修复 | `db_tools.py` 使用参数化查询（`executemany` + 占位符），表名来自 `sqlite_master` 查询非用户输入；但 `_view_db.sqlite3.py` L53 `cur.execute(args.sql)` 支持自由 SQL（本地工具，可接受风险） |
| P1-2 | 无操作审计日志 | ❌ 未修复 | `_handle_execute` (L323-344) 处理 CRUD 操作时无任何审计记录，无法追溯谁在何时修改了什么数据 |
| P1-3 | Logs 表自动清理可被利用销毁证据 | ❌ 未修复 | `_do_cleanup` (L493-528) 按时间和条数清理，攻击者可通过大量写日志触发 `max_records` 裁剪，删除攻击痕迹 |

---

## 🟡 P2 — 中危问题

| # | 问题 | 状态 | 说明 |
|---|------|------|------|
| P2-1 | 日志表自动清理保留策略可配置化 | ✅ 已修复 | `dbv2.py` L65-69 通过 `[logs]` 配置段支持 `retention_days`、`max_records`、`cleanup_interval`，通过 confs/db.ini + 环境变量配置 |
| P2-2 | 错误信息可能泄露表结构/字段名给调用方 | ❌ 未修复 | `_coerce_value` (L262-265) 返回 `"列 {column.name} 的日期时间值无法解析..."` 暴露列名；`_handle_execute` (L332) 返回 `"表加载失败: {e}"` 暴露表名 |

---

## ✅ 已有安全机制

1. ✅ **SQLAlchemy Core 参数化查询**：核心 CRUD 路径使用表反射 + 参数化，零 SQL 注入风险 (`dbv2.py` L346-406)
2. ✅ **仅监听 127.0.0.1**：不对外暴露 (`dbv2.py` L180)
3. ✅ **集中式日志 fail-safe**：db 不可用时静默丢弃，不阻塞业务 (`example_log_client.py` L57-106)
4. ✅ **自动提交/回滚**：异常时自动回滚事务
5. ✅ **日期/时间适配**：ISO 8601 处理，`"$now"` 哨兵 (`dbv2.py` L242-287)
6. ✅ **日志自动清理**：后台线程按时间+条数清理，防止磁盘占满 (`dbv2.py` L480-528)
7. ✅ **log_client 健壮性**：异步队列、后台线程、fail-safe、队列上限 10000 (`example_log_client.py` L38-41)
8. ✅ **配置白名单校验**：`_merge_ini` 仅覆盖已知 section/key，防止意外字段注入 (`dbv2.py` L73-81)
9. ✅ **配置完整性校验**：启动时检查所有必需配置项，缺失则退出 (`dbv2.py` L118-129)
10. ✅ **SQLite PRAGMA 优化**：WAL 模式 + NORMAL 同步 + busy_timeout + mmap (`dbv2.py` L139-155)
11. ✅ **表反射线程安全**：double-check 锁机制防止并发反射竞态 (`dbv2.py` L225-239)

---

## 修复路线图

### 立即（24小时）
- [ ] SELECT 添加强制默认 LIMIT 上限（防止拖库）
- [ ] UPDATE/DELETE 强制执行 WHERE 条件检查

### 短期（72小时）
- [ ] 添加 API Token 认证
- [ ] 无条件 UPDATE/DELETE 拒绝执行
- [ ] 错误信息脱敏

### 中期
- [ ] 表级权限控制（日志表只写不删/改）
- [ ] 管理操作审计日志
- [ ] 日志清理防篡改（保留清理前的摘要/签名）

---

## 代码验证记录

**验证日期**: 2026-08-03  
**验证方式**: 逐条对照审计报告与当前代码（`dbv2.py`、`db_tools.py`、`example_log_client.py`、`_view_db.sqlite3.py`）

### 验证结果汇总

| 等级 | 总数 | 已修复 | 部分修复 | 未修复 | 修复率 |
|------|------|--------|----------|--------|--------|
| P0 | 1 | 0 | 1 | 0 | 50% (部分) |
| P1 | 3 | 0 | 1 | 2 | 17% (部分) |
| P2 | 2 | 1 | 0 | 1 | 50% |
| **合计** | **6** | **1** | **2** | **3** | **33%** |

### 逐条验证

| 编号 | 状态 | 代码位置 | 验证说明 |
|------|------|----------|----------|
| P0-1 | ⚠️ 部分 | `dbv2.py` L180, L323-406 | 已绑定 127.0.0.1；但无认证、SELECT 无默认 LIMIT、UPDATE/DELETE 不强制 WHERE |
| P1-1 | ⚠️ 部分 | `db_tools.py` L166-169, `_view_db.sqlite3.py` L53 | `db_tools.py` 使用参数化查询；`_view_db.sqlite3.py` 支持自由 SQL（本地工具） |
| P1-2 | ❌ 未修复 | `dbv2.py` L323-344 | `_handle_execute` 无任何审计日志记录 |
| P1-3 | ❌ 未修复 | `dbv2.py` L493-528 | `_do_cleanup` 按时间/条数清理，可被攻击者利用 |
| P2-1 | ✅ 已修复 | `dbv2.py` L65-69 | `retention_days`/`max_records`/`cleanup_interval` 通过 confs 可配置 |
| P2-2 | ❌ 未修复 | `dbv2.py` L262-265, L332 | 错误信息暴露列名和表名 |

### 新增安全措施（审计报告未覆盖）

| 措施 | 代码位置 | 说明 |
|------|----------|------|
| 配置白名单校验 | `dbv2.py` L73-81 | `_merge_ini` 仅覆盖已知 section/key，防止意外字段注入 |
| 配置完整性校验 | `dbv2.py` L118-129 | 启动时检查所有必需配置项，缺失则退出 |
| SQLite PRAGMA 优化 | `dbv2.py` L139-155 | WAL + NORMAL 同步 + busy_timeout + mmap |
| 表反射线程安全 | `dbv2.py` L225-239 | double-check 锁机制防止并发反射竞态 |
| 日志队列上限 | `example_log_client.py` L41 | `_QUEUE_MAXSIZE = 10000`，满则丢弃最旧条目 |
| 后台线程异常安全网 | `example_log_client.py` L188-192 | 最外层 catch 防止异常杀死日志线程 |