# tmpertor/raven-storm architecture

> Architecture diagram of the GitHub repository tmpertor/raven-storm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tmpertor/raven-storm
- Repository: https://github.com/tmpertor/raven-storm

## Overview

##### Project type and purpose
- Raven-Storm is a Python 3.8–based, CLI DDoS toolkit.
- It’s structured as a modular command-line application (monolith with plugin‐style modules) for stress-testing networks and services across multiple protocols.

##### File structure
- Top‐level:
- main.py – entry point for the CLI
- install.sh, install_to_bin.sh – installation scripts
- requirements.txt – external dependencies
- Raven-Storm/CLIF_Framework
- framework.py – the custom CLI framework (parses commands, dispatches)
- Raven-Storm/modules
- Subfolders for each attack module: arp, bl, l3, l4, l7, scanner, server, wifi
- Each module implements a .main() that the framework invokes
- Raven-Storm/main.py – imports CLIF_Framework and registers modules

##### Key README insights
- Uses CLIF Framework to provide a consistent CLI experience
- Supports multiple attack “layers” (L3 ping, L4 UDP/TCP, L7 HTTP, ARP, Bluetooth, WiFi)
- Can run standalone or in distributed mode via the “server” module
- No persistent storage or external DB

##### Main components
a. CLI Layer
- User Console (bash/terminal)
- CLI Framework (framework.py)
b. Core Controller
- main.py (module loader & dispatcher)
- L3 Module (icmp/ping)
- L4 Module (udp/tcp flood)
- L7 Module (http flood)
- ARP Module (local network)
- BL Module (Bluetooth)
- WiFi Module (802.11 jamming)
- Scanner Module (discovery)
- Server Module (botnet coordinator)
d. System/OS Network Stack
- Raw sockets or scapy library
- Network interface drivers
e. External Entities
- Target hosts/services
- Distributed clients (when using server module)

##### Relationships & data flow
1. User → CLI Framework → Core Controller
2. Core Controller → selected Module
3. Module → OS Network Stack → Target
4. (Server Module only) → accept connections from remote Raven-Storm clients → forward DDoS commands

##### Architectural patterns & principles
- Plugin/Command pattern: each module adheres to a common interface (.main())
- Single-process, modular design
- Separation of concerns: CLI parsing, orchestration, and attack implementation are distinct

##### Technologies & libraries
- Python 3.8 runtime
- CLIF Framework (custom) for command parsing
- Third-party libraries (e.g., scapy) for packet crafting
- Standard socket/threading libraries
- Bash scripts for install/uninstall

[ ] Clear component labels

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        EntryPoint["main.py\n(Entry Point)"] 
        CLIFramework["CLI Framework\n(framework.py)"]
    end

    %% Core Layer
    subgraph "Core Controller"
        CoreController["Module Loader & Dispatcher\n(main.py)"]
    end

    %% Modules Layer
    subgraph "Attack Modules"
        L3["L3 Module\n(icmp/ping)"]
        L4["L4 Module\n(udp/tcp flood)"]
        L7["L7 Module\n(http flood)"]
        ARP["ARP Module\n(local network)"]
        BL["Bluetooth Module"]
        WiFi["WiFi Module\n(802.11 jamming)"]
        Scanner["Scanner Module\n(discovery)"]
        Server["Server Module\n(distributed mode)"]
        ModuleReg["Module Registration Stub"]
    end

    %% System/OS Layer
    subgraph "System/OS Network Stack"
        OSStack["Raw sockets / scapy"] 
        NetDriver["Network Interface Drivers"]
    end

    %% External Entities
    subgraph "External Entities"
        Target["Target Hosts/Services"]
        Clients["Distributed Clients"]
    end

    %% Connections
    User["User\n(Console)"]:::external
    User -->|"invoke CLI"| EntryPoint
    EntryPoint -->|"load framework"| CLIFramework
    CLIFramework -->|"parse & dispatch"| CoreController

    CoreController -->|"register modules"| ModuleReg
    ModuleReg -->|".main() registration"| CoreController

    CoreController -->|"invoke .main()"| L3
    CoreController -->|"invoke .main()"| L4
    CoreController -->|"invoke .main()"| L7
    CoreController -->|"invoke .main()"| ARP
    CoreController -->|"invoke .main()"| BL
    CoreController -->|"invoke .main()"| WiFi
    CoreController -->|"invoke .main()"| Scanner
    CoreController -->|"invoke .main()"| Server

    L3 -->|"send packets"| OSStack
    L4 -->|"send packets"| OSStack
    L7 -->|"send packets"| OSStack
    ARP -->|"send packets"| OSStack
    BL -->|"send packets"| OSStack
    WiFi -->|"send packets"| OSStack
    Scanner -->|"send packets"| OSStack
    Server -->|"coordinate"| Clients

    OSStack -->|"through drivers"| NetDriver
    NetDriver -->|"to network"| Target
    Clients -->|"forward commands"| Server

    %% Click Events
    click CLIFramework "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/CLIF_Framework/framework.py"
    click CoreController "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/main.py"
    click EntryPoint "https://github.com/tmpertor/raven-storm/blob/master/main.py"
    click L3 "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/l3/main.py"
    click L4 "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/l4/main.py"
    click L7 "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/l7/main.py"
    click ARP "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/arp/main.py"
    click BL "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/bl/main.py"
    click WiFi "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/wifi/main.py"
    click Scanner "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/scanner/main.py"
    click Server "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/server/main.py"
    click ModuleReg "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/modules/main.py"
    click installScripts "https://github.com/tmpertor/raven-storm/blob/master/install.sh"
    click installToBin "https://github.com/tmpertor/raven-storm/blob/master/install_to_bin.sh"
    click uninstall "https://github.com/tmpertor/raven-storm/blob/master/Raven-Storm/uninstall.sh"
    click requirements "https://github.com/tmpertor/raven-storm/blob/master/requirements.txt"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef module fill:#ffe5b4,stroke:#994d00,color:#994d00;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;

    class EntryPoint,CLIFramework cli
    class CoreController core
    class L3,L4,L7,ARP,BL,WiFi,Scanner,Server,ModuleReg module
    class OSStack,NetDriver,Target,Clients external
```
