# git-yousfi-neji/netarmageddon architecture

> Architecture diagram of the GitHub repository git-yousfi-neji/netarmageddon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/git-yousfi-neji/netarmageddon
- Repository: https://github.com/git-yousfi-neji/netarmageddon

## Overview

##### Project type and purpose
- NetArmageddon is a command-line network stress-testing framework (not a client-server web app). It’s written in Python (3.10+) with a small C backend (libpcap-based traffic capture).
- Purpose: simulate device connections and attacks (DHCP exhaustion, ARP keep-alive, deauth, traffic logging) against routers or Wi-Fi APs.

##### File structure
Top-level directories and files:
- netarmageddon/ – main Python package
– __main__.py & cli.py: CLI entrypoint & argument parsing
– core/: individual attack modules (arp_keepalive.py, dhcp_exhaustion.py, deauth.py, traffic.py)
– core/traffic_c/: high-performance C code (traffic.c/h) built via Makefile
– utils/: shared helpers (config_loader, network_tools, metrics, output_manager)
- config/ – formatting and linting configs
- docs/ – markdown guides (development, testing, usage, architecture.md stub)
- tests/ – pytest test suite covering Python core and utils
- setup.py, requirements.txt, dev-requirements.txt, Makefile – build/install scripts

##### README for additional insights
- CLI interface with subcommands: dhcp, arp, traffic, deauth
- Extensible architecture: easy to add new modules under core/
- C-backend for packet capture, BPF filter support, thread-safe generation
- Full type safety (mypy), 90%+ test coverage, pre-commit code quality

##### Elements
- From User Terminal → CLI Dispatcher
- CLI → Config Loader → Attack Module
- Attack Module → Utils → libpcap (C backend) → Network Interface → Target
- Blue rectangles for Python components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    User["User Terminal"]:::external
    NetworkIf["Network Interface"]:::external
    Target["Target Network"]:::external

    %% Python Package
    subgraph "netarmageddon (Python Package)"
        subgraph "CLI Dispatcher"
            Main["__main__.py"]:::pythonComp
            CLI["cli.py"]:::pythonComp
        end
        subgraph "Attack Modules"
            DHCP["DHCP Exhaustion Module"]:::attack
            ARP["ARP Keep-Alive Module"]:::attack
            Deauth["Deauthentication Module"]:::attack
            TrafficPy["Traffic Module (Python)"]:::attack
        end
        subgraph "Utilities"
            Config["Config Loader"]:::util
            NetTools["Network Tools"]:::util
            Metrics["Metrics Manager"]:::util
            Output["Output Manager"]:::util
            NetDefs["Network Definitions"]:::util
        end
    end

    %% C Backend
    subgraph "C Backend (traffic_c)"
        C_C["traffic.c"]:::cBackend
        C_H["traffic.h"]:::cBackend
        Make["Makefile"]:::cBackend
    end

    %% Flows
    User -->|"invoke CLI"| Main
    Main -->|"import & dispatch"| CLI
    CLI -->|"load config"| Config
    CLI -->|"select module"| DHCP
    CLI -->|"select module"| ARP
    CLI -->|"select module"| Deauth
    CLI -->|"select module"| TrafficPy

    Config -.->|"config params"| DHCP
    Config -.->|"config params"| ARP
    Config -.->|"config params"| Deauth
    Config -.->|"config params"| TrafficPy

    DHCP -->|"craft/send DHCP packets"| NetTools
    ARP -->|"craft/send ARP packets"| NetTools
    Deauth -->|"craft/send deauth frames"| NetTools
    TrafficPy -->|"craft/send traffic"| NetTools

    TrafficPy -->|"invoke capture"| C_C
    C_C -->|"libpcap I/O"| NetworkIf
    NetTools -->|"send/receive packets"| NetworkIf
    NetworkIf -->|"network traffic"| Target

    DHCP -->|"record metrics"| Metrics
    ARP -->|"record metrics"| Metrics
    Deauth -->|"record metrics"| Metrics
    TrafficPy -->|"record metrics"| Metrics

    DHCP -->|"output status"| Output
    ARP -->|"output status"| Output
    Deauth -->|"output status"| Output
    TrafficPy -->|"output status"| Output

    Metrics -.->|"metrics feedback"| User
    Output -->|"console/pcap output"| User

    %% Click Events
    click Main "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/__main__.py"
    click CLI "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/cli.py"
    click DHCP "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/core/dhcp_exhaustion.py"
    click ARP "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/core/arp_keepalive.py"
    click Deauth "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/core/deauth.py"
    click TrafficPy "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/core/traffic.py"
    click C_C "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/core/traffic_c/traffic.c"
    click C_H "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/core/traffic_c/traffic.h"
    click Make "https://github.com/git-yousfi-neji/netarmageddon/tree/master/netarmageddon/core/traffic_c/Makefile"
    click Config "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/utils/config_loader.py"
    click NetTools "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/utils/network_tools.py"
    click Metrics "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/utils/metrics.py"
    click Output "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/utils/output_manager.py"
    click NetDefs "https://github.com/git-yousfi-neji/netarmageddon/blob/master/netarmageddon/utils/net_definitions.py"

    %% Styles
    classDef pythonComp fill:#E0F7FA,stroke:#006064;
    classDef attack fill:#B3E5FC,stroke:#0277BD;
    classDef util fill:#FFF9C4,stroke:#F57F17;
    classDef cBackend fill:#C8E6C9,stroke:#2E7D32;
    classDef external fill:#FFCCBC,stroke:#BF360C,stroke-width:2px;
```
