介绍
# Network Scanner
使用 nmap 发现并识别本地或远程网络上的设备。收集 IP 地址、主机名（通过反向 DNS）、MAC 地址和供应商标识。
**安全第一：** 内置保护机制，防止意外扫描公共 IP 范围或不具备正确私有路由的网络 —— 避免收到托管提供商的滥用报告。
## 要求
- `nmap` - 网络扫描 (`apt install nmap` 或 `brew install nmap`) - `dig` - DNS 查询（通常已预装） - 建议使用 `sudo` 权限以发现 MAC 地址
## 快速开始
```bash # Auto-detect and scan current network python3 scripts/scan.py
# Scan a specific CIDR python3 scripts/scan.py 192.168.1.0/24
# Scan with custom DNS server for reverse lookups python3 scripts/scan.py 192.168.1.0/24 --dns 192.168.1.1
# Output as JSON python3 scripts/scan.py --json ```
## 配置
在 `~/.config/network-scanner/networks.json` 中配置命名网络：
```json { "networks": { "home": { "cidr": "192.168.1.0/24", "dns": "192.168.1.1", "description": "Home Network" }, "office": { "cidr": "10.0.0.0/24", "dns": "10.0.0.1", "description": "Office Network" } }, "blocklist": [ { "cidr": "10.99.0.0/24", "reason": "No private route from this host" } ] } ```
然后按名称扫描：
```bash python3 scripts/scan.py home python3 scripts/scan.py office --json ```
## 安全功能
扫描器包含多项安全检查，以防止意外滥用：
1. **黑名单** — `blocklist` 配置数组中的网络始终会被阻止 2. **公网 IP 检查** — 阻止扫描公网（非 RFC1918）IP 范围 3. **路由验证** — 对于临时 CIDR，验证路由是否使用私有网关
**受信任网络**（在 `networks.json` 中配置）会跳过路由验证，因为您已经明确批准了它们。
```bash # Blocked - public IP range $ python3 scripts/scan.py 8.8.8.0/24 ❌ BLOCKED: Target 8.8.8.0/24 is a PUBLIC IP range
# Blocked - in blocklist $ python3 scripts/scan.py 10.99.0.0/24 ❌ BLOCKED: 10.99.0.0/24 is blocklisted
# Allowed - configured trusted network $ python3 scripts/scan.py home ✓ Scanning 192.168.1.0/24... ```
## 命令
```bash # Create example config python3 scripts/scan.py --init-config
# List configured networks python3 scripts/scan.py --list
# Scan without sudo (may miss MAC addresses) python3 scripts/scan.py home --no-sudo ```
## 输出格式
**Markdown（默认）：** ``` ### Home Network *Last scan: 2026-01-28 00:10*
| IP | Name | MAC | Vendor | |----|------|-----|--------| | 192.168.1.1 | router.local | AA:BB:CC:DD:EE:FF | Ubiquiti | | 192.168.1.100 | nas.local | 11:22:33:44:55:66 | Synology |
*2 devices found* ```
**JSON (--json)：** ```json { "network": "Home Network", "cidr": "192.168.1.0/24", "devices": [ { "ip": "192.168.1.1", "hostname": "router.local", "mac": "AA:BB:CC:DD:EE:FF", "vendor": "Ubiquiti" } ], "scanned_at": "2026-01-28T00:10:00", "device_count": 2 } ```
## 用例
- **设备清单**：跟踪您网络上的所有设备 - **安全审计**：识别未知设备 - **文档**：生成用于文档的网络拓扑图 - **自动化**：与家庭自动化集成，以检测设备存在情况
## 提示
- 使用 `sudo` 进行准确的 MAC 地址检测（nmap 需要 ARP 权限） - 配置本地 DNS 服务器以获得更好的主机名解析 - 添加配置的网络，以便在每次扫描时跳过路由验证 - 将无法私下访问的网络添加到黑名单，以防止意外发生 - 扩展脚本中的 `MAC_VENDORS` 以更好地识别设备