RansomGuard-AI

# RansomGuard-AI

RansomGuard-AI is an open-source behavioral monitoring engine designed to detect zero-day ransomware attacks in real time. Instead of relying on static signature matching, it evaluates live file modifications, calculates Shannon entropy shifts, and tracks process disk I/O rates. An integrated unsupervised machine learning model (`IsolationForest`) establishes a baseline of normal operating behavior and flags rapid, anomalous encryption activity.

---

## 🏗️ Architecture & How It Works

RansomGuard-AI runs locally without requiring cloud connectivity or external API queries.

1. **File System Monitoring:** Uses `watchdog` to monitor a specified directory for write, modification, and rename events.
2. **Shannon Entropy Telemetry:** Encrypted data has a high degree of randomness. The engine reads modified bytes to calculate mathematical entropy values (on a scale from $0.0$ to $8.0$). Encrypted payloads consistently score above $7.5$.
3. **I/O Burst Tracking:** Queries `psutil` to track real-time disk write operations, capturing anomalous write frequencies.
4. **AI Anomaly Detection:** Features (`[avg_entropy, modifications_per_sec, io_write_rate]`) are passed into a Scikit-Learn `IsolationForest` pipeline to detect and isolate malicious behavior.

---

## 📂 Directory Structure

```text
RansomGuard-AI/
├── src/
│   ├── __init__.py
│   ├── main.py                 # Application entry point
│   ├── monitor.py              # File system & process telemetry
│   ├── ai_engine.py            # Isolation Forest anomaly model
│   └── utils.py                # Shannon entropy math & terminal logging
├── tests/
│   ├── __init__.py
│   └── ransomware_simulator.py    # Local simulator for testing
├── .gitignore
├── LICENSE
├── README.md
├── RELEASE_NOTES.md
└── requirements.txt

```

---

## ⚙️ Installation & Setup

### Prerequisites

* Windows 10 / 11 / Linux
* Python 3.13

### 1. Clone the Repository

```bash
git clone https://github.com/JuttSahib1999/RansomGuard-AI.git
cd RansomGuard-AI

```

### 2. Create and Activate Virtual Environment

```bash
py -3.13 -m venv venv
# (Or use 'py -3.13 -m venv venv' depending on your preference)
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

```

### 3. Install Dependencies

```bash
pip install -r requirements.txt

```

---

## 💻 Usage

### Run the Detector

Run the detector as a module from the root directory:

```bash
python -m src.main

```

Upon launching, the engine profiles the system for 15 seconds to establish an operational baseline before entering active monitoring mode.

### Testing with the Built-in Simulator

A safe simulator script is included in `tests/` to validate detection behavior without using live malware.

1. Keep the main detector running in your primary terminal (`python -m src.main`).
2. Open a second terminal, activate your virtual environment, and run:
```bash
python -m tests.ransomware_simulator

```



The script generates dummy files in `C:\Users\Public\Documents\RansomGuard_Test` and overwrites them with high-entropy randomized byte streams. The detector terminal will immediately log the anomaly and flag the process.

---

## 👨‍💻 Author

Created by **Abdul Muqeet Tabraiz**

* **GitHub:** [@JuttSahib1999](https://github.com/JuttSahib1999)
* **LinkedIn:** [Abdul Muqeet Tabraiz](https://www.linkedin.com/in/abdul-muqeet-tabraiz/)

---

## 📄 License

This project is licensed under the MIT License. See the `LICENSE` file for details.