emrecdr/netlens
GitHub: emrecdr/netlens
一款面向家庭网络的 Python CLI 安全审计工具，集设备发现、指纹识别、漏洞评估、流量分析、WiFi 安全检测和变更追踪于一体，帮助用户全面掌握局域网资产与风险状况。
Stars: 0 | Forks: 0
# NetLens
[](https://github.com/emrecdr/netlens/releases)
[](https://www.python.org/downloads/)
[](CHANGELOG.md)
一款 Python CLI 工具，可深度扫描本地网络以发现设备，按类型对其进行分类，评估其安全状况，分析流量模式，检测固件漏洞，审计 WiFi 安全，跟踪随时间推移的变更，并映射网络拓扑。
专为个人/家庭网络安全审计而构建。
## 使用场景
- **家庭网络审计** — 发现您网络上的每一台设备，查看它们暴露了哪些端口，并获得可操作的安全修复建议
- **IoT 设备盘点** — 通过类型和置信度评分识别智能音箱、摄像头、集线器、打印机和其他 IoT 设备
- **安全评估** — 测试默认凭据、弱 TLS、过时固件、开放的管理面板以及已知的 CVE
- **流量监控** — 捕获并分析每个设备的流量模式、DNS 查询和信标行为
- **变更检测** — 跟踪随时间出现/消失的设备，比较扫描结果，并在发生变更时获取警报
- **网络分区规划** — 获取分区建议（受信任/IoT/隔离区）和防火墙规则
- **WiFi 安全** — 检测流氓接入点、隐藏的 SSID 和弱加密
## 系统要求
- **Python 3.13+**
- **nmap** 系统二进制文件
```
# macOS
brew install nmap
# Debian/Ubuntu
sudo apt-get install nmap
```
## 安装
```
# Clone 并使用 uv 安装
git clone && cd netlens
uv sync
# 可选：macOS WiFi 扫描支持
uv sync --extra macos
```
## 快速开始
```
# 使用 root 进行完整扫描（效果最佳 — 启用 ARP、流量捕获、WiFi、OS 检测）
sudo uv run netlens scan
# 无 root 扫描（功能受限，无流量/WiFi）
uv run netlens scan
# 扫描特定 subnet
sudo uv run netlens scan 192.168.1.0/24
# 查看安全发现
uv run netlens risks
# 生成 HTML 报告
uv run netlens report
```
## 命令
### 扫描
| 命令 | 描述 |
|---------|-------------|
| `netlens scan [NETWORK]` | 完整的网络发现和安全审计 |
| `netlens watch [NETWORK]` | 持续监控 — 设备变更时发出警报 |
### 分析
| 命令 | 描述 |
|---------|-------------|
| `netlens risks` | 按严重程度排序的安全发现及修复建议 |
| `netlens traffic` | 每个设备的流量模式、DNS 查询、异常情况 |
| `netlens segment` | 网络区域建议和防火墙规则 |
| `netlens topology` | ASCII 网络拓扑图（网关 → 交换机 → 设备） |
### 历史记录与报告
| 命令 | 描述 |
|---------|-------------|
| `netlens history` | 列出过去的扫描及其设备/发现计数 |
| `netlens diff ` | 比较两次扫描 — 新增、移除、变更的设备 |
| `netlens report` | 生成自包含的 HTML 安全报告 |
| `netlens devices` | 查看、标记和注释设备配置文件 |
### 设置
| 命令 | 描述 |
|---------|-------------|
| `netlens setup-geoip` | 下载 MaxMind GeoIP 数据库用于流量地理定位 |
### 全局标志
| 标志 | 描述 |
|------|-------------|
| `--version`, `-V` | 打印 `netlens ` 并退出 |
| `--quiet`, `-q` | 抑制预检和后续步骤面板 |
| `--no-color` | 禁用 ANSI 颜色（适用于 CI 日志） |
| `--no-progress` | 禁用实时扫描仪表板 |
| `--theme {auto,dark,light}` | 颜色主题变体 |
## 扫描选项
每个 `netlens scan` 标志、其功能及其影响的[阶段](#scan-pipeline)。显示了带有值标志的默认设置。
| 标志 | 默认值 | 作用 | 阶段 |
|------|---------|--------------|-------|
| `--full` | 关闭 (前 ~1000 个端口) | 扫描所有 65535 个 TCP 端口 | 2 (指纹识别) |
| `--deep` | 关闭 | 启用 NSE 漏洞脚本、DHCP 流氓检测、SNMP 团体字符串探测以及流量捕获期间的 ARP 跟踪 | 1, 3, 6 |
| `--ports TEXT` | — | 自定义端口列表（例如 `22,80,443` 或 `1-1024`）— 覆盖 `--full` | 2 |
| `--timeout INT` | 10 | 每台主机的扫描超时时间（以秒为单位） | 2 |
| `--capture-time INT` | 60 | 流量捕获持续时间（以秒为单位） | 6 |
| `--skip-creds` | 关闭 | 跳过默认密码测试 (SSH/Telnet/HTTP) | 5 |
| `--skip-traffic` | 关闭 | 跳过数据包捕获（速度更快，但会失去信标检测） | 6 |
| `--skip-wifi` | 关闭 | 跳过 WiFi 环境扫描 | 7 |
| `--skip-topology` | 关闭 | 跳过网络拓扑映射 | 扫描后 |
| `--wifi-interface TEXT` | 自动检测 | 用于监听模式的 WiFi 接口（例如 `en0`） | 7 |
| `--json` | 关闭 | 将结果以 JSON 格式输出到标准输出（机器可读） | 输出 |
| `--verbose`, `-v` | 关闭 | 显示扫描持续时间和每个阶段的额外详情 | 输出 |
### 常见组合
```
# 最重度的扫描 — 所有端口 + 深度检查（速度慢但彻底）
sudo uv run netlens scan --full --deep
# 快速分诊 — 仅发现和分类，无 creds/traffic/wifi
uv run netlens scan --skip-creds --skip-traffic --skip-wifi
# 自定义端口集（覆盖 --full）
uv run netlens scan --ports 22,80,443,8080
# 更长的流量捕获，用于捕获低速率 beaconing
sudo uv run netlens scan --capture-time 300
# 适配 CI / 日志的输出
uv run netlens --no-progress --no-color scan --json
```
## 扫描流水线
NetLens 按顺序运行 7 个阶段。每个阶段都可以独立失败，而不会阻塞其他阶段。
| # | 阶段 | 作用 | 需要 root 权限？ |
|---|-------|-------------|-------------|
| 1 | **发现** | ARP + mDNS + SSDP + DHCP 流氓检测 | 否（回退到 `arp -a`） |
| 2 | **指纹识别** | nmap 端口/服务、MAC 供应商、SNMP 探测、横幅抓取、favicon 哈希 | 否（仅连接扫描） |
| 3 | **SNMP 深度探测** | 接口表、ARP/路由表、团体字符串审计 | 否 |
| 4 | **分类** | 设备类型分配（12 个类别）、固件提取、置信度评分 | 否 |
| 5 | **安全审计** | 12 项并行安全检查（见下文） | 否 |
| 6 | **流量分析** | 数据包捕获、DNS 提取、异常检测 | 是 |
| 7 | **WiFi 安全** | 附近的网络、流氓 AP 检测、加密审计 | 是 |
### 安全检查（第 5 阶段）
| 检查 | 严重程度 | 检测内容 |
|-------|----------|----------------|
| 默认凭据 | CRITICAL | 使用常见默认值（root/root, admin/admin）的 SSH/Telnet/HTTP 登录 |
| CVE 查询 | CRITICAL–LOW | 通过 NVD API 根据 CPE/产品名称发现的已知漏洞 |
| 固件过时 | HIGH | 设备固件落后于制造商的最新版本 |
| TLS/SSL 分析 | HIGH–MEDIUM | 过期的证书、弱加密算法、自签名证书 |
| 管理面板 | MEDIUM | 无需身份验证即可访问的 `/admin`、`/login`、`/console` |
| UPnP 控制面 | HIGH | 接受 SOAP 命令的可控 UPnP 服务 |
| MQTT 注入 | HIGH | 接受发布命令的未经身份验证的 MQTT 代理 |
| REST API 暴露 | MEDIUM | 常见端口上未经身份验证的 API 端点 |
| DNS 重绑定 | MEDIUM | 容易受到 DNS 重绑定攻击的设备 |
| 协议安全 | MEDIUM | Telnet、FTP、未加密的 HTTP、弱 SSH 密码 |
| HTTP 方法 | MEDIUM | 启用了危险的方法（PUT、DELETE、TRACE） |
| 打印机漏洞 | MEDIUM | SNMP 团体字符串、默认管理密码 |
### 设备类型（第 4 阶段）
路由器、网关、托管交换机、智能家居集线器、智能音箱、智能电视、媒体播放器、媒体服务器、打印机、IP 摄像头、IoT 传感器、移动设备、单板计算机。
## 权限级别
NetLens 自动检测权限并优雅降级：
| 功能 | 带 `sudo` | 不带 `sudo` |
|---------|------------|-----------------|
| ARP 扫描 | 原始套接字（快速、完整） | `arp -a` 回退（仅限缓存） |
| 端口扫描 | SYN 扫描 + 操作系统检测 | 仅连接扫描 |
| 流量捕获 | 完整的数据包嗅探 | 跳过 |
| WiFi 扫描 | 监听模式 / CoreWLAN | 跳过 |
| LLDP/CDP 拓扑 | 被动帧嗅探 | 仅限网关 |
| DHCP 流氓检测 | 监听流氓服务器 | 跳过 |
| 安全检查 | 运行所有检查 | 运行所有检查 |
## 输出格式
所有命令均支持用于机器可读输出的 `--json`。终端表格会根据您的终端宽度自动调整列的可见性。
### HTML 报告
```
# 单次扫描报告
uv run netlens report
# 特定扫描的报告
uv run netlens report --scan-id abc123
# 对比报告（前后）
uv run netlens report --scan-id abc123 --compare def456
# 自定义输出路径
uv run netlens report -o my-report.html
```
报告是自包含的 HTML 文件（所有 CSS 均为内联，无外部依赖）。
## 数据存储
| 内容 | 位置 |
|------|----------|
| 扫描历史记录 + 设备配置文件 | `~/.netlens/history.db` (SQLite) |
| HTML 报告 | `docs/reports/`（相对于工作目录） |
| GeoIP 数据库 | `~/.netlens/geoip/`（可选） |
## GeoIP 设置（可选）
流量目的地地理定位需要免费的 MaxMind 数据库：
1. 在 [maxmind.com](https://www.maxmind.com/en/geolite2/signup) 创建一个免费账户
2. 生成一个许可证密钥
3. 运行：`uv run netlens setup-geoip`
## 默认端口集
NetLens 默认扫描 33 个常见的 IoT 端口：
```
21, 22, 23, 25, 53, 80, 81, 443, 554, 631, 1883, 1900,
3000, 3689, 5000, 5353, 5683, 6668, 8000, 8008, 8009,
8080, 8443, 8883, 9000, 9100, 49152, 49153, 49154
```
使用 `--full` 扫描所有 65535 个端口，或使用 `--ports` 指定自定义列表。
## 持续监控
```
# Watch 模式 — 每 5 分钟扫描一次，发生变化时发出警报
sudo uv run netlens watch
# 自定义间隔（秒）
sudo uv run netlens watch -i 600
# 轻量级 watch（跳过 traffic 和 WiFi）
sudo uv run netlens watch --skip-traffic --skip-wifi
```
## 网络分段
```
# 从最新扫描获取 zone 建议
uv run netlens segment
# Verbose — 显示每次分配的依据
uv run netlens segment -v
```
将设备分配到 4 个区域：**TRUSTED**、**SMART_HOME**、**IOT_ISOLATED**、**QUARANTINE**。生成用于区域间通信的防火墙规则。
## 设备配置文件
```
# 列出所有已知设备配置文件
uv run netlens devices list
# 深入了解特定设备
uv run netlens devices show AA:BB:CC:DD:EE:FF
# 显示设备的扫描历史记录
uv run netlens devices show AA:BB:CC:DD:EE:FF --history
# 标记和注释设备
uv run netlens devices edit AA:BB:CC:DD:EE:FF --name "Living Room TV" --label smart-tv --label trusted
```
## 开发
```
# 安装 dev 依赖
uv sync --group dev
# 运行 tests
uv run pytest -q
# Lint 和格式化
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```
### 发布
仓库根目录的 `VERSION` 文件是唯一的权威来源。`pyproject.toml`、
`netlens.__version__`、`pip show netlens` 和 `netlens --version` 都从
该文件中读取。有关发布流程，请参见 [docs/RELEASING.md](docs/RELEASING.md)。
## 技术栈
| 组成部分 | 技术 |
|-----------|-----------|
| 语言 | Python 3.13+ |
| 包管理器 | uv |
| CLI 框架 | Typer |
| 终端 UI | Rich |
| 数据包操作 | Scapy |
| 端口扫描 | nmap via python-nmap |
| mDNS 发现 | zeroconf |
| UPnP 发现 | ssdp |
| SSH 测试 | asyncssh |
| Telnet 测试 | telnetlib3 |
| SNMP 查询 | pysnmp 7 |
| CVE 查询 | nvdlib (NVD API) |
| HTTP 客户端 | httpx |
| 数据模型 | Pydantic |
| XML 解析 | defusedxml |
| MAC 供应商 | mac-vendor-lookup |
| GeoIP | geoip2 (MaxMind) |
| 报告 | Jinja2 |
| 数据库 | SQLite (stdlib) |
| 代码检查/格式化工具 | ruff |
| 测试 | pytest |
## 许可证
私有 — 个人/家庭网络安全审计工具。
标签：AES-256, Nmap, Python CLI, WiFi安全, 固件指纹识别, 家庭网络, 局域网扫描, 开源安全工具, 插件系统, 无线安全, 流量捕获, 漏洞评估, 物联网设备, 网络安全, 网络审计, 网络拓扑, 虚拟驱动器, 设备发现, 运行时操纵, 逆向工具, 逆向工程平台, 防御绕过, 隐私保护