# netequator/neighwatch architecture

> Architecture diagram of the GitHub repository netequator/neighwatch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netequator/neighwatch
- Repository: https://github.com/netequator/neighwatch

## Overview

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: [`neighwatch/table.py`](https://github.com/netequator/neighwatch/blob/main/neighwatch/table.py) (Neighbor Detection), [`neighwatch/cli.py`](https://github.com/netequator/neighwatch/blob/main/neighwatch/cli.py) (CLI Runtime), [`neighwatch/capture.py`](https://github.com/netequator/neighwatch/blob/main/neighwatch/capture.py) (Live Capture), [`neighwatch/__main__.py`](https://github.com/netequator/neighwatch/blob/main/neighwatch/__main__.py) (Module Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Runtime"]
  node_cli["CLI Runtime<br/>[cli.py]"]
  node_module_entry["Module Entry<br/>[__main__.py]"]
end

subgraph group_capture["Packet Capture"]
  node_offline["PCAP Replay<br/>[capture.py]"]
  node_live["Live Capture<br/>[capture.py]"]
end

subgraph group_detection["Parsing and Detection"]
  node_parser["ARP and NDP Parser<br/>[parser.py]"]
  node_window["Flood Window Counter<br/>[window.py]"]
end

subgraph group_state["Neighbor State"]
  node_neighbor_table["Neighbor Detection<br/>[table.py]"]
end

node_operator(("Operator"))
node_packet_source(("Network or Capture"))
node_scapy["Scapy / Npcap"]
node_state_file["JSON State File"]
node_jsonl(("JSONL Output"))

node_operator -->|"configures"| node_cli
node_module_entry -->|"runs"| node_cli
node_cli -->|"starts replay"| node_offline
node_cli -->|"starts capture"| node_live
node_packet_source -.->|"supplies frames"| node_live
node_scapy -.->|"optional backend"| node_live
node_offline -->|"processes frames"| node_neighbor_table
node_live -->|"processes frames"| node_neighbor_table
node_neighbor_table -.->|"parses frames"| node_parser
node_neighbor_table -->|"counts GARP bursts"| node_window
node_cli -->|"configures tracker"| node_neighbor_table
node_cli -->|"loads and saves"| node_neighbor_table
node_neighbor_table -.->|"reads and writes"| node_state_file
node_offline -->|"prints events"| node_jsonl
node_live -.->|"prints events"| node_jsonl

click node_cli "https://github.com/netequator/neighwatch/blob/main/neighwatch/cli.py"
click node_module_entry "https://github.com/netequator/neighwatch/blob/main/neighwatch/__main__.py"
click node_offline "https://github.com/netequator/neighwatch/blob/main/neighwatch/capture.py"
click node_live "https://github.com/netequator/neighwatch/blob/main/neighwatch/capture.py"
click node_parser "https://github.com/netequator/neighwatch/blob/main/neighwatch/parser.py"
click node_neighbor_table "https://github.com/netequator/neighwatch/blob/main/neighwatch/table.py"
click node_window "https://github.com/netequator/neighwatch/blob/main/neighwatch/window.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_module_entry toneBlue
class node_offline,node_live toneAmber
class node_parser,node_window toneMint
class node_neighbor_table toneRose
class node_operator,node_packet_source,node_scapy,node_state_file,node_jsonl toneIndigo
```

## Components

### CLI and Runtime

- [CLI Runtime](https://github.com/netequator/neighwatch/blob/main/neighwatch/cli.py): `neighwatch/cli.py`
- [Module Entry](https://github.com/netequator/neighwatch/blob/main/neighwatch/__main__.py): `neighwatch/__main__.py`

### Packet Capture

- [PCAP Replay](https://github.com/netequator/neighwatch/blob/main/neighwatch/capture.py): `neighwatch/capture.py`
- [Live Capture](https://github.com/netequator/neighwatch/blob/main/neighwatch/capture.py): `neighwatch/capture.py`

### Parsing and Detection

- [ARP and NDP Parser](https://github.com/netequator/neighwatch/blob/main/neighwatch/parser.py): `neighwatch/parser.py`
- [Flood Window Counter](https://github.com/netequator/neighwatch/blob/main/neighwatch/window.py): `neighwatch/window.py`

### Neighbor State

- [Neighbor Detection](https://github.com/netequator/neighwatch/blob/main/neighwatch/table.py): `neighwatch/table.py`

### Other components

- **Operator**
- **Network or Capture**
- **Scapy / Npcap**
- **JSON State File**
- **JSONL Output**

## Connections

- Operator → CLI Runtime: configures (evidence: `neighwatch/cli.py`)
- Module Entry → CLI Runtime: runs (evidence: `neighwatch/__main__.py`)
- CLI Runtime → PCAP Replay: starts replay (evidence: `neighwatch/cli.py`)
- CLI Runtime → Live Capture: starts capture (evidence: `neighwatch/cli.py`)
- Network or Capture → Live Capture: supplies frames
- Scapy / Npcap → Live Capture: optional backend (evidence: `README.md`)
- PCAP Replay → Neighbor Detection: processes frames (evidence: `neighwatch/capture.py`)
- Live Capture → Neighbor Detection: processes frames (evidence: `neighwatch/capture.py`)
- Neighbor Detection → ARP and NDP Parser: parses frames (evidence: `neighwatch/table.py`)
- Neighbor Detection → Flood Window Counter: counts GARP bursts (evidence: `neighwatch/table.py`)
- CLI Runtime → Neighbor Detection: configures tracker (evidence: `neighwatch/cli.py`)
- CLI Runtime → Neighbor Detection: loads and saves (evidence: `neighwatch/cli.py`)
- Neighbor Detection → JSON State File: reads and writes
- PCAP Replay → JSONL Output: prints events (evidence: `neighwatch/capture.py`)
- Live Capture → JSONL Output: prints events
