SSH 防爆破 (FailGuard)

FailGuard 是 rho-aias 内置的 SSH 防暴力破解模块，基于 eBPF probes 内核级检测技术 实现对 SSH 暴力破解攻击的实时监控与自动封禁。与传统 fail2ban 的日志扫描方案不同，FailGuard 直接在内核态通过 eBPF 探针捕获 SSH 认证事件，具有零延迟、无日志依赖、不可绕过的优势。

工作原理

FailGuard 通过挂载多个 eBPF 探针（probes）到内核关键路径上，实现内核级的 SSH 攻击行为捕获：

eBPF 探针说明

FailGuard 使用以下四类 eBPF 探针协同工作：

探针	类型	挂载点	检测内容
`inet_csk_accept`	fexit / kretprobe	TCP 连接接受函数	捕获新 SSH 连接，记录源 IP、PID、连接时间
`sched_process_fork`	tracepoint	进程创建事件	追踪 sshd 子进程派生
`sched_process_exit`	tracepoint	进程退出事件	检测 preauth 阶段短连接（进程快速退出）
`pam_authenticate`	uretprobe	PAM 认证返回	获取认证成功/失败结果

为什么使用 eBPF？

零延迟：直接在内核中捕获事件，无需等待日志写入磁盘
不可绕过：攻击者无法通过清除日志、修改 syslog 配置等方式逃避检测
轻量级：无需额外读取 /var/log/auth.log，不消耗文件 I/O
Docker 友好：不需要挂载主机日志文件到容器内

检测模式

FailGuard 提供三种检测模式，对应不同的安全级别和攻击场景：

模式	说明	覆盖场景	误报风险
normal（默认）	PAM 认证失败检测	密码错误、无效用户、PAM 失败、最大尝试次数	低
ddos	normal + preauth 短连接	扫描器探测、认证超时、preauth 断连	中
aggressive	ddos + 更严格阈值	所有异常 SSH 行为	较高

normal 模式

仅通过 pam_authenticate uretprobe 捕获 PAM 认证失败事件：

密码认证失败
无效用户登录
PAM 模块拒绝认证
超过最大认证尝试次数

ddos 模式

在 normal 基础上增加 preauth 短连接检测：

监控 sched_process_fork 和 sched_process_exit tracepoint
当 SSH 子进程从创建到退出的时间 < short_conn_seconds 时判定为可疑短连接
有效检测端口扫描器和自动化攻击脚本

aggressive 模式

最严格的检测模式，降低触发门槛以应对高强度攻击。

配置

在 config.yml 中配置 FailGuard：

yaml

# SSH 防爆破配置（基于 eBPF probes 内核级检测）
failguard:
  enabled: true                     # 是否启用 FailGuard
  ssh_ports: [22]                   # 监控的 SSH 端口列表
  short_conn_seconds: 2             # preauth 短连接判定阈值（秒）
  mode: normal                      # 检测模式: normal/ddos/aggressive
  max_retry: 5                      # 触发封禁的失败次数阈值
  find_time: 600                    # 滑动窗口时长（秒，默认 10 分钟）
  ban_duration: 3600                # 封禁时长（秒，默认 1 小时）

参数说明

参数	类型	默认值	说明
`enabled`	bool	false	是否启用 FailGuard
`ssh_ports`	[]int	`[22]`	监控的 SSH 端口列表
`short_conn_seconds`	int	`2`	preauth 短连接判定阈值（秒），连接后此时间内断开视为可疑
`mode`	string	`normal`	检测模式：`normal`、`ddos`、`aggressive`
`max_retry`	int	`5`	滑动窗口内触发封禁的失败次数阈值
`find_time`	int	`600`	滑动窗口时长（秒）
`ban_duration`	int	`3600`	封禁时长（秒）

与旧版的区别

旧版 FailGuard 采用日志扫描模式（类似 fail2ban），需要配置 log_path、fail_regex、ignore_regex、ignore_ips 等参数。新版已完全迁移至 eBPF probes 模式，不再需要这些参数。白名单统一由 manual 模块管理。

封禁生命周期

eBPF Probe 捕获 PAM 失败 → 滑动窗口计数 → 达到 max_retry → XDP 内核层封禁（sourceMask 0x80）
                                                              ↓
                                              实际封禁时长 = ban_duration + 最多 5 分钟清理延迟
                                                              ↓
                                              cleanupExpiredBans() 每 5 分钟扫描一次
                                                              ↓
                                              过期 IP 移除 XDP 规则 + 更新数据库状态

封禁延迟

cleanupExpiredBans() 使用固定 5 分钟清理间隔。封禁到期后，XDP 规则不会立即移除，需等待下一个清理周期。建议 ban_duration 设为 300 秒（5 分钟）或更长，使清理延迟占比合理。

与其他模块的协作

白名单集成

FailGuard 在封禁前调用全局白名单检查器（WhitelistChecker），避免误封受信 IP。白名单由 manual 模块统一管理，无需在 FailGuard 中单独配置。

数据库集成

封禁记录自动写入业务数据库（business.db，ban_records 表），可通过 API 查询：

bash

# 查看 FailGuard 封禁记录
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8081/api/ban-records?source=failguard"

位掩码

FailGuard 使用专用位掩码 0x100（Bit 8）标记来源，不与其他模块冲突：

source_mask = 0x100 (仅 FailGuard)

解除封禁时仅移除 FailGuard 位，如果该 IP 还被其他来源封禁则保留规则。

Docker 部署

由于采用 eBPF probes 方式检测，FailGuard 不再需要挂载主机的 SSH 日志文件。只需确保容器具备必要的 eBPF 能力即可：

yaml

services:
  rho-aias:
    image: docker.cnb.cool/makecnbgreatagain/rho-aias/rho-aias:latest
    container_name: rho-aias
    cap_add:
      - CAP_BPF          # 加载 eBPF 程序（FailGuard probes 需要）
      - CAP_PERFMON      # 性能监控
      - CAP_NET_ADMIN    # 网络管理
      - CAP_NET_RAW      # 原始套接字
    # 注意：不再需要挂载 /var/log/auth.log

eBPF 权限要求

FailGuard 的 eBPF probes 需要内核版本 >= 4.x（fexit/kretprobe 需要 5.x+）。请确保宿主机内核满足要求。

动态配置支持

FailGuard 支持运行时动态配置，可通过 API 或数据库热更新以下参数而无需重启服务：

enabled - 开关状态
max_retry - 失败阈值
find_time - 窗口时长
ban_duration - 封禁时长
mode - 检测模式

bash

# 示例：通过 API 动态调整 FailGuard 参数
curl -X POST "http://localhost:8081/api/dynamic-config/failguard" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"max_retry":3,"find_time":300,"ban_duration":86400,"mode":"aggressive"}'

最佳实践

1. 选择合适的检测模式

场景	推荐模式	说明
面向公网的 SSH 服务	`normal`	覆盖常见暴力破解，误报极低
遭遇端口扫描	`ddos`	检测 preauth 阶段异常行为
高安全要求 / 遭受持续攻击	`aggressive`	最严格检测，注意监控误报

2. 调整阈值

根据实际业务需求调整参数：

yaml

failguard:
  max_retry: 3        # 更激进的封禁策略
  find_time: 300      # 缩短窗口到 5 分钟
  ban_duration: 86400 # 封禁 24 小时

3. 配合白名单使用

确保管理 IP 和可信网段不会被误封（通过 manual 模块配置）：

bash

# 添加管理网段到白名单
curl -X POST http://localhost:8081/api/manual/whitelist/rules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"value": "10.0.0.0/8"}'

4. 配合其他模块联动

FailGuard 的 XDP 封禁规则与其他模块共存，位掩码机制确保多源规则不会冲突。可以同时启用 WAF 联动、异常检测等模块实现多层防护。

5. 监控封禁记录

定期检查封禁记录，及时发现异常：

bash

# 查看活跃的 FailGuard 封禁
curl -s "http://localhost:8081/api/ban-records?source=failguard" | jq '.records[] | select(.expired == false)'

SSH 防爆破 (FailGuard) ​

工作原理 ​

eBPF 探针说明 ​

检测模式 ​

normal 模式 ​

ddos 模式 ​

aggressive 模式 ​

配置 ​

参数说明 ​

封禁生命周期 ​

与其他模块的协作 ​

白名单集成 ​

数据库集成 ​

位掩码 ​

Docker 部署 ​

动态配置支持 ​

最佳实践 ​

1. 选择合适的检测模式 ​

2. 调整阈值 ​

3. 配合白名单使用 ​

4. 配合其他模块联动 ​

5. 监控封禁记录 ​

SSH 防爆破 (FailGuard)

工作原理

eBPF 探针说明

检测模式

normal 模式

ddos 模式

aggressive 模式

配置

参数说明

封禁生命周期

与其他模块的协作

白名单集成

数据库集成

位掩码

Docker 部署

动态配置支持

最佳实践

1. 选择合适的检测模式

2. 调整阈值

3. 配合白名单使用

4. 配合其他模块联动

5. 监控封禁记录