内容总览

fail2ban 思维导图

一、背景

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 自动解封

四步链路:

  1. 监听:backend 读取日志文件或 systemd journal
  2. 匹配:filter 按 failregex 正则匹配失败行,同一 IP 在 findtime 内累计计数
  3. 封禁:累计达到 maxretry,action 调用 actionban 下发防火墙规则
  4. 释放: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 查看服务日志