jimmy-mc/ha-wg
GitHub: jimmy-mc/ha-wg
一个 Home Assistant 自定义集成，用于在智能家居平台中管理和监控通过 WatchGuard Cloud 管理的 Firebox 防火墙策略状态及本地 NetFlow 流量摘要。
Stars: 0 | Forks: 0
# 用于 Home Assistant 的 WatchGuard Cloud
Home Assistant disabled policy
```
WatchGuard 的独立设备 ID 非常重要。像 `FB-12345` 这样的 URL 样式的值可能会创建误导性的事务，而不会部署到预期的独立设备；管理调用使用 `12345`。
## 实体
该集成为所选的 Firebox 创建一个设备，为每个所选策略创建一个翻译后的开关，一个 **Latest deployment** 状态传感器，以及五个 **Recent deployment 1–5** 诊断传感器。策略开关使用 Home Assistant 的 `mdi:firewall` 图标翻译。
每个开关公开：
- 实际保存的启用/禁用状态；
- 策略 ID；
- 策略组；
- 策略类型；
- 操作；
- 存在集成驱动的部署时的最新部署 ID 和状态。
开关状态不是乐观更新的。失败的操作会触发刷新，以便实体恢复到 WatchGuard Cloud 报告的状态。
Latest deployment 传感器报告最新的事务状态，并在可用时公开其部署 ID、版本、描述和创建时间。其 `recent_deployments` 属性保留五个最新记录，用于自动化和诊断。
五个 Recent deployment 传感器使同样的最新优先历史记录在标准的 Home Assistant 设备页面上可见。每个状态都包含 Home Assistant 本地时区的 WatchGuard 事务创建时间，后跟描述。选择一行还会显示其状态、ID、部署版本、描述和 ISO 创建时间。这些传感器是只读的，不会发起部署。
启用前一日账户报告后，单独的账户报告设备会公开 **Previous-day top country** 和 **Previous-day top blocked country**。它们的状态是排名最高的国家/地区代码；有界的排名属性包含字节和连接数。时间段为前一个完整的 UTC 日，范围是整个选定的 WatchGuard 账户，而不仅仅是策略条目所代表的 Firebox。
单独发现的 NetFlow 设备会创建：
- Collector 状态；
- 窗口流、流量和数据包；
- 平均流量速率；
- 排名靠前的源、目标和协议；
- 活跃的导出器；
- 解码错误；
- 最后一个数据包。
排名靠前的行受限于 App 的 `top_n` 设置。排名靠前的地址是 Home Assistant 的实体状态/属性，可能会被 Recorder 保留；如果不需要完整地址，请启用地址匿名化。
## 操作
### `watchguard_cloud.deploy_configuration`
部署所选 Firebox 当前保存的配置。
| 字段 | 必填 | 描述 |
|---|---:|---|
| `config_entry_id` | 是 | WatchGuard Cloud 配置条目 |
| `description` | 否 | 部署历史描述 |
### `watchguard_cloud.set_policy_state`
设置策略状态并默认进行部署。
| 字段 | 必填 | 描述 |
|---|---:|---|
| `config_entry_id` | 是 | WatchGuard Cloud 配置条目 |
| `policy_id` | 是 | 稳定的 WatchGuard 防火墙策略 ID |
| `enabled` | 是 | 期望的策略状态 |
| `deploy` | 否 | 默认为 `true`；`false` 表示保留已保存但未部署的更改 |
### `watchguard_cloud.refresh_policies`
立即读取所有选定的策略状态。
| 字段 | 必填 | 描述 |
|---|---:|---|
| `config_entry_id` | 是 | WatchGuard Cloud 配置条目 |
## 使用场景
- 将批准的紧急隔离策略公开为受控开关；
- 临时启用预先存在的维护策略；
- 无需打开 WatchGuard Cloud 即可恢复已批准的策略；
- 从 Home Assistant 仪表板验证选定的已保存策略状态；
- 显式部署之前审查过的已保存更改。
在相关的自动化、回滚程序和故障通知经过审查之前，请避免无人值守的防火墙更改。
## 数据更新
默认情况下，选定的策略每 60 秒轮询一次。部署历史每 15 分钟独立读取一次，而集成触发的部署会立即更新诊断传感器。成功或失败的命令也会请求立即刷新策略。身份验证会在 token 过期之前刷新，并且在收到 `401` 后会重试一次经过身份验证的请求。
轮询仅为读取。写入仅通过开关命令或显式操作发生。
可选报告每六小时对前一个完整的 UTC 日执行两次读取：执行 `top_countries` 和安全 `top_blocked_countries`。
报告失败在单独的协调器中隔离，并且不会更改策略状态。
NetFlow App 持续聚合数据包并公开本地摘要 API。其 HA 条目默认每 30 秒轮询一次该 API，可在 10–300 秒之间配置。重启 App 会清除滚动窗口。运行时内存限制为 100,000 条流记录、4,096 个 NetFlow v9 模板和 256 个导出器；丢弃的记录会在诊断中计数。
## 故障排除
### 策略已保存但未部署
- 确认独立管理 ID 仅包含 `FB-12345` URL 标识符的数字部分。
- 为 FireCluster 保留完整的 `FBCL-12345` 格式。
- 检查开关属性中的 `last_deployment_id` 和 `last_deployment_status`。
- 手动刷新 WatchGuard Cloud Deployment History，并匹配部署描述和 ID。
### 部署响应包含 `errors`
API 在发布可用事务之前拒绝了部署。在检查已保存的策略和部署历史之前，请勿重复执行开关命令。
### 身份验证失败
- 重新对配置条目进行身份验证；
- 验证区域、Access ID、访问密码、API key 和提供商账户 ID；
- 确认所选的受管账户可供 API 身份访问。
### 图标未出现
- 确认 Home Assistant 版本为 2026.3 或更高；
- 确认存在 `custom_components/watchguard_cloud/brand/icon.png`；
- 重启 Home Assistant；
- 刷新或清除前端缓存。
### NetFlow 传感器不可用或保持为零
- 确认在启用 Firebox 导出之前 App 正在运行；
- 确 Firebox 目标为 Home Assistant 主机 IP 和 UDP 端口 `2055`；
- 使用 NetFlow v9 并留出时间以供模板和数据记录到达；
- 确认 `allowed_exporters` 为空或包含 Firebox 源地址；
- 检查 App 仪表板和日志中的数据包/解码计数器；
- 验证 VLAN/防火墙规则是否允许从 Firebox 到 Home Assistant 的 UDP `2055` 通信。
有关恢复和事件处理程序，请参见 [RUNBOOK.md](RUNBOOK.md)。
## 已知限制
- 在开发期间观察到的分配响应不包含数字 Firebox Management 设备 ID。
- 仅有 DEU 行为具有实时证据。
- 事务状态 `complete` 被接受为 WatchGuard 的部署成功信号；Firebox 和 WatchGuard Deployment History 仍然是可操作的真相来源。
- 部署历史响应在运行时内存中缩减为最新的五个事务；外部发起的部署可能需要长达 15 分钟才能显示在 Home Assistant 中。
- 不存在持久的集成自有操作日志。
- 由于不保留策略主体，因此无法进行自动回滚。
- API 失败、超时、权限、速率限制和分页样本仍然不完整。
- 报告的范围为账户，因为测试的请求省略了可选的设备过滤器。仅公开提供的两个国家/地区视图，报告是可选的，并且 API 速率限制指南仍然未知。
- NetFlow App 具有自动化解析器测试、成功的 amd64/aarch64 容器构建以及本地合成 v5 UDP 摄取/回读测试，但尚无实时的 Firebox 流量证据。
- NetFlow 的 top-talker 摘要是操作估计值，而非计费或取证记录。
## 诊断和支持
从 WatchGuard Cloud 配置条目下载诊断信息。诊断信息包括选定的非机密配置、策略摘要、协调器健康状况、token 过期时间以及最新的集成驱动部署状态。该传感器单独公开部署历史返回的最新事务。
切勿发布凭据、token、受众、原始请求标头或未清理的 Postman 环境。
- [支持](SUPPORT.md)
- [安全政策](SECURITY.md)
- [操作](OPERATIONS.md)
- [操作手册](RUNBOOK.md)
## 开发
```
uv sync --extra test --no-install-project
uv run --no-sync pytest -q
uv run --no-sync ruff check .
uv run --no-sync ruff format --check custom_components addons tests scripts
uv run --no-sync mypy --strict --explicit-package-bases custom_components/watchguard_cloud addons/watchguard_netflow/rootfs/app
uv run --no-sync python scripts/validate_release.py
docker build --platform linux/amd64 --build-arg BUILD_FROM=ghcr.io/home-assistant/amd64-base:3.23 --tag watchguard-netflow:test addons/watchguard_netflow
```
Azure DevOps CI 运行的测试包括分支覆盖率、Linting、严格类型检查、编译、元数据验证、品牌验证和发布打包。
参见：
- [项目交接和新聊天提示](HANDOVER.md)
- [架构](ARCHITECTURE.md)
- [API 证据](API_CAPABILITIES.md)
- [贡献](CONTRIBUTING.md)
- [开发指南](DEVELOPMENT.md)
- [质量规模评估](QUALITY_SCALE.md)
- [发布流程](RELEASE.md)
- [路线图](ROADMAP.md)
## 质量目标
该集成遵循面向 Gold/Platinum 的实践，但并未声明获得官方等级。所有集成模块目前均具有 100% 的语句和分支覆盖率，且受跟踪的 Bronze 和 Silver 规则已完成或已合理豁免。Gold 仍然需要已发布、经过审查的自动化蓝图、更广泛的区域证据以及 Home Assistant 审查。有关确切差距的评估，请参见 [QUALITY_SCALE.md](QUALITY_SCALE.md)。
## 移除
1. 从 **Settings → Devices & services** 中删除 WatchGuard Cloud 集成。
2. 删除 WatchGuard NetFlow 集成，并在使用过的情况下卸载 App。
3. 移除 `/config/custom_components/watchguard_cloud`，对于本地 App，还需移除 `/addons/watchguard_netflow`。
4. 重启 Home Assistant。
移除该集成不会删除、还原或部署 WatchGuard 策略。停止 App 会立即停止收集并清除其内存中的数据。
## 许可证
在 MIT 许可证下分发。请参见 [LICENSE](LICENSE)。
标签：Home Assistant, WatchGuard, 物联网, 系统集成, 请求拦截, 逆向工具, 防火墙管理