MursheenDurkin/SafeHaven-PI

# SafeHaven Pi  SafeHaven Pi 是一款基于树莓派 5 打造的便携式开源网络安全设备。只需将其插入电源，让任何设备连接到它的热点，你的网络流量在进入广袤的互联网之前就会被自动加密、过滤和监控——无需下载任何应用程序，无需订阅，也无需信任第三方。它专为旅行者、记者、会议组织者以及任何宁愿随身携带自己的可信网络也不愿依赖酒店网络的人而设计。 它同时运行八个集成的安全层——从 WiFi 热点本身，一直往上涵盖防火墙、VPN 隧道、DNS 过滤、入侵检测、暴力破解防护和 SSH 蜜罐——此外还配备了独立的 Tailscale 通道用于远程管理。整个技术栈被封装在一个单一的命令行界面和一个实时 Web 仪表盘中。四种操作模式涵盖了从日常公共 WiFi 使用到最大匿名性的 Tor 路由等不同场景。 本版本为 **v1.0-alpha**，是提交给 2026 年 5 月一场大学黑客马拉松的版本——也是该项目持续迭代的基石。 ## 快速入门 如果你有一台带有 USB WiFi 适配器的树莓派 4 或 5，只需三条命令即可完成安装： ``` # 1. Clone repository git clone https://github.com/MursheenDurkin/SafeHaven-PI.git cd SafeHaven-PI # 2. 运行 installer（仅一次 — 拉取所有 dependencies） sudo bash install.sh # 3. 启动 control menu sudo bash safehaven.sh ``` 完成。你的树莓派现在正在广播一个加密热点。 ### 首次运行 —— 设置向导 首次启动时，在菜单中按下 **`w`** 即可打开设置向导。它会引导你完成四个步骤，确保树莓派不会以默认配置运行： 1. **热点名称和密码** —— 供其他设备搜索并连接的 WiFi 2. **树莓派主机名** —— 更改广为人知的 `raspberrypi` 默认主机名 3. **管理员密码** —— 替换树莓派的默认密码 4. **WireGuard VPN 密钥** —— 生成专属于你的树莓派的新密钥对 ## 呈现效果 ### 启动序列 每一个安全层逐一启动。你可以在菜单加载前观看每个服务上线的过程。  ### 控制菜单 一切就绪后，控制菜单随即加载。系统实时状态、当前模式、最新检测到的威胁、CPU 和 RAM 占用情况一目了然。  ### 激活模式 按下数字键即可切换安全配置文件。每种模式会按顺序启动其对应的防护层，并在准备就绪时给出确认。  ### 实时安全日志 按下 **`5`** 打开日志查看器，实时查看威胁检测、被拦截的 DNS 查询、被封禁的 IP 或蜜罐连接。  ## 防护原理 SafeHaven Pi 在你连接的瞬间即可同时运行八个安全层： | 层级 | 服务 | 功能 | |-------|---------|--------------| | 1 | **hostapd** | 创建 WPA2 加密的 WiFi 热点 | | 2 | **dnsmasq** | DHCP 服务器 —— 为已连接的设备分配隧道 IP | | 3 | **nftables** | 防火墙与 NAT —— 控制并路由所有流量 | | 4 | **WireGuard** | VPN 隧道 —— 加密你的设备与树莓派之间的所有通信 | | 5 | **Pi-hole** | DNS 过滤器 —— 拦截广告、追踪器和已知的恶意域名 | | 6 | **Suricata** | 入侵检测 —— 约 48,000 个威胁特征库 | | 7 | **Fail2ban** | 暴力破解防护 —— 自动封禁反复攻击者 | | 8 | **Cowrie** | SSH 蜜罐 —— 在 2222 端口诱捕攻击者并记录每一次按键操作 | 此外还通过 **Tailscale** 实现安全的远程管理，而无需将树莓派暴露在公共互联网上。 ## 操作模式 四种配置文件可让你根据实际场景调整树莓派的行为： ### 模式 1 —— 旅行者模式 日常公共 WiFi 防护。通过 WireGuard 加密所有流量，通过 Pi-hole 过滤 DNS，并使用 Suricata 监控入侵行为。连接即受保护。适用于酒店、咖啡馆、机场和大学 WiFi 的默认模式。 ### 模式 2 —— 活动家 / 记者模式 隐私优先配置。在 WireGuard 之上（或替代其）添加 Tor 透明代理，启用零日志 DNS，并在激活时清除流量日志。激活时提供两个子选项： - **仅 Tor** —— 最高匿名性，禁用 WireGuard - **Tor over WireGuard** —— 双重防护，默认选项 适用于对信源保护要求极高的场景。 ### 模式 3 —— 商务模式 专为会议、共享办公室或临时工作区打造的安全临时网络。新增功能： - 位于 `/portal` 的 ** captive portal **，每位用户需通过自己的凭证进行身份验证 - **登录后状态页面**，显示连接详情和流量信息 - 位于 `/admin/users` 的 **管理后台**，用于创建用户、踢出在线会话并查看汇总统计信息 - **模式感知身份验证** —— 管理员凭证与终端用户凭证相互隔离 ### 模式 4 —— 宽松模式 除禁用 WireGuard 外的完整安全堆栈。Pi-hole、防火墙、Suricata、Fail2ban 和 Cowrie 均保持活跃。适用于当网站检测并屏蔽已知 VPN IP 段（例如某些银行、流媒体服务、受 Cloudflare 保护的页面），但你仍需要其余防护措施的场景。 ## 管理 VPN 设备 在主菜单中按下 **`[6] Manage VPN Devices`** 以打开设备管理器。你可以在此进行以下操作： | 选项 | 功能 | |--------|--------------| | **`[a]` Add a Device** | 生成全新的 WireGuard 密钥对，分配下一个可用 IP，并显示一次性二维码。从 WireGuard 移动端应用程序扫描即可连接。树莓派不会存储设备的私钥——一旦你关闭二维码，它就会消失。 | | **`[l]` List Devices** | 显示所有受追踪的设备、分配的 IP、最后一次连接的时间、当前连接的端点，以及其通过隧道传输的数据量。 | | **`[e]` Edit Device Name** | 重命名受追踪的设备以便于管理。不会触及 WireGuard 配置。 | | **`[r]` Remove a Device** | 原子性地撤销某个节点的访问权限——将其从运行中的接口移除，持久化更改，并清理元数据。用户手机上已扫描的现有配置将立即失效。 | 每台设备的元数据（名称、公钥、IP、时间戳）存储在 `/etc/safehaven/wg-devices.json` 中。私钥绝不会被写入磁盘。 ## Web 仪表盘 任何连接到 SafeHaven 热点的设备均可通过访问 **`https://10.42.0.1:5000`** 来打开实时监控仪表盘。该证书是自签名的——你的浏览器会警告一次，随后便会记住。 主视图显示： - 今日拦截的威胁（来自 Suricata 的实时数据） - 被 Pi-hole 拦截的 DNS 查询 - 已连接的客户端 - VPN 运行时间及活跃节点数 - CPU / RAM 仪表 - 网络速度图表 - 过去 24 小时内每小时的威胁数量图表 在**单用户模式**（旅行者 / 活动家 / 宽松模式）下，仪表盘无需身份验证即可加载——热点上的任何人都被默认为管理员。 在**商务模式**下，仪表盘由 `/login` 的管理员登录界面把关，而终端用户则改为在 captive portal `/portal` 处进行身份验证。 ### 首次运行设置 在首次启动仪表盘之前，请设置管理员密码并生成自签名证书： ``` # 设置 admin 密码 sudo python3 app.py --set-admin-password # 生成 HTTPS 证书 sudo mkdir -p /etc/safehaven/ssl sudo openssl req -x509 -newkey rsa:4096 -nodes \ -keyout /etc/safehaven/ssl/key.pem \ -out /etc/safehaven/ssl/cert.pem \ -days 365 -subj "/CN=SafeHaven-Pi/O=SafeHaven/C=GB" sudo chmod 600 /etc/safehaven/ssl/key.pem ``` 仪表盘以 systemd 服务（`safehaven-dashboard.service`）的形式运行，并会在开机时自动启动。 ## 控制菜单参考 交互式菜单（`sudo bash safehaven.sh`）是控制树莓派的主要方式。 ### 模式 | 按键 | 模式 | 功能 | |:---:|------|--------------| | `1` | 旅行者模式 | 日常公共 WiFi 防护 | | `2` | 活动家模式 | Tor 路由 + 零日志，用于信源保护 | | `3` | 商务模式 | Captive portal + 按用户划分的管理 | | `4` | 宽松模式 | 完整安全堆栈（不含 VPN） | ### 工具 | 按键 | 工具 | 功能 | |:---:|------|--------------| | `5` | 实时安全日志 | 实时查看威胁、被拦截的网站、VPN 活动 | | `6` | 管理 VPN 设备 | 添加、列出、编辑或移除 VPN 上的设备 | | `7` | DNS 拦截统计 | 查看 Pi-hole 的查询拦截计数器 | | `8` | Web 仪表盘 | 在浏览器中打开 `https://10.42.0.1:5000` 的仪表盘 | | `9` | 移动端访问 (Termux) | 通过手机管理树莓派的分步指南 | | `0` | 导出安全报告 | 将过去 24 小时的威胁、封禁记录和 DNS 拦截信息保存至单个文件 | ### 系统 | 按键 | 操作 | 功能 | |:---:|--------|--------------| | `w` | 设置向导 | 配置热点、主机名、管理员密码和 WireGuard 密钥 | | `s` | 停止所有服务 | 安全关闭所有防护层 | | `r` | 重启树莓派 | 重启设备——所有服务将在开机时恢复 | | `x` | 关闭树莓派 | 安全关机——防止 SD 卡损坏 | | `f` | 恢复出厂设置 | 清除所有凭证和会话（保留 HTTPS 证书） | | `q` | 退出 | 退回终端——防护功能仍在后台保持运行 | 该菜单采用响应式布局：在标准终端上显示宽大的块状字体 Logo 和三列状态面板，而在 Termux 上则呈现紧凑的单列布局。 ## 硬件 ### 必需 - **树莓派 4 或 5** —— 4GB 或 8GB 内存版本。运行所有安全服务需要额外的内存以避免卡顿。推荐使用树莓派 5 以获得最佳性能，但树莓派 4（4GB / 8GB）也运行良好。 - **microSD 卡** —— 至少 32GB，Class 10 或更高速率。 ### 可选但强烈推荐 —— USB WiFi 适配器 USB WiFi 适配器用于创建供其他设备连接的 SafeHaven 热点。如果没有适配器，客户端只能通过以太网连接。 在开发过程中，本项目使用了 **Alfa Network AWUS036ACS**，该设备在咖啡馆、酒店和大学环境中均表现稳定。任何支持在 Linux 下 AP 模式的 USB 适配器均可使用——这只是经过我们测试的型号。 | 规格 | 参数 | |------|-------| | 标准 | 802.11ac (WiFi 5) 双频 | | 2.4 GHz 速度 | 150 Mbps | | 5 GHz 速度 | 433 Mbps | | 芯片组 | Realtek RTL8811AU | | 天线 | 外置 RP-SMA，2 dBi 双频 | | Linux 支持 | 是 —— 内核自带驱动 | | AP 模式 | 已在树莓派 OS 上确认支持 | ### 其他配件 - **带散热的外壳** —— 在持续的 Suricata 负载下树莓派 5 会变热，推荐使用带散热片的外壳 - **USB 3.0 集线器** —— 如果你需要连接多个外设，这会很有用 - **SIM7600G-H 4G 上网卡** —— 用于在没有上游 WiFi 的环境中提供蜂窝网络上行链路（可配置，但并非 v1 的核心功能） ## 移动端管理 (Termux) 你不需要一台笔记本电脑就能管理 SafeHaven Pi。任何安装了 [Termux](https://f-droid.org/packages/com.termux/)（推荐，优于 Play 商店版本）的 Android 手机都可以通过 SSH 登录并运行完整的菜单。 ``` # 在 Termux 内部 pkg update && pkg install openssh # 确保你的手机与 Pi 在同一个 Tailscale 网络上 ssh @ # 启动 menu cd ~/SafeHaven-PI && sudo bash safehaven.sh ``` 菜单能自动检测窄终端并切换为单列移动端布局——同样的防护，适应屏幕的视图。 ## 文档 | 文档 | 内容 | |----------|--------------| | [`README.md`](README.md) | 本文件——项目概述、安装说明、模式及菜单参考 | | [`BUSINESS_MODE.md`](BUSINESS_MODE.md) | 完整的商务模式演练——设置、管理员和终端用户流程、命令、文件、故障排除 | | [`KNOWN_ISSUES.md`](KNOWN_ISSUES.md) | 坦诚的 v1 限制列表——按设计与已知技术债务分类 | | [`TROUBLESHING.md`](TROUBLESHOOTING.md) | 常见问题的症状及修复指南 | | [`CHANGELOG.md`](CHANGELOG.md) | v1.0-alpha 的发行说明 | | [`CONTRIBUTING.md`](CONTRIBUTING.md) | 如何 Fork 并扩展本项目 | | [`SECURITY.md`](SECURITY.md) | 负责任的漏洞披露与项目维护状态说明 | 如果遇到问题，**请先查阅 `TROUBLESHOOTING.md`**——大部分问题都已在其中通过分步指南的形式记录。如果你遇到的是一个已知的限制，它很可能在 `KNOWN_ISSUES.md` 中。 ## 项目结构 ``` SafeHaven-PI/ ├── install.sh ← Run once after cloning ├── safehaven.sh ← Main control script & menu ├── app.py ← Flask dashboard + auth + Business Mode API ├── safehaven-dashboard.html ← Pi monitoring dashboard ├── login.html ← Admin login page ├── portal.html ← Captive portal login (end-user facing) ├── portal-connected.html ← Post-login VPN status page ├── business-admin.html ← Admin panel for managing business users ├── assets/ │ ├── safehaven_logo.png ← Project logo │ └── screenshots/ ← Documentation screenshots ├── configs/ ← Service configuration templates │ ├── hostapd.conf │ ├── dnsmasq.conf │ ├── wg0.conf ← Template only — real keys never committed │ ├── torrc ← Tor transparent proxy config (Mode 2) │ └── nftables-mode2.conf ← Tor redirect rules ├── _teammate-originals/ ← Pristine versions of contributed HTML ├── README.md ├── KNOWN_ISSUES.md ├── TROUBLESHOOTING.md ├── CHANGELOG.md ├── CONTRIBUTING.md ├── SECURITY.md └── LICENSE ← GPL v3 ``` 由树莓派生成的运行时文件（永不提交）： ``` /etc/safehaven/auth.json ← Hashed admin credentials /etc/safehaven/business-users.json ← Hashed business-user credentials /etc/safehaven/wg-devices.json ← VPN device metadata (no private keys) /etc/safehaven/secret.key ← Flask session key /etc/safehaven/ssl/cert.pem ← HTTPS certificate /etc/safehaven/ssl/key.pem ← HTTPS private key /tmp/safehaven-mode ← Current active mode /var/lib/safehaven/.first-run ← Marker to skip boot animation ``` ## 构建技术 - [WireGuard](https://www.wireguard.com/) — VPN - [Pi-hole](https://pi-hole.net/) — DNS 过滤 - [Suricata](https://suricata.io/) — 入侵检测 - [Fail2ban](https://www.fail2ban.org/) — 暴力破解防护 - [Cowrie](https://github.com/cowrie/cowrie) — SSH 蜜罐 - [nftables](https://wiki.nftables.org/) — 防火墙与 NAT - [Flask](https://flask.palletsprojects.com/) — Web 仪表盘 - [Tailscale](https://tailscale.com/) — 远程管理访问 本项目的工程贡献在于集成层、用户体验设计以及基于模式的配置模型——这些安全工具本身都是久经沙战的开源项目，在全球范围内的其他部署环境中已被广泛应用于生产级别。 ## 学术背景 SafeHaven Pi 是为 2025-2026 学年的一场大学网络安全黑客马拉松而构建的。与通常由组织方给出题目、进行 24 到 48 小时冲刺的典型黑客马拉松不同，这次比赛作为一项正式的大学作业持续了几个月的时间。任务要求是刻意开放式的：识别行业内的一种新兴趋势，并围绕它构建一款产品。主题的选择、产品本身以及技术方案均由团队自主决定。研究、设计和交付全都是作业的一部分。 ## 许可证 GPL v3。可免费使用、修改和分发。 本项目基于 [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) 授权。完整的许可文本位于 [`LICENSE`](LICENSE) 中。简而言之，这意味着： **无担保，无责任** —— 许可证的第 15 和 16 条明确指出，本软件按“原样”提供。如果你在使用过程中出现问题，责任由你自行承担，而非作者。 **对滥用不承担责任** —— SafeHaven Pi 是作为防御性的隐私和安全工具而构建的。如果有人拿这些代码用于恶意或非法目的，那是他们的决定和后果——与原作者无关。 **Copyleft 保护** —— 衍生作品必须同样采用 GPL v3 许可。你不能把这个开源项目放到付费墙后、将其转为闭源，或对代码访问进行收费。它必须保持自由和开源。 **保留署名** —— 任何使用或分发本代码的人都必须保留原始的版权声明和许可证。你可以自由地 Fork 并在此基础上进行构建，但必须保留应得的荣誉。 有关完整的许可文本和 GPL v3 背后的理念，请参阅 [GNU 官方页面](https://www.gnu.org/licenses/gpl-3.0.en.html)。 ## 个人寄语 这是我在 GitHub 上的第一个主要项目。 我以前在这里创建过一些小东西——小脚本、有趣的实验，都是些没有真正发展下去的东西。但绝没有像这样的。SafeHaven Pi 是我第一次从头开始构建出一个真正有意义、让我发自内心感到自豪的东西。 如果你已经读到了这里——感谢你的阅读。无论你是讲师、同学、偶然路过这里的开发者，还是单纯对隐私和安全感到好奇的人——我希望这些内容读起来能让你觉得有趣。 这是一个完全开源的项目。如果你喜欢这里看到的内容，并希望改进它、添加功能、修复问题或将其带向不同的方向——请便。去 Fork 它，在它的基础上构建，让它变得更好。如果你真的这么做了，我非常希望能看到你的成果。欢迎与我分享。 ### 项目状态 **v1.0-alpha** 是提交给 2026 年 5 月一场大学黑客马拉松的版本——这就是本项目的起点。提交的确切状态作为 `v1.0-alpha-submission` 标签保存在 git 中，因此任何人（未来的读者、未来的我）都可以随时查看原始快照。 但这并不是终点。我把 SafeHaven Pi 作为黑客马拉松的提交作品，并且在开发过程中乐在其中，实在不舍得就这样把它丢在一边。**这个仓库将持续获得更新**——错误修复、文档改进，偶尔还会加入一些新功能——只要我有时间并且项目依然充满活力。大学里充满了各种有趣的项目，它们往往在提交后的第二天就被束之高阁。我不希望这成为其中之一。 如果你发现了一个 Bug、想要提出建议，或者打算自己动手修复它，问题页面始终为你敞开，我们也非常欢迎修复 Bug 的 Pull Request。如果你更愿意将它带向属于你自己的方向，去 Fork 它吧——这正是 GPL v3 的意义所在。 如果 SafeHaven Pi 有朝一日推出了 v2 版本，它很可能会作为一个截然不同的产品存在于一个新的仓库中——更新的硬件、更新的架构、全新的设计决策。而 v1 将留在这里，成为它生长的基石。 *本着好奇心、咖啡、深夜以及在大量终端窗口前的陪伴而构建。* *— Durkin*

标签：DNS过滤, IP 地址批量处理, Metaprompt, PE 加载器, Raspberry Pi 5, SSH蜜罐, Tailscale, Tor匿名路由, Web仪表盘, WiFi热点, WireGuard VPN, 便携式安全设备, 入侵检测系统, 公共WiFi安全, 加密热点, 后端开发, 安全数据湖, 安全网关, 应用安全, 开源硬件, 旅行安全, 无订阅安全, 极客项目, 网络信息收集, 网络安全, 网络隐私, 蜜罐, 记者安全工具, 证书利用, 进程注入, 逆向工具, 防暴力破解, 防火墙, 隐私保护, 零信任网络, 黑客车会项目