Light up the unknown devices on your LAN.
A defensive inventory, baseline-diff, and risk-report companion for Nmap, ARP, and router evidence.
Lantern does not try to be another scanner. It ingests evidence from tools like Nmap and ARP/neighbor tables, stores device history, detects changes, scores obvious risks, and emits reports a human can act on.
Nmap XML + ARP/router CSV ──▶ SQLite inventory ──▶ baseline diff + risk report
Most small network scanner projects stop at “here are the hosts and open ports.” Lantern is aimed at the next question:
“What changed, what looks risky, and what should I fix first?”
- Attach human labels, owners, and notes to devices by IP or MAC.
- Native safe TCP connect scanner for Windows/Linux without requiring Nmap.
- Protocol-aware TCP/UDP port profiles for common NAS, admin, media, VPN, and management services.
- Auto-discover Windows LAN devices from Get-NetNeighbor / local ARP evidence.
- Ingest Nmap XML service scans.
- Ingest ARP/router/Windows neighbor CSV exports.
- Track devices by MAC address where available, falling back to IP when needed.
- Merge WSL-style IP-only Nmap observations into MAC-backed ARP records.
- Save named baselines and flag new devices and new ports.
- Export inventory as JSON or CSV.
- Optional Tkinter GUI for people who prefer buttons over command-line flags.
- Score common home-network risks:
- FTP
- Telnet
- SMB / NetBIOS
- AFP / NFS
- UPnP
- SNMP
- RTSP camera streams
- RDP
- VNC
- MQTT / Redis / database ports
- embedded/admin HTTP
- CPE WAN management
- Include per-finding remediation guidance in Markdown/HTML reports.
- Right-click GUI device actions: edit labels/owners/notes, copy IP/MAC, open web consoles, save baselines, refresh.
- Emit plain Markdown or a polished cyberpunk-style standalone HTML report.
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
# Native scanner path: discovers neighbors, scans common ports, writes HTML.
lantern --db home.sqlite scan --output reports/lantern.html
# Existing-evidence path.
lantern ingest-arp examples/sample-arp.csv
lantern ingest-nmap examples/sample-nmap.xml
lantern label 192.168.1.20 --label "Living room camera" --owner "IoT" --notes "Move to guest VLAN"
lantern baseline first-known-good
lantern report --baseline first-known-good
lantern report --baseline first-known-good --format html --output reports/lantern.html
Build standalone Windows binaries with PyInstaller from a Windows Python shell:
py -3 -m pip install --user pyinstaller hatchling click jinja2 pytest ruff
py -3 -m pip install --user -e .
py -3 -m pytest -q
py -3 -m PyInstaller --clean --onefile --console --name lantern lantern_entry.py
py -3 -m PyInstaller --clean --onefile --windowed --name lantern-gui lantern_gui_entry.pyRun it from PowerShell:
.\lantern-gui.exe
.\lantern.exe scan
.\lantern.exe scan --save-baseline known-good
.\lantern.exe scan --baseline known-good --output after.html
.\lantern.exe export --format csv --output devices.csv# Optional but useful from WSL: export Windows neighbor cache to CSV.
powershell.exe -NoProfile -Command \
"Get-NetNeighbor -AddressFamily IPv4 | Select-Object IPAddress,LinkLayerAddress,State,InterfaceAlias | ConvertTo-Csv -NoTypeInformation" \
> arp.csv
# Service scan. Only scan networks you own or are authorized to assess.
nmap -Pn -sT -sV --version-light -oX scan.xml 192.168.1.0/24
# Ingest both evidence sources, then report.
lantern --db home.sqlite ingest-arp arp.csv
lantern --db home.sqlite ingest-nmap scan.xml
lantern --db home.sqlite baseline known-good
lantern --db home.sqlite report --baseline known-good > reports/lan-report.md
lantern --db home.sqlite report --baseline known-good --format html --output reports/lan-report.html| Command | Purpose |
|---|---|
lantern ingest-arp arp.csv |
Ingest ARP/router/neighbor CSV into SQLite inventory |
lantern ingest-nmap scan.xml |
Ingest Nmap XML into SQLite inventory |
lantern label DEVICE --label NAME --owner OWNER --notes TEXT |
Attach human context to a device by IP or MAC |
lantern baseline NAME |
Save current inventory as a named baseline |
lantern report [--baseline NAME] |
Print a Markdown risk/change report |
lantern report --format html --output report.html |
Write a standalone styled HTML dashboard |
Lantern defaults to a mixed TCP/UDP quick profile aimed at home LAN/NAS review. Bare custom port numbers are treated as TCP for compatibility; use udp/53 or tcp/80 when you need to force a protocol.
Useful profiles:
| Profile | Purpose |
|---|---|
quick |
Common home LAN/NAS/admin/media/security ports |
nas / storage |
SMB, NFS, AFP, FTP, NAS web consoles, SNMP/UPnP |
admin / web |
HTTP/HTTPS/admin console ports |
extended |
Wider safe TCP/UDP review profile |
Examples:
lantern scan --ports nas
lantern scan --ports admin
lantern scan --ports tcp/22,tcp/80,udp/53,udp/161UDP scanning is conservative: Lantern only records a UDP port when the service responds. No UDP result means “no response”, not proof that the port is closed.
# Lantern LAN Report
## Summary
| Metric | Count |
|---|---:|
| Devices | 3 |
| Open services | 2 |
| High risk devices | 1 |
## Findings
### 192.168.1.20 ipc-cam
- Telnet exposed
- Embedded/admin HTTP service exposedThe HTML renderer turns the same evidence into a single-file dashboard with dark colors, neon accents, risk badges, and mobile-friendly layout.
- Evidence-first. Lantern stores observations from external tools instead of pretending to be the scanner of record.
- Safe by default. No credential guessing, brute forcing, or exploit checks.
- Home-lab friendly. Works well with WSL, router exports, and partial evidence.
- Human-readable. Reports should help you decide what to unplug, isolate, label, or harden.
See docs/research.md for notes from nearby GitHub projects and the improvement ideas that shaped the current roadmap.
pip install -e '.[dev]'
python -m pytest -q
python -m ruff check .- ✅ Device labels/owners and notes.
- ✅ JSON/CSV export.
- OUI vendor enrichment.
- Optional lightweight web dashboard.
- Scheduled scans and alert diff summaries.
Lantern is for defensive use on networks you own or are explicitly authorized to assess. It is an inventory and reporting companion, not an exploitation framework.
MIT