blackbird/docs/security/gateway_SECURITY_AUDIT.md

gateway 模块安全审计（合并文档）

本文档合并了 gateway 自 v0.8.0 以来的三轮安全审计记录：

• 2026-08-01 初版审计（gateway v0.8.0，2500+ 行，认证内嵌）
• 2026-08-07 复审（P0 全部修复、进程退出 bug 修复）
• 2026-08-09 增量复审（8 项新发现：优雅关闭崩溃、头名大小写、XFF 伪造绕过修复、黑盒测试重写落地）

架构变更（v0.9.0）：gateway 已退化为纯转发服务（仅 loopback 监听，不验签），认证职责（Token 签发/验签、登录/注册/重置、限流、WS 代理鉴权、PBKDF2/RSA）整体迁移至 ca 模块。

所有 ✅ 已修复项已作为代码注释合入 gateway/src/main.cpp（以“审计 A*”“P1-1”等标记内联于对应代码）。本文档仅保留开放项、历史追溯与上线检查清单，避免陈旧信息。

---

1. 审计轮次概览

轮次	日期	基线 / 范围	关键结论
初版	2026-08-01	v0.8.0 src/main.cpp、src/shared/（libth/libhttp/libcrypt/libsqlite3）	建立 P0/P1/P2 分级；P0-1 RSA 持久化定为设计接受；发现认证内嵌带来的 Token 吊销缺失等
复审	2026-08-07	v0.9.0 前 src/main.cpp、inc/、配置	P0 三项全部修复；进程退出 bug 修复；Token 吊销（P1-1）实现并随认证独立化迁 ca
增量复审	2026-08-09	v0.9.0 纯转发 src/main.cpp	8 项新发现（A1/A2/A5/A8 等代理层修复、黑盒测试重写落地）；认证类问题转入 ca 审计

---

2. 已完成修复（已合入代码，供追溯）

代码位置：gateway/src/main.cpp（注释以“审计 A*”/“P1-1”等标记）。

• A1 优雅关闭 double-join 崩溃（删除 else 分支重复 join）
• A2 白名单外 Target-Url 返回 403（改抛 HttpException 2303，不再 500）
• A5 is_special_header 头名大小写归一（统一转小写比较）
• A8 错误消息 [Http][Error NNNN] 前缀剥离（仅 e.message() 外泄，前缀留服务端日志）
• P1-1 路径遍历防护（is_safe_target）+ XFF 剥离与可信注入（is_special_header / handleProxy）
• libhttp P1-2 反向代理响应体 10MB 上限
• 信号安全重构（async-signal-safe 标志 + SIGPIPE 忽略 + 关闭 8s / 日志 3s 超时保护）
• 启动 loopback 强制自检 + X-Auth-User 存在性不变量（v0.9.0 新增）

认证侧脱敏（P0-2 / P0-3 错误信息脱敏）已在 wrapperHttp / ExpBase.hpp 闭环。

---

3. 已随认证迁移至 ca（v0.9.0，不再属 gateway 待办）

以下历史问题在 v0.9.0 认证独立化后于 ca 模块闭环，gateway 侧无需再处理；ca 的独立审计见 ca_SECURITY_AUDIT.md（其 §2 为 ca 相关开放项）。

• P0-1 RSA 密钥持久化（设计接受：重启即密钥轮换）
• P0-2 / P0-3 错误信息脱敏
• P1-1 Token 吊销机制（jti 黑名单 + 用户版本号双轨，已实现于 ca）
• P1-2 账户级登录失败锁定（ca 侧）
• P2-5 JTI 黑名单内存有界（ca 侧）
• P2-6 用户名 / 邮箱长度限制（ca 侧）
• A3 缺字段返回 400（ca 侧 handler）
• A6 / A7 验证码双渠道统一 / 废弃内置验证码（ca + captcha2 侧）

---

4. 当前开放项（gateway v0.9.0 纯转发）

编号	等级	问题	状态	说明 / 修复建议
P1-3	🟠	上游代理 HttpClient 未显式设置超时	⚠️ 部分修复	下游服务（captcha/smtp）超时已配；代理转发 HttpClient 未设连接/读取超时。建议连接 5s、读取 30s（handleProxy 出站调用处）
P1-5	🟠	请求体大小无显式限制	❌ 未修复	req.body() 直接读取，gateway 层未检查 Content-Length；依赖 libhttp 默认 10MB。建议超 10MB 返回 413
P1-7	🟠	CSRF Token 缺失	❌ 未修复（低优先级）	gateway 纯转发、无认证表单；前端 + ca 会话模型覆盖。如启用独立 HTTPS 模式（tls = on）需评估
P1-8	🟠	日志注入	⚠️ 部分修复	用户输入经 ca 透传后直接拼接日志；内部 pymsg→db，外部不可见，风险低。建议对 username/email 等字段做换行符转义
P2-2	🟡	TLS 版本 / 套件未限定	❌ 未修复（低风险）	tls = off，TLS 由 WAF 终止；如启用 tls = on 需增加 TLS 版本与 CipherSuites 配置项
P2-3	🟡	CORS 反射任意 Origin	❌ 未修复	_CORS_ORIGINS 白名单已加载但未用于响应头；OPTIONS 预检由 libhttp 直接反射 Origin。需 libhttp 层接入白名单或由 gateway 注册显式 OPTIONS 路由
P2-4	🟡	HTTP 服务器无 Read/Write/Idle 超时	⚠️ 部分修复	HttpServer(addr,port,4) 的 4 为连接超时，无请求级超时；存在 Slowloris / 连接耗尽风险
A4	🟡	模式 B 独立部署限流可被 XFF 伪造绕过	📝 已文档化	README 模式 B 已加安全降级提示（伪造 XFF 可绕过限流，生产必须用模式 A / WAF 前置）。根因需 libhttp 向 handler 透传 TCP 对端地址（跨模块 API 变更，见 ../reports/libhttp_remote_addr_dev_doc.md）

不在 gateway 范围（libhttp 层，gateway 侧跳过）：P1-4 C++ HTTP 解析器 fuzz（属 libhttp）；P1-6 反向代理响应大小已由 libhttp 默认 10MB 保证（视为已闭环）。

---

5. 配置安全审计（历史结论，仍适用）

检查项	状态	说明
监听地址	✅ 安全	address = 127.0.0.1
TLS 模式	✅ 符合部署	tls = off，WAF 终止
管理员白名单	✅ 安全	users 显式配置，无默认管理员
CORS 白名单	⚠️ 配置未生效	allowed_origins 已配但未用于响应头（见 P2-3）
Token 有效期	✅ 合理	keep_time = 3600，max_refresh = 10
WS 代理路由	✅ 安全	仅 /ws/aibox，需管理员权限
敏感凭据	✅ 无泄露	配置文件无硬编码密码 / 密钥

---

6. 黑盒测试待办（需测试钩子）

• 完整旅程（captcha → send_code → register → login → whoami → logout）、Cookie 链路（Set-Cookie 属性、代理注入 Authorization）、jti / 版本号吊销、refresh_token、白名单 403（A2 已转绿）、防枚举时序
• test_captcha.py / test_smtp.py 重写为 pymsg 直连（captcha2:8009、smtp:8008）
• 钩子方案（二选一）：captcha2 / smtp 提供测试模式（固定验证码答案）；或 gateway.ini 增加 [Security] captcha_required / email_code_required 开关

---

7. 上线前检查清单

• 确认 WAF 规则已启用
• 确认所有服务绑定 127.0.0.1
• 确认云安全组 / ufw 仅放行 TCP 443
• 确认无默认管理员账户
• 确认 .env 权限 0600，SMTP 密码未硬编码
• 确认 gateway 配置 tls = off、address = 127.0.0.1
• 回归测试：登录 / 注册 / 代理 / Token 刷新 / 吊销全链路正常

---

维护说明：新增 / 复测开放项请直接编辑本文件；修复后请将对应行移至“已完成”（§2）或合入 gateway/src/main.cpp 代码注释后删除本行。

审计人: AI Security Auditor 合并于: 2026-08-10（三轮审计合并；源文件 gateway_SECURITY_AUDIT_20260801.md / _20260807.md / _20260809.md 已归档删除）