LordOfPolls/Unifi-Rampart
GitHub: LordOfPolls/Unifi-Rampart
为 UniFi 防火墙自动同步 Spamhaus、Firehol、abuse.ch 等威胁情报 IP 列表的轻量级工具，作为 UniFi Cyber-Secure 的免费替代方案。
Stars: 16 | Forks: 1
# UniFi-Rampart
:/data/custom/unifi-rampart
scp config.toml root@:/data/custom/unifi-rampart
# 通过 SSH 登录并运行
ssh root@
cd /data/custom/unifi-rampart
./unifi-rampart
```
接下来，你可以设置一个 cron 任务，让它定期执行。
### 从其他机器运行
你可以在任何能够通过 HTTPS 访问你的控制器的机器上运行 Rampart。只需将 `config.toml` 中的 `url` 指向控制器的真实地址（例如 `https://192.168.1.1`），如果它使用的是自签名证书，请保持 `verify_tls = false`。
### 获取 API 凭证
你需要提供 API key 或者用户名/密码对之一（无需同时提供）：
- **API key（推荐用于 UDM/UniFi OS 控制器）**：在控制器的 UI 界面中，通过 Settings > Control Plane > Integrations 生成一个本地 API key（确切路径因固件版本而异）。将其设置为 `config.toml` 中的 `api_key`。
- **用户名/密码（适用于经典的自托管控制器）**：创建一个本地管理员账户，并在 `config.toml` 中设置 `username`/`password`。在此账户上禁用 2FA —— 此流程不支持处理 2FA 验证。
## 配置
将 `config.example.toml` 复制为 `config.toml` 并对其进行编辑以匹配你的环境（由于 `config.toml` 会包含你的控制器凭证，因此已被 gitignore 忽略）。
最重要的可能是 `excluded` 列表；它是你的安全网；即使某些 IP 和网络出现在威胁情报源中，它们也永远不会被拦截。
你可能不希望拦截自己的内部私有网络。
## 运行说明
### 基本用法
```
cargo run --release
```
**执行流程：**
1. 登录到你的 UniFi 控制器的 API
2. 从已启用的数据源下载 IP 列表
3. 过滤掉无效内容和被排除的网络
4. 在 UniFi 控制器中创建/更新防火墙组
每个已启用的数据源都会成为一个防火墙组，你可以在 **Settings → Policy Engine → Zones** 中看到它们
### 命令行选项
**试运行模式：**
```
cargo run --release -- --dry-run
```
覆盖你的配置并以 dry-run 模式运行。
在不进行任何数据库更改的情况下模拟同步。使用此选项可以在将更改应用到生产环境之前预览将要更新的内容。
**清理模式：**
```
cargo run --release -- --clean
```
从控制器中删除防火墙组，只能作为最后手段使用。如果在 `config.toml` 中设置了 `group_prefix`，则仅删除名称以该前缀开头的组；如果为空，则会删除站点上的所有防火墙组。
**修剪（默认开启）：**
每次常规同步也会删除任何不再对应于已启用源且属于 `group_prefix` 作用域的防火墙组 —— 例如，在你禁用或重命名某个源之后，或者当一个拆分的源缩减并且需要更少的 `_0`、`_1`、... 分块组时。只有当 Rampart 成功重新下载并重新解析该组在本次运行中可能所属的源之后，该组才会被修剪，因此短暂的下载失败绝不会导致组被删除。如果组仍被活跃的防火墙规则引用，则会跳过并发出警告，这与 `--clean` 的行为相同。需要设置 `group_prefix`。
要禁用修剪并保留孤立的组：
```
cargo run --release -- --no-prune
```
## 威胁情报源
包含的配置中提供了几个常见的情报源，但你可以添加任何公开可访问的 IP 列表。每个源都会创建一个具有指定 `name` 的防火墙组。
**常见数据源：**
- **Firehol level1/2/3**：聚合威胁情报源。Level1 比较保守，level2 和 level3 比较激进（包含 10 万+ IP）。建议从 level1 开始。
- **Spamhaus DROP/EDROP**：已知的垃圾邮件和被劫持的网络。误报率低，被广泛信任。
- **Emerging Threats Compromised IPs**：活跃的僵尸网络节点和被入侵的主机。
- **Feodo Tracker**：银行木马 C2 基础设施（abuse.ch 项目）。
- **Tor Exit Nodes**：如果你的威胁模型有要求，可以拦截 Tor，但请务必清楚你正在拦截的内容。
- **Cloudflare Servers**：不要将这些用作拦截列表，而是应该将它们作为你 Web 服务器的白名单。
像 Firehol Level3 这样激进的源可能会包含超过 100,000 个 IP，可能会使你的控制器不堪重负。
请先在非生产环境的控制器上进行测试，以免导致你的控制器崩溃。
## 常见问题
为 UniFi 防火墙提供自动化威胁情报源
我的控制台提示 "Gateway Configuration Failed"
很可能是你启用的防火墙组中有一个对你的控制器来说太大了。 **解决方案：** 1. 减少每个组中的 IP 数量，或者禁用该情报源 2. 从控制器中删除有问题的组 找到有问题的组： ``` sudo cat /usr/lib/unifi/logs/server.log | grep -E "ERROR|WARN" | grep -v "trafficFlow" ``` **选项 1 - 使用清理模式（最简单）：** ``` cargo run --release -- --clean ``` 这将删除所有的防火墙组。清理完成后，在再次同步之前，请在 `config.toml` 中禁用有问题的源。 **选项 2 - 手动删除：** 使用错误消息中的名称/ID，通过 UniFi Web UI 删除有问题的防火墙组（Settings → Firewall & Security → Firewall Groups，或根据固件版本而定的类似位置）。这会破坏现有的防火墙规则吗？
**不会。**该工具仅创建或更新防火墙 IP 组。你现有的规则将保持不变。这些组在你的控制器中显示时，与任何其他地址组没有区别。 如果你有一条规则依赖于这些组，它将毫无问题地应用这些更改。 你需要在自己的防火墙规则中使用这些组。如果某个拦截列表源宕机了会怎样？
该工具会记录错误并继续处理其他源。一个源下载失败不会阻塞整个同步过程。我可以将其用于 UDM/Cloud Key/云端托管的控制器吗？
我只在 UDM Pro 和 SE 上测试过此工具，但只要其他 UniFi 设备公开了控制器的 REST API，它就应该能正常工作。我该如何在规则中实际使用这些防火墙组？
1. 前往 **Settings → Policy Engine → Zones** 2. 创建一个新规则 3. 将模式设置为 IP，然后选择列表（在列表的 Any、IP、MAC、Region 中选择） 4. 选择你需要的组 5. 配置你的拦截/拒绝操作 6. 保存并应用我应该启用所有的情报源吗？
**不应该。** 从保守的源（Firehol Level1、Spamhaus DROP）开始，并监控是否有误报。启用所有源往往会导致你不小心拦截掉合法的服务。多个站点？
更改 `config.toml` 中 `[controller]` 下的 `site`，使其与你的站点匹配（可以在 UniFi 的 URL 中查看：`/manage/site/your_site_name`）。 我尚未在多站点环境下对此进行过测试 —— 风险自负。标签：Python安全, Rust, UniFi, 可视化界面, 威胁情报, 开发者工具, 网络安全, 网络流量审计, 自动化运维, 通知系统, 防火墙, 隐私保护