GitHub - ostefani/subnetlens: A fast, concurrent network scanner with a TUI and plain-text CLI, built in Go. It discovers live hosts on your network, scans their open ports, resolves hostnames, and fingerprints operating systems—delivered.

4 min read Original article ↗

Go Version CLI Interface License

Bubble Tea Cobra

A fast, concurrent network scanner with a TUI and plain-text CLI, built in Go.

Supports multiple discovery methods:

  • TCP connect scan (no elevated privileges required)
  • ICMP echo (requires root / administrator)
  • ARP scan (Linux/macOS; Windows requires Npcap)
  • mDNS (passive) — listen for local service announcements

Features

  • Host discovery (TCP, ICMP, ARP)
  • Port scanning (TCP connect)
  • OS & Device Fingerprinting: Heuristically detects operating systems and device types.
  • Vendor & MAC Resolution: Uses OUI databases to identify device vendors and detects randomized MAC addresses.
  • Streaming TUI: A visual interface built with Charm's Bubbletea.
  • Plain Text Mode: Script-friendly output.
  • Single binary

Preview

SubnetLens TUI

OUI database

The file scanner/oui.csv maps MAC address prefixes to device vendors. It is obtained from the IEEE Registration Authority and is included in this repository so that both local builds and the release binary ship with full vendor resolution.

If you need to refresh it, download the latest CSV from the link above and replace scanner/oui.csv.

Quick Start

If you want to download repo and build your binary, follow the instruction below. To run a downloaded precompiled binary, read further.

To clone the repository and build from source, follow the instructions below. To use a precompiled binary, see Install precompiled build.

Note: On macOS and Linux, run with sudo to enable ARP and ICMP. On Windows, run the terminal as Administrator. TCP scan requires no elevated privileges.

Development

git clone https://github.com/ostefani/subnetlens
cd subnetlens

# ---Install dependencies---
go mod tidy

# ---Build---
go build .
# or
go build -o subnetlens

# ---Run---
subnetlens scan <target>

Debug mode

# Into console
sudo SLENS_DEBUG=1 ./subnetlens scan <target> --plain
# Into file
sudo SLENS_DEBUG=1 ./subnetlens scan <target> --plain 2>debug.log
# Print from file
cat debug.log

Testing

go test ./...
go test -race ./...

The current test suite includes regression coverage for:

  • models.Host sanitization, concurrent mutation, snapshot safety, and scan option defaults
  • host registry merge behavior for late ARP updates and duplicate events
  • engine coordination, so pre-ready host updates do not emit premature callbacks, and preheating is skipped when target expansion fails
  • scanner resource planning, resolver socket accounting, and local discovery helpers
  • TUI viewport, batching, cached rendering, and local-machine presentation

Update dependencies

Install with Go

cd subnetlens
go install .

Install precompiled build

sudo mv subnetlens /usr/local/bin/

Usage

Scan Your Own Machine

Check interfaces and their assigned IPs. Scan only the subnet that matches your WiFi interface (en0) to stay on your home network.

ip addr                      # Linux
ifconfig  | grep "inet "     # macOS
subnetlens scan [subnet] [flags]

Flags:

  • -p, --ports string Comma-separated ports to scan (default: common 23 ports)
  • -t, --timeout int Per-connection timeout in ms (default: 500)
  • -c, --concurrency int Max concurrent port scan and banner probes (default: 100)
  • --discovery-concurrency int Max concurrent host discovery probes (0 reuses --concurrency)
  • -b, --banners Grab service banners
  • --plain Plain text output (no TUI)
  • --all-alive Show all discovered hosts, including those that respond with TCP connection errors.

Platform Support

Feature Linux macOS Windows
TCP scan ✔ ✔ ✔
ICMP ✔ (root) ✔ (root) ✔ (admin)
ARP ✔ ✔ ✔ (Npcap required)
mDNS ✔ ✔ not tested

Windows prerequisite: Active ARP scanning requires Npcap — a kernel-level packet capture driver. If you have Wireshark installed, Npcap should be already present.

Examples:

  subnetlens scan <IP>
  subnetlens scan <IP start>-<IP end>
  subnetlens scan <IP> --ports 22,80,443,8080
  subnetlens scan <IP> --plain --banners
  subnetlens scan <IP> --concurrency 100 --discovery-concurrency 400 --timeout 300

Project Structure

subnetlens /
├── main.go               # Entrypoint
├── cmd/
│   └── root.go           # Cobra CLI commands
├── scanner/
│   ├── arp.go
│   ├── discovery.go
│   ├── engine.go
│   ├── helpers.go
│   ├── icmp.go
│   ├── osdetect.go
│   └── oui.csv           # bundled IEEE OUI data used for vendor resolution
├── models/
│   └── models.go
└── ui/
    └── tui/
        └── tui.go

Roadmap

  • ARP-based host discovery (requires raw sockets / root)
  • MAC address vendor lookup
  • mDNS listening
  • Add tests
  • Scan profiles: --all-alive
  • JSON / CSV export (--output result.json)
  • UDP port scanning (Pro)
  • GUI with interactive network node graph (Pro)
  • subnetlens watch — re-scan on interval, alert on changes (Pro)

Contributing

Please see CONTRIBUTING.md for contribution and PR guidelines

License

MIT © 2026 Olha Stefanishyna

Disclaimer: This tool is intended for authorized network testing and diagnostics only. Do not scan networks or systems without explicit permission. Use responsibly.

SubnetLens Pro

An upcoming proprietary extension of SubnetLens focused on advanced scanning capabilities. Designed for users who need deeper visibility, automation, and continuous monitoring.

Planned features

  • UDP port scanning and protocol-specific probing
  • Extended service fingerprinting
  • Interactive GUI with network visualization
  • subnetlens watch — continuous scanning with change detection and alerts
  • Advanced output formats and reporting

The core project will remain open source and fully usable. Pro features are designed for advanced analysis and extended workflows.