ITP258Team5/PHALANX

# 项目 Phalanx **家庭网络守护者** — 一款基于 Raspberry Pi 4 的设备，可拦截广告与追踪器、监控网络流量，并通过简洁的 Web 仪表盘向非技术用户发出可疑活动告警。 ## 工作原理 Phalanx 以 DNS 代理方式运行。您指向它的设备会将 DNS 查询通过该 Pi。已知广告/追踪器/恶意域名会被拦截（返回 NXDOMAIN），其余请求转发至 Cloudflare/Google DNS。仪表盘展示当前连接设备、被拦截流量并标记异常。 ## 项目结构 ``` phalanx/ ├── run.sh # Full setup (base + app, interactive) ├── config.env.example # Network config template ├── .gitignore │ ├── base/ # Layer 1: OS hardening │ └── install.sh # Admin user, firewall, SSH, static IP │ └── app/ # Layer 2: Phalanx application ├── main.py # Entry point / orchestrator ├── requirements.txt # Python deps (aiohttp, psutil) ├── config/ │ └── defaults.py # All tunables ├── core/ │ ├── database.py # SQLite schema, versioned migrations │ ├── dns_proxy.py # Async UDP DNS proxy + LRU cache │ ├── blocklist.py # List download/parse, subscription gating │ ├── monitor.py # Per-device traffic + anomaly detection │ ├── subscription.py # Auth + subscription lifecycle │ └── access_control.py# Role-based DB access (reader/writer/admin) ├── api/ │ └── server.py # REST API + embedded fallback dashboard ├── gui/ │ └── phalanx-gui.jsx # React dashboard (design prototype) ├── scripts/ │ ├── install.sh # App installer (safe DNS switchover) │ └── phalanx.service # systemd unit └── tests/ ├── test_dns_proxy.py # 61 tests: DNS parsing, blocking, cache └── test_v2_schema.py # 37 tests: triggers, views, access control ``` ## 快速测试流程 ### 所需设备 - Raspberry Pi 4（4GB） - MicroSD 卡（16GB 或更大） - 一台同网络的独立 PC/Mac 用于测试 ### 步骤 1 — 刷写 Pi OS 下载 [Raspberry Pi OS Lite](https://www.raspberrypi.com/software/)（64 位）。使用 Raspberry Pi Imager 刷入 SD 卡，并在 Imager 设置中启用 SSH、设置密码以便无头连接。 启动 Pi，找到其 IP（可查看路由器 DHCP 租约或运行 `ping raspberrypi.local`）。 ### 步骤 2 — 拷贝项目到 Pi 在您的 PC 上执行： ``` scp -r phalanx/ pi@:~/ ssh pi@ ``` ### 步骤 3 — 基础系统设置（可选但推荐） ``` cd ~/phalanx sudo bash base/install.sh ``` 此步骤会创建安全的管理员用户、配置静态 IP、设置防火墙并加固 SSH。跟随提示完成设置，并记下分配的静态 IP —— 后续步骤均需使用该地址。 若想跳过快速测试，也可直接使用 Pi 当前的 DHCP IP。 ### 步骤 4 — 安装 Phalanx ``` sudo bash app/scripts/install.sh ``` 此步骤会安装依赖、部署应用、启动服务、等待 API 响应、下载黑名单（约 20 万域名），并在确认一切正常后将 Pi 的 DNS 指向本地。如遇失败会自动回滚。 安装成功后，您应看到： ``` ✅ Phalanx Installed and Running! Dashboard: http:// Blocklist: XXXXX domains blocked ``` ### 步骤 5 — 从测试 PC 验证 **不要修改路由器的 DNS 设置。** 请仅将测试 PC 的 DNS 指向该 Pi，以避免影响其他设备。 **macOS：** ``` # 将 DNS 设置为 Pi sudo networksetup -setdnsservers Wi-Fi # 测试完成后重置为自动 sudo networksetup -setdnsservers Wi-Fi empty ``` **Windows（PowerShell 需以管理员运行）：** ``` # 将 DNS 设置为 Pi Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ServerAddresses # 测试完成后重置为自动 Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ResetServerAddresses ``` **Linux：** ``` # 临时（重启后重置） sudo resolvectl dns wlan0 # 重置 sudo resolvectl revert wlan0 ``` ### 步骤 6 — 测试拦截功能 在已将 DNS 指向 Pi 的测试 PC 上： ``` # 这应该 RESOLVE（合法站点） nslookup google.com # 预期：返回类似 142.250.x.x 的 IP # 这应该被 BLOCKED（广告域名） nslookup ads.doubleclick.net # 预期：NXDOMAIN 或 SERVFAIL（不返回 IP） # 这应该被 BLOCKED（追踪器） nslookup tracking.example.com # 预期：NXDOMAIN # 这应该 RESOLVE（不在黑名单中） nslookup github.com # 预期：返回一个 IP ``` ### 步骤 7 — 查看仪表盘 在浏览器中打开 `http://`，您应看到： - 显示测试 PC 的设备计数 - 随浏览增加而上升的被拦截域名计数 - 实时更新的 DNS 查询统计 - 列表中的测试 PC（“已连接设备”） ### 步骤 8 — 恢复测试完成后的设置 将测试 PC 的 DNS 恢复为自动（使用前述对应命令）。Pi 仍在运行，您可随时重新指向其 DNS 以继续使用。 ## API 端点 | 方法 | 路径 | 描述 | |------|------|------| | `POST` | `/api/auth/login` | 登录（邮箱 + 密码） | | `POST` | `/api/auth/logout` | 登出 | | `GET` | `/api/auth/status` | 认证与订阅状态 | | `GET` | `/api/dashboard` | 完整仪表盘摘要 | | `GET` | `/api/devices` | 所有已发现设备 | | `POST` | `/api/devices/rename` | 重命名设备 `{ip, name}` | | `GET` | `/api/alerts` | 近期告警（`?include_low=true&limit=50`） | | `GET` | `/api/alerts/grouped` | 按组聚合的告警 | | `GET` | `/api/blocklist` | 黑名单统计与过期状态 | | `POST` | `/api/blocklist/whitelist` | 将域名加入白名单 `{domain}` | | `DELETE` | `/api/blocklist/whitelist` | 从白名单移除 `{domain}` | | `POST` | `/api/blocklist/blacklist` | 强制将域名加入黑名单 `{domain}` | | `GET` | `/api/diagnostics` | 系统内存、CPU、DNS 代理统计 | ## 测试套件 ``` cd ~/phalanx/app # DNS 代理逻辑（解析、阻止、缓存、匹配） python3 tests/test_dns_proxy.py # 61 tests # 架构、触发器、视图、访问控制 python3 tests/test_v2_schema.py # 37 tests ``` ## 已完成事项 - [x] DNS 代理引擎（异步 UDP、LRU 缓存、父域匹配） - [x] 黑名单管理器（hosts 与域名列表解析、订阅限制、冻结机制） - [x] 流量监控（批处理统计、行为基线、异常检测、告警抑制） - [x] 订阅管理器（ACTIVE → GRACE → LAPSED 生命周期） - [x] SQLite 模式 v2 与版本化迁移 - [x] 数据库触发器（自动记录 last_seen、拦截时告警、每小时汇总、异常转告警） - [x] 只读视图与基于角色的访问控制（reader/writer/admin） - [x] 登录审计日志 - [x] 完整 REST API - [x] 内嵌 HTML 仪表盘（实时、自动刷新） - [x] React GUI 原型（登录、仪表盘、设备、告警、黑名单管理） - [x] 基础系统加固（管理员用户、防火墙、SSH 限制、静态 IP） - [x] 安全安装器（失败时自动回滚 DNS） - [x] 带内存限制与安全加固的 systemd 服务 - [x] 98 个通过测试 ## 待办事项 - [ ] 将 React GUI 构建到 `gui/dist/`（需要打包管线；当前回退 HTML 已可用） - [ ] 订阅云端 API 后端（认证端点为占位 URL） - [ ] 设备自动发现（mDNS、DHCP 租约解析、MAC 厂商查询） - [ ] 将白名单/黑名单持久化到 `user_overrides` 表（当前为内存存储） - [ ] 同步黑名单源至 `blocklist_entries` 表以支持“为何被拦截”查询 - [ ] 支持从仪表盘直接屏蔽设备（丢弃被屏蔽设备的 DNS 请求） - [ ] 仪表盘启用 HTTPS（首次启动时生成自签名证书） - [ ] 首次启动设置向导 - [ ] OTA 更新机制 ## 常见问题与解决 | 问题 | 原因 | 解决方法 | |------|------|----------| | `nslookup` 仍解析被拦截域名 | 测试 PC DNS 未指向 Pi | 按对应系统的 DNS 设置命令重新配置 | | 仪表盘无法加载 | 服务未运行 | 执行 `sudo systemctl status phalanx` 并检查日志 | | 黑名单为空 | 初始下载失败 | 执行 `sudo systemctl restart phalanx`（需联网） | | 53 端口权限不足 | 未以 root 运行 | 服务通过 systemd 以 root 运行；手动运行需使用 `sudo` | | 安装后 Pi 断网 | Phalanx 切换 DNS 后崩溃 | 执行 `sudo cp /etc/resolv.conf.bak.phalanx /etc/resolv.conf` | | SSH 登录失败（基础安装后） | SSH 密钥粘贴出错 | 将 SD 卡挂载到其他机器，修复 `/etc/ssh/sshd_config` | ## Git ``` cd phalanx git init git add . git commit -m "Phalanx v0.5 — DNS proxy, traffic monitor, dashboard, access control - Async UDP DNS proxy with LRU cache and parent-domain matching - Blocklist engine with subscription gating and freeze-on-lapse - Per-device traffic monitoring with behavioral anomaly detection - SQLite v2 schema: triggers, hourly rollups, role-based access control - REST API with embedded dashboard + React GUI prototype - OS hardening layer (firewall, SSH, static IP) - Safe installer with automatic DNS rollback - 98 passing tests" git remote add origin https://github.com//phalanx.git git branch -M main git push -u origin main ```

标签：aiohttp, Cloudflare DNS, DNS代理, DNS查询日志, ETW劫持, Google DNS, HTTP查询日志, LRU缓存, NXDOMAIN, OS硬化, PB级数据处理, Pi 4, psutil, Python, Raspberry Pi, REST API, SQLite数据库, SSH安全, systemd, Web仪表盘, 互联网扫描, 内存执行, 内核监控, 前端React, 可视化仪表盘, 告警通知, 安全运维, 家庭网关, 家庭网络安全, 嵌入式安全, 广告拦截, 异常检测, 异步代理, 恶意域名阻断, 无后门, 日志记录, 流量监测, 版本迁移, 简单界面, 管理员界面, 系统服务, 网络分流, 网络安全, 网络安全, 网络流量分析, 角色访问控制, 订阅分级阻断列表, 读写权限, 追踪拦截, 逆向工具, 防火墙, 隐私保护, 隐私保护, 静态IP, 非技术用户