mchinchilla/NetFirewall

# NetFirewall 多年来我一直使用 pfSense、OPNsense、IPCop、Zentyal、ClearOS、VyOS、IPFire、Endian —— 它们各有优缺点。NetFirewall 旨在打造一个完全符合我个人需求的系统，建立在我深入了解的技术栈之上，不依赖旧平台及遗留依赖，并提供现代化的 WebUI。 I've used pfSense, OPNsense, IPCop, Zentyal, ClearOS, VyOS, IPFire, Endian for years — each with its pros and cons. NetFirewall is an attempt to get exactly what I want, on a stack I know deeply, without legacy platform dependencies and with a modern WebUI. ## 愿景：NetFirewall OS 该项目的最终目标是打造一个**基于 Debian 的 Linux 发行版**（可启动的 ISO），将其安装在机器上即可作为一台多 WAN (Multi-WAN) 应用设备随时可用。三个控制平面共享完全相同的服务层： - **Web UI** — ASP.NET Core MVC + Tailwind 4 + HTMX + Alpine。无特权运行；所有破坏性操作均通过经过身份验证的 Unix socket 交由 daemon 处理，并要求进行 TOTP step-up 验证。 - **基于 TTY 的 TUI** — 用于无网络情况下的初始配置、系统恢复或通过串行控制台进行本地管理。它调用与 Web 相同的 socket；实现逻辑零重复。 - **ISO 安装程序** — 无人值守或向导式安装、分区管理，首次启动时生成 bootstrap token，用于注册首个启用了 TOTP 的管理员。 ### 开箱即用的功能预期 - **多 WAN 故障转移** (Multi-WAN failover)，配备 WAN 监控：基于接口的 ping-watchdog、故障前后执行的脚本 (pre/post-failover)、延迟指标。 - **原生 DHCP 服务器**，直接基于 PostgreSQL 运行（无需 ISC dhcpd，无需 Kea）：地址池、类别、MAC 预留、DDNS、RFC 3074 风格的故障转移、PXE 启动、基于类别的选项。 - **世界级的 nftables 防火墙**：过滤规则、NAT、端口转发、mangle/marks、QoS (HTB)、静态路由、带时区的调度、审计日志、试运行 + 应用并支持自动回滚。 - **集成的 WireGuard VPN**：节点 管理、配置渲染、应用。 - **全面的网络接口配置**：IP/子网掩码/网关、**MAC 伪装**（内核级别，重启后依然有效）、网桥、VLAN、MTU。具备发行版感知能力：根据情况自动检测并写入 Netplan / NetworkManager / Debian `interfaces`。 - **DNS 解析器**（已规划）、**代理/强制门户 captive portal**（已规划）、带实时指标的**监控**。 - **真正的 MFA 身份验证**：Argon2id + 服务端会话 + TOTP 注册 + 恢复码 + 针对破坏性操作的 step-up 验证。 - 全局配置的**全文搜索**：tsvector + GIN 索引，在页面头部提供防抖动自动补全。 ## 目录 - [各子系统状态](#estado-por-subsistema) - [技术栈](#stack-técnico) - [安全模型](#modelo-de-seguridad) - [项目规则（不可妥协）](#reglas-del-proyecto-no-negociables) - [架构设计](#arquitectura) - [网络与接口配置](#configuración-de-red-e-interfaces) - [数据库与迁移](#base-de-datos-y-migraciones) - [构建与开发](#build-y-desarrollo) - [测试与覆盖率](#tests-y-cobertura) - [生产环境部署](#despliegue-en-producción) - [DHCP — RFC 2131 备注与性能](#dhcp--notas-rfc-2131-y-performance) - [路线图](#roadmap) - [贡献指南](#contribuir) ## 各子系统状态 | 子系统 | 状态 | 备注 | |---|---|---| | **WAN Monitor** | 生产环境 | 双 WAN 故障转移功能完善，已在家用生产环境的 systemd 下稳定运行数月。 | | **DHCP Server** | Beta | RFC 2131 pipeline + 选项 + 类别 + 预留 + DDNS + 基础故障转移 (RFC 3074 风格)。热路径 实现零内存分配 (zero-allocation，使用 Span/stackalloc/ArrayPool)。LeaseCache 单例在启动时预热。支持 PXE 启动。 | | **Firewall (nftables)** | Beta | 过滤规则、NAT、端口转发、mangle/marks、QoS (HTB)、静态路由、审计日志的增删改查。支持在 UI 中进行真实的 backup/rollback 应用。 | | **Schedules** | Beta | 带有时间窗口和时区的规则；daemon 监视器会在状态改变时重新应用。 | | **VPN (WireGuard)** | Alpha | Peers 节点 + 配置渲染 + 应用。尚缺用于移动端的完整二维码 UI。 | | **Network Objects / Services** | Beta | 可复用别名 (host/CIDR/range/FQDN/group) 以及约 70 个知名服务的目录。解析器具备循环依赖检测能力。 | | **Network interfaces config** | Beta | 发行版感知。写入 `/etc/network/interfaces` 或 Netplan YAML + 通过 daemon 进行网口启动。**支持 MAC 伪装**。 | | **Auth (sesión + TOTP)** | Beta | Argon2id + 服务端会话 + MFA TOTP + 恢复码 + 首次启动的 bootstrap token。破坏性操作强制要求通过 `[RequireElevated]` 进行 **Step-up TOTP** 验证。 | | **Daemon Web ↔ root** | Beta | 认证的 Unix socket (`X-NetFw-Session`)，拥有最小权限 (`CAP_NET_ADMIN`/`CAP_DAC_OVERRIDE`/`CAP_NET_RAW`) 的端点 `/v1/{network,firewall,crypto,...}`。 | | **Setup wizard** | Beta | 5 步向导式配置，逐步持久化，支持幂等重新运行。 | | **Búsqueda full-text** | Beta | tsvector + GIN，通过触发器同步，在 header 提供防抖的自动补全。 | | **Monitoreo** | Alpha | 系统指标 + 实时仪表盘 (HTMX polling)。 | | **WebUI** | Beta | ASP.NET Core MVC + Tailwind 4 + HTMX + Alpine，无 npm。使用语义化 token 的主题 (`bg-surface`, `--accent`, `--feedback-*`)。 | | **TUI** | 已规划 | 用于无网络初始配置、控制台恢复、本地管理。使用相同的 daemon socket。 | | **ISO installer** | 已规划 | 基于 Debian，向导式安装，首次启动引导。 | ## 技术栈 - **后端：** C# / .NET 10，ASP.NET Core MVC + Minimal APIs，.NET Aspire (开发环境编排)，Serilog。 - **数据：** PostgreSQL 14+，Npgsql，RepoDb (微型 ORM)，tsvector + GIN 用于搜索。 - **前端：** Tailwind CSS 4 (独立二进制文件，**无 Node**)，HTMX，Alpine.js —— 均作为第三方库存放在 `wwwroot/lib/` 下。 - **系统：** nftables，iproute2，tc (HTB)，用于 DHCP 的 Linux 原始套接字，WireGuard CLI，Netplan / NetworkManager / `/etc/network/interfaces` 自动检测。 - **加密：** Argon2id (密码)，AES-GCM (TOTP 密钥加密，密钥仅存在于 daemon 中)，TOTP RFC 6238。 - **测试：** xUnit + Moq + `Aspire.Hosting.Testing` + Testcontainers (真实的 Postgres)。 - **部署：** systemd (两个 units：具有最小 capabilities 的 `netfirewall-daemon`，无 caps 的 `netfirewall-web`)，带有 TLS 的 nginx，幂等安装程序。 ## 安全模型 NetFirewall 对破坏性操作（更改防火墙规则、应用网络配置、修改用户信息）极其重视。其安全模型如下： 1. **无特权的 Web 进程。** `netfirewall-web` 进程以普通系统用户身份运行，不具备任何 capabilities，只能写入 `/var/lib/netfirewall/web`。 2. **具备最小权限的 root daemon。** `netfirewall-daemon` 仅拥有 `CAP_NET_ADMIN` + `CAP_DAC_OVERRIDE` + `CAP_NET_RAW`（没有 `CAP_SYS_ADMIN`，也没有 `CAP_SYS_MODULE`）。systemd 沙盒配置包括：`ProtectSystem=strict`、`NoNewPrivileges`、`PrivateTmp`、`LockPersonality`、`RestrictNamespaces` 以及自定义的 `SystemCallFilter`。 3. **Web ↔ Daemon 通信** 基于包含会话头 (`X-NetFw-Session`) 的 Unix socket (`/run/netfirewall/daemon.sock`，模式为 0660 root:netfirewall)。daemon 在执行任何操作前会先根据 Postgres 验证该会话。 4. **用于加密 TOTP 密钥的主密钥** 仅存在于 daemon 进程中 (`/etc/netfirewall/daemon.env`，模式为 0600 root:root)。Web 端永远无法接触到它 —— 若要注册/验证 TOTP，需通过 socket 调用 `POST /v1/crypto/{encrypt,decrypt}`。**即使 Web 应用被攻破，也无法解密存储的 TOTP 密钥。** 5. **针对破坏性操作的强制 Step-up TOTP 验证** (`[RequireElevated]` 过滤器)：用户必须在过去 15 分钟内通过 TOTP 验证。如果是基础会话，过滤器将返回带有 `HX-Trigger: showElevationModal` 的 401 状态，随后前端会弹出 step-up 模态框，在验证后重新发起原始请求。 6. **Auth 审计日志** —— 所有 auth 操作 (登录、登出、TOTP 失败、锁定、提权) 都将连同 IP + UA + 结构化详情持久记录到 `auth_audit_log` 中。 7. **`__Host-` cookie** —— 属性包含 `Secure`、`Path=/`、无 `Domain`、`SameSite=Lax`、`HttpOnly`。可抵御子域名劫持。 8. **Argon2id** 附带 salt + 32 字节 hash（默认值），如果参数提升，会在登录时通过 `NeedsRehash` 自动进行密钥轮换。 ## 项目规则（不可妥协） 代码库中的硬性规定，记录在 [`CLAUDE.md`](./CLAUDE.md) 中。简要总结如下： 1. **禁止使用 npm / Node。** Tailwind 通过独立二进制文件编译，JS 依赖项直接 vendor 引入。 2. **所有 I/O 操作均使用 Async/await**（服务器端和浏览器端）。严禁使用 `.Result`、`.Wait()`、`.then()` 链式调用。 3. **只有一个 CSS 文件和一个 JS 文件：** `Styles/site.css` → `wwwroot/css/site.css` 和 `wwwroot/js/site.js`。严禁使用内联 `