16 KiB
16 KiB
Fail2ban 安全检测与人工封禁第一版测试用例
版本：V1.0（设计评审用例）
日期：2026-08-14
关联设计：docs/fail2ban-assisted-blocking-design-20260814.md
原则：真实后端、真实 PostgreSQL、真实日志与真实执行器；禁止 mock、静态数据和 localStorage 作为验收证据
1. 测试边界
- 自动化测试使用隔离的 Fail2ban/Nginx/nftables namespace 或测试节点，不得封禁测试执行机、预生产运维 IP、Cloudflare 节点或真实客户 IP。
- 预生产验收优先使用文档保留测试 IP 和短时封禁；所有人工封禁必须先确认回滚路径。
- 不发送、补发或重投短信，不修改通道账号、密码、启停状态、企业余额或客户连接。
- HTTP 密钥、签名、CMPP AuthenticatorSource、账号和日志证据必须脱敏。
2. 规则配置
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-RULE-001 | P0 | 查询规则列表 | 返回九类第一版规则；数据来自 PostgreSQL；展示当前配置版本和生效版本 |
| TC-F2B-RULE-002 | P0 | 修改规则阈值、窗口、冷却时间和风险等级并保存 | 写入真实数据库，生成新版本，代理校验并应用成功；回读值一致；写操作日志 |
| TC-F2B-RULE-003 | P0 | 提交小于最小值、大于最大值、零、负数、小数、非数字或非法枚举 | 后端逐项拒绝，不生成规则版本，不依赖前端校验兜底 |
| TC-F2B-RULE-004 | P0 | 两名管理员基于同一旧版本并发保存不同阈值 | 仅一方成功；另一方返回版本冲突，不覆盖新配置 |
| TC-F2B-RULE-005 | P0 | 让新配置语法校验或 reload 失败 | 数据库标记 apply_failed；上一生效版本继续工作；页面不得提示已生效 |
| TC-F2B-RULE-006 | P1 | 停用一条规则后持续产生匹配日志 | 停用后不创建新告警；已有告警和历史事件保留 |
| TC-F2B-RULE-007 | P1 | 重新启用规则 | 新事件按当前版本统计，不错误合并停用期间日志 |
| TC-F2B-RULE-008 | P0 | 尝试通过接口提交 regex、日志路径、shell、action、jail 名或执行器 | DTO 不接受或后端拒绝；配置文件和系统命令不受影响 |
| TC-F2B-RULE-009 | P0 | 无 security.rule.manage 权限修改规则 |
返回 403，不写数据库、不调用安全代理 |
| TC-F2B-RULE-010 | P0 | 超过近期认证时间后修改规则 | 要求重新认证；重新认证成功后才能保存 |
3. 登录与 SSH 检测
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-AUTH-001 | P0 | 同一测试 IP 在窗口内触发达到阈值的运营端密码错误 | 只生成一条聚合告警，计数准确，状态 pending，未自动封禁 |
| TC-F2B-AUTH-002 | P0 | 同一测试 IP 在客户端登录达到阈值 | 产生客户端规则告警，不与运营端规则错误合并 |
| TC-F2B-AUTH-003 | P1 | 失败次数低于阈值或分散在窗口外 | 保存检测事件但不产生达到阈值告警 |
| TC-F2B-AUTH-004 | P0 | 同一浏览器已有有效运营会话时，在客户端提交错误登录 | 产生正确检测事件；运营会话不被清除、广播退出或跳转 |
| TC-F2B-AUTH-005 | P0 | 检查事件、告警详情和日志 | 不含明文密码、密码散列、完整账号或验证码答案 |
| TC-F2B-SSH-001 | P0 | 从保留测试 IP 对 12022 触发达到阈值的 SSH 失败 | Fail2ban 检测 jail 产生事件和告警，但 nftables 未自动加入封禁 |
| TC-F2B-SSH-002 | P1 | SSH 登录成功、连接中断或握手超时 | 不错误计入认证失败规则 |
| TC-F2B-SSH-003 | P0 | 重启 Fail2ban/collector 后重放同一事件 | eventKey 幂等，不重复增加计数或创建告警 |
4. CMPP 检测
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-CMPP-001 | P0 | 同一测试 IP 使用未知账号达到阈值 | 生成 cmpp_auth_failure 告警；保存脱敏账号指纹和真实 TCP IP |
| TC-F2B-CMPP-002 | P0 | 使用错误 AuthenticatorSource 达到阈值 | 认证继续按原协议拒绝；告警分类准确；不保存完整 AuthenticatorSource |
| TC-F2B-CMPP-003 | P0 | 从不允许 IP、停用企业或停用应用发起连接 | 原认证结果不变；事件分类可区分真实拒绝原因 |
| TC-F2B-CMPP-004 | P0 | 高频发送非法包、异常版本或短连接扫描 | 达到协议滥用规则阈值后形成告警，不污染普通认证失败统计 |
| TC-F2B-CMPP-005 | P1 | 正常断线、心跳超时、最大连接数限制或服务重启恢复 | 不作为恶意认证或协议滥用告警 |
| TC-F2B-CMPP-006 | P0 | 检查事件和页面证据 | 不包含平台密码、完整认证材料、短信正文或通道凭据 |
5. HTTP API 检测
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-HTTP-001 | P0 | 同一 IP 使用不存在的 HTTP API 密钥达到阈值 | 生成 http_invalid_api_key 告警；仅保存不可逆密钥指纹 |
| TC-F2B-HTTP-002 | P0 | 使用存在但错误的签名达到阈值 | 生成 http_signature_failure，不与错误密钥混淆，不保存签名密钥或完整签名 Header |
| TC-F2B-HTTP-003 | P0 | 分别触发签名缺失、格式错误、算法不支持、验签失败和时间偏差 | 内部原因分类准确；页面使用安全文案；敏感细节不泄露给调用方 |
| TC-F2B-HTTP-004 | P0 | 重复使用已消费 nonce/签名请求达到阈值 | 生成 http_replay_attempt 严重告警；原接口仍按既有幂等/重放规则拒绝 |
| TC-F2B-HTTP-005 | P0 | 合法客户端按接口幂等协议重试同一业务请求 | 不误判为恶意重放；响应和业务幂等结果保持原语义 |
| TC-F2B-HTTP-006 | P0 | 请求常见敏感路径和漏洞路径，达到次数及不同路径双阈值 | 生成 http_malicious_scan；路径已标准化且 query 敏感值不保存 |
| TC-F2B-HTTP-007 | P0 | 对同一不存在业务路径重复请求，仅满足次数、不满足不同路径数 | 不触发恶意扫描告警 |
| TC-F2B-HTTP-008 | P1 | 产生普通业务 400、字段校验失败、合法 401/403 和单次 404 | 不错误计入恶意扫描或错误密钥规则 |
| TC-F2B-HTTP-009 | P0 | 从两个 IP 分别达到一半阈值 | 不跨 IP 错误聚合；每个 IP 独立计算 |
| TC-F2B-HTTP-010 | P0 | 修改 HTTP 规则阈值后继续产生事件 | 新事件使用新生效版本，告警规则快照可追溯当时阈值 |
6. Cloudflare 与真实 IP
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-IP-001 | P0 | 经真实 Cloudflare 回源请求运营端和客户端 | 事件 IP 等于访客真实 IP，TCP 代理 IP 保留在安全元数据中但不作为攻击者 IP |
| TC-F2B-IP-002 | P0 | 直连源站并伪造 CF-Connecting-IP |
Header 被忽略，事件使用真实 TCP 来源 IP |
| TC-F2B-IP-003 | P0 | 人工封禁 Cloudflare 入口告警 | 使用 Nginx real-IP deny，不调用访客 IP nftables action |
| TC-F2B-IP-004 | P0 | 人工封禁灰云 API、SSH 或 CMPP 告警 | 使用 nftables/manual jail，不修改 Nginx Cloudflare deny 列表 |
| TC-F2B-IP-005 | P0 | 尝试封禁 Cloudflare 官方节点、源站自身、回环、内网、运维和健康检查 IP | 后端和安全代理双重拒绝，记录保护名单命中，不产生真实封禁 |
| TC-F2B-IP-006 | P1 | Cloudflare 官方网段更新 | 使用受控来源更新并审计；旧配置切换原子化；失败保留旧可信网段 |
7. 告警聚合与状态机
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-ALERT-001 | P0 | 同规则、IP、窗口内并发写入多条事件 | 唯一 fingerprint 生效，只创建一条告警，计数无丢失 |
| TC-F2B-ALERT-002 | P0 | 冷却时间内再次达到阈值 | 更新原告警计数和最近时间，不产生告警风暴 |
| TC-F2B-ALERT-003 | P1 | 冷却结束后再次达到阈值 | 按设计创建新告警或新周期，历史告警不覆盖 |
| TC-F2B-ALERT-004 | P0 | 对 pending 告警执行忽略 |
状态原子变为 ignored，保留事件和原因，封禁按钮不可再执行 |
| TC-F2B-ALERT-005 | P0 | 两名管理员同时对同一告警点击封禁和忽略 | 仅一个状态迁移成功，另一请求返回 409 |
| TC-F2B-ALERT-006 | P1 | 告警超过可处置期限 | 状态变为 expired；历史仍可查询；不能用旧告警封禁 |
8. 人工封禁与解封
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-BLOCK-001 | P0 | 有权限管理员对待处理告警选择1小时、填写原因并确认 | 创建唯一操作记录，代理执行正确执行器，回读成功后状态才为 blocked |
| TC-F2B-BLOCK-002 | P0 | 前端篡改 IP、jail、action、执行器或时长 | 后端忽略未定义字段或拒绝请求；实际值只来自告警和固定映射 |
| TC-F2B-BLOCK-003 | P0 | 重复点击、网络超时重试或同一 operationKey 重放 |
代理和数据库幂等，仅存在一条真实封禁，不延长原期限 |
| TC-F2B-BLOCK-004 | P0 | 代理返回成功但执行器回读不存在规则 | 不标记 blocked；状态为失败/异常并生成系统告警 |
| TC-F2B-BLOCK-005 | P0 | Security Agent 停止或 Socket 不可用 | 明确返回封禁失败；告警不伪装已封禁；记录错误和审计 |
| TC-F2B-BLOCK-006 | P0 | PostgreSQL 不可用时点击封禁 | 拒绝无法审计的操作，不调用代理 |
| TC-F2B-BLOCK-007 | P0 | 无 security.block.manage 权限或近期认证过期 |
返回403或要求重新认证，不产生操作记录和系统封禁 |
| TC-F2B-BLOCK-008 | P0 | 对已封禁 IP执行解封并填写原因 | 调用原执行器解除，回读确认后变为 unblocked，完整记录操作人和原因 |
| TC-F2B-BLOCK-009 | P0 | 封禁自然到期 | 执行器真实解除；对账任务回读后更新 expired，不只依赖数据库时间 |
| TC-F2B-BLOCK-010 | P0 | 到期后执行器仍存在规则或平台记录与执行器不一致 | 标记同步异常并告警，不静默显示已解封 |
| TC-F2B-BLOCK-011 | P1 | 规则配置 manualBlockAllowed=false |
告警可查看，封禁按钮禁用，直接调用接口同样拒绝 |
9. 保护名单
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-PROTECT-001 | P0 | 查询保护名单 | 返回真实数据库和系统内置项，展示类型、范围和来源 |
| TC-F2B-PROTECT-002 | P0 | 新增合法 IPv4、IPv6 或 CIDR 人工保护项 | 后端规范化、检查重叠并保存；要求权限、重新认证、原因和审计 |
| TC-F2B-PROTECT-003 | P0 | 提交非法、过宽、重复或与系统项冲突的网段 | 后端拒绝，现有保护项不变化 |
| TC-F2B-PROTECT-004 | P0 | 尝试删除系统内置保护项 | 拒绝；只能通过受控发布变更 |
| TC-F2B-PROTECT-005 | P0 | 待处理告警 IP 后续加入保护名单 | 告警更新为 whitelisted 或明确标记保护命中，不允许封禁 |
10. 自研 UI 与真实数据
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-UI-001 | P0 | 进入“安全控制 / 安全检测” | 页面使用平台自研布局、组件和中文状态，不嵌入第三方 Fail2ban UI |
| TC-F2B-UI-002 | P0 | 对照 SQL/API 检查总览五项指标、趋势、分布和 Top IP | 页面与真实后端结果一致，无 mock、静态或 localStorage 数据 |
| TC-F2B-UI-003 | P0 | 使用 IP、规则、风险、状态、入口和日期组合筛选及分页 | 查询由后端完成；总数、页码、跨页结果准确 |
| TC-F2B-UI-004 | P0 | 打开告警详情 | 显示规则快照、聚合时间线、脱敏证据和处置历史；无密钥或认证材料泄露 |
| TC-F2B-UI-005 | P0 | 打开封禁确认弹窗 | 显示执行器、影响入口、固定时长、保护检查、风险提示和必填原因 |
| TC-F2B-UI-006 | P0 | 规则保存成功、保存但应用失败、版本冲突 | 三种状态分别准确提示；失败不得显示成功 toast |
| TC-F2B-UI-007 | P1 | 1440、1280、1024、768和375宽度验收 | 指标、图表、表格、筛选和弹窗无横向溢出；关键操作可见可用 |
| TC-F2B-UI-008 | P1 | 仅键盘和读屏操作页面 | 表单有 label，错误有关联说明，状态不只依赖颜色，弹窗焦点和按钮名称准确 |
| TC-F2B-UI-009 | P0 | 后端、collector 或 agent 不可用 | 页面显示明确降级和最后成功时间，不用空数据伪装“零攻击” |
11. 权限、进程与系统加固
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-SEC-001 | P0 | 检查 cmpp-api.service 和运行进程 |
NestJS 使用专用非 root 用户；有效 UID/GID 非0 |
| TC-F2B-SEC-002 | P0 | 检查 NestJS capabilities、sudoers、可写目录 | 无通用 sudo、无 CAP_NET_ADMIN/CAP_SYS_ADMIN；只能写明确业务和日志目录 |
| TC-F2B-SEC-003 | P0 | 以 NestJS 用户尝试读取/写入 /etc/fail2ban、运行防火墙命令或访问代理管理文件 |
全部被操作系统权限拒绝 |
| TC-F2B-SEC-004 | P0 | 检查 Security Agent Socket | 只在本机 Unix Socket，权限和用户组符合设计，无 TCP 监听 |
| TC-F2B-SEC-005 | P0 | 向 Agent 提交未知动作、非法 JSON、超长字段、shell 字符和非白名单规则 | 全部拒绝且无命令执行；记录限量安全日志 |
| TC-F2B-SEC-006 | P0 | 检查操作日志 | 规则变更、封禁、解封、忽略、保护名单、失败和回读异常均可追溯 |
| TC-F2B-SEC-007 | P1 | 查看告警详情和完整证据 | 读取动作按设计写访问审计；低权限用户只能看到脱敏数据 |
12. 可用性、恢复和数据保留
| 编号 | 优先级 | 测试步骤 | 预期结果 |
|---|---|---|---|
| TC-F2B-OPS-001 | P0 | 停止 Fail2ban | 健康面板显示对应来源异常；已有告警可查；不得显示“当前无攻击” |
| TC-F2B-OPS-002 | P0 | Collector 暂停后恢复并重放积压 | 事件按幂等键补录，计数准确，无重复告警 |
| TC-F2B-OPS-003 | P0 | 重启 API、Gateway、Fail2ban、collector 和 agent | 已生效规则、活动封禁和告警状态恢复一致，不自动执行新封禁 |
| TC-F2B-OPS-004 | P0 | 发布失败触发回滚 | PostgreSQL、代码、环境、Fail2ban/Nginx生成配置和防火墙规则均有可验证恢复路径 |
| TC-F2B-OPS-005 | P1 | 执行30天事件、180天告警/审计保留任务 | 只删除到期且不受保护数据；活动封禁、未完成处置和审计期数据不删除 |
| TC-F2B-OPS-006 | P1 | 大量扫描事件压测 | Collector 有界处理，API与Gateway业务不被阻塞；告警聚合避免写放大 |
| TC-F2B-OPS-007 | P0 | 对比执行器、数据库和页面 | 当前封禁集合、到期时间和执行器类型一致；差异进入异常状态和告警 |
13. 发布验收证据
第一版发布前至少保留：
- Fail2ban filter 单元样例，包含命中与不命中日志。
- 九类规则的专项自动化结果。
- API 权限、参数边界、并发、幂等和审计测试。
- PostgreSQL migration 状态和表/索引/唯一约束核对。
- NestJS 非 root、capabilities、sudoers 和文件权限证据。
- Cloudflare 真实 IP、伪造 Header 和 Nginx 执行器真实验证。
- 直连 API/SSH/CMPP 的隔离测试 IP nftables 封禁与解封证据。
- Fail2ban、collector、agent、API、Gateway、Nginx、PostgreSQL 和 Redis 健康证据。
- 自研 UI 桌面端、平板端和移动端截图以及控制台日志。
- 发布前 PostgreSQL、运行源码、环境文件、生成配置和防火墙规则恢复资产校验。
14. 判定规则
- 任一 P0 失败：第一版不得发布。
- 检测达到阈值但未生成告警、未达到阈值却告警、错误 IP 聚合、密钥泄露、保护地址可被封禁、页面显示封禁而执行器未生效、NestJS 仍为 root或可执行任意系统命令，均按 P0 处理。
- 只验证 Fail2ban 命令输出、只验证前端样式或只写数据库不验证真实执行器，不能作为功能通过。