# halildeniz/ransomwaresim architecture

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

- Interactive diagram: https://gitdiagram.com/halildeniz/ransomwaresim
- Repository: https://github.com/halildeniz/ransomwaresim

## Overview

##### Project Type and Purpose
- RansomwareSim is a Python-based educational simulation tool (not a web or GUI app) that mimics ransomware behavior: it encrypts files (Encoder.py), communicates with a command-and-control server (ControlServer.py), and then decrypts them (Decoder.py).

##### Top-Level File Structure
- ControlServer.py
- Encoder.py (the “ransomware” client)
- Decoder.py (the recovery client)
- requirements.txt (dependencies: cryptography, colorama)
- Readme.md, LICENSE, SECURITY.md

##### Key Components
A. Encoder (Ransomware Client)
- Modules:
- File Scanner & Encryptor (uses cryptography library)
- Desktop Wallpaper Changer (OS calls)
- Ransom Note Writer (README.txt on desktop)
- Network Client (sockets) to send system info and request key
B. Control Server
- Listens for incoming client connections
- Receives system metadata from Encoder
- Generates & stores per-session encryption/decryption keys
- Responds to clients (sends decryption key when authorized)
C. Decoder (Recovery Client)
- Network Client to contact Control Server with key request
- Decryptor module (uses cryptography library) to restore files
D. File System
- Target directory for encryption/decryption
- User’s Desktop (for ransom note & wallpaper)
E. External Libraries
- cryptography (AES key generation, file encryption)
- colorama (console coloring)

##### Component Relationships & Data Flows
1. Encoder scans and encrypts files → writes encrypted files back to file system.
2. Encoder changes desktop wallpaper & drops ransom note.
3. Encoder opens TCP socket → sends system info → receives session ID (and/or placeholder key).
4. User runs Decoder → it connects to Control Server over TCP → submits session ID + request.
5. Control Server verifies session → sends back decryption key.
6. Decoder uses key to decrypt files, restoring the original data.

##### Architectural Patterns & Principles
- Client-Server pattern: two clients (Encoder, Decoder) communicating with central Control Server.
- Layered responsibilities within each client:
- Presentation/CLI layer (console prompts, colorama)
- Business logic layer (encryption/decryption, wallpaper change)
- Data layer (file I/O)
- Clear separation between “malicious behavior” (Encoder) and “remediation” (Decoder).

##### Detail Level
- Method groupings rather than every function.
- Sequence: encrypt → notify C&C → request key → decrypt.
- Don’t overcrowd: keep per-component internals to 2–3 bullet labels.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Components
    Encoder["Encoder.py\n(cryptography, colorama, sockets)"]:::encoder
    ControlServer["ControlServer.py\n(key generation, session store)"]:::control
    Decoder["Decoder.py\n(cryptography, sockets)"]:::decoder
    FileSystem["File System\n(Target Directory & Desktop)"]:::storage
    Network["Network\n(TCP: port 4444)"]:::network

    %% External Libraries and Assets
    Req["requirements.txt"]:::docs
    Img["img/"]:::docs

    %% Project Documentation
    Readme["Readme.md"]:::docs
    LICENSE["LICENSE"]:::docs
    SECURITY["SECURITY.md"]:::docs

    %% Component Relationships
    Encoder -->|"Encrypt & Write Files"| FileSystem
    Encoder -.->|"Drop Ransom Note & Change Wallpaper"| FileSystem
    Encoder -->|"Open TCP Socket"| Network
    Network -->|"Send System Info & Receive Session ID"| ControlServer

    Decoder -->|"Open TCP Socket"| Network
    Network -->|"Send Session ID & Receive Decryption Key"| Decoder
    Decoder -->|"Decrypt & Restore Files"| FileSystem

    %% Dependencies & Assets flows
    Req -.-> Encoder
    Req -.-> Decoder
    Img -.-> Encoder

    %% Documentation grouping
    subgraph "Project Docs & Assets"
        Readme
        LICENSE
        SECURITY
    end

    %% Click Events
    click Encoder "https://github.com/halildeniz/ransomwaresim/blob/main/Encoder.py"
    click ControlServer "https://github.com/halildeniz/ransomwaresim/blob/main/ControlServer.py"
    click Decoder "https://github.com/halildeniz/ransomwaresim/blob/main/Decoder.py"
    click Req "https://github.com/halildeniz/ransomwaresim/blob/main/requirements.txt"
    click Img "https://github.com/halildeniz/ransomwaresim/tree/main/img/"
    click Readme "https://github.com/halildeniz/ransomwaresim/blob/main/Readme.md"
    click LICENSE "https://github.com/halildeniz/ransomwaresim/tree/main/LICENSE"
    click SECURITY "https://github.com/halildeniz/ransomwaresim/blob/main/SECURITY.md"

    %% Styles
    classDef encoder fill:#add8e6,stroke:#000,stroke-width:1px
    classDef control fill:#f8d7da,stroke:#000,stroke-width:1px
    classDef decoder fill:#d4edda,stroke:#000,stroke-width:1px
    classDef storage fill:#e2e3e5,stroke:#000,stroke-width:1px,shape:cylinder
    classDef network fill:#fff3cd,stroke:#000,stroke-width:1px
    classDef docs fill:#f0f0f0,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
