johnnyh1975/ha_sophos_fw
GitHub: johnnyh1975/ha_sophos_fw
该项目是一个 Home Assistant 自定义集成，通过 XML API 和 SNMP 将 Sophos 防火墙接入智能家居平台，实现本地监控与自动化控制。
Stars: 0 | Forks: 2
# Sophos Firewall — Home Assistant 集成
[](https://github.com/hacs/integration)
[](https://github.com/johnnyh1975/ha_sophos_fw/releases)
[](https://www.home-assistant.io)
[](https://www.home-assistant.io/docs/quality_scale/)
Home Assistant Custom Integration，适用于 Sophos Firewall (SFOS 20.x / 22.x)。通过 XML API 和 SNMP 将 HA 与防火墙连接 —— 无需云服务，无需第三方。
## 功能
| 类别 | 实体 |
|---|---|
| **网络接口** | PortA, PortB — 已连接/已断开, Zone, IP-Assignment |
| **防火墙规则** | 开关（带写入权限）或只读传感器 — 位于配置区域 |
| **DHCP** | 组合传感器：服务器状态 + 租约数量 + 作为属性的完整租约列表 |
| **系统** | RAM, Disk, Swap (%), 运行时间 (`"77 d 14 h"`), 备份频率 |
| **连接** | HTTP-, SMTP-, IMAP-, POP3 连接, FTP 命中, Captive-Portal 用户 |
| **服务** | 聚合传感器：`"19 / 21 running"` — `running`/`stopped` 列表作为属性 |
| **VPN 隧道** | 带有连接状态的 IPSec 隧道 |
| **高可用性** | HA 集群状态（活动/非活动），此节点和对等节点的角色（主/从/独立/…） |
| **许可证** | 聚合传感器：`"8 / 9 OK"` — 下一个到期日期，详细信息作为属性 |
| **安全** | Web 过滤器默认操作, IPS 签名版本, Webcat 版本 |
| **硬件健康** | CPU/NPU 温度, 风扇转速, 电源状态（仅限物理设备） |
| **控制** | 触发备份（按钮），切换防火墙规则和 Web 过滤器 |
### 配置区域 (EntityCategory.CONFIG)
防火墙规则和 Web 过滤器策略出现在设备页面的配置区域 —— 而不是在标准视图中。它们仍然可以完全切换并可用于自动化。
## 前置条件
- Home Assistant 2024.9+
- Sophos Firewall SFOS 20.x 或 22.x
- Python 3.12+ (puresnmp 2.x，pysnmp 不兼容)
- API 访问：**网络 → 管理 → 设备访问 → 启用 HTTPS 管理**
- 可选 SNMP：**系统 → 管理 → SNMP → 配置 Community-String**
## 安装说明
### 通过 HACS（推荐）
1. HACS → 集成 → ⋮ → 自定义仓库
2. URL：`https://github.com/johnnyh1975/ha_sophos_fw`，类别：集成
3. 搜索集成：“Sophos Firewall” → 安装
4. 重启 HA
### 手动安装
```
cp -r custom_components/sophos_firewall \
/config/custom_components/sophos_firewall
```
重启 HA。
## 设置
**设置 → 设备与服务 → 添加集成 → “Sophos Firewall”**
设置向导将引导您完成 4 个步骤：
**步骤 1 — 连接：**主机/IP，API 端口（默认：4444），用户名，密码，SSL 验证
**步骤 2 — SNMP（可选）：**启用 SNMP 以获取系统指标、服务、VPN 隧道和许可证。配置 Community-String 和 SNMP 版本（1 或 2c）。
**步骤 3 — 写入访问（可选）：**允许从 HA 切换防火墙规则和 Web 过滤器策略。开启写入访问：显示为开关。不开启：显示为只读传感器。
**步骤 4 — 轮询配置：**轮询间隔和活动端点 —— 按 Tier 分组。所有默认值均已优化预设。
## 轮询间隔 (Tiered Polling)
| Tier | 默认 | XML 端点 | SNMP 端点 |
|---|---|---|---|
| ⚡ 实时 | 30s | 网络接口 | 统计信息, 服务 |
| 🔄 快速 | 120s | — | VPN 隧道, HA 状态 |
| 🔧 运营 | 600s | 防火墙规则 | 系统健康 |
| 🗄 静态 | 1800s | DHCP, Web 过滤器, 备份 | 许可证 |
| 🔁 一次 | 启动时 | 管理设置 | 设备信息 |
写入操作（开关、按钮）总是会立即触发受影响 Tier 的刷新。
## 技术架构
### 数据源
**XML API**（端口 4444，HTTPS）：网络接口，防火墙规则，DHCP 服务器 + 静态租约，Web 过滤器，备份，管理设置。
**SNMP**（端口 161，UDP，puresnmp 2.x）：系统统计信息，服务 (21)，VPN 隧道，许可证（9 个模块），硬件健康，设备信息（型号，固件，IPS 版本，Webcat 版本）。
OID 基础：`1.3.6.1.4.1.2604.5.1`（Sophos 专有 MIB，SFOS 22.x，在 APIVersion 2200.1 上测试）
### 会话管理
持久的 `aiohttp.TCPConnector` 会话，带有 `force_close=True` 和 `asyncio.Semaphore(2)`。防止因服务器端 Keep-Alive 分离导致的超时，并将并行请求限制为 2 个。
### SNMP 特性
使用 `puresnmp 2.x` 而不是 pysnmp（在 Python 3.12+ 上不兼容）。安全插件发现在启动时于 Executor 线程中执行一次并被缓存 —— HA Event Loop 中没有阻塞式 I/O。
### 虚拟机检测 (SFVH)
在虚拟设备上，温度和风扇 OID 不可用。集成会在第一次健康抓取后自动检测到这一点，并永久禁用硬件健康轮询。
### 多防火墙支持
实体 ID 基于防火墙主机名 —— 在多个实例中无冲突：
```
sensor.5heynexg_system_dienste
sensor.buero_fw_system_dienste ← zweite Firewall, kein Konflikt
```
## DHCP 租约传感器
每个 DHCP 服务器一个组合传感器：
```
Netz · DHCP Main_DHCP → In Betrieb · 3 Leases
Netz · DHCP Guest VLAN → In Betrieb · 0 Leases
Netz · DHCP DMZ → Außer Betrieb
```
作为属性的完整租约列表 —— 可直接用于自动化：
```
{{ state_attr('sensor.5heynexg_dhcp_leases_main_dhcp', 'leases')
| selectattr('MACAddress', 'eq', 'aa:bb:cc:dd:ee:ff')
| map(attribute='IPAddress') | first }}
```
## 服务聚合传感器
使用一个包含完整概览的传感器代替 21 个单独的 Binary Sensor：
```
System · Dienste → 19 / 21 running
Attribute:
running: [Antivirus, DNS, HTTP-Proxy, IPS, ...]
stopped: [Anti-Spam, HA-Service]
```
用于自动化：
```
{{ 'Anti-Spam' in state_attr('sensor.5heynexg_system_dienste', 'stopped') }}
```
## 自动化示例
**许可证到期时通知：**
```
trigger:
- platform: template
value_template: >
{{ state_attr('sensor.5heynexg_sicherheit_lizenzen', 'problem') | length > 0 }}
action:
- service: notify.mobile_app
data:
message: >
Sophos Lizenz-Problem:
{{ state_attr('sensor.5heynexg_sicherheit_lizenzen', 'problem') | join(', ') }}
```
**回家时启用防火墙规则：**
```
trigger:
- platform: state
entity_id: person.jean_christoph
to: home
action:
- service: switch.turn_on
target:
entity_id: switch.5heynexg_rule_homeautomation_to
```
## 高级指南
| 指南 | 描述 |
|---|---|
| [Top-25 拦截连接仪表板](docs/top25_blocked_connections.md) | 使用 Sophos syslog + HACS Syslog Receiver + pyscript 构建一个实时的“拦截的前 25 个源 IP”卡片 —— 无需更改此集成 |
## 兼容性
| 设备 / 版本 | 状态 | 测试于 |
|---|---|---|
| SFVH（虚拟设备） | ✅ 完全兼容 | KV01, SFOS 22.0.0 GA-Build411 |
| XGS 系列（硬件） | ✅ 支持 | 硬件健康已激活 |
| SFOS 20.x | ✅ 支持 | API 兼容 |
| SFOS 22.x | ✅ 已测试 | APIVersion 2200.1 |
| HA 2024.9+ | ✅ 必需 | 配置流程中的 Sections API |
## 故障排除
**启动后所有实体均显示“未知”**
→ 首次抓取需要 30-45 秒。重新加载后请稍等片刻。
**SNMP 传感器保持“未知”状态**
→ 检查 Community String：系统 → 管理 → SNMP
**设置时提示“Cannot connect”**
→ 检查 API 访问权限：网络 → 管理 → 设备访问 → 启用 HTTPS 管理
**缺少温度传感器**
→ 在 SFVH（虚拟设备）上正常。已自动识别 —— 这不是故障。
**HA 日志中出现 Blocking I/O**
→ 仅在安装后首次启动时出现。若持续存在：请重启 HA。
## 更新日志
| 版本 | 更改内容 |
|---|---|
| **v1.0.2** | **新实体：** 高可用性集群（来自 adi-debug99 的 Issue）—— `SophosHAEnabledSensor`、`SophosHAStateSensor`、`SophosHAPeerStateSensor`（通过 ENUM 获取角色，已本地化）；电源状态（`SophosPSUSensor`，仅限物理设备）；IMAP 和 POP3 连接传感器。**错误修复（来自代码审查）：** `trigger_backup()` 现在会检查响应状态 —— 失败的备份不再被静默吞没，而是作为可见错误报告；真正实现了 `RestoreEntity`（开关/传感器在重启后显示最后的状态，而不是 `unavailable`）；响应级别状态码 532/534/535（API 被禁用 / IP 被封锁 / 认证）会被识别，而不是作为空响应漏过；乐观的开关状态（即时 UI 反馈，出错时回滚）；`_get_tag` 跳过损坏的单个记录，而不是丢弃整个列表；删除了死代码和未使用的导入。**强化：** 集中的 `field_str()` 保护，防止损坏的 XML 字段值（防止在值为 `None`/嵌套时导致平台崩溃）；健康查询中强大的 OID 解析；异常容忍的 HTTP 会话关闭；防止无效轮询间隔导致的 Busy-Loop；在并行的多防火墙设置中对 SNMP 插件补丁使用 Thread-Lock。**测试：** 从约 120 个扩展到 164 个，全套测试运行无需取消选择。 |
| **v1.0.1** | 错误修复（来自 taracraft 的 Issue）：Config-Flow 和 Options-Flow 中的 SNMP 连接测试*总是*以 "snmp_cannot_connect" 失败，与真实的凭据/可达性无关 —— `preload()` 从未在 `test_connection()` 之前被调用，产生的 `RuntimeError` 被 `_get()` 的通用异常处理器吞没了。修复：现在正确调用了 `preload()`；来自 `_get_client()` 的 `RuntimeError` 在 `_get`/`_multiget`/`_walk` 中被单独作为 `WARNING` 记录，而不是与正常的超时混在一起作为 `DEBUG` 记录。额外发现并修复了：`SophosUptimeSensor` 在运行时间 <24 小时的情况下显示了错误的分钟数（例如 "3 h 205 min" 而不是 "3 h 25 min"）。测试套件首次使用 pytest 完全执行，而不是仅进行语法检查 —— 并在此过程中修正了两个过时的测试预期。 |
| **v1.0.0** | 完全符合 Quality Scale Gold：`exception-translations`（所有异常都使用 `translation_key`/`translation_domain`），`strict-typing`（`SophosData` TypedDict, `DataUpdateCoordinator[SophosData]`）。完整的 Config-Flow 测试：新增 `test_config_flow.py`（user/snmp/write_access/polling/reauth/reconfigure 包括所有错误路径）。DHCP 传感器测试适应了 ENUM 模式。 |
| **v0.10.0** | 错误修复：实现了 `async_step_reauth()` —— HA 现在在发生身份验证错误时显示 UI 对话框，而不是出现 `UnknownStep` 崩溃。重新登录后重置 Tier 时间戳。按 Tier 进行 SNMP 错误处理（一个失败的 OID 不再中断所有其他 Tier）。针对网络接口、防火墙规则、VPN 隧道、DHCP 服务器和开关的陈旧实体清理。DHCP 传感器可本地化（`SensorDeviceClass.ENUM`，`lease_count` 属性）。修复了 `CONF_SNMP_ENABLED` 字面量错误。新测试。 |
| **v0.9.0** | 5 层协调器：实时/快速/运营/静态/一次。可通过 Options-Flow 配置轮询间隔和来源。SNMP 信号量并发。虚拟机检测 (SFVH)。配置流程中的 Sections-API。重新配置流程。Quality Scale Silver。 |
| **v0.8.1** | Quality Scale Silver：`async_migrate_entry()`，配置条目上的 `unique_id`。IPS 和 Webcat 版本传感器。更新了 README。 |
| **v0.8.0** | 错误修复：Switch-Tier-Force，按时间顺序排列的许可证日期，XML 转义。运行时间显示为 `"77 d 14 h"`。FTP 传感器。RestoreEntity。`DEFAULT_POLL_SNMP_HA=False`。`hacs.json`。 |
| **v0.7.0** | 用于服务和许可证的传感器。用于规则和 Web 过滤器的 EntityCategory.CONFIG。实体名称中的排序前缀。组合的 DHCP 传感器。 |
| **v0.6.6** | 修复：通过 `mod.create()` 正确创建了 SNMP SecurityModel 实例 |
| **v0.6.5** | 修复：缓存了 puresnmp 安全插件加载器 —— 不再有阻塞式 I/O |
| **v0.6.4** | 修复：修复了实体 ID 重复 `5heynexg_5heynexg_...` 的问题 |
| **v0.6.2** | 用于配置流程的 Sections API —— 分组的轮询配置 |
| **v0.5.8** | 虚拟机检测 (SFVH) —— 如果没有数据，则永不创建硬件传感器 |
| **v0.5.6** | 用于多防火墙设置的基于主机名的实体 ID |
## 许可证
MIT —— 使用风险自负。写入访问权限可以更改防火墙配置。
标签：Home Assistant, Sophos防火墙, 智能家居, 网络设备集成, 计算机取证, 逆向工具