LAN Device Scanner / 局域网设备扫描工具

English | 中文

---

English

A Python-based network scanning tool for discovering and listing all active devices in your local area network (LAN).

Features

• Smart Network Detection: Automatically detects the current active network interface and subnet without manual configuration.
• Active ARP Scanning: Sends ARP requests to the specified subnet to quickly discover hosts.
• Passive ARP Monitoring: Listens to ARP broadcasts on the network to discover devices joining the network in real-time.
• Device Information Query:
  • Retrieves device IP and MAC addresses
  • Queries device manufacturer (Vendor) via MAC address
  • Attempts to get device hostname via reverse DNS lookup
• Port Scanning (Optional): Can perform common TCP port scans on discovered hosts.
• Multi-threading: Uses multi-threading to parallelize device information queries for improved scanning efficiency.
• Flexible Configuration: Supports manual specification of network interface, target subnet, and listening duration via command-line arguments.
• Async API Support: Provides both synchronous and asynchronous interfaces for integration into other applications.

Installation

1. Clone or download this repository.

2. (Windows users only) Install Npcap.

   • Scapy depends on Npcap to capture and send network packets. Download and install from Npcap official website.
   • Important: During installation, make sure to check "Install Npcap in WinPcap API-compatible Mode".

3. Install required Python dependencies:

   pip install -r requirements.txt

Usage

The script requires administrator or root privileges to send and capture network packets.

• On Windows, please "Run as Administrator" in PowerShell or Command Prompt.
• On Linux or macOS, please use sudo.

Command Line Options

• -h, --help: Show help information.
• -t, --target: Target subnet to scan (CIDR format, e.g., 192.168.1.0/24). Auto-detected if not provided.
• -i, --iface: Specify network interface to use (e.g., eth0, en0). Auto-detected if not provided.
• -d, --duration: Duration for passive ARP listening (seconds). Default is 60.
• --ports: (Optional) List of TCP ports to scan, comma-separated (e.g., 80,443,8080).

Usage Examples

• Fully Automatic Scan (Most Common): Automatically find current network and scan, then listen for 60 seconds.

  # Windows (Run as Administrator)
  python scanIP.py
  
  # Linux / macOS
  sudo python scanIP.py

• Automatic Scan with Port Detection:

  sudo python scanIP.py --ports 80,443,22,3389

• Manual Subnet and Listen Time: Scan 192.168.0.0/24 subnet and listen for 2 minutes.

  sudo python scanIP.py -t 192.168.0.0/24 -d 120

• Using Async API Example:

  # Run the async example (English version)
  python example-English.py

Files Description

• scanIP.py - Main scanner module with both sync and async interfaces
• example.py - Chinese usage example demonstrating async API
• example-English.py - English usage example demonstrating async API
• requirements.txt - Python dependencies

Requirements

• Python 3.7+
• Scapy
• Npcap (Windows only)
• Administrator/root privileges

---

中文

这是一个基于 Python 的网络扫描工具，用于发现和列出局域网中的所有活动设备。

功能

• 智能网络检测: 自动检测当前活动的网络接口和所在网段，无需手动配置。
• 主动 ARP 扫描: 发送 ARP 请求到指定网段，快速发现主机。
• 被动 ARP 监听: 监听网络中的 ARP 广播，实时发现新加入网络的设备。
• 设备信息查询:
  • 获取设备的 IP 地址和 MAC 地址。
  • 通过 MAC 地址查询设备制造商 (Vendor)。
  • 尝试通过反向 DNS 查询获取设备的主机名 (Hostname)。
• 端口扫描 (可选): 可指定对发现的主机进行常见的 TCP 端口扫描。
• 多线程加速: 使用多线程并行处理设备信息的查询，提高扫描效率。
• 灵活配置: 支持通过命令行参数手动指定网络接口、扫描目标网段和监听时长。

安装

1. 克隆或下载本仓库。

2. (仅限 Windows 用户) 安装 Npcap。

   • Scapy 依赖 Npcap 来捕获和发送网络包。请从 Npcap 官网 下载并安装。
   • 重要: 在安装过程中，请务必勾选 "Install Npcap in WinPcap API-compatible Mode" (以 WinPcap API 兼容模式安装 Npcap) 选项。

3. 安装所需的 Python 依赖库：

   pip install -r requirements.txt

使用方法

脚本需要管理员或 root 权限来发送和捕获网络包。

• 在 Windows 上，请 “以管理员身份运行” PowerShell 或命令提示符。
• 在 Linux 或 macOS 上，请使用 sudo。

命令行选项

• -h, --help: 显示帮助信息。
• -t, --target: 要扫描的目标网段 (CIDR 格式，如 192.168.1.0/24)。如果未提供，将自动检测。
• -i, --iface: 指定要使用的网络接口 (例如 eth0, en0)。如果未提供，将自动检测。
• -d, --duration: 被动 ARP 监听的持续时间（秒）。默认为 60。
• --ports: (可选) 要进行 TCP 扫描的端口列表，以逗号分隔 (例如 80,443,8080)。

使用示例

• 全自动扫描 (最常用): 自动查找当前网络并扫描，然后监听 60 秒。

  # Windows (以管理员身份)
  python scanIP.py
  
  # Linux / macOS
  sudo python scanIP.py

• 自动扫描并进行端口探测:

  sudo python scanIP.py --ports 80,443,22,3389

• 手动指定网段和监听时间: 在 192.168.0.0/24 网段上扫描，并监听 2 分钟。

  sudo python scanIP.py -t 192.168.0.0/24 -d 120

• 使用异步 API 示例:

  # 运行异步示例（中文版本）
  python example.py

文件说明

• scanIP.py - 主扫描模块，包含同步和异步接口
• example.py - 中文使用示例，演示异步 API
• example-English.py - 英文使用示例，演示异步 API
• requirements.txt - Python 依赖项

系统要求

• Python 3.7+
• Scapy
• Npcap (仅限 Windows)
• 管理员/root 权限

---

License / 许可证

This project is open source. / 此项目为开源项目。

Contributing / 贡献

Feel free to submit issues and pull requests. / 欢迎提交问题和拉取请求。