A visual network topology mapper and scanner for the terminal.
netmap discovers devices on your local network via ARP scanning, probes for open ports, measures latency, and renders an interactive topology graph — all inside a beautiful terminal UI. Think nmap meets a TUI dashboard.
Preview
Features
|
Network Discovery
- ARP scanning (with root) for fast, reliable host detection
- Fallback mode without root — parses ARP cache + TCP probing
- ARP proxy detection — automatically collapses captive portal ghost hosts
- Auto-detects active interface, subnet, and gateway
|
Port Scanning
- TCP connect scan on top 50 common ports (configurable)
- 10 concurrent connections per host
- Automatic service name mapping (SSH, HTTP, DNS, MySQL...)
- Device type heuristics from vendor + open ports
|
|
Interactive TUI
- Real-time topology graph with Unicode box drawing
- Scrollable host table sorted by IP, latency, ports, or vendor
- Detailed host panel with ports, MAC, vendor, latency sparkline
- Keyboard-driven navigation with vim-style bindings
|
Monitoring
- Auto-refresh every 30s (configurable)
- Latency tracking with history per host
- Online/offline detection across scan cycles
- JSON export for integration with other tools
|
Scan Pipeline
Install
From source
# Requires Go 1.22+ and libpcap
# macOS: libpcap ships with Xcode CLI tools
# Linux: apt install libpcap-dev
git clone https://github.com/8tp/netmap.git
cd netmap
go build -o netmap .
Run
# Full scanning (recommended) — requires root for ARP
sudo ./netmap
# Limited mode (no root) — uses ARP cache fallback
./netmap
# Specific interface
sudo ./netmap -i en0
# Specific subnet
sudo ./netmap -r 192.168.1.0/24
# Custom ports
sudo ./netmap --ports 22,80,443,8080
# Fast mode — host discovery only, skip port scanning
sudo ./netmap --fast
# Top N most common ports
sudo ./netmap --top-ports 20
Usage
Flags
| Flag |
Short |
Default |
Description |
--interface |
-i |
auto-detect |
Network interface to scan |
--range |
-r |
from interface |
CIDR range to scan |
--ports |
|
top 50 |
Comma-separated port list |
--top-ports |
|
50 |
Scan N most common ports |
--fast |
|
false |
Discovery only, skip port scan |
--refresh |
-R |
30 |
Auto-refresh interval (seconds) |
--export |
|
|
Export results to JSON on exit |
Keybindings
| Key |
Action |
↑ ↓ / j k |
Navigate hosts / scroll topology |
Tab |
Cycle focus: topology → detail → table |
Enter |
Select host |
t |
Toggle topology / expanded table view |
r |
Trigger rescan |
s |
Cycle sort order (IP → latency → ports → vendor) |
e |
Export scan to netmap_<timestamp>.json |
p |
Pause / resume auto-refresh |
? |
Help overlay |
q / Esc |
Quit |
Architecture
netmap/
├── main.go Entry point
├── cmd/
│ └── root.go Cobra CLI, flag definitions
└── internal/
├── app/
│ ├── app.go Bubble Tea model + Update/View loop
│ └── keys.go Key binding definitions
├── scanner/
│ ├── arp.go Raw ARP scanning via gopacket/pcap
│ ├── fallback.go Non-root: ARP cache + TCP probing
│ ├── ports.go Concurrent TCP connect scanner
│ ├── ping.go Latency measurement
│ └── discovery.go Scan pipeline orchestrator
├── network/
│ ├── interface.go Interface detection, gateway lookup
│ ├── dns.go Reverse DNS resolution
│ └── oui.go MAC vendor database (~400 OUIs)
├── ui/
│ ├── topology.go ASCII network graph renderer
│ ├── detail.go Host detail panel
│ ├── table.go Sortable host table
│ ├── header.go Status bar with progress
│ ├── help.go Help overlay
│ └── styles.go Lip Gloss theme definitions
├── models/
│ └── host.go Core data types
└── export/
└── json.go JSON export
How It Works
Host Discovery — On a root-privileged run, netmap sends raw ARP requests to every IP in your subnet using gopacket/pcap and listens for replies. This is the fastest and most reliable method. Without root, it falls back to parsing arp -a and doing TCP probes to populate the ARP cache.
ARP Proxy Detection — On captive portal or enterprise networks, a single gateway often responds to ARP for every IP with its own MAC address. netmap detects this pattern (one MAC → 10+ IPs) and collapses the duplicates so you see real devices, not hundreds of ghost entries.
Port Scanning — For each discovered host, netmap opens TCP connections to common ports with a 1-second timeout, running 10 goroutines per host. Open ports are mapped to service names from a built-in database.
Device Identification — Hosts are identified through reverse DNS, MAC address OUI vendor lookup (embedded database of ~400 vendors), and heuristic matching based on vendor + open ports (e.g., Synology + port 5001 = NAS, Apple + no server ports = iPhone).
Dependencies
JSON Export
Press e to export, or use --export flag:
{
"scan_time": "2025-03-04T14:35:00Z",
"interface": "en0",
"subnet": "192.168.1.0/24",
"local_ip": "192.168.1.42",
"gateway": "192.168.1.1",
"hosts": [
{
"ip": "192.168.1.1",
"mac": "A0:36:BC:12:34:56",
"vendor": "ASUSTek",
"hostname": "router.local",
"device_type": "Router",
"latency_ms": 1.2,
"status": "online",
"ports": [
{ "port": 22, "service": "SSH", "state": "open" },
{ "port": 80, "service": "HTTP", "state": "open" }
],
"first_seen": "2025-03-04T14:22:00Z",
"last_seen": "2025-03-04T14:35:00Z"
}
]
}
Notes
- macOS primary target — uses
en0 default, route -n get default for gateway detection
- Requires libpcap for ARP scanning (ships with macOS Xcode CLI tools)
- Graceful degradation — runs without root in limited mode, shows warning in header
- Concurrency safe — mutex-protected scan state, all scanning in background goroutines
- Non-blocking TUI — Bubble Tea event loop never blocks during network operations
License
MIT