How netequator/neighwatch works
neighwatch passively reads live Layer 2 traffic or replays PCAP/PCAPNG captures, parses ARP and IPv6 NDP frames, updates neighbor bindings, and emits normalized JSONL events. Its core detection covers address changes, hardware mismatches, DAD probes, gratuitous-ARP floods, and stale-entry eviction. The CLI configures capture and optional state persistence; the neighbor table uses a sliding-window counter for flood detection. Capture and CLI paths are shown from excerpts; some parsing and backend details are documented but not fully sampled, so uncertain links are omitted.
Main entry points: table.py Neighbor Detection · cli.py CLI Runtime · capture.py Live Capture · __main__.py Module Entry
Components 12
CLI and Runtime
- CLI Runtime
neighwatch/cli.py - Module Entry
neighwatch/__main__.py
Packet Capture
- PCAP Replay
neighwatch/capture.py - Live Capture
neighwatch/capture.py
Parsing and Detection
- ARP and NDP Parser
neighwatch/parser.py - Flood Window Counter
neighwatch/window.py
Neighbor State
- Neighbor Detection
neighwatch/table.py
Other components
- Operator
- Network or Capture
- Scapy / Npcap
- JSON State File
- JSONL Output
Connections 15
- Operator → CLI Runtime: configures
neighwatch/cli.py - Module Entry → CLI Runtime: runs
neighwatch/__main__.py - CLI Runtime → PCAP Replay: starts replay
neighwatch/cli.py - CLI Runtime → Live Capture: starts capture
neighwatch/cli.py - Network or Capture → Live Capture: supplies frames
- Scapy / Npcap → Live Capture: optional backend
README.md - PCAP Replay → Neighbor Detection: processes frames
neighwatch/capture.py - Live Capture → Neighbor Detection: processes frames
neighwatch/capture.py - Neighbor Detection → ARP and NDP Parser: parses frames
neighwatch/table.py - Neighbor Detection → Flood Window Counter: counts GARP bursts
neighwatch/table.py - CLI Runtime → Neighbor Detection: configures tracker
neighwatch/cli.py - CLI Runtime → Neighbor Detection: loads and saves
neighwatch/cli.py - Neighbor Detection → JSON State File: reads and writes
- PCAP Replay → JSONL Output: prints events
neighwatch/capture.py - Live Capture → JSONL Output: prints events