koiakoia/sentinel-unifi
GitHub: koiakoia/sentinel-unifi
一套完整的 UniFi Network 可观测性技术栈，整合 Python API 客户端、Prometheus 指标导出、Wazuh SIEM 告警规则和 Grafana 可视化面板。
Stars: 1 | Forks: 0
# sentinel-unifi
一套完整的 UniFi Network 可观测性技术栈：包含 Python API 客户端、CLI、Prometheus exporter、Wazuh SIEM 集成以及 Grafana dashboard。
专为运行 Integration API (v10+) 的 UniFi 控制器构建，例如 UCG-Fiber、UDM Pro 和 UDM SE。
## 组件
| 组件 | 文件 | 用途 |
|-----------|------|---------|
| **API Client** | `unifi/` | 具备自动分页、mixin 组合和 Vault/环境变量认证的 Python 客户端 |
| **CLI** | `cli.py` | 基于 Click 的 CLI，用于交互式网络查询 |
| **Collector** | `collector.py` | 计划数据收集器（专为 systemd timer 设计） |
| **Exporter** | `exporter.py` | Prometheus 指标端点（默认端口 9120） |
| **Wazuh Rules** | `wazuh/` | 用于网络事件的自定义 decoder + 告警规则 |
| **Grafana Dashboard** | `grafana/` | 用于 UniFi 指标可视化的 Dashboard JSON |
## 快速开始
```
# 安装依赖
pip install requests click prometheus_client
# 设置您的 API key
export UNIFI_API_KEY="your-api-key"
export UNIFI_CONTROLLER_URL="https://192.168.1.1" # your controller IP
# CLI 使用
python3 cli.py info
python3 cli.py devices
python3 cli.py clients
python3 cli.py networks
python3 cli.py snapshot
```
## 认证
API 密钥按以下顺序读取：
1. 位于 `secret/unifi` 的 **HashiCorp Vault**（字段：`api_key`, `controller_url`）
2. **环境变量** `UNIFI_API_KEY` 和 `UNIFI_CONTROLLER_URL`
Vault 集成是可选的 —— 环境变量即可独立运行。
## 架构
```
UniFi Controller API
│
▼
Collector (5min) ──→ /var/log/sentinel/unifi/ (snapshots + events)
│
▼
Exporter (:9120) ──→ Prometheus ──→ Grafana Dashboard
│
▼
Wazuh Rules (100500-100513) ──→ SIEM Alerts
```
## Prometheus Exporter
将 exporter 作为 systemd 服务或独立程序运行：
```
python3 exporter.py
# 指标位于 http://localhost:9120/metrics
```
暴露的关键指标：设备运行时间、每台设备的客户端数量、端口利用率、TX/RX 吞吐量、固件版本、错误率。
## Wazuh SIEM 集成
用于网络事件告警的自定义规则：
| Rule ID | 事件 |
|---------|-------|
| 100500 | 设备离线 |
| 100501 | 设备恢复 |
| 100502 | 固件变更 |
| 100503 | 新设备采纳 |
| 100504–100513 | 客户端异常、配置变更、端口事件 |
将 `wazuh/unifi-api-decoder.xml` 和 `wazuh/unifi-api-rules.xml` 部署到您的 Wazuh 服务器规则目录中。
## UniFi API 说明
- 字段名使用 **camelCase**（而非 snake_case）
- 设备类型为 **UPPERCASE**（`USW`, `UAP`, `UGW`）
- Base path：`/proxy/network/integration/v1/...`
- 需要在 UniFi 控制器 UI 的 Settings → API 中生成的 API 密钥
## 许可证
MIT
标签：API客户端, API集成, Click CLI, Dashboard, DNS解析, Grafana, HashiCorp Vault, PE 加载器, Python, UDM Pro, UniFi, Wazuh, 可观测性, 告警规则, 命令控制, 开源项目, 数据导出器, 数据采集, 无后门, 系统集成, 网络安全, 网络安全审计, 网络设备管理, 自动化运维, 自定义请求头, 逆向工具, 隐私保护