kazim-45/NETSPY
GitHub: kazim-45/NETSPY
基于 Scapy 和 Flask 的实时网络数据包嗅探器，通过浏览器仪表盘可视化展示流量协议分布、数据包详情和可疑活动告警。
Stars: 1 | Forks: 0
# NetSpy 🌐
**基于浏览器的实时网络数据包嗅探器仪表盘。**
使用 Scapy 从你的网络接口捕获数据包，实时进行解析，并将结果流式传输到浏览器中的深色主题仪表盘 —— 包括协议细分、主要攻击 IP、每秒数据包时间线，以及带有颜色编码危险级别的实时滚动数据包表。
```
sudo netspy → http://127.0.0.1:5000
```
![显示实时数据包捕获的 NetSpy 仪表盘，包括协议环形图、时间线迷你图和颜色编码的数据包表]
## 安装说明
```
git clone https://github.com/kazim-45/netspy.git
cd netspy
pip install -e .
```
在 Linux/macOS 上捕获数据包需要 root 权限（Scapy 需要访问原始套接字）。
## 使用方法
```
# 启动 dashboard（自动打开浏览器）
sudo netspy
# 自定义 port
sudo netspy --port 8080
# 在 local network 上 expose 以便其他设备查看
sudo netspy --host 0.0.0.0
# 不自动打开浏览器
sudo netspy --no-browser
# 帮助
netspy --help
```
然后在浏览器中：
1. 从下拉菜单中选择一个网络接口（或留空以自动检测）
2. 可选输入 BPF 过滤器 —— 例如 `tcp port 443` 或 `host 192.168.1.1`
3. 按下 **▶ START** —— 数据包将实时流入
4. 使用过滤按钮可专注于 TCP / UDP / DNS / HTTP 或可疑流量
5. 在搜索框中按 IP、端口或关键字进行搜索
## 界面说明
**侧边栏 —— 实时计数器**
- 已捕获的数据包总数和字节数
- 各协议细分：TCP、UDP、DNS、ICMP、ARP
- 发送流量最多的前 5 个源 IP
- 流量目标最多的前 5 个目的 IP
- 按端口统计的前 8 个服务（HTTP、HTTPS、DNS、SSH 等）
**图表行**
- 协议环形图 —— 按类型直观划分流量，每秒更新一次
- 每秒数据包迷你图 —— 过去 60 秒的流量波动
**数据包表**
- 每个捕获的数据包：时间、协议标签、源地址、目标地址、长度、信息
- 按危险级别进行颜色编码：🔴 危险（Telnet、RDP），🟡 警告（SSH 尝试），正常
- 过滤器：ALL / TCP / UDP / DNS / HTTP / HTTPS / ICMP / ARP / ⚠ SUSPICIOUS
- 搜索框：按 IP 地址、端口号或任意信息字符串进行过滤
- 随数据包到达自动滚动；当你向上滚动时停止自动滚动
## BPF 过滤器示例
BPF（Berkeley Packet Filter）是用于过滤捕获流量的标准语法。在按下 START 之前，将这些内容输入到过滤框中：
| 过滤器 | 捕获内容 |
|---|---|
| `tcp port 80` | 仅 HTTP 流量 |
| `tcp port 443` | 仅 HTTPS 流量 |
| `host 8.8.8.8` | 与 Google DNS 之间的流量 |
| `src net 192.168.1.0/24` | 来自你局域网的所有流量 |
| `icmp` | 仅 Ping 流量 |
| `not port 22` | 除 SSH 外的所有流量 |
| `udp port 53` | 仅 DNS 查询 |
## 检测内容与颜色编码说明
| 级别 | 颜色 | 示例 |
|---|---|---|
| 危险 | 红色 | Telnet (端口 23) —— 明文凭证，RDP (3389) |
| 警告 | 黄色 | SSH 连接尝试（无 ACK 的 SYN），SMB (445) |
| 信息 | 蓝色 | ICMP ping，ARP 请求 |
| 正常 | 青色 | HTTP、HTTPS、DNS、标准 TCP/UDP |
## 运行原理
NetSpy 同时运行两项任务：
**捕获线程** —— Scapy 的 `sniff()` 在后台线程中运行，为每个数据包调用一次回调函数。该回调将数据包解析为结构化的 dict（协议、IP、端口、标志、信息字符串、危险级别），并将其追加到一个限制最多 500 个数据包的线程安全环形缓冲区中。
**Flask 服务器** —— 提供仪表盘 HTML 并公开 JSON API。浏览器每秒轮询一次 `/api/packets?since=N`，仅获取它尚未看到过的数据包。它还会轮询 `/api/stats` 以获取侧边栏计数器和时间线数据。
这种设计意味着捕获引擎和 Web UI 是完全解耦的 —— 嗅探器永远不会等待浏览器，浏览器也绝不会阻塞嗅探器。
## 支持的协议
TCP、UDP、ICMP、ARP、DNS、HTTP、HTTPS、SSH、FTP、SMTP、Telnet、RDP、SMB、MySQL、PostgreSQL、Redis、MongoDB —— 通过端口号自动识别，并附带易于理解的标签。
## 项目结构
```
netspy/
├── netspy_pkg/
│ ├── __init__.py
│ ├── capture.py ← Scapy sniffer, packet parser, ring buffer
│ ├── app.py ← Flask routes and JSON API
│ └── cli.py ← netspy command entry point
├── templates/
│ └── dashboard.html ← single-file dashboard (HTML + CSS + JS)
├── pyproject.toml
├── requirements.txt
└── README.md
```
## 依赖项
- [`scapy`](https://scapy.net/) —— 数据包捕获与解析
- [`flask`](https://flask.palletsprojects.com/) —— Web 服务器与 API
- [`rich`](https://pypi.org/project/rich/) —— 终端输出
## 法律与道德使用声明
请仅在你拥有或获得明确授权监控的网络上捕获流量。在未经授权的情况下，在公共或企业网络上捕获流量在大多数国家都是非法的。请仅在你自己的机器或家庭实验室中使用 NetSpy。
## 许可证
MIT —— 随意使用、分支并在此基础上进行构建。
*由 [kazim-45](https://github.com/kazim-45) 开发 —— 与 [MetaHunter](https://github.com/kazim-45/MetaHunter)、[MilkyWay-CTF](https://github.com/kazim-45/MilkyWay-CTF)、[PassAudit](https://github.com/kazim-45/passaudit) 和 [LogWatch](https://github.com/kazim-45/logwatch) 共同作为网络安全 CLI 工具包的一部分。*
标签：Python, Scapy, 后端开发, 无后门, 网络嗅探, 网络流量分析, 运维监控, 逆向工具, 防御绕过