domo-monster/HomeSecurityAssistant

# 家庭安全助手 家庭安全助手是一个自定义的 Home Assistant 集成，提供实时网络流量安全监控。它结合了被动的 NetFlow/IPFIX 流量分析与主动的网络扫描、外部 IP 威胁情报、DNS 黑名单检查以及漏洞检测——所有内容通过一个专用的多视图侧边栏仪表板呈现。 ## 功能 ### 网络流量分析 - 在可配置的 UDP 端口上监听 **NetFlow v5、v9 和 IPFIX** 数据报 - 使用可配置的 CIDR 范围区分内部与外部流量 - 跟踪每个设备的流量计数、字节流量和连接历史 - 检测可疑模式：向外发送到滥用端口、端口扫描、异常出站流量 ### 主动网络扫描器 - 可选地对所有观察到的内部主机执行 ping + 端口扫描（nmap 风格，可配置间隔） - **可配置的扫描端口**——指定单个端口、范围或两者（例如 `22,80,443,8000-9000`）。默认为 47 个知名端口：21-23、25、53、80、110、111、135、139、143、443、445、465、515、554、587、631、993、995、1080、1433、1521、1723、1883、2049、2323、3306、3389、4443、5000、5060、5432、5555、5900、6379、6667、8000、8008、8080、8443、8883、8888、9090、9100、9200、27017、49152 - 即使主机阻止 ping，也能发现开放服务与操作系统指纹 - **HTTP 指纹识别**——基于 WhatWeb 风格的技术检测，对 HTTP(S) 端口进行轻量级识别。可识别 CMS 平台（WordPress、WooCommerce、Joomla、Drupal、Magento）、Web 服务器（Tomcat、IIS、Caddy、Varnish、HAProxy）、应用程序（Grafana、GitLab、Nextcloud、Jenkins、phpMyAdmin、Pi-hole、Synology DSM、UniFi、Elasticsearch、Prometheus）以及运行时（PHP、Node.js、ASP.NET），依据响应头、Cookie 与 HTML 内容进行识别 - 按主机报告扫描结果：活跃状态、Ping 延迟、开放端口、操作系统猜测、识别到的技术 ### 外部 IP 情报 - 为外部 IP 补充 **IPInfo.io、VirusTotal、Shodan 和 AbuseIPDB**（均为可选，需配置 API 密钥） - 对外部 IP 进行 **反向 DNS 解析** - 将外部 IP 与主机名检查 **威胁情报黑名单**（默认使用 abuse.ch 馈送，可自定义） - 可配置的 **外部 IP 历史保留窗口**（默认 24 小时，0 表示永久保留） ### 漏洞检测 - **NVD 增强**——查询 NIST 国家漏洞数据库 REST API 2.0，匹配检测到的服务横幅中的 CVE。对 20 多种服务的映射进行精确的 CPE 厂商/产品过滤：SSH（OpenSSH、Dropbear）、HTTP（Apache、nginx、lighttpd）、MySQL/MariaDB、FTP（vsftpd、ProFTPD）、SMTP（Postfix、Exim、Sendmail）、Redis、MongoDB、PostgreSQL、SMB/NetBIOS/Microsoft-DS（Samba）、IMAP（Dovecot）、MQTT/MQTT-TLS（Mosquitto）、ADB（Android Debug Bridge）、DNS（BIND、dnsmasq）、NTP（ntpd、Chrony）、RTSP（Live555、GStreamer）以及 UPnP（MiniUPnP）。通用基于横幅的匹配可覆盖任何其他具有可识别版本字符串的服务 - **服务感知预取**——NVD 关键词预取范围限定于网络上实际检测到的服务，避免对未出现的产品发起不必要的 API 调用 - **HTTP 技术验证**——仅当技术通过 HTTP 指纹识别 **实际确认** 时，才报告 Web 应用程序（WordPress、WooCommerce、Drupal 等）的 CVE，消除误报 - **CISA KEV 集成**——将发现结果与 CISA 已知被利用漏洞目录交叉引用，标记处于活跃利用状态的 CVE - **版本范围匹配**——使用 CPE 配置数据检查检测到的确切版本是否在漏洞范围内 - 可配置的 NVD API 密钥（提高速率限制）、缓存 TTL、最低 CVE 年份以及 **可自定义的搜索关键词** ### 设备指纹识别与增强 - 从观察到的服务端口与流量行为对设备进行指纹识别 - 推断设备角色：网关、摄像头、IoT、未知等 - **可编辑的角色**——通过“主机”视图中的下拉菜单更正自动识别的角色；覆盖设置将在重启后保持 - 从 Home Assistant `device_tracker` 实体增强设备身份（IP、名称、主机名、MAC 地址） - 将已知具有高/关键 CVE 漏洞的设备标记为“存在风险” ### 安全发现 - 针对高/关键问题提供可操作发现结果，包含严重性、源 IP、类别与发生次数 - 类别：可疑端口、端口扫描、高出站流量、漏洞 - **可关闭的发现结果**——可从 UI 关闭单个发现 - 基于观察行为与遥测缺口生成加固建议 ### 侧边栏仪表板 一个在 HA 侧边栏注册的多视图单页应用： - **概览**——统计摘要、**主动扫描**卡片（最后扫描时间、持续时间、发现主机、扫描间隔）、NetFlow 监听器健康状态、最近告警，以及 **NVD 关键词芯片**（按来源着色：用户配置为紫色，扫描派生为绿色） - **网络地图**——支持缩放与拖放的实时力导向图，展示扫描主机、活跃流量主机、存在风险设备、网关及顶级外部对等节点。筛选开关：全部 / 已扫描 / 仅流量 / 外部 - **主机**——可搜索的设备库存，包含推断角色、扫描结果与通过 tracker 增强的主机名（仅活跃主机） - **发现**——可操作的安全发现结果，带关闭按钮、CVE 详情与修复提示 - **外部 IP**——增强后的外部 IP 表，包含威胁评级、VirusTotal 命中、AbuseIPDB 评分、最后出现时间以及按需查询 - **漏洞**——可排序的漏洞浏览器，列出 **所有缓存的 NVD CVE**（不仅限于网络检测到的），包含 CVSS 评分、严重性、影响服务/技术、发布日期、CISA KEV 标志、网络检测次数，以及 **CVE 详情模态框**（展示完整描述与 CPE 条件）。未匹配任何主机的 CVE 以“未检测”灰色标识显示 - **建议**——基于当前网络状态优先排序的加固建议 仪表板每 30 秒自动刷新一次。网络地图在更新时不会重置物理模拟。 ### 品牌图标 为 HA 集成列表页提供自定义集成图标（含暗色模式变体）。 ## 传感器 | 传感器 | 描述 | |---|---| | 活跃设备 | 观察到的内部设备数量 | | 已扫描设备 | 拥有活跃扫描结果的设备数量 | | 总流量 | 摄入的 NetFlow/IPFIX 记录总数 | | 开放发现 | 可操作（高/关键）发现数量 | | 漏洞数量 | 检测到的 CVE 漏洞数量 | | 可疑来源 | 访问常用滥用端口的设备 | | 高出站来源 | 超出出站数据阈值的设备 | | NVD 关键词 | 缓存中的 NVD 搜索关键词数量（属性：每个关键词的 CVE 数量、来源分类 —— `custom` / `product_map` / `fingerprint` / `banner` —— 与获取时间） | 每个传感器都提供诊断属性，包括设备库存、监听器健康状态、导出器 IP、协议版本、模板计数与丢弃数据报计数。 ## 服务 | 服务 | 描述 | |---|---| | `homesec.trigger_scan` | 立即执行完整的主动网络扫描，无需等待下一次计划间隔 | | `homesec.nvd_refresh` | 清除本地 NVD CVE 缓存并重新获取最新漏洞数据 | ## 安装 1. 将 `custom_components/homesec` 目录复制到 Home Assistant `custom_components/` 文件夹。 2. 重启 Home Assistant。 3. 进入 **设置 → 设备及服务 → 添加集成**，搜索“Home Security Assistant”。 4. 配置绑定主机、UDP 端口、内部网络 CIDR、扫描器设置以及可选的 API 密钥。 5. 将路由器或流量导出器指向 Home Assistant 主机及配置的端口。 设备追踪增强是自动完成的——如果你拥有创建 `device_tracker` 实体的路由器或存在性集成，Home Security Assistant 将使用这些名称、主机名与 MAC 地址。 ## 配置选项 | 选项 | 默认值 | 描述 | |---|---|---| | 绑定主机 | `0.0.0.0` | UDP 监听地址 | | 绑定端口 | `2055` | UDP 监听端口 | | 内部网络 | `192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12` | 逗号分隔的 CIDR 范围 | | 端口扫描检测窗口 | `300` 秒 | 端口扫描启发式的时间窗口 | | 唯一端口阈值（触发扫描告警） | `20` | 触发端口扫描发现的端口数量阈值 | | 高出站阈值 | `50 MB` | 触发高出站告警的每间隔字节数 | | 启用侧边栏面板 | `true` | 注册 Web UI 面板 | | 启用主动扫描器 | `true` | Ping + 端口扫描内部主机 | | 扫描间隔 | `300` 秒 | 两次主动扫描之间的秒数 | | 扫描例外 | （空） | 主动扫描期间跳过的 IP 列表（逗号分隔） | | 扫描端口 | （47 个默认端口） | 要探测的端口或范围（逗号分隔，例如 `22,80,443,8000-9000`） | | 外部 IP 保留时间 | `24` 小时 | 保留外部 IP 的时间（0 表示永久） | | 启用反向 DNS 解析 | `true` | 解析外部 IP 主机名 | | 黑名单 URL | abuse.ch 馈送 | 逗号分隔的威胁情报馈送 URL | | IPInfo 令牌 | （空） | 可选，提升 IP 地理定位配额 | | VirusTotal API 密钥 | （空） | 可选，启用 VirusTotal 查询 | | Shodan API 密钥 | （空） | 可选，启用 Shodan 查询 | | AbuseIPDB API 密钥 | （空） | 可选，启用滥用评分查询 | | 增强缓存 TTL | `300` 分钟 | 增强提供者的缓存时间 | | IPInfo 每日配额 | `1500` | 每日最大 IPInfo 查询次数 | | VirusTotal 每日配额 | `500` | 每日最大 VirusTotal 查询次数 | | Shodan 每日配额 | `1000` | 每日最大 Shodan 查询次数 | | AbuseIPDB 每日配额 | `1000` | 每日最大 AbuseIPDB 查询次数 | | NVD API 密钥 | （空） | 可选，提升 NVD 速率限制至 50 次/30 秒 | | NVD API URL | `services.nvd.nist.gov/…` | NVD REST API 2.0 端点 | | NVD 缓存 TTL | `12` 小时 | 重新获取 CVE 数据前的间隔小时数 | | NVD 最低 CVE 年份 | `2020` | 包含的最早 CVE 年份（0 表示所有年份） | | NVD 搜索关键词 | （16 个默认值） | 用于查询 NVD 的逗号分隔产品名称（例如 OpenSSH、nginx、WordPress） | 所有选项均可在设置后通过集成卡片上的 **配置** 进行修改。更改会自动触发重载。 ## 推荐导出器 - OpenWrt 搭配 `softflowd` - OPNsense / pfSense NetFlow 或 IPFIX 导出 - UniFi 网关流量导出 - MikroTik 流量流 ### 示例：softflowd ``` softflowd -i br-lan -n 192.168.1.10:2055 -v 5 ``` ### 示例：OPNsense / pfSense - 目标主机：Home Assistant IP - 目标端口：`2055` - 版本：`9` 或 `IPFIX` - 接口：LAN 及需要监控的任意 VLAN ## 故障排查 ### 侧边栏面板缺失 1. 确认集成已在 **设置 → 设备及服务** 中加载。 2. 更新组件文件后重启 Home Assistant。 3. 强制刷新浏览器（Ctrl+Shift+R）。 4. 尝试备用 URL：`/api/homesec/panel` 5. 检查侧边栏面板是否在用户配置中被隐藏。 6. 确认集成配置中已启用“启用侧边栏面板”。 ### 未收到流量 - 检查导出器是否将目标指向正确的 IP 与端口。 - 验证防火墙是否允许目标端口的 UDP 流量。 - 若使用 Docker，请确保端口已映射到容器。 ## 实际限制 - 流量分析基于元数据（IP、端口、字节数），而非数据包载荷，无法识别所有协议误用或漏洞利用。 - 设备指纹识别是启发式方法，提供参考信息而非权威判定。 - 主动扫描需要 HA 实例具备访问内部主机的网络权限。 - 外部 IP 增强质量取决于配置的（可选）API 密钥。 - 追踪增强依赖 Home Assistant 中暴露 `device_tracker` 实体的路由器或存在性集成。 ## 持久化存储 Home Security Assistant 将四个纯文本 YAML 文件写入 Home Assistant 配置目录（与 `configuration.yaml` 同级）。它们在集成更新、HA 重启与配置项重载时保留。如果包含 API 密钥，请勿将其纳入版本控制。 ### `homesec.yaml`——集成设置 所有面向用户的配置选项在每次重载时都会镜像至此。启动时文件会被读回并与活动配置项合并，确保通过 HACS 或手动复制更新组件时不会丢失值。仅写入以下键；文件中存在的其他键将被忽略。 | 键 | 描述 | |---|---| | `bind_host` / `bind_port` | UDP 监听地址与端口 | | `internal_networks` | 逗号分隔的内部 CIDR 范围 | | `scan_window_seconds` / `scan_port_threshold` | 端口扫描检测参数 | | `high_egress_threshold` | 高出站告警的字节阈值 | | `enable_webui` | 侧边栏面板是否注册 | | `enable_scanner` / `scan_interval` / `scan_exceptions` / `scan_ports` | 主动扫描器设置 | | `external_ip_retention_hours` | 外部 IP 历史保留时长 | | `enable_dns_resolution` / `blacklist_urls` | DNS 解析与威胁馈送 URL | | `ipinfo_token` / `virustotal_api_key` / `shodan_api_key` / `abuseipdb_api_key` | 外部增强 API 凭证 | | `enrichment_ttl_minutes` | 增强提供者缓存 TTL | | `ipinfo_daily_budget` / `virustotal_daily_budget` / `shodan_daily_budget` / `abuseipdb_daily_budget` | 每个提供者的每日查询配额 | | `nvd_api_key` / `nvd_api_url` / `nvd_ttl_hours` / `nvd_min_year` | NVD CVE 增强设置 | | `nvd_keywords` | 逗号分隔的 NVD 搜索关键词 | **合并行为：** 文件中的值会填充到配置项中不存在或为空的键；UI 中的值始终优先。当两者同时存在时，UI 的值生效。这允许在安装前通过写入文件预设配置。 ### `homesec_roles.yaml`——设备角色覆盖 存储通过“主机”视图下拉菜单手动更正的角色。结构为扁平的 `IP: 角色` 映射。每次角色变更时写入；启动时读取以立即应用所有覆盖，无需等待新的扫描周期。 可用角色与指纹词汇匹配：`gateway`、`camera`、`iot`、`desktop`、`server`、`mobile`、`unknown`。 ### `homesecs.yaml`——已发现主机 每次主动扫描周期结束后写入，并在启动时重新加载。确保“主机”视图与网络地图在重启后立即填充，无需等待首次完整扫描。每个键为一个 IP 地址，值为包含扫描结果的字典（`alive`、`open_ports`、`os_guess`、`ping_ms` 等）。 此文件由系统自动管理——不建议手动编辑，否则会在下次扫描后被覆盖。 ### `homesec_dismissed.yaml`——已关闭的发现 每次通过“发现”视图关闭一个发现时写入；启动时读取以使关闭状态在重启与组件更新后保留。结构为一个扁平的 YAML 列表，包含发现键字符串。可手动从文件中移除某个键以恢复已关闭的发现——它将在下次协调器刷新后重新出现。 这些文件在首次运行集成时由 Home Assistant 实例在运行时创建，不会出现在此开发工作区中。它们会被写入 `hass.config.config_dir`，即你的 HA 配置所在目录（包含 `configuration.yaml` 的目录）。 典型路径取决于安装类型： HA 安装类型 配置目录 Home Assistant OS / 托管 /config/ Home Assistant 容器（Docker） 映射到 /config 的卷 Home Assistant Core（虚拟环境） ~/.homeassistant/ 因此文件将位于： /config/homesec.yaml /config/homesec_roles.yaml /config/homesec_hosts.yaml /config/homesec_dismissed.yaml 它们会在以下时刻创建： homesec.yaml——集成首次加载后 homesec_roles.yaml——首次保存角色覆盖时 homesec_hosts.yaml——首次主动扫描周期完成后 homesec_dismissed.yaml——首次在“发现”视图中关闭告警时 ## 常见问题 ### 为什么 CISA KEV 匹配数量看起来很少？ 漏洞浏览器仅显示与网络上实际检测到的服务相关的 CVE。CISA 已知被利用漏洞（KEV）目录包含约 1,100 个 CVE，涵盖数百种产品（Microsoft Windows、Adobe、Cisco、Apple 等），但 NVD 缓存仅包含运行在主机上的服务（例如 OpenSSH、nginx、PostgreSQL）的 CVE。KEV 匹配数量反映的是这两组数据的实际重叠，对于家庭网络通常较小（个位数到十位数）。 这是预期行为而非缺陷：低 KEV 匹配数量意味着 CISA 目录中活跃利用的漏洞与网络上发现的软件版本之间重叠很少。 ## 开发 语法检查： ``` python3 -m compileall custom_components/homesec ```

标签：ASP.NET, Caddy, CMS 识别, DNS 黑名单, Drupal, Elasticsearch, GitLab, GNU通用公共许可证, Grafana, HAProxy, Home Assistant 集成, HTTP 指纹识别, IIS, IPFIX, Jenkins, Joomla, Magento, NetFlow, Nextcloud, Node.js, OpenVAS, PHP, phpMyAdmin, Pi-hole, pip 包, Synology DSM, Talos规则, Tomcat, UniFi, Varnish, WhatWeb, WooCommerce, WordPress, 主动扫描, 人体姿态估计, 可疑模式识别, 外联检测, 多视图仪表板, 威胁情报, 安全可视化, 安全研究社区, 家庭网络防护, 开发者工具, 异常流量检测, 数据统计, 物联网安全, 端口扫描, 端口扫描检测, 网络流量分析, 逆向工具