🛡️ RansomGuard.ai — ML-Powered Ransomware Attack Classifier

RansomGuard is a network traffic classification system designed to detect and categorize network security attacks (specifically identifying ransomware-related traffic phases) using the UNSW-NB15 dataset.

This project is built using a Clean Architecture (Domain-Driven Design style) and demonstrates the implementation of 6 Gang of Four (GoF) Design Patterns in Python, with a FastAPI backend and a responsive, interactive vanilla HTML/CSS/JS frontend dashboard.

---

🚀 Key Features

• Interchangeable ML Models: Swap between a Random Forest classifier and an XGBoost classifier at runtime.
• 10-Class Classification: Classifies network packet flows into:
  • Normal (Benign traffic)
  • Fuzzers, Analysis, Backdoors, DoS, Exploits, Generic, Reconnaissance, Shellcode, and Worms.
• Ransomware Relevance Mapping: Flags categories based on their role in a ransomware attack lifecycle (e.g., Shellcode as payload delivery/dropper, Backdoor as Command & Control).
• Real-time Analytics Dashboard: Dynamic Chart.js charts showing prediction class distribution, model usage, and live request statistics.
• Flexible Inputs: Run classification by pulling a random row from the test set, pasting CSV data, or uploading a CSV file directly.

---

📐 Software Architecture & Design Patterns

The project follows clean architecture principles, separating the core business logic (Domain) from the data fetching, machine learning framework details (Infrastructure), and API endpoints (Presentation).

Project Root
├── backend/
│   ├── domain/           # Core Entities & interfaces (Framework-independent)
│   ├── application/      # Service layer & Facade (App use-cases)
│   ├── infrastructure/   # ML strategies, data loaders, and observers
│   └── presentation/     # FastAPI routers and schemas
├── frontend/             # Single-page web app (HTML, CSS, JS)
├── data/                 # UNSW-NB15 train/test CSVs (Ignored by Git)
├── models/               # Saved model (.pkl) files (Ignored by Git)
├── logs/                 # Execution logs (Ignored by Git)
└── train.py              # CLI script to train models

The 6 Implemented GoF Patterns

Pattern	Category	Role in RansomGuard	File Context
⚔️ Strategy	Behavioral	Defines a unified interface (IClassificationStrategy) for classification algorithms. Makes RandomForestStrategy and XGBoostStrategy fully interchangeable at runtime.	backend/infrastructure/ml/*_strategy.py
🏭 Factory Method	Creational	DataExtractorFactory instantiates the correct parser object (e.g. UnswCsvExtractor) based on the input type without exposing the creation logic.	backend/infrastructure/data/extractor_factory.py
👁️ Observer	Behavioral	Subscribes side-effects to the classification pipeline. When a prediction is made, ClassificationService (Subject) notifies LoggerObserver and StatsObserver (Observers) to update dashboards/logs.	backend/application/classification_service.py
💎 Singleton	Creational	ModelRegistry loads and stores trained .pkl models and scaling helpers into memory exactly once at startup, ensuring memory efficiency.	backend/infrastructure/ml/model_registry.py
🎭 Facade	Structural	ClassificationFacade hides the complexity of coordinating the extractor factory, ML strategies, model registry, and observer service behind a single simple API.	backend/application/classification_facade.py
📋 Template Method	Behavioral	MLPipeline defines the rigid algorithmic skeleton for training a model (Load ➔ Preprocess ➔ Select Features ➔ Build ➔ Train ➔ Evaluate ➔ Save). Subclasses override only build_model() and save().	backend/infrastructure/ml/ml_pipeline.py

---

🛠️ Installation & Setup Guide

1. Prerequisites

Ensure you have Python 3.10 or higher installed.

2. Clone the Repository

git clone https://github.com/bitwise-adi/ranDetect.git
cd ranDetect

3. Create and Activate a Virtual Environment

• Windows (PowerShell/CMD):

  python -m venv env
  .\env\Scripts\activate

• macOS / Linux:

  python3 -m venv env
  source env/bin/activate

4. Install Dependencies

pip install -r requirements.txt

5. Add the Dataset

Make sure your CSV datasets are placed in the data/ folder in the root directory:

• data/train.csv (UNSW-NB15 training dataset)
• data/test.csv (UNSW-NB15 testing dataset)

---

🏃 How to Run the Application

Step 1: Train the Machine Learning Models

Before starting the backend web server, you must train the models to generate the pickled model files:

• Train all models (recommended):

  python train.py

• Train only a specific model:

  python train.py --models rf      # Trains only Random Forest
  python train.py --models xgb     # Trains only XGBoost

The pipeline outputs the model weights to models/rf_model.pkl, models/xgb_model.pkl, and the shared data scaler to models/scaler.pkl.

Step 2: Start the FastAPI Server

Start the server using uvicorn:

uvicorn backend.main:app --reload

The server will start up on http://127.0.0.1:8000.

Step 3: Open the Frontend Dashboard

Open your web browser and navigate to: 👉 http://127.0.0.1:8000

You can now:

1. Select your ML strategy (Random Forest or XGBoost).
2. Grab random samples from the test set or input custom CSV data to classify.
3. Observe live analytics updates in the charts and tables below.