wolffcatskyy/crowdsec-unifi-parser
GitHub: wolffcatskyy/crowdsec-unifi-parser
为 UniFi Dream Machine 提供 iptables LOG 规则部署与 CrowdSec 解析器，让原本嘈杂无结构的防火墙日志变得可解析、可检测。
Stars: 1 | Forks: 0
# CrowdSec UniFi 解析器
[](https://github.com/wolffcatskyy/awesome-unifi)
**注意：** 本项目是在 AI 的协助下开发并受其支持的。问题和 PR 由 AI 智能体进行分类和响应。如果您需要人工服务只需提出，但老实说 AI 更快、更聪明，也更友好。
从 UniFi Dream Machines 获取干净的、 CrowdSec 可解析的防火墙日志 —— 不再有 syslog 噪音。
在您的 UDM/UDR 上部署针对性的 iptables LOG 规则，并提供自定义 CrowdSec 解析器，从每个被丢弃的数据包中提取源 IP、目的 IP、端口、协议、区域和动作。
## 您需要准备什么
**是的，这需要一台单独运行 CrowdSec 的机器。** CrowdSec 并不在 UDM 本身上运行。以下是各组件的分布：
| 组件 | 运行位置 | 功能 |
|------|--------------|-------------|
| `deploy-log-rules.py` | 任何装有 Python 3 的机器（您的笔记本电脑、服务器等） | 一次性通过 SSH 连接到 UDM 以插入 LOG 规则。运行一次，固件更新后需再次运行。 |
| Syslog 接收器 (rsyslog) | 您的 CrowdSec 主机或任何 Linux 设备 | 接收来自 UDM 的 syslog，将防火墙条目写入文件 |
| CrowdSec + 这些解析器 | 与 syslog 接收器相同的机器 | 读取日志文件，检测威胁，发出封禁决策 |
| UDM / UDR | 您的 UniFi 设备 | 发送 syslog。仅此而已。无需安装软件，无额外负载。 |
典型设置：UDM 将 syslog 发送到运行 CrowdSec 的 Raspberry Pi / NAS / 虚拟机。部署脚本在您的笔记本电脑上运行。
## 问题所在
如果您曾尝试将 UniFi syslog 输入 CrowdSec，您会遇到以下障碍：
- **99% 的噪音**：UniFi 的默认 syslog 输出充斥着内核链路状态变化、摄像头事件、控制器通信和固件消息
- **0% 的解析率**：CrowdSec 没有内置的 UniFi 防火墙日志解析器。将其指向原始 UniFi syslog，您会得到 `0 parsed / 47,231 unparsed`
- **无官方支持**：没有针对 UniFi 的 CrowdSec 采集套件。[CrowdSec Hub](https://hub.crowdsec.net/) 有针对 pfsense、OPNsense 和 iptables 的解析器 —— 但没有针对 UniFi 的
- **防火墙事件不可见**：UniFi 静默丢弃数据包。当数据包命中 DROP 规则时没有日志条目，除非您自己添加
## 解决方案
本项目采用不同的方法：与其试图解析 UniFi 嘈杂的默认 syslog，我们通过在 UDM 上部署 iptables LOG 规则，将**干净的、结构化的日志条目**直接注入内核日志。
```
UDM iptables LOG rules CrowdSec parsers
| |
v v
[UNIFI-WAN_LOCAL-D-INVALID] Extract: source_ip, dst_ip,
IN=eth4 SRC=45.33.32.156 port, protocol, zone, action
DST=192.168.1.1 PROTO=TCP
DPT=22 -> Port scan detection
-> Brute force detection
-> CrowdSec decisions
```
### 工作原理
```
+-------------------+ syslog-ng +------------------+ file/syslog +------------------+
| UDM / UDR | -----------------> | Syslog Server | -----------------> | CrowdSec |
| | (UDP 514) | (rsyslog, etc) | acquisition | |
| iptables LOG | | unifi-fw.log | | unifi-logs |
| rules deployed | | | | parser |
| before every | | | | -> scenarios |
| DROP rule | | | | -> decisions |
+-------------------+ +------------------+ +------------------+
| |
| deploy-log-rules.py crowdsec-unifi-bouncer
| (SSH + paramiko) (push bans back to UDM)
| |
+<---------- Complete feedback loop: detect -> ban -> enforce ---------<---------+
```
## 功能特性
- **适用于 UDM, UDM SE, UDR, UDM Pro** —— 任何具有 SSH 和 iptables 的 UniFi OS 设备
- **在固件更新后依然有效** —— 升级后只需重新运行部署脚本
- **速率限制**（10/分钟，突发 20）以防止扫描期间日志泛洪
- **幂等部署** —— 可安全重复运行；首先清理旧规则
- **试运行模式** —— 在不触及 iptables 的情况下预览更改
- **完整的 CrowdSec 集成** —— 解析器 + 场景 + 集合包
- **干净的标记日志条目**，如 `[UNIFI-WAN_LOCAL-D-INVALID]`，易于解析
- **双日志管道**：基于 syslog 的防火墙日志和 CEF 格式的控制器事件
- **开箱即用的端口扫描检测**（5 秒内 3+ 个端口 = 封禁）
- **DDoS/洪水检测**（30 秒内 100+ 次丢弃 = 24 小时封禁）
- **SSH 暴力破解检测**，通过 dropbear 解析器（UDM 的 SSH 守护进程）
- **与 [crowdsec-unifi-bouncer](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer) 配对**，实现完整的检测与阻断闭环
## 快速开始
### 1. 在您的 UDM 上部署 LOG 规则
```
# 安装 paramiko
pip3 install paramiko
# 部署 LOG 规则（SSH 登录到 UDM 并插入 iptables 规则）
python3 deploy-log-rules.py --host 192.168.1.1 --user root --pass YOUR_PASSWORD
# 或者使用环境变量
export UDM_PASS=YOUR_PASSWORD
python3 deploy-log-rules.py --host 192.168.1.1
# 预览更改而不应用
python3 deploy-log-rules.py --host 192.168.1.1 --pass YOUR_PASSWORD --dry-run
```
### 2. 设置 syslog 转发
配置您的 UDM 将 syslog 转发到远程服务器。在 UniFi 控制器中：
**Settings -> System -> Advanced -> Remote Syslog Server**
将 IP 设置为您的 syslog 接收器（例如，您的 CrowdSec 主机或专用 syslog 服务器）。
在接收端，配置 rsyslog 将 UniFi 日志写入专用文件：
```
# /etc/rsyslog.d/10-unifi.conf
:msg, contains, "UNIFI-" /var/log/unifi/unifi-fw.log
& stop
```
### 3. 安装 CrowdSec 解析器
```
# 克隆此 repo
git clone https://github.com/wolffcatskyy/crowdsec-unifi-parser.git
cd crowdsec-unifi-parser
# 运行安装程序
sudo ./install.sh
# 或者手动安装
sudo cp parsers/s00-raw/unifi-logs.yaml /etc/crowdsec/parsers/s00-raw/
sudo cp parsers/s00-raw/cef-logs.yaml /etc/crowdsec/parsers/s00-raw/
sudo cp parsers/s01-parse/unifi-cef.yaml /etc/crowdsec/parsers/s01-parse/
sudo cp parsers/s01-parse/dropbear-logs.yaml /etc/crowdsec/parsers/s01-parse/
sudo cp scenarios/iptables-scan-multi_ports.yaml /etc/crowdsec/scenarios/
sudo cp scenarios/unifi-port-knock.yaml /etc/crowdsec/scenarios/
sudo cp scenarios/unifi-flood-detection.yaml /etc/crowdsec/scenarios/
sudo cp collections/unifi.yaml /etc/crowdsec/collections/
```
### 4. 配置采集
```
# 复制示例 acquisition 配置
sudo cp acquis.d/unifi.yaml /etc/crowdsec/acquis.d/
# 编辑 log 路径以匹配您的设置
sudo $EDITOR /etc/crowdsec/acquis.d/unifi.yaml
```
### 5. 重载 CrowdSec
```
sudo systemctl reload crowdsec
# 验证解析器已加载
cscli metrics
# 您应该能看到日志在 "unifi-logs" 下被解析
```
## 解析内容
### 防火墙日志格式
部署脚本创建如下日志条目：
```
Feb 1 14:23:45 UDM kernel: [UNIFI-WAN_LOCAL-D-INVALID] IN=eth4 OUT= MAC=xx:xx:xx SRC=185.220.101.42 DST=192.168.1.1 LEN=40 TOS=0x00 TTL=243 ID=54321 PROTO=TCP SPT=54321 DPT=22 WINDOW=1024 SYN
```
解析器提取：
| 字段 | 示例 | 描述 |
|-------|---------|-------------|
| `source_ip` | `185.220.101.42` | 攻击者 IP |
| `dst_zone` | `LOCAL` | 目标区域 (LOCAL, LAN, WAN, VPN, DMZ) |
| `action` | `drop` | 防火墙动作 (drop, reject, accept) |
| `log_type` | `iptables_drop` | 供场景过滤使用 |
| `hostname` | `UDM` | 设备主机名 |
| `protocol` | `TCP` | IP 协议 |
| 端口, MAC 等 | ... | 完整的 iptables 日志字段 |
### CEF 事件格式
UniFi 还会为控制器事件发出 CEF（通用事件格式）日志：
```
CEF:0|Ubiquiti|UniFi Network|8.6.9|3004|IPS Alert|7|src=45.33.32.156 dst=192.168.1.100 ...
```
CEF 解析器提取 IPS 警报、威胁事件、管理员操作等。
### 覆盖的链
| 链 | 区域 | 捕获内容 |
|-------|------|-----------------|
| `UBIOS_WAN_LOCAL_USER` | WAN -> 路由器 | SSH 扫描，管理探测 |
| `UBIOS_WAN_LAN_USER` | WAN -> LAN | 针对局域网主机的入站攻击 |
| `UBIOS_WAN_IN_USER` | WAN -> 内部 | 端口转发，NAT 穿越尝试 |
| `UBIOS_WAN_DMZ_USER` | WAN -> DMZ | 针对 DMZ 的攻击 |
| `UBIOS_WAN_GUEST_USER` | WAN -> 访客网络 | 访客网络探测 |
| `UBIOS_WAN_VPN_USER` | WAN -> VPN | VPN 端点攻击 |
| `UBIOS_WAN_WAN_USER` | WAN -> WAN | 传输流量丢弃 |
## 包含的场景
### 端口扫描检测 (`iptables-scan-multi_ports`)
检测激进的 TCP 端口扫描：同一源 IP 在 5 秒内访问 3 个或更多不同目标端口即触发封禁。
- **类型**：Leaky bucket
- **容量**：2（在第 3 个不同端口触发）
- **泄漏速度**：5 秒
- **黑洞**：1 分钟（抑制重复警报）
- **标签**：`remediation: true`（CrowdSec 将发出封禁决策）
- **MITRE ATT&CK**：T1595.001, T1018, T1046
### 顺序端口试探检测 (`unifi-port-knock`)
检测与随机突发扫描不同的系统性顺序端口扫描。这可以捕获像 nmap 顺序扫描、masscan 和 zmap 这样在较长时间内按顺序探测端口的方法性侦察工具。
- **类型**：Leaky bucket
- **容量**：9（在第 10 个不同端口触发）
- **泄漏速度**：1 分钟
- **黑洞**：2 分钟（抑制重复警报）
- **标签**：`remediation: true`（CrowdSec 将发出封禁决策）
- **MITRE ATT&CK**：T1595.001, T1018, T1046
- **置信度**：2（由于持续的活动模式，置信度较高）
**为什么有两个扫描场景？**
| 场景 | 检测对象 | 阈值 | 时间范围 | 用例 |
|----------|---------|-----------|-----------|----------|
| `iptables-scan-multi_ports` | 激进的突发扫描 | 3 个端口 | 5 秒 | 快速扫描器，脚本小子 |
| `unifi-port-knock` | 顺序/系统性扫描 | 10 个端口 | 1 分钟 | nmap, masscan, 系统性侦察 |
这两个场景互为补充：突发检测立即捕获快速攻击者，而顺序检测捕获那些为了规避突发检测而随时间分散探测的耐心攻击者。
### DDoS/洪水检测 (`unifi-flood-detection`)
检测大容量洪水攻击：同一源 IP 在 30 秒内被丢弃 100 个或更多数据包即触发 24 小时封禁。
- **类型**：Leaky bucket
- **容量**：99（在第 100 次丢弃时触发）
- **泄漏速度**：30 秒
- **黑洞**：5 分钟（在持续攻击期间抑制重复警报）
- **封禁时长**：24 小时
- **标签**：`remediation: true`（CrowdSec 将发出封禁决策）
- **MITRE ATT&CK**：T1498 (Network Denial of Service), T1499 (Endpoint Denial of Service)
此场景捕获：
- SYN 洪水
- UDP 洪水
- ICMP 洪水
- 任何导致防火墙丢弃的大容量攻击
### Dropbear SSH 暴力破解 (`dropbear-bf`)
检测针对 UDM/UDR dropbear 守护进程的 SSH 暴力破解尝试：同一源 IP 在 1 分钟内 5 次认证失败即触发 4 小时封禁。
- **类型**：Leaky bucket
- **容量**：4（在第 5 次失败尝试时触发）
- **泄漏速度**：1 分钟
- **黑洞**：4 小时（封禁时长）
- **标签**：`remediation: true`（CrowdSec 将发出封禁决策）
- **MITRE ATT&CK**：T1110.001 (Password Guessing), T1110.003 (Password Spraying)
此场景与 `dropbear-logs.yaml` 解析器配合使用，该解析器从 UDM/UDR 日志中提取失败的 SSH 认证事件，包括：
- 错误的 PAM 密码尝试
- 不存在用户的登录尝试
- 预认证断开连接
### UniFi IPS/威胁管理警报 (`unifi-ips-alert`)
检测来自 UniFi 内置威胁管理系统的 IPS 签名匹配。当 UniFi IPS 检测到恶意流量（漏洞利用、恶意软件、C2 通信等）时，此场景触发 CrowdSec 封禁。
- **类型**：Leaky bucket
- **容量**：2（在第 3 次 IPS 警报时触发）
- **泄漏速度**：5 分钟
- **黑洞**：5 分钟（抑制重复警报）
- **标签**：`remediation: true`（CrowdSec 将发出封禁决策）
- **MITRE ATT&CK**：T1190 (Exploit Public-Facing Application), T1203 (Exploitation for Client Execution), T1059 (Command and Scripting Interpreter)
此场景使用来自 UniFi syslog 输出的 CEF 日志。当同一源 IP 在 5 分钟内产生 3 次以上 IPS 警报时触发，表明存在持续的恶意活动。
**CEF IPS 警报示例：**
```
CEF:0|Ubiquiti|UniFi Network|8.6.9|3004|IPS Alert|7|src=45.33.32.156 dst=192.168.1.100 UNIFIipsSignature=ET EXPLOIT ... UNIFIipsSignatureId=2024897
```
### UniFi 管理控制台暴力破解 (`unifi-admin-bf`)
检测针对 UniFi 管理控制台（Web UI）的暴力破解尝试。此场景解析失败的管理员登录事件的 CEF 格式日志。
- **类型**：Leaky bucket
- **容量**：4（在第 5 次失败登录时触发）
- **泄漏速度**：2 分钟
- **黑洞**：5 分钟（抑制重复警报）
- **标签**：`remediation: true`（CrowdSec 将发出封禁决策）
- **MITRE ATT&CK**：T1110.001 (Password Guessing), T1078 (Valid Accounts)
**检测的日志格式**（CEF）：
```
CEF:0|Ubiquiti|UniFi Network|9.0.108|101|Admin Login Failed|5|UNIFIsrcIp=192.168.1.100 UNIFIuser=admin msg=Invalid credentials
```
**要求**：在 UniFi 控制器设置中启用 CEF 日志记录（Settings > System > Advanced > Remote Logging）。
## Docker CrowdSec 设置
如果您在 Docker 中运行 CrowdSec，请挂载日志文件和配置：
```
# docker-compose.yaml
services:
crowdsec:
image: crowdsecurity/crowdsec
volumes:
# Mount UniFi firewall logs
- /var/log/unifi:/var/log/unifi:ro
# Mount custom parsers (or use install.sh inside container)
- ./parsers/s00-raw/unifi-logs.yaml:/etc/crowdsec/parsers/s00-raw/unifi-logs.yaml:ro
- ./parsers/s00-raw/cef-logs.yaml:/etc/crowdsec/parsers/s00-raw/cef-logs.yaml:ro
- ./parsers/s01-parse/unifi-cef.yaml:/etc/crowdsec/parsers/s01-parse/unifi-cef.yaml:ro
- ./parsers/s01-parse/unifi-admin-auth.yaml:/etc/crowdsec/parsers/s01-parse/unifi-admin-auth.yaml:ro
- ./parsers/s01-parse/dropbear-logs.yaml:/etc/crowdsec/parsers/s01-parse/dropbear-logs.yaml:ro
- ./scenarios/iptables-scan-multi_ports.yaml:/etc/crowdsec/scenarios/iptables-scan-multi_ports.yaml:ro
- ./scenarios/unifi-port-knock.yaml:/etc/crowdsec/scenarios/unifi-port-knock.yaml:ro
- ./scenarios/unifi-flood-detection.yaml:/etc/crowdsec/scenarios/unifi-flood-detection.yaml:ro
- ./scenarios/dropbear-bf.yaml:/etc/crowdsec/scenarios/dropbear-bf.yaml:ro
- ./scenarios/unifi-ips-alert.yaml:/etc/crowdsec/scenarios/unifi-ips-alert.yaml:ro
- ./scenarios/unifi-admin-bf.yaml:/etc/crowdsec/scenarios/unifi-admin-bf.yaml:ro
- ./collections/unifi.yaml:/etc/crowdsec/collections/unifi.yaml:ro
- ./acquis.d/unifi.yaml:/etc/crowdsec/acquis.d/unifi.yaml:ro
```
## 文件结构
```
crowdsec-unifi-parser/
├── README.md # This file
├── LICENSE # MIT
├── deploy-log-rules.py # iptables LOG rule deployer (runs on UDM via SSH)
├── install.sh # One-command installer
├── parsers/
│ ├── s00-raw/
│ │ ├── unifi-logs.yaml # Raw UniFi syslog parser
│ │ └── cef-logs.yaml # CEF (Common Event Format) parser
│ └── s01-parse/
│ ├── unifi-cef.yaml # UniFi CEF event enrichment
│ ├── unifi-admin-auth.yaml # UniFi admin auth failure parser
│ └── dropbear-logs.yaml # UDM SSH auth failure parser
├── scenarios/
│ ├── iptables-scan-multi_ports.yaml # TCP burst port scan detection
│ ├── unifi-port-knock.yaml # Sequential port-knock detection
│ ├── unifi-flood-detection.yaml # DDoS/flood attack detection (100+ drops/30s = 24h ban)
│ ├── dropbear-bf.yaml # SSH brute force detection (UDM dropbear)
│ ├── unifi-ips-alert.yaml # UniFi IPS/Threat Management detection
│ └── unifi-admin-bf.yaml # UniFi admin brute force detection
├── collections/
│ └── unifi.yaml # Collection bundle
├── acquis.d/
│ └── unifi.yaml # Example acquisition config
└── docs/
├── ARCHITECTURE.md # Detailed architecture walkthrough
└── TROUBLESHOOTING.md # Common issues and fixes
```
## 验证是否工作
安装后，检查 CrowdSec 指标：
```
# 检查 acquisition（日志是否正在被读取？）
cscli metrics | grep unifi
# 检查解析器成功率
cscli metrics show parsers
# 检查 alerts
cscli alerts list
# 实时查看 logs
tail -f /var/log/unifi/unifi-fw.log
# 测试完整 pipeline
cscli explain --file /var/log/unifi/unifi-fw.log --type unifi
```
您应该看到类似如下的输出：
```
line: Feb 1 14:23:45 UDM kernel: [UNIFI-WAN_LOCAL-D-INVALID] IN=eth4 ...
├ s00-raw/unifi-logs ✅ success
└ s01-parse/iptables-logs ✅ success
├ meta.source_ip 185.220.101.42
├ meta.log_type iptables_drop
└ meta.action drop
```
## 固件更新后重新运行
UniFi 固件更新会重新生成所有 iptables 规则，这将移除 规则。固件更新后：
```
python3 deploy-log-rules.py --host 192.168.1.1 --pass YOUR_PASSWORD
```
考虑将此添加到 cron 作业中，或作为固件更新过程的一部分运行。
## CrowdSec UniFi 生态系统的一部分
| 项目 | 描述 |
|---------|-------------|
| [crowdsec-unifi-suite](https://github.com/wolffcatskyy/crowdsec-unifi-suite) | 全栈一键安装程序 |
| [crowdsec-unifi-bouncer](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer) | 在 UniFi 防火墙上执行 CrowdSec 决策 |
| [crowdsec-blocklist-import](https://github.com/wolffcatskyy/crowdsec-blocklist-import) | 将 28+ 个威胁源导入 CrowdSec |
## 系统要求
- **UniFi 设备**：UDM, UDM SE, UDR, UDM Pro（任何带有 SSH + iptables 的 UniFi OS）
- **CrowdSec**：v1.4+（已在 v1.6.x 上测试）
- **Python 3**：用于部署脚本
- **paramiko**：`pip3 install paramiko`
- **Syslog 转发**：UDM -> 远程 syslog 服务器 -> CrowdSec 采集
## 许可证
MIT
标签：CrowdSec, iptables, PE 加载器, Python, rsyslog, SSH, Syslog, Ubiquiti, UDM, UDR, UniFi, 威胁情报, 子域名变形, 家庭实验室, 开发者工具, 数据清洗, 无后门, 日志解析, 特权提升, 网络安全, 自动化部署, 证书伪造, 请求拦截, 边缘网关, 逆向工具, 防火墙日志, 隐私保护