Mattmorris-dev/netwatch-sec

# NetWatch [](https://pypi.org/project/netwatch-sec/) [](https://pepy.tech/project/netwatch-sec) [](https://pepy.tech/project/netwatch-sec) [](LICENSE) [](https://www.python.org/downloads/) [](https://flask.palletsprojects.com/) [](https://www.raspberrypi.org/) [](https://www.linux.org/) [](https://www.parrotsec.org/) [](https://www.kali.org/) [](https://www.debian.org/) [](tests/) [](CHANGELOG.md) []() [](https://buymeacoffee.com/pr0xy_22) **一体化网络安全仪表盘** — 部署 honeypot，捕获流量，运行 OSINT，扫描目标，拦截威胁，并通过 mesh radio 转发警报。一条命令，一个文件，实时运行。 ``` sudo netwatch ``` NetWatch 能将任何 Linux 主机变成全功能的网络安全传感器。它会部署 4 个 honeypot 服务来诱导并记录攻击者，使用 raw socket 和 tshark 嗅探接口上的所有流量，自动通过地理位置和威胁评分来丰富每个 IP 的信息，并为您提供 100 多条命令来调查、跟踪和拦截威胁 — 所有这些都可以在单个终端或浏览器中完成。 专为 Raspberry Pi、Kali、Parrot OS 以及任何基于 Debian 的 Linux 打造。它作为单个 Python 文件运行，无需 microservice、Docker 或云依赖。 ## 工作原理 1. **启动** — `sudo netwatch` 会启动一切：4 个 honeypot 绑定其端口，raw socket 嗅探器附加到您的接口，tshark 开始协议分析，ARP 监控器发现设备，Web 仪表盘在 :9090 打开 2. **捕获** — 解析每个数据包的源/目的 IP、端口、协议和 DNS 查询。Honeypot 会记录凭据、命令、文件上传和恶意软件下载尝试 3. **丰富** — 根据端口行为、已知的恶意端口和扫描模式，自动对每个新 IP 的威胁级别进行评分。运行 OSINT 命令以添加地理位置、WHOIS、滥用报告和 ASN 数据 4. **响应** — 使用 iptables 拦截攻击者，标记并监视 IP，运行深度的 nmap 扫描，捕获 payload，导出报告。通过 LoRa mesh radio 转发关键警报以进行离网监控 5. **查看** — 带有 11 个选项卡的全屏 TUI，或者带有实时图表、可点击 IP、5 种颜色主题和 CRT 扫描线效果的浏览器仪表盘 ## 架构 ``` ┌──────────────────────────────────────────────────────────────┐ │ NETWATCH v1.1.0 │ ├──────────────────────────────────────────────────────────────┤ │ TERMINAL UI (TUI) │ WEB DASHBOARD (:9090) │ │ Full-screen ANSI │ Flask + SSE live updates │ │ 11 tabs, console mode │ 5 themes, CRT scanlines │ │ Tab/number key nav │ Charts, clickable IPs, API │ ├──────────────────────────────────────────────────────────────┤ │ HONEYPOTS │ TRAFFIC MONITORING │ │ HTTP :8080 (NVR panel) │ Raw socket sniffer │ │ Telnet :2323 (DVR) │ tshark protocol analysis │ │ FTP :2121 (bait files) │ tcpdump PCAP recording │ │ RTSP :8554 (camera) │ ARP device discovery │ ├──────────────────────────────────────────────────────────────┤ │ SCANNING & RECON │ OSINT (16 tools) │ │ nmap integration │ GeoIP, WHOIS, DNS enum │ │ Port scanning │ SSL/TLS, HTTP headers │ │ Service detection │ Abuse/ASN, cert transparency │ │ Stealth (Tor) mode │ Tech fingerprinting, speedtest │ ├──────────────────────────────────────────────────────────────┤ │ DEFENSE │ MESH RADIO │ │ iptables blocking │ Meshtastic LoRa support │ │ Threat scoring │ Alert forwarding │ │ Watchlists & tagging │ Two-way messaging │ └──────────────────────────────────────────────────────────────┘ ``` ## 安装 **快速安装（来自 PyPI）：** ``` sudo apt install -y nmap tshark tcpdump traceroute iproute2 iptables \ openssl curl dnsutils whois psmisc arp-scan tor proxychains4 pipx install netwatch-sec sudo netwatch ``` **从源码安装：** ``` # 系统工具（一次性运行 — 涵盖 NetWatch 调用的所有命令） sudo apt install -y nmap tshark tcpdump traceroute iproute2 iptables \ openssl curl dnsutils whois psmisc arp-scan \ tor proxychains4 # Python deps pip3 install -r requirements.txt # 可选功能 pip3 install graphene flask-graphql # GraphQL API at :9090/graphql pip3 install meshtastic # LoRa mesh radio alerts sudo apt install -y speedtest-cli # `speed` command # 在系统范围内安装 launcher chmod +x netwatch-start.sh sudo ln -s $(pwd)/netwatch-start.sh /usr/local/bin/netwatch ``` **Docker（单行命令）：** ``` docker run -d --name netwatch --restart unless-stopped \ --network host --cap-add NET_ADMIN --cap-add NET_RAW \ -e NETWATCH_TELNET_PORT=23 -e NETWATCH_FTP_PORT=21 \ -e NETWATCH_HTTP_PORT=80 -e NETWATCH_RTSP_PORT=554 \ -v netwatch-logs:/app/logs \ ghcr.io/mattmorris-dev/netwatch-sec:latest eth0 ``` 这将运行 headless 模式：honeypot 位于标准端口 (23/21/80/554) + Web 仪表盘位于 `:9090`。系统工具（nmap, tshark, tcpdump, …）已内置在镜像中。支持多架构 — 可在 x86-64 和 ARM64（Raspberry Pi）上运行。将 `eth0` 替换为您的捕获接口。 或者使用 Compose： ``` docker compose up -d # uses docker-compose.yml docker compose logs -f # watch attacks ``` 查看攻击流（纯净的 JSON，每次命中一行）： ``` docker exec netwatch tail -f /app/logs/all_events.json ``` **验证您的安装：** 启动 NetWatch 并在提示符下运行 `doctor`（别名 `deps`/`check`）— 它会列出每个所需的 Python 包和系统工具，并显示存在/缺失的状态，标记 passive（非 root）模式，并告诉您如何安装任何缺失的内容。 ## 快速入门 ``` # 每次启动使用随机 token（默认 — 更安全） sudo netwatch # 重启后保持持久的 token（需要 NETWATCH_FIXED_TOKEN env var） export NETWATCH_FIXED_TOKEN=$(openssl rand -hex 24) sudo -E netwatch --fixed-token # 指定 interface sudo netwatch eth0 ``` 启动时会打印脱敏的 token 预览（`ABCDEF…WXYZ`），完整的 token 会写入 `~/.config/netwatch/token`（权限 0600）。使用它登录位于 `http://:9090` 的 Web 仪表盘。 TUI 和 Web UI 会同时启动 — 一条命令即可运行一切。 ### 密钥与 token 轮换 从 TUI 提示符中： | 命令 | 效果 | |---------|--------| | `rotate-key` | 生成新的 Fernet 密钥 — 使所有活动的 Web 会话失效。持久化到 `~/.config/netwatch/web.key`。 | | `rotate-token` | 生成新的身份验证 token — 使所有会话失效。重新写入 `~/.config/netwatch/token` (0600)。 | ### Honeypot 端口 默认绑定到高端口，因此不需要 root 权限：HTTP `:8080`，Telnet `:2323`，FTP `:2121`，RTSP `:8554`。通过环境变量覆盖以移动到标准端口（需要 `CAP_NET_BIND_SERVICE` 或 root 权限）： ``` NETWATCH_HTTP_PORT=80 \ NETWATCH_TELNET_PORT=23 \ NETWATCH_FTP_PORT=21 \ NETWATCH_RTSP_PORT=554 \ sudo -E netwatch ``` 通过添加到 `/etc/netwatch.env` 并在 systemd unit 的 `EnvironmentFile=` 中引用来持久化。面向互联网的扫描器会命中标准端口 — 非标准端口对大多数路过式流量保持不可见。 ### Replay 可调参数 相同 IP 的 telnet 尝试会汇总为一个聚合会话（`all_`），因此整天敲击您 honeypot 的扫描器将显示为一个条目，而不是五十个。在时间线内，`── ATTEMPT N (timestamp UTC) ──` 标记分隔了突发请求。使用以下命令调整突发阈值： ``` NETWATCH_TELNET_GAP_SEC=86400 sudo -E netwatch # one marker per day (default: 300 = 5 min) ``` 每个独立的尝试会话仍然可以通过其原始的 `_HHMMSS` ID 加载，以便进行深入分析。 ### CrowdSec 自动封禁（可选） 如果主机上安装了 [`cscli`](https://docs.crowdsec.net/)，每次 honeypot 捕获（`credential`、`telnet`、`ftp`、`rtsp`、`malware_attempt`、`ftp_upload`、`telnet_cmd`）都会自动调用 `cscli decisions add` 进行 4 小时的封禁。CrowdSec 防火墙 bouncer 通过 ipset 执行丢弃（drop）操作，因此规则数量永远不会激增。60 秒内的相同 IP 事件会被去重。设置 `NETWATCH_AUTODEFEND=0` 以禁用。如果没有安装 CrowdSec，该钩子将静默无效化（no-op）。 在 Debian 上安装： ``` curl -s https://install.crowdsec.net | sudo sh sudo apt install -y crowdsec crowdsec-firewall-bouncer-iptables sudo systemctl enable --now crowdsec crowdsec-firewall-bouncer ``` 将您的操作员 IP 加入白名单，以免封禁自己 — 添加 `/etc/crowdsec/parsers/s02-enrich/whitelists.yaml`： ``` name: netwatch/operator-whitelist whitelist: reason: "operator home" ip: [""] ``` ## 会话重放 ``` sudo netwatch # capture starts immediately python tools/synth_ftp_session.py 198.51.100.42 # optional — fake an attacker # 打开 http://localhost:9090 并点击 REPLAY 标签页 ``` 每个捕获的会话（FTP、Telnet、HTTP 探测）都被记录为可拖动的时间线。Web 播放器会自动列出会话；选择一个并逐帧单步执行击键。在 TUI 中，`replay list` 显示最近的会话，`replay ` 进入播放器。 播放器按键：`space` 播放/暂停 · `←/→` 单步执行 · `` 跳转会话 · `+/-` 速度 · `Home/End` 结尾。 ## 远程访问 当 `cloudflared` 可用时，NetWatch 会在启动时自动启动一个快速隧道。公共的 `*.trycloudflare.com` URL 会在启动时打印，并固定在仪表盘的 **all** 选项卡顶部，以便您无需滚动浏览警报即可复制它。 控制台命令（在提示符下输入）： | 命令 | 用途 | |---------|---------| | `tunnel` | 重新打印当前的 trycloudflare URL + 完整的 Web token | | `restart-tunnel` | 终止 cloudflared，生成一个新的隧道（新 URL） | | `token` | 重新打印完整的 Web token + 磁盘路径 | ``` # 如果 cloudflared 不在 $PATH 中，请使用手动 fallback cloudflared tunnel --url http://localhost:9090 # 或者将 NetWatch 指向非默认的 cloudflared 二进制文件 NETWATCH_CLOUDFLARED_BIN=/opt/cf/cloudflared sudo -E netwatch ``` ### 公共 IP 访问（无隧道） Web 仪表盘的 IP 白名单默认为 **loopback + RFC1918 + Tailscale (100.64/10)**，因此全新的安装不会意外地从开放的互联网被访问。要允许您的家庭/办公室 IP，请将 `NETWATCH_WEB_ALLOW` 设置为一个或多个 CIDR： ``` # 单个主机 NETWATCH_WEB_ALLOW=203.0.113.42/32 sudo -E netwatch # 多个范围（以逗号分隔） NETWATCH_WEB_ALLOW="203.0.113.42/32,198.51.100.0/24" sudo -E netwatch ``` 无效的 CIDR 将在启动时被跳过并发出警告。Token 身份验证仍然适用 — 添加 IP 仅允许登录页面呈现。与 `ufw`/`iptables` 结合使用以实现深度防御。 ## Termux / 非 root（passive 模式） NetWatch 可以在 Termux（Android）和任何非 root 环境下以 **passive 模式** 运行 — honeypot、OSINT、Web 仪表盘和 nmap connect-scan 仍然有效。需要 raw socket 或 kernel 访问权限的功能会被自动禁用： | 功能 | Root | Termux / 非 root | |---------|------|-------------------| | Honeypot (HTTP/Telnet/FTP/RTSP) | ✓ | ✓ | | Web 仪表盘 + OSINT | ✓ | ✓ | | nmap (connect / `-sV`) | ✓ | ✓ | | Raw-socket 嗅探器 / `traffic` | ✓ | — | | `tshark` / `tcpdump` 捕获 | ✓ | — | | ARP 监控器 | ✓ | — | | `block` / `unblock` (iptables) | ✓ | — | | nmap SYN 扫描 (`-sS`) | ✓ | — | ``` # Termux 快速开始 pkg install python nmap whois tor pip install netwatch-sec netwatch # passive mode — no sudo needed ``` ## 终端 UI 三个屏幕，通过快捷键切换。切换屏幕会保留您的选项卡和滚动位置。 | 屏幕 | 快捷键 | 用途 | |--------|--------|---------| | **仪表盘** | `F1` | 11 个选项卡，实时的主机/协议/honeypot 视图 | | **命令行** | `F2` | 全屏提示符 + 命令输出 | | **控制台** | `F3` | 工具输出的全屏日志 | ``` F1 / F2 / F3 Switch screens 1-9, 0 Jump to tab Type anything Open command prompt Up/Down History recall PgUp / PgDn Scrollback Home / End Top / bottom ESC Close help overlay clear Wipe console buffer ``` ### 选项卡 `all` · `hosts` · `proto` · `dns` · `honeypot` · `nmap` · `arp` · `alerts` · `osint` · `proxy` · `mesh` ## Web 仪表盘 位于 `:9090` 的浏览器 UI，具有实时 SSE 更新、5 种主题和 CRT 扫描线效果。 - **主题**：Terminal Classic、Matrix Green、Midnight Blue、Cyberpunk、Light Mode - **CRT 扫描线**：Off、Soft、Heavy — 复古终端美学 - **图表**：实时流量时间线、协议分布、威胁分类 - **点击任意 IP** 呼出上下文菜单 — 扫描、地理定位、whois、traceroute、全面侦测 - **可调整大小的输出面板**，带有拖动手柄 - **主机详情模态框**，显示端口、标签、OSINT 结果、honeypot 活动 - **键盘快捷键**：1-0 切换选项卡，`/` 聚焦命令栏，ESC 关闭 ### 安全性 - 需要 Token 身份验证（自动生成或通过 `--token ` 或环境变量 `NETWATCH_TOKEN`） - Fernet 加密的会话 cookie，密钥持久化存储于 `~/.config/netwatch/web.key` - 默认允许私有网络访问 (127/10/192.168/100.64)；通过 `NETWATCH_WEB_ALLOW=cidr,cidr,...` 添加公共 CIDR - 对所有 POST endpoint 进行 CSRF 源验证 - 通过 Web 禁用破坏性命令 - 对出站 OSINT 进行 SSRF 保护（安全关闭，拒绝私有 IP） - 速率限制：每个 IP 每分钟 20 条命令，每分钟 3 次高消耗命令 - Web 扫描命令的 CIDR 最大为 /20 - 在函数入口处进行 Nmap 目标验证（正则表达式 + flag 白名单） ## 命令 ### OSINT（16 种工具） | 命令 | 描述 | |---------|-------------| | `geo ` | IP 地理定位 | | `whois ` | WHOIS 查询 | | `dnsinfo ` | DNS枚举 (A/AAAA/MX/NS/TXT/SOA/CNAME/SRV) | | `rdns ` | 反向 DNS | | `ssl [port]` | TLS 证书检查 | | `secheaders ` | 安全头部审计 + 评级 | | `techstack ` | Web 技术指纹识别 | | `ping [count]` | 抖动分析 + TTL 操作系统猜测 | | `health ` | 完整配置文件（ping + SSL + 头部 + 技术 + 地理位置 + DNS） | | `etrace ` | 带有逐跳 GeoIP 的增强型 traceroute | | `portscan ` | 基于 Socket 的 Top 1000 端口扫描 | | `subnet [cidr]` | 多线程 ping 扫描 | | `crt ` | 证书透明度搜索 | | `headers ` | HTTP 响应头 | | `asn ` | ASN/BGP 信息 | | `abuse ` | IP 信誉检查 | | `speed` | 网络速度测试（下载/上传/ping） | | `ifinfo` | 本地接口信息 + 路由表 | ### 扫描 | 命令 | 描述 | |---------|-------------| | `scan [preset]` | Nmap 扫描（快速/SYN/UDP/ping/完整） | | `deep ` | 所有端口 + 漏洞脚本 | | `stealth ` | 通过 Tor 进行 SYN 扫描 | | `recon ` | 完整的 OSINT 配置文件 | | `fullrecon ` | 7 阶段侦测链 | | `sweep [cidr]` | ARP + ping + 端口扫描 | | `banner ` | 服务 banner 抓取 | | `trace ` | Traceroute | ### 跟踪与捕获 需要 root 权限。在 passive 模式下自动禁用。 | 命令 | 描述 | |---------|-------------| | `track [secs]` | 实时数据包跟踪（tshark） | | `conns ` | TCP 会话捕获 | | `sniff [secs]` | Raw payload 捕获 | | `trackdns ` | DNS 查询捕获 | | `pcap start/stop` | PCAP 录制 | ### 防御 | 命令 | 描述 | |---------|-------------| | `block ` | iptables DROP（仅限 root） | | `unblock ` | 移除拦截（仅限 root） | | `blockall attackers` | 拦截所有 honeypot IP（仅限 root） | | `diffarp` | ARP 表更改检测 | ### 系统 | 命令 | 描述 | |---------|-------------| | `status` | 服务信息 + 运行时间 | | `dashboard` / `d` | 返回仪表盘屏幕 | | `clear` | 清除控制台缓冲区 | | `help` | 显示完整的参考覆盖层 | | `rotate-key` | 新的 Fernet 密钥（使 Web 会话失效） | | `rotate-token` | 新的 Web 身份验证 token（使会话失效） | ### 智能过滤器 | 命令 | 描述 | |---------|-------------| | `top [n]` | Top N 通讯者 | | `sus` | 可疑主机（威胁 > 0） | | `new [mins]` | 最近出现的主机 | | `loud` | 触及最多端口的主机 | | `find ` | 搜索所有数据 | | `ports ` | 使用特定端口的主机 | | `country ` | 按国家/地区过滤 | ### 批量操作 ``` scanall [list] reconall [list] geoall [list] whoisall [list] ``` 列表：`hosts` · `attackers` · `arp` · `nmap` · `watchlist` · `tracked` · `blocked` 使用 `@N` 按索引引用 IP：`scan @3` 扫描当前列表中的第 3 个 IP。 ### 代理 / Tor ``` proxy add socks5 127.0.0.1:9050 proxy list proxy test proxy rotate proxy start proxy stop ``` ### Mesh Radio ``` mesh send mesh status mesh nodes mesh alert on/off ``` ## Honeypot | 服务 | 端口 | 捕获内容 | |---------|------|----------| | **HTTP NVR 面板** | 8080 | 凭据、会话 token、API 探测 | | **Telnet DVR** | 2323 | 登录尝试、shell 命令、恶意软件下载 | | **FTP 诱饵服务器** | 2121 | 凭据、击键记录、文件上传（最大 10MB） | | **RTSP 摄像头** | 8554 | 身份验证探测、流请求 | 所有事件均以 JSON 记录，数据经过 ANSI 剥离和净化。每个服务的连接数限制（最多 50 个）。FTP 具有路径遍历保护和文件名净化功能。 ### 会话重放 → GIF 将任何 FTP 会话日志转换为可观看的 asciinema 回放和 GIF： ``` python3 tools/replay_to_gif.py logs/ftp_session__.log demo.gif ``` 保留真实的攻击者节奏，压缩空闲停滞。GIF 步骤需要 [`agg`](https://github.com/asciinema/agg)。 ## GraphQL API 安装 `graphene` 后可在 `:9090/graphql` 使用。 ``` { hosts(minThreat: 10, limit: 20) { ip hostname threatScore tags } } { honeypotEvents(service: "telnet") { time ip summary } } mutation { runCommand(cmd: "geo 8.8.8.8") { output } } ``` ## 测试 ``` python3 -m pytest tests/ -q # 1900 项测试，在 Pi 5 上约需 30 秒 ``` Lint（CI 阈值 `--fail-under=9.0`）： ``` pylint $(git ls-files '*.py') --fail-under=9.0 ``` ## 安全模型 - 所有子进程调用均使用参数列表，从不使用 `shell=True` - 在函数入口进行 Nmap 目标正则表达式验证 + flag 白名单 - 对所有记录的数据进行 ANSI 转义剥离（防止日志注入） - 通过 `os.path.realpath` 检查阻止 FTP 上传路径遍历 - 使用 `threading.Event` 同步 FTP 数据连接 - 会话存储受 TTL 驱逐限制 - 日志轮转大小为 50MB - SSRF 保护：在出站 OSINT 上拒绝私有 IP，在 DNS 错误时安全关闭 - 安全决策从不信任 PTR 记录 - Flask 密钥在每次启动时随机生成 - Fernet 加密的 Web cookie — 无明文回退 - 通过 RLock 同步实现线程安全渲染 - GraphQL 查询复杂性受限（深度 7，别名 10，长度 4000） - Web API 速率限制：每个 IP 每分钟 20 条命令，每分钟 3 次高消耗命令 - Web 扫描命令的 CIDR 最大为 /20 ## 需求 | 组件 | 详情 | |-----------|---------| | **操作系统** | Linux（Debian、Ubuntu、Raspbian、Parrot、Kali）— 也可在 Termux（Android）上以 passive 模式运行 | | **Python** | 3.9+ | | **Root** | 推荐（raw socket、iptables、绑定小于 1024 的端口）。非 root 和 Termux 以 passive 模式运行（honeypot、OSINT、Web、nmap connect-scan）。 | | **系统** | nmap, tshark, tcpdump, traceroute | | **Python** | flask, requests, python-whois, dnspython, markupsafe, cryptography | | **可选** | graphene, flask-graphql, meshtastic, speedtest-cli | 已在 Raspberry Pi 5、Parrot OS 和 Termux（Android，passive 模式）上测试。 ## 部署 ``` git clone https://github.com/Mattmorris-dev/netwatch-sec.git && cd netwatch-sec sudo apt install nmap tshark tcpdump traceroute pip3 install -r requirements.txt # 系统范围安装 sudo ln -s $(pwd)/netwatch-start.sh /usr/local/bin/netwatch # 开机启动（可选） sudo cp netwatch.service /etc/systemd/system/ sudo systemctl enable --now netwatch ``` ## Headless 模式 未检测到 TTY（SSH 管道、systemd、Docker）= headless 模式。仅在 `:9090` 提供 Web 仪表盘。所有 honeypot 和流量监控仍保持活动状态。 ## 支持 NetWatch 由个人独立开发和维护。如果它为您节省了时间或保护了您的网络，请考虑打赏 — 这将维持项目的正常运转，并为下一个版本的开发工具提供资金。 [](https://buymeacoffee.com/pr0xy_22) ## 许可证 Apache 2.0 — 详见 [LICENSE](LICENSE)

标签：Flask, Python, 密码管理, 底层分析, 插件系统, 无后门, 网络安全, 蜜罐技术, 请求拦截, 逆向工具, 隐私保护