内容总览
一、背景
1.1 核心功能
fail2ban 是基于日志的入侵防御工具,核心能力是扫描服务运行日志,识别其中的失败认证、恶意扫描、限流触发等异常行为,对来源 IP 自动下发防火墙封禁规则,到达封禁时长后自动解封。整个流程无需人工介入。
1.2 主要作用
| 作用 | 说明 |
|---|---|
| 实时阻断暴力破解 | 监控 SSH、FTP、邮件、Web 认证日志,对反复失败的 IP 封禁 |
| 阻断恶意扫描 | 识别扫描 .env、wp-login.php、/admin 等路径的爬虫 |
| 协同应用限流 | Nginx limit_req 触发 429 后由 fail2ban 升级为 IP 级封禁 |
| 降低资源消耗 | 在防火墙层丢弃请求,避免业务进程被慢速攻击拖垮 |
| 留存攻击证据 | 封禁记录写入 SQLite 与 fail2ban.log,便于溯源 |
| 累犯递增封禁 | 通过 recidive jail 对反复被封的 IP 提升封禁时长 |
1.3 适用边界
fail2ban 适用于单机或少量主机的被动防御场景。对分布式拒绝服务(DDoS)海量 IP 攻击、应用层业务逻辑漏洞、零日漏洞利用等无能为力,这类场景需流量清洗、WAF、漏洞修复等手段配合。
fail2ban 由 Cyril Jaquier 于 2004 年发起,使用 Python 编写,最初目的是应对 SSH 暴力破解。传统被动防御手段(密码强度、禁用 root 登录、改默认端口)只能提高攻击门槛,无法阻止持续扫描;fail2ban 通过扫描服务日志,对短时间内多次失败认证的来源 IP 自动下发防火墙封禁规则,将日志从「事后审计」变为「实时阻断」。
fail2ban 不是防火墙,也不是入侵检测系统(IDS)。它只做三件事:读日志、匹配规则、调用防火墙命令。这种聚焦定位使其轻量、可移植、易扩展。
二、工作原理
2.1 架构
fail2ban 由三类组件构成:
| 组件 | 职责 |
|---|---|
| server(fail2ban-server) | 守护进程,加载配置,调度 filter 与 action |
| client(fail2ban-client) | 命令行客户端,与 server 通信,查询状态、下发封禁 |
| jail(监狱) | filter + action + 参数的组合单元,一个 jail 监控一类日志 |
2.2 工作流程
日志文件 → filter 按 findtime 窗口统计失败次数 → 达到 maxretry → action 调用防火墙命令封禁
↓
bantime 到期 → actionunban 自动解封
四步链路:
- 监听:backend 读取日志文件或 systemd journal
- 匹配:filter 按 failregex 正则匹配失败行,同一 IP 在 findtime 内累计计数
- 封禁:累计达到 maxretry,action 调用
actionban下发防火墙规则 - 释放:bantime 到期,action 调用
actionunban删除规则
2.3 三要素
filter(过滤器)
位于 /etc/fail2ban/filter.d/,定义匹配失败行的正则。例如 sshd 的 filter 匹配 Failed password for invalid user、Authentication failure 等模式。filter 只负责「识别失败」,不负责封禁。
action(动作)
位于 /etc/fail2ban/action.d/,定义封禁与解封命令链:
| 钩子 | 触发时机 |
|---|---|
| actionstart | jail 启动时执行一次(初始化链) |
| actionstop | jail 停止时执行一次(清理链) |
| actioncheck | 每次封禁前检查环境 |
| actionban | 达到 maxretry 时封禁 |
| actionunban | bantime 到期时解封 |
action 通过 iptables、nftables、firewalld、ipset、tcpwrappers 等后端落地封禁。
backend(后端)
| 取值 | 说明 |
|---|---|
| auto | 自动选择(默认) |
| polling | 主动轮询文件修改时间 |
| systemd | 读取 systemd journal(需 journald) |
| python | 纯 Python 实现,兼容性最好 |
2.4 与防火墙集成
fail2ban 创建独立的链(chain)或 ipset 集合,避免污染用户既有规则:
- iptables:创建
f2b-<jail>链,INPUT 链跳入 - nftables:创建
table inet f2b-<jail> - firewalld:创建 rich rule 或 ipset
- 封禁动作默认 DROP,可配置为 REJECT
三、安装
3.1 apt(Debian/Ubuntu)
sudo apt update
sudo apt install fail2ban
3.2 yum/dnf(CentOS/RHEL)
sudo dnf install epel-release
sudo dnf install fail2ban
3.3 源码编译
git clone https://github.com/fail2ban/fail2ban.git
cd fail2ban
sudo python3 setup.py install
sudo cp files/redhat-initd /etc/init.d/fail2ban
sudo systemctl enable fail2ban
3.4 Docker
docker run -d --name fail2ban --restart=always \
--cap-add=NET_ADMIN --cap-add=NET_RAW \
-v /var/log:/var/log:ro \
-v /etc/fail2ban:/etc/fail2ban \
-v /run/fail2ban:/run/fail2ban \
crazymax/fail2ban:latest
容器模式必须挂载日志目录与配置目录,并赋予 NET_ADMIN 能力以便操作容器网络命名空间的 iptables。
四、配置文件层级
4.1 三层覆盖
| 文件 | 用途 | 是否修改 |
|---|---|---|
jail.conf | 默认配置,包升级被覆盖 | 禁止修改 |
jail.local | 本地覆盖,优先级最高 | 只改这里 |
path/to/*.local | 同名 .conf 的 .local 覆盖 | 按需新建 |
加载顺序:.conf 先加载,.local 覆盖同名键。filter 与 action 同理(sshd.conf 被 sshd.local 覆盖)。
4.2 最小配置示例
/etc/fail2ban/jail.local:
[DEFAULT]
bantime = 1h
findtime = 10m
maxretry = 5
backend = auto
usedns = warn
ignoreip = 127.0.0.1/8 ::1 192.168.0.0/16
[sshd]
enabled = true
port = ssh
logpath = /var/log/auth.log
[DEFAULT] 为全局默认,各 jail 可单独覆盖。ignoreip 白名单永远不会被封。
五、关键参数
| 参数 | 说明 | 建议值 |
|---|---|---|
| bantime | 封禁时长,支持 1h/1d/-1(永久) | 初期 1h,累犯递增 |
| findtime | 统计窗口 | 10m |
| maxretry | 窗口内失败阈值 | 5 |
| backend | 日志读取后端 | auto |
| usedns | 是否反向解析主机名 | warn(解析失败用 IP) |
| ignoreip | 白名单 CIDR | 内网 + 跳板机 |
| banaction | 默认封禁动作 | iptables-multiport |
| action | 封禁动作模板 | %(action_mwl)s(封禁+邮件+报告) |
| destemail | 告警收件人 | 运维邮箱 |
| dbpurgeage | 封禁记录数据库保留期 | 1d |
bantime 支持递增语法(需 bantime.increment = true):
bantime.increment = true
bantime.maxtime = 1w
bantime.factor = 2
首次封禁 1h,第二次 2h,第三次 4h,直至 maxtime 上限。
六、内置 jail
6.1 sshd
监控 SSH 失败认证,最常用:
[sshd]
enabled = true
port = ssh
logpath = %(sshd_log)s
backend = %(sshd_backend)s
maxretry = 5
bantime = 1h
6.2 nginx-limit-req
匹配 Nginx 限流日志(limit_req 触发的 429),封禁超频 IP:
[nginx-limit-req]
enabled = true
logpath = /var/log/nginx/error.log
maxretry = 10
findtime = 600
bantime = 7200
6.3 nginx-botsearch
匹配扫描 .env、wp-login.php、/admin 等敏感路径的爬虫。
6.4 nginx-noscript
匹配对 .php、.asp、.exe 等可执行脚本后缀的扫描请求。
6.5 nginx-http-auth
匹配 Nginx Basic Auth 失败日志(user "xxx" was not found in "/etc/.htpasswd")。
6.6 recidive
二次封禁累犯,监控 fail2ban 自身日志中已封禁 IP,对反复被封的 IP 给予更长时间封禁:
[recidive]
enabled = true
logpath = /var/log/fail2ban.log
maxretry = 3
findtime = 1d
bantime = 1w
七、启动与状态
sudo systemctl enable --now fail2ban
sudo systemctl restart fail2ban
sudo fail2ban-client status
sudo fail2ban-client status sshd
sudo fail2ban-client set sshd unbanip 1.2.3.4
sudo fail2ban-client set sshd banip 1.2.3.4
status sshd 输出示例:
Status for the jail: sshd
|- Filter
| |- Currently failed: 3
| |- Total failed: 17
| `- File list: /var/log/auth.log
`- Actions
|- Currently banned: 2
|- Total banned: 5
`- Banned IP list: 1.2.3.4 5.6.7.8
八、自定义 jail
以封禁频繁请求 Nginx 403 的 IP 为例。
8.1 创建 filter
/etc/fail2ban/filter.d/nginx-403.conf:
[Definition]
failregex = ^<HOST> .* "GET .* HTTP/.*" 403 .*$
ignoreregex =
datepattern = %%d/%%b/%%Y:%%H:%%M:%%S %%z
<HOST> 是 fail2ban 占位符,匹配客户端 IP。datepattern 指定日志时间格式(与 Nginx combined 格式对齐)。
8.2 创建 jail
/etc/fail2ban/jail.local 追加:
[nginx-403]
enabled = true
logpath = /var/log/nginx/access.log
filter = nginx-403
maxretry = 20
findtime = 10m
bantime = 1h
action = iptables-multiport[name=nginx403, port="http,https", protocol=tcp]
8.3 测试与重载
sudo fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/nginx-403.conf
sudo fail2ban-client reload
sudo fail2ban-client status nginx-403
九、持久化封禁
默认封禁记录存于内存 SQLite(/var/lib/fail2ban/fail2ban.sqlite3),重启后保留尚未解封的规则。dbpurgeage 控制记录保留期:
[DEFAULT]
dbpurgeage = 1d
结合 recidive jail 实现「累犯递增封禁」:首次 1h,recidive 捕获后提升至 1w。
十、验证手段
10.1 正则自检
测试 filter 能否匹配日志,不触发实际封禁:
fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf
fail2ban-regex "Nov 1 10:00:00 host sshd[123]: Failed password for invalid user admin from 1.2.3.4" sshd
输出 Lines: X matched 即正则生效。
10.2 故意触发封禁
从另一主机连续输错 SSH 密码达到 maxretry:
for i in $(seq 1 6); do sshpass -p wrong ssh testuser@target; done
随后在目标机查看:
sudo fail2ban-client status sshd
sudo iptables -L f2b-sshd -n
Banned IP list 出现该 IP,iptables 链有 DROP 规则,即闭环成功。
10.3 防火墙链检查
sudo iptables -L -n | grep f2b
sudo nft list ruleset | grep f2b
sudo firewall-cmd --list-rich-rules
10.4 fail2ban 自身日志
sudo tail -f /var/log/fail2ban.log
关键事件:
NOTICE [sshd] Ban 1.2.3.4
NOTICE [sshd] Unban 1.2.3.4
10.5 常见问题排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 不封禁 | filter 未匹配 | fail2ban-regex 验证正则 |
| 不封禁 | logpath 路径错误 | 检查日志文件路径与权限 |
| 不封禁 | usedns 解析阻塞 | 设 usedns = no |
| 误封内网 | ignoreip 未配置 | 加内网 CIDR |
| 重启规则丢失 | 未用 systemd 启动 | systemctl enable fail2ban |
| 容器内 iptables 失败 | 缺 NET_ADMIN | docker run 加 --cap-add=NET_ADMIN |
| bantime 到期未解封 | actionunban 命令错误 | 检查 action.d 配置 |
十一、命令速查表
| 命令 | 作用 |
|---|---|
systemctl start fail2ban | 启动服务 |
fail2ban-client status | 列出所有启用的 jail |
fail2ban-client status sshd | 查看 sshd jail 详情 |
fail2ban-client set sshd banip IP | 手动封禁 |
fail2ban-client set sshd unbanip IP | 手动解封 |
fail2ban-client reload | 重载配置 |
fail2ban-client reload sshd | 重载单个 jail |
fail2ban-regex LOG FILTER | 测试正则 |
iptables -L f2b-sshd -n | 查看封禁链 |
journalctl -u fail2ban -f | 查看服务日志 |