codewithserr/homenetguard

# HomeNetGuard [](https://github.com/sergioflores/homenetguard/actions) [](https://python.org) [](LICENSE) **面向家庭和个人使用的开源网络安全监控工具。** 在任何 Linux 或 macOS 机器上实时捕获、分析和审计网络流量——无需云端支持，无需订阅，所有数据均保存在本地。 HomeNetGuard 让您全面了解网络中正在发生的事情：哪些 IP 正在与您的机器通信、使用了哪些协议、是否存在已知威胁、正在解析哪些域名以及每个连接产生了多少流量。 ## ⚠️ 法律声明 ## 功能 - 🔍 **实时数据包捕获** — 由 Scapy 驱动的实时嗅探，支持自动检测网络接口 - 🛡 **威胁检测** — 端口扫描、流量泛洪、信标通信、ARP 欺骗、DNS 隧道、IP 黑名单 - 🌍 **地理定位** — 离线 MaxMind GeoLite2 IP 地理定位（无需 API 调用） - 📊 **Cyber SOC 仪表板** — 暗色主题实时 Web UI，集成 Chart.js 流量图和 Leaflet 世界地图 - 🔔 **告警** — 邮件和 Telegram 通知，支持可配置的严重级别阈值 - 📋 **报告** — 自动生成 HTML 和 PDF 报告（每日、每周或按需生成） - 🗄 **本地持久化** — SQLite 数据库，无外部依赖 - 🔎 **DNS 分析** — 查询时间线、热门域名、异常检测 - 🌐 **信誉检查** — AbuseIPDB 集成（可选，免费 API） - ⌨️ **完整的 CLI** — 基于 Click 的 CLI，包含 8 个子命令 - 🧪 **经过测试** — Pytest 单元测试，强制执行 70%+ 的测试覆盖率 ## 系统要求 | | 要求 | |---|---| | **操作系统** | Linux (Ubuntu 20.04+, Fedora 36+) 或 macOS 12+ | | **Python** | 3.11 或更高版本 | | **系统软件包** | `tshark` (Wireshark CLI), `libpcap-dev` | | **权限** | `sudo` / root，或 `CAP_NET_RAW` 权能 / `access_bpf` 用户组 | | **内存** | 最低 256 MB | | **磁盘** | 500 MB（包含 GeoIP 数据库） | ## 安装说明 ### 1. 克隆仓库 ``` git clone https://github.com/sergioflores/homenetguard.git cd homenetguard ``` ### 2. 创建并激活虚拟环境 ``` python3 -m venv .venv source .venv/bin/activate # Linux/macOS ``` ### 3. 安装系统依赖 ``` bash scripts/install_system_deps.sh ``` 此步骤将安装 `tshark`、`libpcap` 以及 WeasyPrint 依赖。 ### 4. 安装 Python 依赖 ``` pip install -e ".[dev]" # 或：make install-dev ``` ### 5. 配置 ``` cp config/config.example.yaml config/config.yaml cp .env.example .env # 根据需要编辑 config/config.yaml ``` ### 6. （可选）下载 GeoIP 数据库 ``` # 在 https://www.maxmind.com/en/geolite2/signup 获取免费 license key MAXMIND_LICENSE_KEY=your_key bash scripts/download_geoip.sh ``` ## 配置 所有设置均位于 `config/config.yaml` 中。API 密钥和密码存放在 `.env` 中： ``` ABUSEIPDB_API_KEY=your_key_here EMAIL_PASSWORD=your_smtp_password TELEGRAM_BOT_TOKEN=your_bot_token ``` 主要配置选项： | 设置 | 默认值 | 描述 | |---|---|---| | `network.interface` | `auto` | 用于捕获的网络接口 | | `network.capture_filter` | `""` | BPF 过滤器（例如 `"not port 22"`） | | `dashboard.port` | `5000` | Web 仪表板端口 | | `detection.port_scan.threshold_ports` | `15` | 每分钟每个 IP 触发端口扫描告警的端口数 | | `alerts.email.enabled` | `false` | 启用邮件告警 | 请参阅 [`docs/configuration.md`](docs/configuration.md) 获取完整参考。 ## 使用方法 ### 启动监控 ``` sudo homenetguard start # 或使用 venv：sudo .venv/bin/homenetguard start # 在特定 interface 上： sudo homenetguard start --interface eth0 # 持续 5 分钟，保存 capture： sudo homenetguard start --duration 300 --output captures/session.pcap ``` 预期输出： ``` ⚠ LEGAL NOTICE: HomeNetGuard is intended for use ONLY on networks you own... Starting capture on en0 — press Ctrl+C to stop 2026-05-15T10:00:01 | INFO | Dashboard at http://127.0.0.1:5000 ``` ### 仅启动仪表板（不进行捕获） ``` homenetguard dashboard # 在浏览器中打开 http://127.0.0.1:5000 ``` ### 分析 PCAP 文件 ``` homenetguard analyze --file capture.pcap homenetguard analyze --file capture.pcap --report ``` ### 生成报告 ``` homenetguard report --type daily --format html homenetguard report --type weekly --format pdf homenetguard report --type custom --from 2026-05-01 --to 2026-05-14 --format both ``` ### 管理告警 ``` homenetguard alerts --list homenetguard alerts --acknowledge 42 homenetguard alerts --clear-all ``` ### 系统状态 ``` homenetguard status ``` ### 配置 ``` homenetguard config --show homenetguard config --init # create config.yaml from template ``` ## 仪表板 启动后访问 `http://127.0.0.1:5000`。 **视图：** - **概览** — 实时流量图、协议分布、地理地图、告警信息流 - **告警** — 支持确认/导出的可过滤告警列表 - **流量** — 带有 IP/协议过滤器的分页流量浏览器 - **DNS** — 查询时间线、热门域名、可疑域名检测 - **报告** — 生成并下载 HTML/PDF 报告 - **配置** — 活动配置查看器 + 集成状态 仪表板采用暗色“Cyber SOC”主题，通过 WebSocket 每 2 秒进行实时更新。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ HomeNetGuard │ ├──────────────┬──────────────────────────────────────────────────┤ │ Presentation│ CLI (Click) │ Dashboard (Flask+SocketIO) │ Reports│ ├──────────────┼──────────────────────────────────────────────────┤ │ Analysis │ TrafficAnalyzer │ ThreatDetector │ DNSAnalyzer │ │ │ GeoLookup │ ReputationChecker │ ├──────────────┼──────────────────────────────────────────────────┤ │ Storage │ SQLite (WAL mode) │ Repository pattern │ │ │ Tables: flows, alerts, dns_queries, reputation │ ├──────────────┼──────────────────────────────────────────────────┤ │ Capture │ Sniffer (Scapy) │ PcapReader (PyShark) │ │ │ InterfaceDetector │ └──────────────┴──────────────────────────────────────────────────┘ ``` 详情请参阅 [`docs/architecture.md`](docs/architecture.md)。 ### 运行测试 ``` make test # all tests make test-cov # with coverage (requires 70%) pytest tests/unit/ # unit tests only ``` ### 代码风格 - Black (`line-length = 100`) - Ruff linting (E, F, I, UP, B 规则) - 所有公共函数均带有类型提示 - 不允许使用裸 `except` 子句 ## 路线图 ### v1.1 - [ ] 信标通信检测（C2 流量模式识别） - [ ] 进程与连接映射（确定哪个应用程序拥有哪个连接） - [ ] 通过 iptables/nftables/pf 自动拦截 IP ### v1.2 - [ ] 多主机监控（中央收集器） - [ ] SIEM 导出（CEF/LEEF 格式） - [ ] Docker 容器部署 ### v1.3 - [ ] 机器学习异常检测 - [ ] 与 CVE 数据库进行漏洞关联 - [ ] 移动端伴侣应用 ## 许可证 MIT 许可证 — 详见 [LICENSE](LICENSE)。 版权所有 (c) 2026 HomeNetGuard 贡献者

标签：AbuseIPDB, AMSI绕过, ARP欺骗检测, Beacon Object File, Chart.js, Click, DLL注入, DNS分析, DNS隧道检测, HTML报告, IP 地址批量处理, IP黑名单, Leaflet地图, MaxMind, PDF报告, Pytest, Python, Scapy, SOC仪表盘, SQLite, TCP SYN 扫描, Telegram告警, Web UI, 个人安全, 信标检测, 信誉查询, 威胁检测, 实时抓包, 家庭网络监控, 密码管理, 开源网络安全, 异常检测, 无后门, 无需云服务, 本地存储, 流量审计, 流量泛洪检测, 深色模式, 离线IP地理定位, 端口扫描检测, 网络可视, 逆向工具, 邮件通知, 防御绕过