# namhyunko-assignment-with-gilgil/arp-spoof architecture

> Architecture diagram of the GitHub repository namhyunko-assignment-with-gilgil/arp-spoof, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/namhyunko-assignment-with-gilgil/arp-spoof
- Repository: https://github.com/namhyunko-assignment-with-gilgil/arp-spoof

## Overview

##### Project Type and Purpose
- This is a small, single‐binary network utility written in C++ whose sole purpose is ARP spoofing.
- The README (“arp-spoofing”) and the file names (arphdr, ethhdr, ipv4, tcp, main.cpp) confirm that it builds and injects raw Ethernet/ARP/IPv4/TCP packets.

##### File Structure Analysis
- Top-level sources:
- main.cpp          → entry point, CLI parsing, control flow
- arphdr.{cpp,h}    → ARP header creation/manipulation
- ethhdr.{cpp,h}    → Ethernet frame header
- ipv4.{cpp,h}      → IPv4 header utilities
- tcp.{cpp,h}       → TCP header utilities
- makefile          → build rules, compiler flags, linking libraries (libpcap or raw sockets)
- No subdirectories—flat structure. This implies a monolithic architecture with clear protocol‐layer modules.

##### Key Architectural Components
a. User Interface Layer
- main.cpp: command-line arguments (target IP/MAC, spoof parameters), logging, user feedback.
b. Core Logic / Controller
- The sequencing logic in main.cpp that uses the protocol modules to build spoofed ARP replies and inject them.
c. Protocol Modules (Packet Builders)
- ethhdr module
- arphdr module
- ipv4 module (likely used for calculating checksums or embedding IPs in ARP payloads)
- tcp module (if the tool also builds TCP or inspects TCP headers; may be optional)
d. System / OS Interface
- Raw sockets or libpcap injection/sniffing API
- OS network stack (kernel space)
e. External Network
- LAN segment, victim host(s), gateway

##### Relationships and Data Flow
1. User runs `arp-spoof` with CLI args → main
2. main calls the ethhdr/arphdr modules to craft a raw Ethernet frame containing an ARP reply
3. The raw frame is handed to the OS via a raw socket (or libpcap)
4. OS emits the frame onto the wire
5. Victim host receives spoofed ARP → traffic interception / MITM setup

##### Architectural Patterns & Principles
- Layered design by network protocol layer
- Single responsibility modules: each header type is in its own source pair
- Monolithic CLI tool—no client/server or multi‐process components
- Build decoupling: makefile abstracts compiler/linker flags, making it easy to swap injection backends (raw socket vs. pcap)

##### Final Advice
- Clearly that main.cpp orchestrates calls into ethhdr, arphdr, ipv4, tcp modules and then interacts with the OS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    Makefile["Makefile"]:::code
    %% CLI and Controller
    CLI["CLI Parser & Controller\n(main.cpp)"]:::code
    %% Protocol Modules
    Eth["Ethernet Module\n(ethhdr.cpp/h)"]:::code
    ARP["ARP Module\n(arphdr.cpp/h)"]:::code
    IPv4["IPv4 Module\n(ipv4.cpp/h)"]:::code
    TCP["TCP Module\n(tcp.cpp/h)"]:::code
    %% OS Interfaces
    RawAPI["Raw Socket / libpcap API"]:::os
    Kernel["OS Kernel Network Stack"]:::os
    %% External System
    External["External LAN / Victim Hosts"]:::external

    %% Connections
    Makefile -->|"compile/link"| CLI
    CLI -->|"build header"| Eth
    CLI -->|"build header"| ARP
    CLI -->|"build header"| IPv4
    CLI -->|"build header"| TCP
    CLI -->|"inject frame"| RawAPI
    RawAPI -->|"system call sendto()"| Kernel
    Kernel -->|"packet on wire"| External

    %% Click Events
    click CLI "https://github.com/namhyunko-assignment-with-gilgil/arp-spoof/blob/main/main.cpp"
    click Eth "https://github.com/namhyunko-assignment-with-gilgil/arp-spoof/blob/main/ethhdr.cpp"
    click ARP "https://github.com/namhyunko-assignment-with-gilgil/arp-spoof/blob/main/arphdr.cpp"
    click IPv4 "https://github.com/namhyunko-assignment-with-gilgil/arp-spoof/blob/main/ipv4.cpp"
    click TCP "https://github.com/namhyunko-assignment-with-gilgil/arp-spoof/blob/main/tcp.cpp"
    click Makefile "https://github.com/namhyunko-assignment-with-gilgil/arp-spoof/tree/main/makefile"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef os fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px
    class Makefile,CLI,Eth,ARP,IPv4,TCP code
    class RawAPI,Kernel os
    class External external
```
