Halino/Wazuh-Unifi
GitHub: Halino/Wazuh-Unifi
为 Wazuh 提供 UniFi 网络设备的日志解码器、分类规则与关联告警，实现 UniFi 环境的集中监控与安全分析。
Stars: 7 | Forks: 4
# 用于 Wazuh 的 UniFi log parser
本项目提供 **decoders** 和 **rules**，使 Wazuh 能够摄取和分析 UniFi 日志（CEF 导出和设备 syslog）。
## 包含内容
| 文件 | 用途 |
|------|--------|
| `wazuh/decoders/unifi_decoders.xml` | 用于 UniFi CEF 和设备 syslog 的 decoders |
| `wazuh/rules/unifi_rules.xml` | 用于分类、告警和关联 UniFi 事件的 rules |
| `wazuh/ossec-unifi.conf.snippet` | 用于远程 syslog 的 `ossec.conf` 示例片段 |
| `tests/sample_logs.txt` | 使用 `wazuh-logtest` 进行测试的示例日志行 |
## 支持的日志来源
1. **UniFi CEF 导出 (SIEM)**
当您将日志发送到 SIEM/syslog 服务器时，来自 **Settings > Control Plane > Integrations > Activity Logging** 的日志。格式：`CEF:0|Ubiquiti|UniFi Network|...`
2. **UniFi 设备 syslog**
来自 UniFi 设备（APs、交换机、网关）的原始 syslog，例如 `hostapd`、`ath*`、STA 关联/取消关联。
3. **网关防火墙 (netfilter)**
当您在网关防火墙/流量规则 (UDM/UXG/USG) 上启用 **Log** 时，网关会发送内核 netfilter 日志行，如 `[WAN_LOCAL-D-0] DESCR="..." SRC=... DST=... PROTO=... DPT=...`。`unifi-fw` decoder 会解析这些内容；rules 对 ACCEPT / DROP-REJECT / **DNAT**（入站到端口转发/暴露的服务）进行分类，并关联端口扫描。
## 部署
### 1. 将 decoder 和 rules 复制到 Wazuh manager
在 Wazuh manager 上：
```
# Decoders
sudo cp wazuh/decoders/unifi_decoders.xml /var/ossec/etc/decoders/
# Rules
sudo cp wazuh/rules/unifi_rules.xml /var/ossec/etc/rules/
```
### 2. （可选）在 manager 上接收 syslog
如果 UniFi（或您的 SIEM）将 syslog **发送到 Wazuh manager**，请将 `wazuh/ossec-unifi.conf.snippet` 中的代码片段添加到 `/var/ossec/etc/ossec.conf` 中的 `` 内部：
- 将 `` 设置为您的 UniFi/网络范围（例如 `192.168.0.0/16`）。
- 经典 syslog 使用 `udp`；如果您的发送方使用 TCP，请使用 `tcp` 和端口 514。
### 3. 替代方案：syslog 写入文件，然后由 Wazuh 读取该文件
如果另一台主机（例如 rsyslog）接收到 UniFi syslog 并将其写入文件，请让 Wazuh 指向该文件。
**rsyslog 示例**（例如 `/etc/rsyslog.d/unifi.conf`），用于将 UniFi 消息写入文件：
```
# 在 514 端口接收 UDP syslog，将 UniFi 写入文件
module(load="imudp")
input(type="imudp" port="514")
if $msg contains "CEF:0|Ubiquiti" or $msg contains "hostapd" or $msg contains "ath" then {
action(type="omfile" file="/var/log/unifi.log")
}
```
**Wazuh** - 在拥有 `/var/log/unifi.log` 文件的主机（manager 或 agent）上，将其添加到 `` 内部的 `ossec.conf` 中：
```
/var/log/unifi.log
syslog
```
- 如果该文件位于 **manager** 上，请将此内容添加到 manager 的 `ossec.conf` 中。
- 如果该文件位于另一台服务器上，请在该处安装 Wazuh **agent**，并将此代码块添加到 **agent** 的 `ossec.conf`（或等效文件）中，以便 agent 将该日志转发给 manager。
### 4. 重启 Wazuh
```
sudo systemctl restart wazuh-manager
```
## UniFi 端：将日志发送到 Wazuh
- **CEF（推荐）**
在 UniFi 中：**Settings > Control Plane > Integrations > Activity Logging** > 选择 **SIEM Server** > 设置您的 Wazuh manager（或 syslog 中继）的 **IP** 和 **端口**（例如 **514**）。
日志将为 CEF 格式，并由 `unifi_decoders.xml` 解码。
- **设备 syslog**
在 UniFi 控制器/设备上，将 **Remote syslog** 设置为相同的 IP 和端口。设备将发送 hostapd 样式的消息；相同的 decoders/rules 会处理它们。
## 规则组和级别
| 组 / 概念 | 示例 |
|----------------|----------|
| `unifi` | 所有 UniFi 事件 |
| 管理员 / 配置 | 管理员访问、配置更改 (级别 3-5) |
| 客户端 WiFi | 客户端连接/断开/漫游 (级别 2) |
| 安全 | 威胁检测并阻止、蜜罐、防火墙阻止 (级别 5-8) |
| WAN / 性能 | 故障转移、高延迟、丢包 (级别 4-5) |
| 电源 | PoE / AP 功率不足、超出 PoE 可用性 (级别 5-6) |
| 网关防火墙 | netfilter ACCEPT (静默) / DROP-REJECT / DNAT 端口转发命中 (级别 0-4) |
| 关联 | 暴力破解、取消认证震荡 (deauth flapping)、重复阻止、端口扫描、多重威胁 (级别 8-12) |
在 Wazuh UI 中，您可以使用例如 `rule.groups:unifi`、`rule.groups:firewall` 或规则 ID 范围 `100100`-`100234` 进行过滤。
## 关联 / 频率规则
当基础规则在时间窗口内重复触发时，这些规则将激活：
| 规则 ID | 触发条件 | 频率 / 窗口 | 级别 | 描述 |
|---------|------------|-------------------|-------|-------------|
| 100210 | 100204 (RADIUS) | 60 秒内 5 次 | 10 | 可能的 RADIUS 暴力破解 |
| 100211 | 100201 (取消关联) | 60 秒内 10 次 | 8 | 快速取消关联 (取消认证 / 震荡) |
| 100212 | 100111 (防火墙阻止) | 120 秒内 10 次，相同源 | 8 | 重复的防火墙阻止 (扫描) |
| 100213 | 100109 (威胁) | 120 秒内 3 次 | 12 | 多次威胁检测 |
| 100214 | 100120 (内部威胁) | 300 秒内 3 次，相同源 | 12 | 来自主机的多次内部威胁 |
### 激进的关联规则
这些规则**更敏感且可能产生更多噪音**。它们都会将 `aggressive` 添加到 `rule.groups` 中，以便您可以对其进行过滤或区别处理：
| 规则 ID | 触发条件 | 频率 / 窗口 | 级别 | 描述 |
|---------|------------|-------------------|-------|-------------|
| 100215 | 100111 (防火墙阻止) | 300 秒内 3 次，相同源 | 10 | 激进：早期防火墙扫描检测 |
| 100216 | 100204 (RADIUS) | 300 秒内 3 次，相同源 | 10 | 激进：早期 RADIUS 暴力破解嫌疑 |
| 100217 | 100214 (内部威胁) | 900 秒内 2 次，相同源 | 14 | 激进：持续的内部威胁源 |
| 100218 | 100109 (威胁) | 600 秒内 2 次，相同源 | 14 | 激进：触发多次威胁检测的源 |
## MITRE ATT&CK 映射
规则包含 `` 标签，因此事件会显示在 Wazuh MITRE 仪表板中：
| 技术 | ID | 规则 |
|-----------|-----|-------|
| Valid Accounts | T1078 | 100101 (管理员访问) |
| Impair Defenses | T1562 | 100102 (配置更改) |
| Hardware Additions | T1200 | 100103 (设备采用) |
| Service Stop | T1489 | 100104, 100112 (设备离线，WAN 故障转移) |
| Application Layer Protocol | T1071 | 100109, 100111, 100213, 100232 (威胁、防火墙阻止) |
| Network Service Scanning | T1046 | 100110, 100212, 100234 (蜜罐、重复阻止、端口扫描) |
| Exploit Public-Facing Application | T1190 | 100233 (针对暴露服务的 DNAT / 端口转发命中) |
| Brute Force | T1110 | 100210 (RADIUS 暴力破解) |
| Network Denial of Service | T1498 | 100211 (取消认证震荡) |
## 测试 decoder 和 rule
在 manager 上使用 `wazuh-logtest`：
```
/var/ossec/bin/wazuh-logtest
```
粘贴示例行，例如：
```
CEF:0|Ubiquiti|UniFi Network|9.3.33|544|Admin Accessed UniFi Network|1|UNIFIcategory=System UNIFIhost=Office UDM Pro src=203.0.113.59 msg=Admin accessed.
```
您应该会看到 `unifi-cef` decoder 和相应的规则（例如 100101）匹配。
完整的带注释示例日志集位于 `tests/sample_logs.txt` 中——每行都注明了预期的 decoder 和规则 ID。
## 文件结构
```
Wazuh-Unifi/
|-- README.md
|-- LICENSE
|-- CHANGELOG.md
|-- .gitignore
|-- tests/
| |-- sample_logs.txt
|-- wazuh/
| |-- decoders/
| | |-- unifi_decoders.xml
| |-- rules/
| | |-- unifi_rules.xml
| |-- ossec-unifi.conf.snippet
```
## 兼容性
根据 2026 年 2 月的官方 [UniFi System Logs & SIEM Integration](https://help.ui.com/hc/en-us/articles/33349041044119-UniFi-System-Logs) 文档进行了验证。已使用 **UniFi Network Application 10.0.x**（最新版本：10.0.162）进行测试。
| 组件 | 状态 |
|-----------|--------|
| **CEF (SIEM 导出)** | 与 UniFi Network 9.3.x 和 10.0.x 兼容。格式未更改：`CEF:0\|Ubiquiti\|UniFi Network\|Version\|EventID\|Name\|Severity\|Extension`。decoder 接受可选的 "UniFi Network Application" 产品名称，以备未来版本之需。 |
| **CEF 键** | Parser 提取标准标头 + `src` (IPv4/IPv6)、`UNIFIcategory`、`UNIFIsubCategory`、`UNIFIadmin`、`UNIFIclientMac`。其他扩展键（例如 `UNIFIutcTime`、`UNIFIdeviceName`、`UNIFIclientIp`）保留在 `extra_data` 中，不会中断解码。 |
| **事件名称** | 规则匹配来自[官方文档](https://help.ui.com/hc/en-us/articles/33349041044119-UniFi-System-Logs)的所有当前事件名称：管理员访问/进行配置更改、设备采用/离线、WiFi 客户端连接/断开/漫游、检测并阻止威胁、触发蜜罐、被防火墙阻止、WAN 故障转移、高延迟/丢包、PoE 输出不足/超出 PoE 可用性/AP 功率不足。 |
| **日志类别** | Monitoring (访客热点、WiFi、有线、状态)、Internet (中断与故障转移、性能)、Power (PoE、冗余)、Security (防火墙、蜜罐、入侵防御)、System (管理员活动、设备、网络、VPN、WiFi、有线)。System 下的 VPN 事件由通用规则 (100199) 捕获。 |
| **CyberSecure / Traffic Flows** | 根据[官方 Traffic Flows 文档](https://help.ui.com/hc/en-us/articles/32201256219799)，Traffic Flow 日志 (DPI/IDS) 尚未通过 CEF 导出。它们仅以 CSV 和 NetFlow/IPFIX 格式提供。当 Ubiquiti 为流量流添加 CEF 支持时，可能需要新的 decoders/rules。 |
| **设备 syslog** | 与来自 UniFi AP 和转发到远程 syslog (STA 关联/取消关联、RADIUS) 的设备的 hostapd/ath 样式日志兼容。设备固件也可能发出 JSON；此 parser 针对经典的 syslog 格式。 |
如果 Ubiquiti 添加了新的事件类型，通用规则 (100199) 会将未知的 CEF 事件保留在 `unifi` 组中而不发出警报。可根据需要添加特定规则。
## 参考
- [UniFi System Logs & SIEM Integration](https://help.ui.com/hc/en-us/articles/33349041044119-UniFi-System-Logs-SIEM-Integration)
- [Wazuh - 配置 syslog](https://documentation.wazuh.com/current/user-manual/capabilities/log-data-collection/syslog.html)
- [Wazuh - 自定义 decoders](https://documentation.wazuh.com/current/user-manual/ruleset/decoders/custom.html)
标签：IP 地址批量处理, Syslog, UniFi, Wazuh, 云计算, 安全运营, 扫描框架, 插件系统, 日志解析, 红队行动, 规则引擎, 证书伪造