# garvits01/arp-spoof-detector architecture

> Architecture diagram of the GitHub repository garvits01/arp-spoof-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/garvits01/arp-spoof-detector
- Repository: https://github.com/garvits01/arp-spoof-detector

## Overview

ARP Spoof Detector is a command-line network monitor: an operator selects an interface, the detector sniffs ARP replies, learns IP-to-MAC mappings, compares them with trusted entries, and reports changed mappings through colored console alerts and persistent logs. It also lists available interfaces and prints a session summary when monitoring stops. The repository documents a separate Scapy-based attack simulator that sends forged replies. Relationships are based on the sampled source and README; the network and user are external actors.

Main entry points: [`detector.py`](https://github.com/garvits01/arp-spoof-detector/blob/main/detector.py) (ARP Detector), [`main.py`](https://github.com/garvits01/arp-spoof-detector/blob/main/main.py) (CLI Entry), [`alerter.py`](https://github.com/garvits01/arp-spoof-detector/blob/main/alerter.py) (Alert Formatter), [`attacker.py`](https://github.com/garvits01/arp-spoof-detector/blob/main/attacker.py) (Packet Simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command Entry"]
  node_cli["CLI Entry<br/>[main.py]"]
  node_scapy_interfaces["Interface Discovery<br/>[main.py]"]
end

subgraph group_detection["ARP Detection"]
  node_detector["ARP Detector<br/>[detector.py]"]
  node_arp_table[("IP-MAC Cache<br/>[detector.py]")]
  node_whitelist["Static Whitelist<br/>[whitelist.py]"]
end

subgraph group_reporting["Alert Reporting"]
  node_alerter["Alert Formatter<br/>[alerter.py]"]
  node_alert_log[("Alert Log<br/>[alerter.py]")]
end

subgraph group_simulation["Attack Simulation"]
  node_attacker["Packet Simulator<br/>[attacker.py]"]
end

node_operator(("Operator"))
node_arp_traffic["ARP Network Traffic"]
node_console["Terminal Output"]

node_operator -->|"runs"| node_cli
node_cli -->|"lists interfaces"| node_scapy_interfaces
node_cli -->|"starts"| node_detector
node_detector -->|"loads entries"| node_whitelist
node_detector -->|"seeds and updates"| node_arp_table
node_arp_traffic -->|"delivers ARP replies"| node_detector
node_detector -->|"reports mismatch"| node_alerter
node_alerter -->|"writes alerts"| node_alert_log
node_alerter -->|"prints alerts"| node_console
node_detector -->|"prints status and summary"| node_console
node_operator -->|"runs simulation"| node_attacker
node_attacker -->|"sends forged replies"| node_arp_traffic

click node_cli "https://github.com/garvits01/arp-spoof-detector/blob/main/main.py"
click node_scapy_interfaces "https://github.com/garvits01/arp-spoof-detector/blob/main/main.py"
click node_detector "https://github.com/garvits01/arp-spoof-detector/blob/main/detector.py"
click node_arp_table "https://github.com/garvits01/arp-spoof-detector/blob/main/detector.py"
click node_whitelist "https://github.com/garvits01/arp-spoof-detector/blob/main/whitelist.py"
click node_alerter "https://github.com/garvits01/arp-spoof-detector/blob/main/alerter.py"
click node_alert_log "https://github.com/garvits01/arp-spoof-detector/blob/main/alerter.py"
click node_attacker "https://github.com/garvits01/arp-spoof-detector/blob/main/attacker.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_scapy_interfaces toneBlue
class node_detector,node_arp_table,node_whitelist toneAmber
class node_alerter,node_alert_log toneMint
class node_attacker toneRose
class node_operator,node_arp_traffic,node_console toneIndigo
```

## Components

### Command Entry

- [CLI Entry](https://github.com/garvits01/arp-spoof-detector/blob/main/main.py): `main.py`
- [Interface Discovery](https://github.com/garvits01/arp-spoof-detector/blob/main/main.py): `main.py`

### ARP Detection

- [ARP Detector](https://github.com/garvits01/arp-spoof-detector/blob/main/detector.py): `detector.py`
- [IP-MAC Cache](https://github.com/garvits01/arp-spoof-detector/blob/main/detector.py): `detector.py`
- [Static Whitelist](https://github.com/garvits01/arp-spoof-detector/blob/main/whitelist.py): `whitelist.py`

### Alert Reporting

- [Alert Formatter](https://github.com/garvits01/arp-spoof-detector/blob/main/alerter.py): `alerter.py`
- [Alert Log](https://github.com/garvits01/arp-spoof-detector/blob/main/alerter.py): `alerter.py`

### Attack Simulation

- [Packet Simulator](https://github.com/garvits01/arp-spoof-detector/blob/main/attacker.py): `attacker.py`

### Other components

- **Operator**
- **ARP Network Traffic**
- **Terminal Output**

## Connections

- Operator → CLI Entry: runs (evidence: `README.md`)
- CLI Entry → Interface Discovery: lists interfaces (evidence: `main.py`)
- CLI Entry → ARP Detector: starts (evidence: `main.py`)
- ARP Detector → Static Whitelist: loads entries (evidence: `detector.py`)
- ARP Detector → IP-MAC Cache: seeds and updates (evidence: `detector.py`)
- ARP Network Traffic → ARP Detector: delivers ARP replies (evidence: `detector.py`)
- ARP Detector → Alert Formatter: reports mismatch (evidence: `detector.py`)
- Alert Formatter → Alert Log: writes alerts (evidence: `alerter.py`)
- Alert Formatter → Terminal Output: prints alerts (evidence: `alerter.py`)
- ARP Detector → Terminal Output: prints status and summary (evidence: `detector.py`)
- Operator → Packet Simulator: runs simulation (evidence: `README.md`)
- Packet Simulator → ARP Network Traffic: sends forged replies (evidence: `README.md`)
