SysAdminDoc/HostsGuard

# HostsGuard      ## 截图 实时的 DNS 活动流，带有精选的域名用途标注、每个根域的 24 小时迷你图以及 `field:value` 搜索 DSL —— 包含深色和浅色主题：   ## 架构 HostsGuard 是一款基于 .NET 10 (LTS) 构建的**信任分离的双进程**应用程序： ``` ┌───────────────────────────────┐ gRPC over Named Pipe ┌────────────────────────────────────┐ │ HostsGuard.App (WPF) │ (ACL'd pipe, per-session │ HostsGuard.Service (LocalSystem) │ │ UNELEVATED desktop UI │◄────token authentication)───────►│ Windows Service — owns ALL │ │ tray · dashboards · prompts │ unary + server-streaming │ privileged mutation │ └───────────────────────────────┘ │ · hosts file (transactional) │ │ · Windows Firewall COM rules │ ┌───────────────────────────────┐ same contract │ · ETW DNS / IPHLPAPI connections │ │ HostsGuard.Cli │─────────────────────────────────►│ · tamper watch · scheduler │ │ block/allow/status/export… │ │ · SQLite (ProgramData) │ └───────────────────────────────┘ └────────────────────────────────────┘ ``` 提权逻辑驻留在一个随操作系统启动的 LocalSystem 服务中，因此 UI **无需 UAC**，所有修改操作都是集中且可审计的，防篡改自愈功能即使在无人登录时也会运行，并且每次 OS 调用都是类型化的 Windows API（Firewall COM、ETW、IPHLPAPI），而不是解析子进程。 ## 安装 1. 从 [Releases](https://github.com/SysAdminDoc/HostsGuard/releases) 下载 `HostsGuard-vX.Y.Z-dotnet-Setup.exe`。 2. 运行它（安装程序会提权一次以注册 `HostsGuardSvc` 服务；应用程序本身以非提权状态运行）。 3. 从开始菜单或托盘启动 **HostsGuard**。 **系统要求：** Windows 10/11，x64。该服务依赖于 Windows 防火墙服务（MpsSvc）。卸载时会停止服务，恢复默认的防火墙姿态，并移除所有 `HG_` 规则。 ### 从 Python 构建版本 (v3.x) 迁移 `HostsGuard.Migrator.exe` 会将 Python 时代的配置文件进行一次性导入 —— 包括 `hostsguard.db`（域名、订阅源、事件日志、配置文件、防火墙状态）、`config.json`（计划任务、允许列表、DoH 状态、学习信任集）和 `doh_resolvers.json` —— 并转换至新 schema。`HG_` 防火墙规则会通过 COM 实时重新发现并自动延续。迁移是幂等的，并支持 `--dry-run`。 最终的 Python 构建版本 (v3.17.0) 保留在 [`python-eol`](https://github.com/SysAdminDoc/HostsGuard/releases/tag/python-eol) 标签中。 ## 功能 ### 授权提示（连接前询问） | 功能 | 描述 | |---------|-------------| | 过滤模式 | **Normal**（静默拦截）、**Notify**（针对新的出站连接弹出提示）、**Learning**（自动允许并记录）—— 可从托盘切换 | | 授权窗口 | 在拦截出站尝试时置顶显示提示，包含进程路径、签名者、解析出的主机名、GeoIP 国家、威胁情报判定以及域名用途 | | 作用域 + 持续时间 | 按程序、远程 IP 或端口进行允许/拦截 —— 可永久生效或在限定时间窗口内生效 | | 已知安全基线 | 操作系统核心二进制文件（Windows Update、Defender、内核、LSA）会被自动允许，从而使提示聚焦于值得关注的流量 | | 绑定身份的规则 | 规则会记录二进制文件的 SHA-256 和签名者；位于白名单路径下的重命名冒充程序会再次触发提示，而移动到新版本目录的自动更新程序会被识别为同一个应用 | | 信任的发布者 / 文件夹 | 自动允许由受信任的 Authenticode 发布者签名的未来软件，或受信任安装文件夹下的任何二进制文件 —— 可在提示中开启 | | 入站授权 | 可选择对无规则的**入站**连接也进行提示，从而生成限定作用域的入站规则（默认关闭，以避免未请求入站带来的干扰） | | 决策历史 | 每一项授权决策都会被记录并可供审查 | | 姿态护栏 | 启用 Notify/Learning 会针对每个配置文件设置默认的出站 Block；切回 Normal 或停止服务时会恢复之前的姿态 | | 辅助功能 | 提供完整的 AutomationProperties 覆盖、明确的 Tab 顺序、实时区域的威胁横幅、键盘/屏幕阅读器焦点管理 | ### 主机活动 | 功能 | 描述 | |---------|-------------| | 实时 DNS 流 | ETW `Microsoft-Windows-DNS-Client` 事件会在域名解析时将其展示出来 —— 无需轮询 | | 域名拦截 | 通过 hosts 文件（`0.0.0.0` 条目）拦截单个域名或整个根域 | | 域名用途 | 在数据流和提示中内联展示精选的离线域名→用途注释（“Microsoft 遥测”、“Akamai CDN”、“Google Analytics”） | | 24 小时迷你图 | 按根域渲染的每小时命中汇总内联活动迷你图 | | 临时允许 | 允许某个域名 15 分钟 / 1 小时 / 8 小时，到期后自动恢复为拦截状态 | | 隐藏 / 隐藏根域 | 在活动流中隐藏域名，重启后依然保持生效 | | 高级搜索 | `field:value`、`!term` 和 `field!=value` 过滤器，适用于所有表格 | | 研究链接 | 右键点击任何域名即可打开 Google、VirusTotal、who.is 等链接 | ### 防火墙活动 | 功能 | 描述 | |---------|-------------| | 实时连接 | 通过 IPHLPAPI 扩展表实现实时出站 TCP/UDP 视图（带 PID 属性，无需提权） | | 按应用分组 + 搜索 | 使用 `field:value` 搜索 DSL（`port:443 country!=US`，`fw:threat`）进行可折叠的按进程分组 | | 服务归属 | 由 svchost 托管的连接会显示负责的 Windows 服务（通过 SCM 枚举） | | 拦截连接监视 | 安全事件日志 5157/5152 检测反馈给授权代理 | | 状态叠加 | 每个连接都会显示被 hosts/防火墙/威胁拦截的状态，对于没有预先进行 DNS 查询的原始 IP 拨号，还会显示 **DIRECT-IP** | | 快速拦截 | 拦截任何远程 IP 或程序，或者将程序的作用域限制在 Internet / LAN / localhost / inbound | | GeoIP + 威胁情报 | 离线 MMDB 国家/ASN 解析，外加 URLhaus/Feodo 已知恶意覆盖层 | | 连接历史 | 保留期限受限的过去连接的可搜索日志（默认为 30 天） | | 每个应用的带宽 | 通过 ETW 内核字节计数器显示排名前 5 的进程带宽时间线 | | 解释 / 查询连接 | 右键点击连接进行查询 —— 在解析出的域名上查询 VirusTotal、who.is、Google；在 IP 上查询 AbuseIPDB | | 学习审查 | 批量提升、撤销或丢弃 Learning 模式下的自动决策 | ### Hosts 文件 | 功能 | 描述 | |---------|-------------| | 托管域名 | 基于数据库的域名管理，包含状态、来源、命中跟踪和规范原因 | | 原始编辑器 | 直接编辑 `drivers\etc\hosts`，提供清理并保存（去重、验证、规范化）功能 | | 备份 / 还原 | 带时间戳的备份，支持一键还原和紧急重置为 Windows 默认设置 | | 拦截列表导入 | 12+ 种精选社区拦截列表（HaGezi、StevenBlack、OISD、URLhaus 等），合并时允许列表优先 | | 允许列表订阅 | 白名单远程允许列表中的域名，且优先级高于拦截列表 | | 拦截服务 | 一键切换以拦截 YouTube、TikTok、Facebook、Discord、Netflix 等 | | 遥测预设 | 一键拦截约 28 个 Microsoft 遥测 endpoint，可作为一个整体撤销 | | 篡改监视 | SHA-512 完整性跟踪可区分 HostsGuard 的写入与外部写入；可选自动还原 | ### 防火墙规则 | 功能 | 描述 | |---------|-------------| | 完整规则查看器 | 显示所有 Windows 防火墙规则，包含名称、方向、操作、协议、地址和程序 | | `HG_` 前缀跟踪 | 可识别并批量管理 HostsGuard 创建的规则 | | 安全规则保护 | 可选的篡改保护：如果任何 `HG_` 规则在后台被删除或禁用，服务会重新创建或重新启用它（仅限 HostsGuard 自己的规则 —— 绝不会触碰您的其他配置） | | 孤立检测 + 重新绑定 | 标记其可执行文件已移动的程序规则，并在重新绑定前通过预览建议签名身份匹配项 | | 规则组 | 将 `HG_` 规则分配给一个命名组，并原子地开启/关闭整个组；组设置可通过可移植策略进行往返同步 | | 规则编写 | 具有方向、操作、协议、地址和程序的自定义规则 —— 使用 COM API，无需 PowerShell 拨号 | ### 工具 | 功能 | 描述 | |---------|-------------| | DNS 绕过防御 | 拦截 QUIC/UDP-443，拦截已知的 DoH 引导解析器，以及 DoT/DoQ 端口 853（您自己的解析器除外），从而防止应用程序通过隧道绕过 hosts 拦截 | | CNAME 伪装防护 | 可选的响应式拦截，针对通过 CNAME 解析到被拦截追踪器的第一方主机 | | DNS 解析器切换器 | 一键切换至 Cloudflare、Google、Quad9、AdGuard DNS 或 NextDNS 并刷新 DNS | | DoH 情报 | 可刷新的、经过 SHA-256 验证的 DoH 解析器列表，与 Windows 已知服务器合并 | | 计划拦截 | 在每周重复的计划上拦截域名、服务或**防火墙规则**（`fw:` 目标）（时间窗口可跨越午夜） | | 网络配置文件 | 保存/切换命名的规则集，并根据加入网络的指纹（网关 MAC）实现**自动切换** | | 设置锁定 | 使用可选的定时解锁功能，通过密码锁定模式/姿态/规则更改；一键开启 hosts 文件写保护 | | 全局出站 | 托盘提供 Block-all / Allow-all 出站姿态选择器（无需重启） | | VPN kill-switch | 监视选定的 VPN 适配器；每当它断开时，在每个配置文件上强制执行默认的出站 Block，确保没有任何内容泄漏到隧道之外，重新连接时恢复（需主动开启） | | Loopback API | 可选（`HG_LOOPBACK_API=1`）的 token 认证 `127.0.0.1` JSON-RPC/OpenAPI 接口 | | 事件 webhooks | 可选的引擎事件签名 HTTP(S) POST（`X-HG-Signature` HMAC-SHA256，限定重试次数），通过 loopback API 配置 | | Defender 排除助手 | 处理拦截 Microsoft 遥测时出现的 `HostsFileHijack` 误报 | | 支持包 | 脱敏的诊断 zip —— 包含配置、数据库完整性、日志、事件历史、防火墙摘要（不含 token、webhooks、私有域名或远程 IP） | | 事件分类 | 结构化、可过滤的事件日志，记录每一次拦截、允许、防火墙和策略操作 | ### CLI ``` HostsGuard.Cli status HostsGuard.Cli block [reason] HostsGuard.Cli allow [reason] HostsGuard.Cli unblock HostsGuard.Cli export [path.json] HostsGuard.Cli mode [normal|notify|learning] HostsGuard.Cli release-smoke ``` CLI 通过与应用相同的已验证管道契约与服务进行通信，因此它也可以在非提权状态下运行。 ## 数据位置 | 路径 | 用途 | |------|---------| | `%ProgramData%\HostsGuard\` | 策略状态：`hostsguard.db` (SQLite WAL)、授权状态、DoH 情报 —— 通过 DACL 锁定为仅 SYSTEM+Admins 可访问 | | `%APPDATA%\HostsGuard\` | 每用户的 UI 设置（`config.json`：主题、UI 缩放）和日志 | ## 从源码构建 ``` git clone https://github.com/SysAdminDoc/HostsGuard.git cd HostsGuard dotnet build HostsGuard.sln # requires .NET 10 SDK dotnet test HostsGuard.sln # 774 tests, no elevation needed build\publish.ps1 # single-file self-contained win-x64 -> dist\dotnet\ winget install --id JRSoftware.InnoSetup -e & "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer-dotnet.iss # 生成 installer_output/HostsGuard-v0.12.0-dotnet-Setup.exe ``` 解决方案布局：`HostsGuard.Core`（纯领域，无 OS 依赖）、`HostsGuard.Contracts`（gRPC protos）、`HostsGuard.Windows`（Firewall COM / ETW / IPHLPAPI / ACL 互操作）、`HostsGuard.Service`（提权引擎）、`HostsGuard.App`（WPF UI）、`HostsGuard.Cli`、`HostsGuard.Migrator`，以及位于 `tests/` 下的各项目测试套件。 ## 安全 .NET 引擎锁定了其运行时和依赖姿态： - **运行时维护基准：** 该解决方案目标为 **.NET 10 (LTS，支持至 8 年 11 月)**，并且构建会解析最新的维护补丁 （`TargetLatestRuntimePatch`），因此自包含的工件会捆绑当前的 运行时。 - **依赖项 CVE：** `dotnet list package --vulnerable --include-transitive` 保持整洁无异常。原生 SQLite 捆绑包被锁定为 `SQLitePCLRaw.bundle_e_sqlite3` 3.0.3，以清除 GHSA-2m69-gcr7-jv3q (CVE-2025-6965)；Google.Protobuf ≥ 3.35 包含了递归深度的修复；.NET 10 SDK 裁剪了框架提供的 传递依赖，淘汰了旧有的仅用于测试的 4.3.0 基准版本。 - **提权表面：** LocalSystem 服务的数据目录 （`%ProgramData%\HostsGuard`）在任何状态文件被写入之前， 已通过 DACL 锁定为仅 SYSTEM+Admins 可访问；客户端的 blocklist URL 在服务获取它们之前， 会经过 SSRF 防护（拒绝 loopback/RFC1918/链路本地/CGNAT/ULA/元数据）； gRPC 控制管道经过 ACL 保护，并使用基于会话的 token 进行了身份验证。 请通过 GitHub issue 提交漏洞报告，并附带脱敏后的支持包 （工具 → **导出支持包**）。 ## 常见问题 / 故障排除 **问：应用程序需要管理员权限吗？** 不需要。UI 和 CLI 在非提权状态下运行；所有特权工作都在安装程序注册的 `HostsGuardSvc` LocalSystem 服务中完成（安装过程本身会提权一次）。 **问：我拦截了一个域名，但它仍然可以解析** 刷新 DNS 缓存（工具选项卡）或等待缓存过期。某些应用程序维护着独立于 OS 的自己的 DNS 缓存 —— DNS 绕过防御（QUIC 拦截、DoH blocklist）封堵了常见的隧道。 **问：我该如何撤销所有操作？** Hosts 文件选项卡 → **还原** 会恢复最近的备份；**紧急重置** 将 hosts 文件重写为 Windows 默认设置；防火墙规则选项卡 → **删除 HG 规则** 会移除所有由 HostsGuard 创建的防火墙规则。卸载操作会自动执行所有这些操作，并恢复您之前的防火墙姿态。 **问：Windows Defender 将 hosts 文件标记为威胁** 拦截 Microsoft 遥测域名会导致 Defender 报告 `SettingsModifier:Win32/HostsFileHijack`。这是一个误报 —— HostsGuard 是有意修改 hosts 文件的。请为 `C:\Windows\System32\drivers\etc\hosts` 添加一个排除项；HostsGuard 在导入会触发此情况的列表之前会发出警告。 **问：Python 版本怎么了？** HostsGuard v3.x 曾是一个 Python/PySide6 应用程序。它已被停用，转而采用这款 .NET 10 重写版本，后者移除了 PowerShell 子进程调用（改为类型化的 Windows API）、仅运行时的错误呈现（编译的核心）以及 127 MB 的 PyInstaller 捆绑包（改为小型自包含二进制文件 + 真正的 Windows 服务）。最终的 Python 构建版本保留在 `python-eol` 标签中，且 `HostsGuard.Migrator` 可导入 v3.x 的配置文件。 ## 许可证 MIT 许可证 —— 详情请参阅 [LICENSE](LICENSE)。 ## 贡献 欢迎提交 issue 和 PR。如果报告 bug，请附上脱敏后的支持包（工具 → **导出支持包**）。

标签：DNS监控, Python工具, 桌面应用, 系统运维, 网络隐私管理, 防火墙管理