Skip to content

README.md

Latest commit

 

History

History
301 lines (227 loc) · 10.2 KB

README.md

File metadata and controls

301 lines (227 loc) · 10.2 KB
Raw

README.md

🔴 RST — Ransomware Simulation Tool

⚠️ FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY This project simulates ransomware behavior in a controlled environment. Never run this on systems or files you do not own. See DISCLAIMER.md for full legal notice.

📌 Overview

RST (Ransomware Simulation Tool) is an educational cybersecurity project that demonstrates how ransomware works at a technical level — including file discovery, AES-256-CBC encryption, IV handling, and decryption with a password gate.

It is built as a WPF desktop application (C#) with a native C++ DLL that handles all cryptographic operations using the Windows BCrypt API.

This project was created to help cybersecurity students understand:

  • How ransomware locates and encrypts target files
  • How AES-256-CBC encryption works at the system level
  • How attackers use file renaming (.locked extension) as a signal
  • How defenders can detect and respond to encryption-based attacks

🏗️ Architecture

┌─────────────────────────────────────┐
│         C# WPF Frontend             │
│  ┌──────────────┐  ┌─────────────┐  │
│  │  MainWindow  │  │ AwarenessPage│  │
│  └──────┬───────┘  └─────────────┘  │
│         │                           │
│  ┌──────▼───────┐                   │
│  │  ToolPage    │  ← Encryption UI  │
│  │  + AppConfig │  ← Configuration  │
│  └──────┬───────┘                   │
└─────────┼───────────────────────────┘
          │  P/Invoke (DllImport)
          ▼
┌─────────────────────────────────────┐
│     C++ Native DLL (x64)            │
│  ┌──────────────────────────────┐   │
│  │  dllmain.cpp                 │   │
│  │  ├── EncryptDirectory()      │   │
│  │  └── DecryptDirectory()      │   │
│  ├──────────────────────────────┤   │
│  │  EncryptFileAes.h  (BCrypt)  │   │
│  │  DecryptFileAes.h  (BCrypt)  │   │
│  │  Search.h  (WinAPI FindFile) │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

Components

File Language Role
MainWindow.xaml/.cs C# App shell, sidebar navigation, status bar
Pages/ToolPage.xaml/.cs C# Encryption/Decryption UI, DLL interop
Pages/AwarenessPage.xaml C# Ethical use guidelines page
Modules/AppConfig.cs C# Centralized configuration (paths, extensions, password)
Ransomware-code.dll C++ AES-256-CBC encrypt/decrypt engine (BCrypt API)

🔐 How the Encryption Works

Encryption Flow (EncryptDirectory)

1. BCryptOpenAlgorithmProvider → AES / CBC mode
2. BCryptGenRandom → generate random 256-bit key (per session)
3. Walk directory tree with WinAPI FindFirstFile / FindNextFile
4. For each matching file:
   a. Read file content into memory
   b. Apply PKCS#7 padding to align to 16-byte AES block size
   c. BCryptGenRandom → generate random 128-bit IV (per file)
   d. BCryptEncrypt → encrypt with AES-256-CBC
   e. Write to file: [32-byte key][16-byte IV][ciphertext]
   f. Rename file → filename.ext.locked
5. SecureZeroMemory → wipe key from memory

Decryption Flow (DecryptDirectoryWithPassword)

1. Password check performed in C# (AppConfig.DecryptPassword)
2. If correct → call DecryptDirectoryWithPassword in DLL
3. Walk directory for all *.locked files
4. For each file:
   a. Read first 32 bytes → key
   b. Read next 16 bytes → IV
   c. Read remainder → ciphertext
   d. BCryptDecrypt → decrypt with AES-256-CBC
   e. Strip PKCS#7 padding
   f. Write plaintext back, truncate file
   g. Rename filename.ext.locked → filename.ext
5. SecureZeroMemory → wipe key and IV from memory

💡 Educational Note: In this simulation, the AES key is stored inside the encrypted file itself. Real ransomware would send the key to a remote C2 server, making decryption impossible without paying. This design is intentionally safe for simulation.

📁 Project Structure

RST-Ransomware-Simulation-Tool/
├── README.md
├── DISCLAIMER.md
├── .gitignore
└── Ransomware_GUI/
    ├── Ransomware_GUI.sln
    ├── Ransomware_GUI.csproj
    ├── App.xaml
    ├── App.xaml.cs
    ├── MainWindow.xaml
    ├── MainWindow.xaml.cs
    ├── alert.png
    ├── Pages/
    │   ├── AwarenessPage.xaml
    │   ├── AwarenessPage.xaml.cs
    │   ├── ToolPage.xaml
    │   └── ToolPage.xaml.cs
    ├── AppConfig.cs 
    └── /bin/Debug/net8.0-windows/Module                      ← DLL goes here (see Setup)
        └── Ransomware-code.dll

⚙️ Configuration

Before running, edit Modules/AppConfig.cs to match your environment:

public static class AppConfig
{
    // 📁 Folder to simulate encryption on (USE A TEST FOLDER!)
    public static string TargetPath { get; set; } =
        @"C:\Your\Test\Folder";

    // 🚫 Subfolder that will NEVER be encrypted (safe zone)
    public static string ExceptionPath { get; set; } =
        @"C:\Your\Test\Folder\safe";

    // 📄 File extensions to target
    public static string[] Extensions { get; set; } =
    {
        "*.pdf", "*.txt", "*.docx", "*.xlsx",
        "*.jpg", "*.jpeg", "*.png", "*.json",
        "*.xml", "*.log", "*.py", "*.bat"
    };

    // 🔑 Password required to decrypt (simulation only)
    public static string DecryptPassword { get; set; } =
        "simulation123";
}

⚠️ Always point TargetPath to a dedicated test folder with dummy files — never to real documents.

🚀 How to Build & Run

Prerequisites

  • Windows 10/11 (x64)
  • Visual Studio 2022 with:
    • .NET Desktop Development workload
    • Desktop development with C++ workload
  • .NET 8 (or as targeted in the project)

Step 1 — Clone the repository

git clone https://github.com/YourUsername/RST-Ransomware-Simulation-Tool.git
cd RST-Ransomware-Simulation-Tool

Step 2 — Place the DLL

Copy the prebuilt Ransomware-code.dll into:

Ransomware_GUI/Module/Ransomware-code.dll

The DLL must be compiled as x64. The WPF project must also target x64.

Step 3 — Configure paths

Open Modules/AppConfig.cs and set TargetPath and ExceptionPath to your test folder.

Step 4 — Build the WPF project

Visual Studio → Build → Build Solution (Ctrl+Shift+B)

Make sure Platform Target = x64 in:

Project Properties → Build → Platform Target → x64

Step 5 — Run

F5 or Debug → Start Debugging

On launch, the app will immediately encrypt the configured TargetPath. Use the Decrypt button and enter simulation123 to restore files.

🖥️ GUI Walkthrough

Encryption Tab

Element Description
Target Path Shows the configured directory being encrypted
Extensions Lists all file types targeted
Output Log Live log with timestamps of every action
Decrypt Button Opens password prompt to restore files

Awareness Tab

Contains the ethical use guidelines and legal warning — built directly into the app to remind users of responsible use every time they open it.

🛡️ What This Project Teaches

Topic Detail
AES-256-CBC How symmetric block cipher encryption works
IV Randomness Why a unique IV per file prevents pattern analysis
PKCS#7 Padding How data is aligned to block boundaries
WinAPI File I/O CreateFileW, ReadFile, WriteFile, SetEndOfFile
BCrypt API Windows-native crypto via bcrypt.lib
Directory Traversal Recursive file discovery with FindFirstFile
SecureZeroMemory Wiping sensitive data from memory after use
P/Invoke Interop Calling native C++ DLL exports from C#
Exception Paths Protecting specific folders from encryption
Defender Perspective Understanding what security tools detect

🔍 Technical Details

DLL Exports

Encrypted File Format

┌──────────────────┬──────────────────┬──────────────────────────────┐
│   AES Key        │   IV             │   Ciphertext                 │
│   32 bytes       │   16 bytes       │   N bytes (padded)           │
└──────────────────┴──────────────────┴──────────────────────────────┘

Extension Filter

Files are matched using WinAPI wildcard patterns (*.pdf, *.txt, etc.) passed from C# as a wchar_t** array via P/Invoke.

⚠️ Legal & Ethical Notice

This tool is strictly for:

  • ✅ Personal cybersecurity education
  • ✅ Isolated lab/VM environments
  • ✅ Academic research and coursework
  • ✅ Understanding defensive security

Never use on:

  • ❌ Systems you do not own
  • ❌ Files belonging to others
  • ❌ Production environments
  • ❌ Any real-world attack scenario

Misuse of this tool may violate computer fraud laws in your country and result in criminal liability.

👤 Author

Khalid

📄 License

This project is released for educational use only. No warranty is provided. Use entirely at your own risk.