vadhh/minifw-ai

# MiniFW-AI — AI 行为防火墙引擎 MiniFW-AI 是一个部署在 Linux 网关硬件上的 AI 驱动行为防火墙引擎。它通过构建正常流量的行为模型，并结合硬规则门控、威胁情报评分、ML 推理 (MLP) 和 YARA 模式匹配来标记偏差，从而检测未知的网络威胁。通过 nftables/ipset 在六个垂直锁定领域（医院、教育、政府、金融、法律、企业）的数据包级别执行强制策略。 同一个 `.deb` 包支持所有六个领域。活动领域在部署时设置一次，并在该安装的生命周期内锁定。 ## 系统要求 - **操作系统**: Ubuntu 22.04+ / Debian 12+ (任何支持 nftables 的 Linux) - **Python**: 3.10+ - **Root 权限**: nftables 执行和 conntrack 读取所需 - **硬件**: 4+ CPU 核心, 8 GB 内存, 100 GB 磁盘, 1 Gbps 网卡 - **系统软件包** (由 `.deb` 自动安装): `python3`, `python3-venv`, `nftables`, `openssl` - **建议**: `dnsmasq` (用于基于 DNS 日志的威胁检测) ## 安装说明 ### 步骤 1 — 验证软件包 在安装之前，确认软件包未被篡改： ``` # 导入 signing key gpg --import minifw-ai-release.asc # 验证 GPG signature gpg --verify minifw-ai_2.0.0_amd64.deb.asc minifw-ai_2.0.0_amd64.deb # 预期："Good signature from MiniFW-AI Release ..." # 验证 SHA-256 checksum sha256sum -c minifw-ai_2.0.0_amd64.deb.sha256 # 预期："minifw-ai_2.0.0_amd64.deb: OK" ``` 完整详情请参阅 [docs/release-verification.md](docs/release-verification.md)。 ### 步骤 2 — 设置领域 (安装前或安装后) 默认领域是 `establishment`。要为其他领域部署， 请立即决定 — 参阅下文的 [更改领域](#changing-the-sector)。 ### 步骤 3 — 安装系统依赖 ``` sudo apt update sudo apt install -y python3 python3-venv nftables openssl dnsmasq ``` ### 步骤 4 — 安装软件包 ``` sudo dpkg -i minifw-ai_2.0.0_amd64.deb ``` 安装程序自动执行以下操作： 1. 创建 Python 虚拟环境并安装所有依赖项 2. 生成随机 JWT 密钥和管理员密码 → `/etc/minifw/minifw.env` 3. 生成自签名 TLS 证书 → `/etc/minifw/tls/` 4. 在数据库中创建 `admin` 用户（密码打印到控制台 — 请保存） 5. 加载 `nf_conntrack` 内核模块并使其在重启后持久化 6. 将 Grafana 限制为仅本地访问（如果已安装） 7. 禁用 CUPS 打印服务 8. 启用并启动 `minifw-ai` 和 `minifw-ai-web` 服务 ### 步骤 5 — 启用 DNS 日志 基于 DNS 的威胁检测需要 dnsmasq 写入查询日志： ``` # 如果尚未存在于 /etc/dnsmasq.conf： echo "log-queries" | sudo tee -a /etc/dnsmasq.conf echo "log-facility=/var/log/dnsmasq.log" | sudo tee -a /etc/dnsmasq.conf sudo systemctl restart dnsmasq ``` ### 步骤 6 — 连接网络接口 将以太网线插入网关 NIC (`enp1s0`, `enp3s0`, 或 `enp4s0`)。 通过 netplan 配置接口： ``` # 示例：/etc/netplan/01-minifw.yaml network: version: 2 ethernets: enp1s0: dhcp4: true # or set a static IP sudo netplan apply ``` ### 步骤 7 — 验证安装 ``` # 服务运行中 systemctl status minifw-ai minifw-ai-web # Engine 正在处理事件 journalctl -u minifw-ai -f # nftables enforcement table 已创建 sudo nft list table inet minifw # Prometheus metrics 可用 curl -s http://localhost:9090/metrics | grep minifw_ai_flows # Dashboard 可访问 # 在浏览器中打开 https://localhost:8443 # 登录：admin / <安装时的密码> ``` ### 步骤 8 — 更改管理员密码 首次在 `https://localhost:8443` 登录时，系统会提示更改密码。或者通过仪表板操作：**Users → admin → Change Password**。 ### 卸载 ``` sudo dpkg -r minifw-ai # remove (keeps /etc/minifw, feeds, and logs) sudo dpkg -P minifw-ai # purge (removes everything including secrets) ``` ### 构建软件包 ``` bash scripts/build_deb.sh # 输出：build/minifw-ai_2.0.0_amd64.deb # Checksum：build/minifw-ai_2.0.0_amd64.deb.sha256 ``` ## 更改领域 `.deb` 包支持所有六个领域。领域在 systemd 服务单元中设置，并在守护进程启动时锁定 — 运行时无法更改。 ### 可用领域 | 领域 | 用例 | 封锁阈值 | 特殊行为 | |--------|----------|-----------------|-------------------| | `establishment` | 一般商业、中小企业、零售 | 90 (默认) | 均衡 | | `hospital` | 医院、诊所 | 较高 (更少误报) | HIPAA 负载脱敏, IoMT 告警 | | `finance` | 银行、金融机构 | 较低 (更严格) | Tor/匿名器封锁 | | `education` | 学校、大学 | 90 | 强制 SafeSearch | | `government` | 政府网络 | 90 | Geo-IP 限制 | | `legal` | 律师事务所 | 90 | 数据渗出监控 | ### 如何设置领域 **选项 A — 首次安装前 (推荐)** 在构建 `.deb` 之前编辑源码仓库中的服务单元： ``` # 编辑 systemd/minifw-ai.service Environment=MINIFW_SECTOR=hospital # change this line bash scripts/build_deb.sh sudo dpkg -i build/minifw-ai_2.0.0_amd64.deb ``` **选项 B — 安装后** ``` # 编辑实时服务单元 sudo nano /etc/systemd/system/minifw-ai.service # 更改：Environment=MINIFW_SECTOR=establishment # 为：Environment=MINIFW_SECTOR=hospital # 应用更改 sudo systemctl daemon-reload sudo systemctl restart minifw-ai # 确认新的 sector 已激活 journalctl -u minifw-ai -n 5 | grep SECTOR ``` ### 验证活动领域 ``` journalctl -u minifw-ai | grep "SECTOR_LOCK" # 预期：[SECTOR_LOCK] Device sector: hospital (LOCKED) # 或通过 dashboard 检查 # https://localhost:8443/admin/api/sector-lock ``` ## 配置 ### 领域锁定 请参阅上文的 [更改领域](#changing-the-sector) 以获取完整的领域表、 如何在安装前后设置领域，以及如何验证其是否处于活动状态。 ### DNS 来源 在 systemd 单元中设置 `MINIFW_DNS_SOURCE`： | 来源 | 描述 | |--------|-------------| | `file` | Tail dnsmasq 日志 (默认) | | `journald` | 从 systemd-resolved 流式传输 | | `udp` | 在 UDP socket 上监听 | | `none` | 降级模式 — 仅流量, 无 DNS 评分 | ### 威胁源 填充 `/opt/minifw_ai/config/feeds/` 中的源文件： ``` deny_domains.txt — blocked domain patterns (fnmatch: *.malware.com) allow_domains.txt — whitelisted domains (bypass deny checks) deny_ips.txt — blocked IP addresses deny_asn.txt — blocked ASNs (e.g. AS12345) asn_prefixes.txt — IP-to-ASN mapping (CIDR ASN format) tor_exit_nodes.txt — Tor exit IPs (auto-loaded for finance sector) ``` 源文件被标记为配置文件 — 它们在包升级时会被保留。 ### 评分权重 编辑 `/opt/minifw_ai/config/policy.json` 以调整评分： | 信号 | 默认权重 | 描述 | |--------|---------------|-------------| | DNS 拒绝匹配 | +40 | 域名在 deny_domains.txt 中 | | TLS SNI 拒绝匹配 | +35 | SNI 在 deny_domains.txt 中 | | ASN 拒绝 | +15 | IP 的 ASN 在 deny_asn.txt 中 | | IP 拒绝 (Tor) | +15 | IP 在 deny_ips.txt 中 | | DNS 突发 | +10 | QPM 超过阈值 | | MLP 评分 | 0–30 | ML 模型置信度 | | YARA 评分 | 0–35 | 模式匹配严重程度 | | 硬规则门控 | =100 | 覆盖: PPS, 突发, 僵尸网络检测 | 决策阈值（可按网段配置）： - 评分 < 60 → **允许** - 评分 >= 60 → **监控** - 评分 >= 90 → **封锁** (IP 添加到 nftables) ## Web 管理面板 仪表板在启用 TLS 的 `https://localhost:8443` 上运行。 默认凭据在安装期间生成并存储在 `/etc/minifw/minifw.env` 中。管理员用户首次登录时需要更改密码。 功能： - 实时流量监控和事件日志 - 威胁源管理（允许/拒绝域名、IP、ASN） - 策略配置编辑器 - 具有基于角色的访问控制 的用户管理 - 2FA/TOTP 注册 - 审计日志查看器 - 事件导出 (XLSX) ## 开发 ### 运行测试 ``` pip install pytest python -m pytest testing/ -v # all tests python -m pytest testing/ -m "not integration" -v # unit tests only ``` ### 重训 MLP 模型 ``` python3 scripts/train_mlp.py --data /opt/minifw_ai/logs/flow_records.jsonl ``` ## 架构 ``` DNS event → pump_zeek() + pump_flows() → StateManager.check_and_transition() → FeedMatcher [deny_domains, deny_ips, deny_asn] → BurstTracker [QPM tracking] → evaluate_hard_threat() [PPS/burst/bot gates] → MLPThreatDetector.is_suspicious() [optional] → YARAScanner.scan_payload() [optional] → score_and_decide() → allow / monitor / block → ipset_add() [nftables enforcement on block] → EventWriter.write() [JSONL log] → Prometheus metrics update ``` 两种保护状态： - **BASELINE_PROTECTION** — 仅硬规则门控 (MLP/YARA 禁用) - **AI_ENHANCED_PROTECTION** — 硬规则门控 + MLP + YARA 基于 DNS 遥测健康状况自动转换。系统故障安全关闭 — 如果 DNS 遥测丢失，它将降级为 BASELINE_PROTECTION (硬规则门控 保持活动，AI 模块禁用)。 ## 文件布局 ``` /opt/minifw_ai/ ├── app/ # Application code │ ├── minifw_ai/ # Firewall engine (daemon) │ ├── web/ # FastAPI web admin │ ├── models/ # SQLAlchemy models │ ├── services/ # Business logic │ ├── controllers/ # Route handlers │ └── middleware/ # Auth middleware ├── config/ │ ├── policy.json # Scoring thresholds and weights │ └── feeds/ # Threat intelligence feeds ├── models/ │ └── mlp_model.pkl # Pre-trained MLP model ├── yara_rules/ # YARA detection rules ├── prometheus/ # Metrics module ├── scheduler/ # Retraining scheduler ├── logs/ # Runtime logs (events.jsonl, audit.jsonl) ├── scripts/ # Backup, restore, training tools ├── venv/ # Python virtual environment (created at install) └── requirements.txt /etc/systemd/system/ ├── minifw-ai.service # Firewall engine daemon └── minifw-ai-web.service # Web admin panel /etc/minifw/ ├── minifw.env # Secrets (JWT key, admin password) └── tls/ ├── server.key # TLS private key └── server.crt # TLS certificate ``` ## 文档 | 文档 | 描述 | |----------|-------------| | [DEVELOPER.md](DEVELOPER.md) | 架构深度剖析, 模块参考, 11 阶段开发模型 | | [CHANGELOG.md](CHANGELOG.md) | 版本历史 | | [TODO.md](TODO.md) | 第 4 阶段准备任务列表 (全部完成) | | [docs/monitoring-mode.md](docs/monitoring-mode.md) | 监控模式参考, 评分阈值, 分析师工作流 | | [docs/release-verification.md](docs/release-verification.md) | GPG 签名密钥, 包验证步骤 | | [docs/rollback.md](docs/rollback.md) | 回滚和紧急移除程序 | | [docs/report-2026-03-16.md](docs/report-2026-03-16.md) | 客户端部署准备报告 (2026-03-16) | ## 许可证 专有 — RitAPI V-Sentinel。保留所有权利。

标签：AI防火墙, Apex, Beacon Object File, Debian, DNS信息、DNS暴力破解, Google搜索, Linux网关, MLP神经网络, ML安全, nftables, YARA规则, 入侵防御系统, 协议分析, 威胁情报, 威胁猎捕, 安全网关, 开发者工具, 异常检测, 数据包过滤, 机器学习, 权限提升, 流量建模, 流量监控, 深度包检测, 网络安全, 网络安全分析, 网络访问控制, 自定义请求头, 逆向工具, 防火墙引擎, 隐私保护