网络扫描器

使用 nmap 发现并识别本地或远程网络中的设备。可收集 IP 地址、主机名（通过反向 DNS 查询）、MAC 地址以及厂商信息。

安全第一：内置防护机制，可防止意外扫描公网 IP 段或缺乏合法私有路由的网络，从而避免因误操作被托管服务商投诉。

依赖要求

• nmap — 网络扫描工具（apt install nmap 或 brew install nmap）
• dig — DNS 查询工具（通常已预装）
• 推荐具备 sudo 权限，以便准确获取 MAC 地址

快速开始

# 自动检测并扫描当前所在网络
python3 scripts/scan.py

# 扫描指定 CIDR 网段
python3 scripts/scan.py 192.168.1.0/24

# 使用自定义 DNS 服务器进行反向解析
python3 scripts/scan.py 192.168.1.0/24 --dns 192.168.1.1

# 以 JSON 格式输出结果
python3 scripts/scan.py --json

配置

在 ~/.config/network-scanner/networks.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"
    }
  ]
}

随后可通过名称调用扫描：

python3 scripts/scan.py home
python3 scripts/scan.py office --json

安全特性

该扫描器内置多重安全检查，防止误用：

1. 黑名单机制 —— 配置于 blocklist 数组中的网段将始终被拦截
2. 公网 IP 检查 —— 禁止扫描非 RFC1918 定义的公网 IP 范围
3. 路由验证 —— 对临时指定的 CIDR，验证其是否经由私有网关可达

可信网络（在 networks.json 中显式配置）将跳过路由验证，因其已被用户明确授权。

# 被拦截 — 公网 IP 段
$ python3 scripts/scan.py 8.8.8.0/24
❌ BLOCKED: Target 8.8.8.0/24 is a PUBLIC IP range

# 被拦截 — 在黑名单中
$ python3 scripts/scan.py 10.99.0.0/24
❌ BLOCKED: 10.99.0.0/24 is blocklisted

# 允许 — 已配置的可信网络
$ python3 scripts/scan.py home
✓ Scanning 192.168.1.0/24...

命令

# 创建示例配置文件
python3 scripts/scan.py --init-config

# 列出已配置的网络
python3 scripts/scan.py --list

# 不使用 sudo 执行扫描（可能无法获取 MAC 地址）
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 参数）：

{
  "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 服务器可提升主机名解析成功率
• 将常用网络添加至配置文件，避免每次扫描均执行路由验证
• 将无法通过私有路由访问的网段加入 blocklist，防止误操作
• 可在脚本中扩展 MAC_VENDORS 映射表，提升设备厂商识别精度