Simple LAN Scanner

Simple LAN Scanner is a Python wrapper around nmap -sn for tracking devices on a local network. It includes:

• a CLI (lan-scan)
• a Tkinter GUI (lan-scan gui)
• persistent device history keyed by MAC address

If you want a lightweight way to answer "what is currently on this LAN and when was it last seen?", this project is built for that.

Requirements

• Python 3.10+
• nmap installed and available in your PATH

Install nmap:

• Windows: winget install -e --id Insecure.Nmap (or installer from nmap.org)
• Ubuntu/Debian: sudo apt install nmap
• macOS: brew install nmap

Install

From PyPI:

pip install "simple-lan-scanner[cli]"

From source:

git clone https://github.com/IBN5100-0/simple-lan-scanner.git
cd simple-lan-scanner
pip install -e ".[cli]"

CLI Quick Start

Show help:

lan-scan --help

Run a one-time scan:

lan-scan scan

Scan a specific subnet:

lan-scan scan --network 192.168.1.0/24

Write a snapshot to file:

lan-scan scan -o devices.json
lan-scan scan -o devices.csv

Run continuous monitoring:

lan-scan monitor
lan-scan monitor --interval 60
lan-scan monitor --online-only
lan-scan monitor --search "apple"
lan-scan monitor --json monitor.json --csv monitor.csv

Start the GUI:

lan-scan gui

What Gets Stored

Each device record includes:

• mac_address
• ip_address
• hostname (if nmap returns one)
• manufacturer (if nmap returns one)
• date_added
• last_seen

Persistent files are stored in the user data directory:

• Windows: %APPDATA%\simple-lan-scanner\devices.json
• Linux/macOS: ~/.simple-lan-scanner/devices.json

GUI settings are stored next to it as gui_settings.json.

Behavior Notes

• Auto-detection selects a /24 subnet from local IPv4 addresses.
• 169.254.x.x and 192.168.56.x are skipped during auto-detection.
• Devices are considered "online" if seen in the last 120 seconds.
• scan loads existing history to preserve timestamps, then writes only the requested output file.
• monitor and the GUI update the persistent device file after each scan.

Python API

from simple_scanner import NetworkMonitor

monitor = NetworkMonitor()  # auto-detect network
monitor.scan()

for device in monitor.devices():
    print(device.mac_address, device.ip_address, device.hostname, device.manufacturer)

monitor.to_json("devices.json")
monitor.to_csv("devices.csv")

Development

python -m venv .venv
# Windows:
# .venv\Scripts\activate
# Linux/macOS:
# source .venv/bin/activate

pip install -e ".[cli,test]"
pytest

Or use the Makefile targets (make test, make test-cov, make scan, make gui).

Project Layout

src/simple_scanner/   core package (scanner, models, cli, gui)
tests/                test suite
examples/             usage examples
docs/                 additional documentation

Contributing

See CONTRIBUTING.md.

License

MIT, see LICENSE.