# fail2ban-ebpf

一个基于 eBPF 的轻量级 SSH 暴力破解拦截工具。

- 占用资源少
- 速度快
- 从内核直接防护，无需编写正则表达式，无需配置sshd日志配置，开箱即用


## 功能概览

- 目前仅支持ssh防护

## 运行要求

- Linux
- 支持 eBPF / XDP 的内核
- 宿主机存在 `/sys/kernel/btf/vmlinux`
- 需要 root 权限
- 需要宿主机存在 `libpam.so.0`

说明：

- 本项目依赖 `pam_authenticate` `uprobe`，因此必须能访问宿主机的 `libpam.so`。
- Docker 方式部署时，本质上仍然是在观测和操作宿主机资源，不属于强隔离场景。

## Docker 部署

仓库内提供`docker-compose.yml`：

[LingJianCode/fail2ban-ebpf](https://cnb.cool/LingJianCode/fail2ban-ebpf)

### 启动

如果你使用 compose 中指定的镜像，需要提前修改 `config.yaml` 中的网卡名称( `xdp.iface` )，详见注意事项：

```bash
docker compose up -d
```

查看日志：

```bash
tail -f ./logs/fail2ban-ebpf.log
```

## 日志格式

日志为单行文本，示例：

```text
time=2026-04-29T12:00:00+08:00 event=service_started config=config.yaml ssh_port=22 xdp_iface=ens33 xdp_mode=driver
time=2026-04-29T12:01:02+08:00 event=auth_failed ip=192.168.1.10 pid=1234 ret=7
time=2026-04-29T12:03:15+08:00 event=ip_blocked ip=192.168.1.10 threshold=3 window_minutes=10 expires_at=2026-04-29T12:13:15+08:00
time=2026-04-29T12:13:20+08:00 event=ip_unblocked ip=192.168.1.10
```

## 注意事项

- `xdp.iface` 必须是实际承载 SSH 入站流量的网卡。
- 如果 SSH 监听端口不是 `22`，需要同步修改 `ssh.port`。
- `mode=normal` 仅统计 PAM 认证失败；`mode=aggressive` 会额外启用 preauth 短连接检测。
- `whitelist.entries` 支持单个 IPv4 和 IPv4 CIDR；命中白名单或本机地址的 IP 不会下发到 XDP。
- 某些虚拟网卡或驱动不支持 `offload`/`driver` 模式，程序会自动降级到 `generic`。
- 如果容器内或宿主机上找不到正确的 `libpam.so.0`，`uprobe` 将无法挂载。
- 本项目当前主要支持 IPv4 黑名单拦截。

## 故障排查

- XDP 挂载失败
  检查网卡是否支持 XDP，检查是否以 root 运行。

- `pam_authenticate` 挂载失败
  检查宿主机 `libpam.so.0` 是否存在，检查容器是否挂载了宿主机库目录。

- 没有日志输出
  检查 `log.file` 路径是否可写，检查运行目录下是否创建了 `logs` 目录。

- 容器方式无法生效
  检查是否启用了 `privileged: true`、`pid: host`、`network_mode: host`。

## 本地构建

### 依赖

至少需要：

- `go`
- `clang`
- `llvm`
- `bpftool`

本项目依赖 pam_authenticate uprobe，因此必须能访问宿主机的 libpam.so。

eBPF高性能版fail2ban

一个基于 eBPF 的轻量级 SSH 暴力破解拦截工具，无需编写正则表达式，无需配置sshd日志配置，开箱即用。

安全

网络与通信

操作系统

fail2ban-ebpf是一款基于eBPF技术的高效SSH防护工具，直接在内核层拦截暴力破解攻击。无需配置sshd日志和正则表达式，开箱即用。支持Docker部署，占用资源少速度快，提供白名单和多种检测模式。适用于Linux系统，需要root权限和eBPF/XDP内核支持，当前主要防护SSH服务的IPv4攻击。

容器

Docker

Linux

2026采购季 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

eBPF高性能版fail2ban-腾讯云开发者社区-腾讯云

eBPF高性能版fail2ban

eBPF高性能版fail2ban

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐