Metadata-Version: 2.1
Name: scanlan
Version: 0.1.0
Summary: Find devices on your LAN without the headache.
Project-URL: Homepage, https://github.com/syntaxerror019/scanlan
Project-URL: Issues, https://github.com/syntaxerror019/scanlan/issues
Keywords: network,lan,scan,nmap,arp,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# scanlan

**Find devices on your LAN without losing your mind.**

```
  scanlan  → 192.168.1.0/24

  IP ADDRESS       HOSTNAME              MAC ADDRESS        VENDOR
  ──────────────────────────────────────────────────────────────────────────
  192.168.1.1      router.local          A4:77:33:12:AB:CD  Google
  192.168.1.42     —                     B8:27:EB:4F:12:99  Raspberry Pi Foundation
  192.168.1.55     macbook-pro.local     AC:BC:32:88:11:22  Apple
  192.168.1.101    android-phone.local   38:AA:3C:77:44:55  Samsung

  4 devices found on 192.168.1.0/24
```

nmap is great. But when you just want to find your new Pi on the network, it's overkill. scanlan does the one thing you actually need: **scan your subnet, show you what's there, and tell you what it is.**

Zero dependencies. Pure stdlib. Works on Linux, macOS, and Windows.

---

## Install

```bash
pip install scanlan
```

> **Note:** Scanning requires sending ICMP pings and reading the ARP table.
> On Linux/macOS you may need to run with `sudo` (or grant ping capabilities).

---

## Usage

```
scanlan [options]
```

### Just run it

```bash
scanlan
```

Auto-detects your subnet and scans it. Raspberry Pi rows are highlighted in green.

### Check open ports too

```bash
scanlan -p
```

Checks ports: `22 (ssh), 80 (http), 443 (https), 8080, 8443, 3389 (rdp), 5900 (vnc), 554 (rtsp), 1883 (mqtt), 8883`

### Wait for a device to appear

```bash
scanlan -w
```

Re-scans every 5 seconds and prints new devices as they show up. Perfect for waiting on a Pi to boot.

```bash
scanlan -w --interval 10   # check every 10 seconds instead
```

### Scan a specific subnet

```bash
scanlan -s 10.0.0.0/24
```

### JSON output (for scripts)

```bash
scanlan --json
scanlan --json | jq '.[] | select(.vendor | contains("Raspberry Pi"))'
```

---

## All options

```
  -s, --subnet CIDR     Subnet to scan (auto-detected if not given)
  -p, --ports           Check common ports on each device
  -w, --watch           Watch for new devices continuously
  --interval SECONDS    Seconds between watch-mode scans (default: 5)
  --json                Output as JSON
  --workers N           Parallel workers (default: 64)
  --version             Show version
```

---

## How it works

1. **Pings** every host in the subnet in parallel (default 64 workers)
2. **Reads the ARP table** for MAC addresses of responding hosts
3. **Looks up the MAC OUI** against a bundled vendor table (no internet needed)
4. **Reverse DNS** each IP for a hostname
5. Optionally **checks ports** with TCP connect

The bundled OUI table covers the most common home/office vendors (Raspberry Pi, Apple, Google, Amazon, TP-Link, ASUS, Samsung, Ubiquiti, etc.).

---

## Permissions

| Platform | Required |
|----------|----------|
| Linux    | `sudo` or `CAP_NET_RAW` for ping |
| macOS    | `sudo` or group `admin` |
| Windows  | Run as Administrator |

**Quick fix on Linux (no sudo every time):**
```bash
sudo setcap cap_net_raw+ep $(which python3)
```

---

## License

MIT
