✧ Subnetlens ✧

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

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

Update dependencies

go get -u all

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 Parallel goroutines (default: 100) -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 200 --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        # is not included in the repo, download from https://regauth.standards.ieee.org if building locally
├── 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 | --all
• UDP port scanning
• JSON / CSV export (--output result.json)
• GUI with interactive network node graph
• subnetlens watch — re-scan on interval, alert on changes

Contributing

To contribute, please consult CONTRIBUTING.md about PR requirements.

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.