Installation Guide

Setting Up RansomShield AI

Give this about 25 minutes the first time. Most of that is pip downloading things. Follow the steps in order — the training step has to happen before the server step, otherwise you'll get a missing model file error and wonder what went wrong.

Prerequisites

• Python 3.10 or higher. 3.11 is what this was built on. Grab it from python.org, and on Windows tick the "Add Python to PATH" checkbox during install — forgetting that one causes about half of all setup problems. Check with python --version.
• pip. Ships with Python. Verify with pip --version.
• A code editor. VS Code is fine.
• That's it. No database server, no Docker, no Node. SQLite3 comes bundled with Python.

Step 1 — Open the project folder in a terminal

Extract the ZIP somewhere sensible. Not Downloads. Open a terminal there and confirm you can see the agent, detection, backend and scripts folders when you run dir on Windows or ls on macOS and Linux. If you don't see all four, you're one directory too high or too deep.

Step 2 — Create a virtual environment

This keeps the project's packages away from the rest of your system. From the repo root:

python -m venv .venv

Then activate it. On Windows:

.venv\Scripts\activate

On macOS or Linux:

source .venv/bin/activate

You'll know it worked because (.venv) appears at the start of your terminal line. If PowerShell refuses with an execution policy error, run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass in that same window and try again.

Step 3 — Install the dependencies

pip install -r requirements.txt

This pulls in Django 5, Django REST Framework, scikit-learn, XGBoost, psutil, watchdog and a few others. XGBoost is the biggest download, so give it a minute on slow wifi.

Step 4 — Train the detection models

python -m detection.train

This generates synthetic training telemetry, trains all three models and writes them as .joblib files into detection/model_store/, along with eval_results.json holding the evaluation metrics. Watch the console — the printed accuracy, precision, recall and false positive rate numbers are the ones you'll want to copy into your report. It's deterministic on seed 42, so re-running gives identical numbers.

Step 5 — Generate the demo scenarios

python scripts/generate_scenarios.py

Creates three .jsonl files in scenarios/: benign desktop activity, a backup job, and ransomware-like behaviour. All synthetic. No real files are read, written or harmed by this step.

Step 6 — Set up the database and seed the demo

cd backend
python manage.py migrate
python manage.py seed_demo

The seed_demo command creates your SOC analyst login, registers two demo agent nodes and replays all three scenarios in one go. When it finishes you'll have a populated dashboard, one open CRITICAL incident and a clean false-positive example already sitting there.

Step 7 — Run the server

python manage.py runserver

Open http://127.0.0.1:8000/login/ in your browser and log in:

username: soc_analyst
password: RansomShield!2026

Those credentials also get printed to your console during seeding, and the account is a Django superuser, so /admin/ works too.

Step 8 — Verify it's actually working

Four things to check, in this order:

1. On /dashboard, svchost32.exe should be sitting at risk score 100, marked CRITICAL.
2. Right below it, BackupAgent.exe should be in LOW or SAFE despite writing a lot of files. That's the false positive test passing.
3. Click into the CRITICAL incident on /incidents. You should see the event timeline, the feature contribution bar chart and the list of rule hits.
4. Open /models. If the comparison table is populated with real numbers, your training step worked properly.

All four good? You're done.

Optional — Run the live agent

Only if you want to show telemetry coming from your own machine. Open a second terminal, keep the server running in the first:

pip install -r agent/requirements.txt

On Windows PowerShell:

$env:RANSOMSHIELD_API_URL = "http://127.0.0.1:8000"
$env:RANSOMSHIELD_WATCH_DIR = "C:\Users\YourName\Documents"
python -m agent.main

On macOS or Linux use export RANSOMSHIELD_API_URL=... instead. The agent registers itself on first run and saves its API key to agent/agent_config.json. It reads only. Nothing in that folder gets touched.

Common Problems

"No such file or directory: detection/model_store/rf_model.joblib" — you skipped step 4 or ran it from the wrong folder. Go back to the repo root, activate the venv, run python -m detection.train again.

"No module named detection" when running the train command — you're inside backend/ instead of the repo root. Run cd .. first. Alternatively there's a python manage.py train_models command that works from inside backend/, if you'd rather stay there.

XGBoost fails to install or import on Windows — usually a missing Visual C++ Redistributable. Install it from Microsoft's site, restart the terminal, retry the pip install.

Dashboard loads but looks unstyled — Tailwind comes from a CDN, so this means no internet or a blocked CDN. The app still functions, it just looks plain. For an offline viva, download the Tailwind and Chart.js files into your static folder and update the template links beforehand.

Port 8000 already in use — something else is running there. Use python manage.py runserver 8080 and open port 8080 instead.