ViperShard/ViperScan
GitHub: ViperShard/ViperScan
ViperScan 是一款零依赖纯 Python 局域网扫描器，帮助用户发现并审计网络中所有设备的安全状况。
Stars: 0 | Forks: 0
# ⬡ ViperScan
**了解你所在的网络上的每一台设备 —— 以及哪些设备需要额外关注。**
ViperScan 会扫描本地网络，识别每台设备的供应商和可能
的类型，并**标记出那些重要的设备**：摄像头、监控 DVR、常开的
语音助手、隐藏以躲避 ping 的主机、暴露的管理面板，以及
任何它无法识别的设备。走进任何一家咖啡馆、办公室、Airbnb 或酒店，
运行一条命令，就能看到与你同在网络中的设备。
```
git clone https://github.com/ViperShard/ViperScan
cd ViperScan && python3 viperscan.py # live dashboard → http://localhost:8731
```
它是**纯 Python 编写的，仅使用标准库。** 不需要 `pip install`，不需要 scapy，也不需要
root 权限。
### 平台支持
ViperScan 是 **Linux 优先** 的 —— 这是它的构建和测试平台，也是
所有功能都能正常运行的地方。
| 操作系统 | 状态 |
|---|---|
| **Linux** | ✅ 完全支持 —— 所有功能 |
| **macOS** | ⚠️ 部分支持 —— 核心扫描、Web 仪表盘和审计运行；如果未安装 nmap 的 OUI 数据库，供应商 ID 将回退到内置的品牌映射表；**Wi-Fi 定位器无法工作**（它需要 Linux 的 `AF_PACKET` + 监控模式） |
| **Windows** | ❌ 暂不支持 —— 发现功能依赖于 Linux 网络工具（`ip`, `iw`）和 `/proc`；需要移植。欢迎提交 PR |
**Wi-Fi RF 定位器**（`--locate`）在设计上**仅限 Linux** —— 它使用原始
`AF_PACKET` 监控模式套接字。其他所有功能原则上都是可移植的；只是
Linux 的特定假设尚未针对 macOS/Windows 进行抽象。
## 它的功能
| 阶段 | 方式 |
|---|---|
| **发现主机** | 多线程 ICMP ping 扫描填充内核 ARP 缓存，然后将其读回以获取 IP↔MAC。捕获那些*忽略* ping 但仍响应 ARP 的设备（并将其标记为隐藏）。对于极其顽固的设备，可选 TCP-knock 回退机制。 |
| **识别供应商** | 使用系统上已有的任何 OUI 数据库（nmap 的 4.2 万条记录表、Wireshark 的 `manuf` 或 IEEE `oui.txt`）进行离线 MAC→供应商查询，此外还包含内置的摄像头/IoT 品牌映射表，因此与安全相关的供应商*始终*能被识别。 |
| **指纹识别** | 对摄像头/DVR/IoT/管理端口进行 TCP connect 扫描，探测 HTTP `Server`/`` + RTSP 标语（摄像头会泄露其型号），并通过 **SSDP、mDNS/Bonjour 和 NetBIOS** 进行名称发现，以获取友好名称和型号。 |
| **标记** | 透明的规则引擎会标记摄像头、DVR/NVR、麦克风、隐藏主机、未知设备、telnet/暴露的/远程控制服务 —— 每一项都附带简明的英文原因。 |
| **记忆** | 记录它在*每个网络*上看到过的设备（以网关 MAC 为键，因此家庭 ≠ 咖啡馆）。新的 MAC 会获得一个 `NEW` 标记 —— 这样“刚刚出现了什么？”只需一次扫描即可知晓。 |
### 标记说明
| 标记 | 含义 |
|---|---|
| `CAMERA` / `CAMERA?` | 网络摄像头（RTSP/ONVIF 端口、摄像头供应商或型号标语） |
| `SURVEILLANCE` | DVR / NVR / 多摄像头录像机 |
| `MIC` | 始终监听的语音助手（Echo、Nest、HomePod 等） |
| `HIDDEN` | 响应 ARP 但忽略 ICMP —— 未对外广播自己 |
| `UNKNOWN` | 完全无法识别 —— 值得手动查看 |
| `INSECURE` | 暴露的 Telnet / 已知脆弱的服务 |
| `EXPOSED` | 可访问的 Web/管理登录面板 |
| `REMOTE` | 开放的 RDP / VNC / ADB 远程控制服务 |
| `RANDOM-MAC` | 随机/本地管理的 MAC（隐私保护 —— 或是伪装） |
| `NEW` | 首次在此网络中检测到 |
| `ROUTER` | 网关本身 |
## 用法
**一条命令 —— 一切都在仪表盘中。** 只需运行：
```
python3 viperscan.py # or just `viperscan` if you ran pipx install .
```
它会在 **http://localhost:8731** 启动实时 Web 应用（并自动打开你的
浏览器）。在该页面上，你可以控制每种模式，而无需触碰命令
行：
- **扫描模式** —— `Quick`（快速） / `Deep`（深度） / `Unhide`（取消隐藏）（切换时会立即重新扫描）
- **网络** —— 输入任何 CIDR（例如 `10.0.0.0/24`）并点击 *Scan*（扫描），或留空以扫描当前局域网
- **自动** —— 重新扫描间隔（15 秒 …… 每小时）
- **立即扫描** —— 强制立即重新扫描
- **过滤器** —— 全部 / 已标记 / 摄像头 / 麦克风 / 未知 / 新增
### 点击设备进行调查
点击任意卡片可打开**“关于此设备”**面板。在后台，ViperScan 会：
1. **查找其 Web/管理面板** —— 通过 HTTP+HTTPS 探测每个 Web 端口，对其进行排名，并**自动在新的浏览器标签页中打开最佳的一个**，以便你可以登录
查看。（系统能检测到在每个路径都返回 `200` 的单页应用，因此
你不会得到误报。）
2. **运行深度探测** —— 使用 nmap 探测服务/版本（如果使用
`sudo` 启动还会检测操作系统），并检查常见的管理
路径。
3. **检查出厂密码** —— 针对设备的供应商，它会尝试通过 HTTP Basic auth 进行一小部分
已知默认登录凭据的测试。如果其中一个仍然有效，
该设备将获得一个红色的 **`DEFAULT-CREDS`** 标记，准确告诉你
哪个 `user / password` 可以打开它 —— 以便你及时修改。
### 针对设备的单项安全审计
点击设备还会运行**安全审计**，并给出一个**风险评分**
（0–100）。它分为两个层级，因此嘈杂的（高影响的）操作是可选的：
**静默层级 —— 自动运行，足迹低：**
- **TLS 证书**检查（自签名 / 已过期）
- 来自精选的、离线设备→CVE 映射表的**已知 CVE 提示**（例如，标记
具有已知身份验证绕过 CVE 的 Hikvision/Dahua 摄像头类别，以提示检查固件）
- **明文管理**检测（通过纯 HTTP 提供的登录页面）
- **互联网暴露** —— 通过 **UPnP** 查询你的路由器以获取 WAN 端口转发，
并标记任何可从**公共互联网**访问的设备
- 将 ViperScan 自身的标记（telnet、远程控制等）转化为调查结果
**深度层级 —— “🔍 Deep audit” 按钮（影响较大，但不猜测密码）：**
- **nmap** 服务/版本（以及作为 root 时的操作系统）
- **RTSP 开放流检查** —— 确认摄像头的视频是否可以在**无密码**的
情况下观看，并提供 `ffplay rtsp://…` 命令供你验证
- **匿名 FTP**
**凭据层级 —— 独立的 “🔑 Test factory passwords” 按钮 + 同意提示：**
- 通过 HTTP **Basic 和 Digest** 进行**默认凭据检查**，使用针对特定供应商的
出厂密码列表（在首次命中时停止）。
- **弱密码审计**（复选框可选） —— 还会尝试大约 30 个最常见的
弱密码。**有界限**（硬性限制 60 次尝试）且**具备锁定感知**
（一旦设备开始阻止访问，它就会停止）。它是一项密码强度
*审计*，特意**不**做无界限的字典破解 —— 真正的
暴力破解器会锁定或变砖你自己的设备。
- **锁定 / 速率限制检测** —— 发送几次错误的登录请求，查看
设备是否具备抵御暴力破解的能力。如果一台设备接受无限次猜测
且没有节流限制，其本身就会被标记（说明它可被暴力破解）。
- 与深度审计完全分开，因为它会发送设备会记录在日志中的**真实登录
尝试** —— 除非你点击此按钮并确认“我拥有 / 我被授权测试此设备”的对话窗口，否则它不会猜测任何密码。
**🛡 加固检查清单** —— 每次审计都会附带一份具体的、针对设备的“如何
对其进行强化”的列表（在 VLAN 上隔离 IoT、设置唯一密码、启用
锁定/2FA、移除互联网暴露、禁用 Telnet、更新固件等）。它将显示在设备模态框和导出的安全报告中。
每项调查结果都包含严重程度、解释和修复建议；红色的
标记（`DEFAULT-CREDS`、`OPEN-CAM`、`INTERNET`、`OPEN-FTP`）会被固定在设备卡片上。
## 操作员 / 红队功能
ViperScan 是为**授权的**评估而构建的，并具备相应的脚手架来保持
这种合规性：
- **🛡 授权范围** —— 你需要声明你被允许测试哪些 CIDR。
静默层级可以在任何地方运行（它只是进行识别），但**主动
层级拒绝针对你授权范围之外的任何 IP 运行** —— 仪表盘会阻止它们，并提供一个“Authorize this network”（授权此网络）按钮。这正是
从构建架构上确保公开发布的版本保持白帽合规的原因。
- **📄 网络安全报告** —— 一键生成可打印的、独立的 HTML
报告（`/api/report`），按风险评分对每台设备进行排名，包含
所有调查结果、CVE 链接和建议。打印为 PDF 即可作为交付物。
- **🔔 持续监控 + 警报** —— 每次重新扫描都会与上次进行差异对比；
新设备、新打开的端口，或设备变得**暴露于互联网**，
都会触发警报（支持可选的浏览器通知）。
- **🕑 历史记录与时间线** —— 每台设备都会在其模态框中获得一个重建的时间线（首次
发现、端口开放历史、在线/离线时间窗口：*“3 天前首次发现，
隔夜离线 8 小时，现已恢复在线”*），此外 **History**（历史记录）
面板会显示整个网络中的异常情况 —— *“摄像头凌晨 2 点离线”*、
*“新的管理/远程服务开启”*、*“设备隔夜出现”*、*“变为
暴露于互联网”*。一键 **Export history (JSON)（导出历史记录 JSON）** 即可生成合规记录。
- **🗒 操作日志** —— 每一项主动操作（深度审计、密码测试、范围
更改、报告）都会带有时间戳记录到 `~/.viperscan/engagement.jsonl` 中，作为审计
轨迹。
状态保存在 `~/.viperscan/` 目录下：`scope.json`、`engagement.jsonl`、
`events.jsonl`、`known_devices.json`、`dashboard.json`。任何数据都不会离开
操作员的机器。
## 设备智能与深度
- **重命名、标记与信任设备** —— 点击设备为其指定自定义名称
（“Michael 的 Wyze 摄像头”）、进行标记、添加备注，并将其标记为受信任/不受信任。所有这些信息都**能在重新扫描和重启后保留下来**，并且仪表盘也会记住你的
扫描模式 / 网络 / 间隔。
- **DHCP 租约主机名** —— 如果 ViperScan 运行在 DHCP 服务器（Pi-hole /
dnsmasq / 路由器设备）上，它会读取租约文件以获取权威名称，
将 `UNKNOWN` 设备转换为已命名设备。
- **端口时间线** —— 每台设备都会跟踪每个端口首次开放的时间（“开放
自……”），因此你可以区分长期存在的服务和新服务。
- **原生 TLS 状态** —— 通过 Python 自身的
`ssl` 进行协议 + 密码 + 证书 + HSTS 检查（标记 TLS ≤ 1.1、弱密码、过期/自签名证书） —— 无需
外部 `openssl`。
- **真实的 UDP 扫描** —— 针对 DNS、NTP、TFTP、SNMP 和
CoAP 的特定协议探测，这是 TCP 扫描无法看到的，此外还针对有速率限制的设备提供自适应重试。
- **IoT 暴露检查** —— 开放的 MQTT broker、开放的 CoAP endpoint，以及
非破坏性的 **SNMP-write** 测试（可通過 SNMP 重新配置）。
- **JSON 导出** —— ⬇ Export（导出）会从仪表盘下载完整的设备清单
（与 CLI 的 `--json` 保持一致）。
- **活动状态 —— “它现在在做什么？”** —— 点击设备 → Check activity（检查活动）：
存活状态（在线 / 延迟 / 抖动 / 丢包）、此时哪些服务正在运行、
摄像头的推流是否确实已启动、启用了 SNMP 的设备的
**真实吞吐量**（实时 ↓/↑ 每秒比特数 + 运行时间），以及它扮演的角色
（AirPlay 接收器、RTSP 源、DNS 解析器、打印机、MQTT broker 等）。
- **📡 Locate（定位） —— Wi-Fi 冷热寻找器** —— 选择一个设备并在物理上靠近它进行
寻找：一个实时的信号强度计会在你靠近时上升（🔥 变暖 / ❄
变冷）。这是寻找隐藏摄像头/追踪器的真实有效方法。纯 Python 编写的 802.11
捕获（radiotap RSSI，无需 scapy）。
sudo python3 viperscan.py --locate 192.168.1.50 # 实时终端信号计
**在仪表盘中一键操作：** 使用 sudo 运行仪表盘
（`sudo python3 viperscan.py --web`），点击设备 → **🛰 Find this device（定位此设备）**。
它会**自动检测**支持监控模式的适配器（优先选择第二个适配器，以便你的
主连接保持在线），将其切换到监控模式，**自动 ping 设备
以保持其唤醒/传输状态**，捕获 RSSI，并显示实时仪表盘 —
然后点击 **Stop**（停止）会恢复适配器。无需终端，无需手动执行 `iw`/`nmcli`。
如果没有 sudo 权限，它会解释如何启用该功能（CLI 命令仍然
有效）。
### 更喜欢终端？
一切仍然可以通过 `--cli` 进行脚本化（或任何意味着包含 CLI 的输出标志）：
```
viperscan --cli # one-shot flagged report in the terminal
viperscan --cli --deep # full port list — slower, more thorough
viperscan --cli --unhide # squeeze identity out of quiet/HIDDEN hosts
viperscan --cli --alerts-only # only the flagged devices
viperscan --watch 30 # rescan every 30s, announce what changed
viperscan --json out.json # machine-readable output
viperscan --net 10.0.0.0/24 # (web) open the dashboard pre-pointed at a subnet
```
### “取消隐藏”静默设备
`HIDDEN` 标记仅意味着设备响应了 **ARP**（因此我们知道它在那儿，
并且我们拥有它的 MAC + 供应商），但忽略了我们的 **ICMP ping** —— 这几乎总是
防火墙/隐私设置，而不是什么恶意的举动。它并非不可见，只是静默而已。
为了识别静默设备的真实身份，请运行 `--unhide`。除了
正常扫描之外，它还会针对每台主机添加：
- 一次**全端口扫描**（意味着包含 `--deep`），
- 一次 **SNMP** `sysDescr`/`sysName` 探测 (UDP/161) —— 单凭这一项往往就能准确指出打印机、
路由器、交换机、摄像头和 IoT 的确切品牌/型号/固件，
- 对每台主机进行一次 **NetBIOS** 名称查询（而不仅仅是那些播发 SMB 的主机），以及
- 对于那些*仍然*完全黑暗的主机，执行一次 **nmap** 服务/版本探测
（如果你使用 `sudo` 运行，还会进行操作系统检测）。
```
viperscan --unhide # deep-identify everything
sudo viperscan --unhide # adds nmap OS detection + a true ARP sweep
viperscan --unhide --no-nmap # skip the (slower) nmap step
```
注意：由于包含 SNMP/NetBIOS/nmap 探测，`--unhide` 的速度较慢，而且如果
设备开启了防火墙且没有运行任何服务，可能*仍然*会返回 `UNKNOWN` ——
此时它的 MAC 供应商是你最好的线索。`HIDDEN` 标记本身会保留
（这是对主机 ping 行为的真实描述）；改变的是，
设备通常会获得真实的名称和类型，而不是 `UNKNOWN`。
无需安装任何程序即可直接运行：
```
python3 viperscan.py # from inside the ViperScan/ folder
# 或
./viperscan-run.sh --web
```
### 安装（可选 —— 为了在你的 PATH 中使用 `viperscan` 命令）
ViperScan 在未安装的情况下也能正常运行（见上文）。如果你更希望在
任何地方都只输入 `viperscan`，那就安装它吧 —— 它仍然是仅限标准库的，安装过程只是在你的
`PATH` 中放入一个启动器：
```
pipx install . # recommended (isolated); from inside ViperScan/
# 或
pip install --user .
viperscan # now works anywhere → same as python3 viperscan.py
```
### Docker
```
docker compose up # dashboard → http://localhost:8731
# 或
docker build -t viperscan .
docker run --rm -it --net host viperscan # dashboard
docker run --rm -it --net host viperscan --cli # one-shot terminal report
```
`--net host` 是**必需的** —— ViperScan 通过主机局域网上的 ARP/ping 发现设备，
这是桥接容器无法看到的。在 `/data` 上挂载卷
（`-v viperscan-data:/data`）以在多次运行之间保留范围/已知设备/配置。
### Prometheus 指标
仪表盘以 Prometheus 文本格式暴露了一个 `/metrics` endpoint ——
设备计数、在线/新增/已标记的总数、开放端口计数、每个标记和
每个类别的指标，以及扫描耗时。将 Prometheus 指向它并在 Grafana 中绘制你的
网络图表：
```
scrape_configs:
- job_name: viperscan
static_configs: [{ targets: ["localhost:8731"] }]
```
（`/metrics` 仅包含只读计数 —— 没有针对设备的详细信息。它在
你绑定的任何地址上提供服务；除非你的抓取
主机需要，否则请将仪表盘保持在回环地址上，然后在受信任的网络上使用 `--bind 0.0.0.0`。）
### 键盘与鼠标
在仪表盘中：<kbd>s</kbd> 立即扫描 · <kbd>e</kbd> 导出 ·
<kbd>/</kbd> 跳转到网络输入框 · <kbd>?</kbd> 快捷键帮助 ·
<kbd>Esc</kbd> 关闭。**右键点击任何设备**可复制 IP / MAC / 供应商并
一键进行 OUI 查询。
### 可选：更清晰的发现
- 以 **root** 身份运行并安装 `scapy`，ViperScan 就会添加真正的 ARP 广播
扫描（以捕获最后遗漏的设备）。这两者都不是必需的 —— 无需 root 的路径
已经能找到所有响应 ARP 的设备。
- `--deep` 会扫描完整的约 60 个端口列表，而不是快速默认的端口集。
## 这合法/安全吗？
ViperScan 仅查看你**已经连接到**的网络 —— 这与
你的笔记本电脑上“查看此网络上的设备”功能相同，只是要全面和具备安全意识得多。它倾向于被动方式（ping、读取 ARP、轻量级 TCP
连接、标准发现多播）。**仅扫描你拥有或被授权评估的网络。** 端口扫描你无法控制的网络可能会违反
它们的可接受使用政策或当地法律。
一切都保留在你的机器上：设备记忆保存在
`~/.viperscan/known_devices.json` 中，不会向任何地方发送任何内容。
## 它如何保持零依赖
- **发现：** 系统 `ping` + `ip neigh`（或 `/proc/net/arp`）
- **供应商：** 解析系统上已存在的 OUI 数据库
- **指纹识别：** 原始 `socket` TCP 连接 + 手工编写的 SSDP/mDNS/NetBIOS
- **仪表盘：** 使用标准库 `http.server` 提供的一个独立 HTML 页面服务
无第三方包。需要 Python 3.9+。
*ViperShard 工具包的一部分。*</div><div><strong>标签：</strong>Maven构建, Python, 占用监测, 局域网扫描, 插件系统, 无后门, 网络发现, 资产管理, 逆向工具</div></article></div>
<!-- 人机验证 -->
<script>
(function () {
var base = (document.querySelector('base') && document.querySelector('base').getAttribute('href')) || '';
var path = base.replace(/\/?$/, '') + '/cap-wasm/cap_wasm.min.js';
window.CAP_CUSTOM_WASM_URL = new URL(path, window.location.href).href;
})();
</script>
</body>
</html>