Skip to content
qalarcPublic

About

Passive network intelligence for the home LAN — device catalog, traffic accounting, security heuristics, wardrive mapping, and an MCP server for AI agents

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

NetSleuth — Network Traffic Investigator

A Tauri 2 desktop app that monitors all internet traffic on a router you control, attributes it to every device on the network, resolves the sites each device talks to (DNS + TLS SNI), and gives you a live dashboard plus a full history / analytics view — all stored locally in SQLite. No cloud, no telemetry.

┌──────────────────────────── NetSleuth ────────────────────────────┐
│                                                                   │
│  Router (OpenWrt / any Linux box)          Desktop app            │
│  ┌────────────────────┐    ssh + tcpdump   ┌───────────────────┐  │
│  │ tcpdump -i br-lan  │ ═════════════════> │ pcap stream       │  │
│  │   -U -w -          │   (classic pcap)   │  ├─ L2–L4 parser  │  │
│  └────────────────────┘                   │  ├─ DNS  ▸ domains │  │
│                                           │  ├─ SNI  ▸ domains │  │
│  or: local interface / .pcap file         │  ├─ DHCP ▸ hostnames│  │
│                                           │  └─ Engine:        │  │
│                                           │     • devices (MAC)│  │
│                                           │     • flows+bytes  │  │
│                                           │     • site mapping │  │
│                                           │  SQLite (WAL)      │  │
│                                           │  Tauri events ⇄ UI │  │
│                                           └───────────────────┘  │
└───────────────────────────────────────────────────────────────────┘

Screenshot

NetSleuth dashboard

(Fresh-install view — no capture configured yet. Once a capture source is running, this dashboard fills with the live device list, site accounting and security alerts.)

Features

  • Router-wide capture via SSH: runs ssh user@router tcpdump -i br-lan -U -w - and parses the live pcap stream — works on OpenWrt and any Linux router with tcpdump and key-based SSH. Nothing needs to be installed on the router.
  • Alternative sources: capture on a local interface (mirror port / hub / this machine), or import a .pcap file for offline investigation.
  • Per-device view: every device identified by MAC with vendor (58k-entry embedded IEEE OUI database), hostname (DHCP option 12 + mDNS hints), user-settable alias, auto-detected gateway, online status and 60-second up/down sparklines.
  • Sites, not just IPs: DNS answers build an IP→name map; TLS ClientHello SNI confirms HTTPS hosts. Sites are shown per device with byte counts, hit counts and clickable links.
  • Live dashboard: total up/down rate chart, device table with live rates, top sites, and a rolling activity feed (dns / sni / dhcp / new device / ip change events).
  • History & analytics: hourly rollups in SQLite — stacked traffic timelines, top talkers, day×hour activity heatmap, range filters (1h…30d), event log with filters, retention trimming.
  • Local-first & private: everything on your disk (netsleuth.db in the app data dir). Wipe history any time.

How it works

Concern Approach
Getting packets ssh … tcpdump -U -w - streamed over stdout; classic-pcap reader (both endiannesses, µs/ns) handles EN10MB, LINUX_SLL/SLL2, RAW link types
Device identity Ethernet MACs (primary), ARP learning for IP↔MAC, DHCP chaddr/hostname, mDNS *.local hints, OUI vendor lookup, gateway auto-election by traffic votes (manual override in settings)
Site identity DNS A/AAAA answers → IP→qname map; TLS ClientHello SNI → authoritative name; registrable domain (last 2 labels) for aggregation
Traffic accounting Per-device byte/packet counters + 60s ring buffers (live) + per-flow (mac, remote IP, proto, port) accumulators, flushed to SQLite every 5s as hourly rollups
DoH / ECH caveat Encrypted DNS and Encrypted Client Hello hide names — those flows still count by IP/bytes but may show no site name (surfaced in Settings)

Contract

The Rust backend ⇄ React frontend interface is frozen in CONTRACT.md: 16 invoke commands + 2 event streams (live-update at 1 Hz, capture-status on transitions).

Development

# prerequisites: rust, node ≥ 20, libwebkit2gtk-4.1 (Linux),
# `tcpdump` and `ssh` on PATH
npm install
npm run tauri dev      # dev app
cargo test --lib       # backend unit + end-to-end pipeline tests
npm run tauri build    # release bundle

Local-interface capture needs CAP_NET_RAW on the bundled tcpdump — usually just run the app once with sudo, or sudo setcap cap_net_raw,cap_net_admin=eip $(which tcpdump).

Router setup (SSH mode)

  1. Enable SSH on the router (OpenWrt: dropbear is on by default).
  2. Install your desktop's public key: ssh-copy-id root@192.168.1.1.
  3. Ensure tcpdump exists on the router: OpenWrt opkg install tcpdump.
  4. In NetSleuth → Capture → SSH to router, fill host/user/interface (usually br-lan), hit Test connection, then Start.

Project layout

netsleuth/
├── src/                  # React 19 + TS + Tailwind 4 + ECharts frontend
│   ├── lib/api.ts        # typed invoke wrappers (CONTRACT.md)
│   ├── store.tsx         # live-update/capture-status state
│   └── views/            # Dashboard, Devices, DeviceDetail, Sites, History, Capture
├── src-tauri/src/
│   ├── parser/           # hand-rolled wire parsers: eth/vlan/ip/tcp/udp,
│   │                     # DNS (compression), TLS SNI, DHCP/BOOTP
│   ├── capture/          # ssh/local/file sources + classic-pcap stream reader
│   ├── engine.rs         # devices, flows, gateway election, site mapping,
│   │                     # ring buffers, tick/flush payloads
│   ├── store.rs          # SQLite (WAL) writer thread + query surface
│   ├── oui.rs (+oui_data.rs)  # embedded IEEE OUI vendor DB (regenerable)
│   └── commands.rs       # the 16 Tauri commands
├── scripts/gen_oui_data.py  # regenerates oui_data.rs from Wireshark manuf
└── CONTRACT.md           # frozen backend ⇄ frontend API contract

MCP server for AI agents (v0.3.0)

netsleuth-mcp (built alongside the app) is a read-only Model Context Protocol server over the same SQLite DB — let your agents review your network data: status, devices, device_detail, sites, search_sites, events, timeline, security_alerts, heatmap. Registered in the qalcode/opencode MCP config as netsleuth; safe to run while the app is open (WAL). Device detail is now a full-page view with port/protocol/IP aggregates.

Security heuristics (v0.2.0)

Mild malware detection, evaluated every 30 s while capturing: C2-style beaconing (regular-interval connections), DGA/DNS-tunneling rate patterns, malware ports (4444/31337/6667/…), throwaway TLDs, exfiltration shape (>50 MB/hour upload ≫ download to one host), raw-IP traffic without DNS/SNI, possible unsolicited inbound connections, and a user blocklist (blocklist.txt next to the DB: one domain suffix or IP per line). Findings dedupe and surface in the Security view, dashboard card, sidebar strip, and per-device detail. Heuristics, not ground truth — each alert explains its reasoning.

Troubleshooting

"I started monitoring but see no traffic or devices" — in order of likelihood:

  1. Router has no SSH. SSH mode needs an SSH-capable router (OpenWrt, pfSense, a Linux box…). Stock consumer routers (D-Link, TP-Link, Netgear ISP boxes) usually don't expose it — the SSH card now runs a preflight test and tells you immediately. Alternative: flash OpenWrt if your model is supported.
  2. tcpdump lacks capture permission locally. "This machine" mode shells out to tcpdump, which needs CAP_NET_RAW: sudo setcap cap_net_raw,cap_net_admin=eip "$(which tcpdump)" (once), or launch the app with sudo.
  3. Switched/WiFi networks hide other devices' traffic. A capture on YOUR interface physically only sees: your own traffic + broadcasts (ARP, DHCP, mDNS). NetSleuth uses those broadcasts to discover and list every LAN device (with vendor/hostnames) — but per-device traffic for other devices is only visible from the router (SSH mode) or a mirror port. "This machine" mode = full site/traffic analysis of the monitoring computer + device inventory of the whole LAN.

Limitations / roadmap

  • QUIC (UDP/443 v1) and DoH/DoT hide site names (ECH worsens this) — bytes still tracked per device/IP.
  • IPv6 extension-header chains beyond hop-by-hop/routing are not followed.
  • NetFlow/IPFIX collector mode (softflowd on the router) is planned as a lower-CPU alternative to SSH streaming.
  • Per-flow TCP reassembly is out of scope; SNI is parsed from the first client flight, which covers normal browsers.

License

MIT

About

Passive network intelligence for the home LAN — device catalog, traffic accounting, security heuristics, wardrive mapping, and an MCP server for AI agents

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages