lan-inventory

A zero-config home-LAN inventory tool. Run it, see your network.

A single Go binary that auto-discovers devices on your local /24, presents a live TUI dashboard, and can also dump a one-shot JSON or text snapshot for scripts and cron.

What it shows

• IP, MAC, vendor (OUI lookup)
• Hostname (mDNS preferred, reverse DNS fallback)
• OS family guess (mDNS / vendor / NBNS / ports / TTL)
• Common open ports with service labels
• mDNS service announcements
• Last-seen timestamp and online/stale/offline status

Install

Linux

go install github.com/lab1702/lan-inventory/cmd/lan-inventory@latest
sudo setcap cap_net_raw,cap_net_admin=eip $(which lan-inventory)

Or build from source:

make build
sudo setcap cap_net_raw,cap_net_admin=eip ./bin/lan-inventory
./bin/lan-inventory

The setcap step is needed once; lan-inventory needs raw-socket access to sniff ARP packets and send ICMP ping. Without it the tool refuses to start.

Windows

1. Install Npcap and check "WinPcap API-compatible mode" during install. The driver grants user-level packet capture so the binary runs from an ordinary (non-elevated) terminal.

2. Install the binary:

   go install github.com/lab1702/lan-inventory/cmd/lan-inventory@latest
   lan-inventory

ICMP echo uses the unprivileged IcmpSendEcho Win32 API on Windows, so no Administrator prompt is needed at runtime.

macOS

The recommended path uses Wireshark's ChmodBPF launchd helper to grant non-root access to /dev/bpf*, mirroring the Linux setcap UX:

brew install --cask wireshark
go install github.com/lab1702/lan-inventory/cmd/lan-inventory@latest
lan-inventory

Or, without Wireshark, run per-invocation as root:

go install github.com/lab1702/lan-inventory/cmd/lan-inventory@latest
sudo lan-inventory

libpcap ships with macOS — no extra install step is needed. ICMP uses unprivileged SOCK_DGRAM sockets, so the only privilege gate is BPF read access.

Usage

lan-inventory                 # interactive TUI dashboard
lan-inventory --once          # single scan, JSON to stdout, exit
lan-inventory --once --table  # single scan, human-readable table, exit
lan-inventory --version

TUI keys

• 1–4 switch tabs (Devices / Services / Subnet / Events)
• ↑/↓ or j/k navigate
• / filter (Enter or Esc exits filter input; clear with Backspace)
• r force a rescan
• q, Esc, or Ctrl+C quit
• ? help overlay

Exit codes (non-interactive)

Code	Meaning
0	Success
1	Runtime error
2	Configuration error (no privilege, no default route, oversized subnet)
3	No devices discovered

Limitations

• IPv4 only.
• Targets /24 home networks; subnets larger than /22 are refused.
• No persistence: state is wiped on quit.
• Supported on Linux, macOS, and Windows. *BSD builds compile but fail at startup (default-route detection is not implemented for those platforms).

Development

make test            # run all unit tests
make vet             # go vet
make lint            # staticcheck
make smoke           # build, setcap, and run --once --table on your live network
make manuf-refresh   # refresh the OUI vendor database from Wireshark upstream

The OUI vendor database (internal/oui/manuf.txt) is sourced from Wireshark and committed to the repo. Run make manuf-refresh to update it; it pulls from wireshark.org, filters to 24-bit OUI entries, and rewrites the file. Review the diff and commit if it looks right.

License

GPL-2.0-or-later. See LICENSE.

The bundled OUI vendor database is sourced from Wireshark, which is also licensed under GPL-2.0-or-later; the upstream license text is preserved at internal/oui/MANUF-LICENSE.