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

Package	Purpose
Bubble Tea	Terminal UI framework
Lip Gloss	TUI styling and layout
gopacket	Raw ARP packet crafting
cobra	CLI argument parsing

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