Metadata-Version: 2.4
Name: yyds-net-scan
Version: 0.1.9
Summary: A lightweight, zero-dependency, root-free friendly network scanner and device discovery library for Python.
Home-page: https://github.com/yyds-fast/yyds-net-scan
Author: yyds-fast
Author-email: yyds.fast@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.8.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# yyds-net-scan: Fast, Zero-Dependency, Root-Free Network Scanner for Python

<p align="center">
  <a href="https://pypi.org/project/yyds-net-scan/"><img src="https://img.shields.io/pypi/v/yyds-net-scan.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/yyds-net-scan/"><img src="https://img.shields.io/pypi/pyversions/yyds-net-scan.svg" alt="Python Versions"></a>
  <a href="https://github.com/yyds-fast/yyds-net-scan/blob/main/LICENSE"><img src="https://img.shields.io/github/license/yyds-fast/yyds-net-scan.svg" alt="License"></a>
</p>

`yyds-net-scan` is an ultra-fast, zero-dependency, root-free friendly network scanner and LAN device discovery library for Python.

Designed to discover alive devices, resolve MAC hardware addresses, look up hardware manufacturers (OUI), probe open TCP ports, and grab service banners without requiring `sudo` privileges or bulky native C extensions.

Available both as a clean Python library and as a standalone CLI tool.

[中文文档 (README_CN.md)](README_CN.md)

---

## ✨ Features

- 🚀 **Root-Free & Non-Privileged First**: Uses UDP ARP trigger techniques + OS kernel neighbor tables + asynchronous TCP sockets to discover alive hosts and MACs without `sudo`.
- ⚡ **Auto-Discovery**: Automatically determines primary physical LAN network interface (Ethernet or Wi-Fi) and calculates subnet CIDR (e.g. `192.168.1.0/24`).
- 🏷️ **Built-in MAC OUI Database**: Automatically identifies hardware manufacturers (Apple, Huawei, Xiaomi, TP-Link, Intel, Realtek, Espressif/ESP32, Raspberry Pi, Cisco, etc.).
- 🌐 **Async TCP Port Scanner**: Scans open ports concurrently (`top20`, `top100`, or custom port ranges like `80,443,8000-8088`).
- 🔎 **Local Port to PID / Process Mapping**: When scanning localhost or local machine IPs, automatically associates open listening ports with process IDs (PID) and process names for quick port conflict debugging.
- 🕵️ **Service & Banner Detection**: Identifies service protocols and extracts banners (HTTP Server & Title, SSH versions, Redis Auth state, etc.).
- 💻 **Intuitive CLI & SDK**: Output formatted terminal tables or machine-readable JSON.

---

## 📦 Installation

```bash
pip install yyds-net-scan
```

Supports Python **>= 3.8**.

---

## 🚀 Quick Start: Python SDK

### 1. One-Line LAN Auto-Discovery

```python
from yyds_net_scan import auto_discover

# Auto-detects your primary LAN subnet and scans alive devices
devices = auto_discover()

for d in devices:
    print(f"IP: {d.ip:<15} MAC: {d.mac:<17} Vendor: {d.vendor:<12} Hostname: {d.hostname}")
```

### 2. Subnet Scan with Open Ports

```python
from yyds_net_scan import scan_network

# Scan CIDR subnet and check top 20 ports on alive devices
report = scan_network("192.168.1.0/24", ports="top20", timeout=0.8)

print(f"Found {report.alive_count} active devices in {report.duration_seconds:.2f}s:")
for host in report.hosts:
    print(f"- {host.ip} ({host.vendor}): {host.ports_display()}")
```

### 3. Fast Port Scanning on a Single Host

```python
from yyds_net_scan import scan_host_ports

ports = scan_host_ports("192.168.1.1", ports="22,80,443,8080", timeout=1.0)

for p in ports:
    print(f"Port {p.port} [{p.service}]: {p.banner}")
```

### 4. Asynchronous Support

```python
import asyncio
from yyds_net_scan import scan_network_async

async def main():
    report = await scan_network_async("192.168.1.0/24", ports="80,443")
    print(report.to_json(indent=2))

asyncio.run(main())
```

---

## 💻 Command Line Interface (CLI)

`yyds-net-scan` installs the `yyds-net-scan` CLI binary automatically.

### Auto Scan Current LAN

```bash
# Automatically detects current subnet and finds all alive devices
yyds-net-scan
```

### Scan Specific Subnet or IP Range

```bash
# Scan a CIDR subnet
yyds-net-scan scan 192.168.1.0/24

# Scan with ports
yyds-net-scan scan 192.168.1.0/24 --ports top100

# Output as JSON
yyds-net-scan scan 192.168.1.1-192.168.1.50 --json
```

### Inspect Open Ports & Local Process (PID)

```bash
# Scan a remote target
yyds-net-scan ports 192.168.1.1 --ports 1-1024

# Scan localhost to inspect open ports AND listening PID / Process name!
yyds-net-scan ports 127.0.0.1 -p 80,443,3000,5000,8080

# Sample output for localhost:
# Port   Proto  State  Service  PID    Process        Banner / Info
# -----  -----  -----  -------  -----  -------------  -------------------------
# 5000   tcp    open   http     677    ControlCenter  Server: AirTunes/870.14.1
# 8080   tcp    open   http     12345  node           Server: nginx/1.24
```

### View Local Network Interfaces & Subnets

```bash
yyds-net-scan ifaces
```

---

## 🛠️ CLI Options Reference

```text
usage: yyds-net-scan [-h] [-v] {scan,ports,ifaces} ...

positional arguments:
  {scan,ports,ifaces}
    scan               Scan local LAN or specified IP/CIDR.
    ports              Scan ports and identify services on a single host.
    ifaces             List local network interfaces and active subnets.

options:
  -h, --help           show this help message and exit
  -v, --version        show program's version number and exit
```

---

## 📄 License

[MIT License](LICENSE) © 2026 yyds-fast
