RansomGuard

A tool that simulates a ransomware attack and detects it in real time. Educational project to understand how ransomware works and how security software catches it.

What is this?

Basically, this project does two things:

1. The Attacker Side — A fake "ransomware" that rapidly renames and encrypts files (but only in a test folder, totally safe)
2. The Defender Side — A detection engine that watches what's happening and flags suspicious behavior

Think of it like a controlled crash test for security software.

Why build this?

I wanted to understand:

• How ransomware actually operates (it's faster and more systematic than you'd think)
• How real security tools like CrowdStrike or Defender catch attacks
• What "entropy" means and why encrypted files look different from normal files

It's also a cool portfolio project to show you understand real security engineering, not just theory.

How to run it

Requirements

• Python 3.11+
• Node.js 18+
• 10 minutes of your time

Setup

Terminal 1 — Start the backend:

cd backend
pip install -r requirements.txt
python server.py

You'll see: 🛡️ RansomGuard backend running on http://localhost:5000

Terminal 2 — Start the frontend:

cd frontend
npm install
npm start

This opens a browser tab to http://localhost:3000 with the dashboard.

Using the dashboard

1. Wait for the "● LIVE" badge to show up (means it's connected)

2. Click the "▶ Launch Attack" button

3. Watch what happens:

   • Threat score climbs in the orb (top left)
   • Entropy graph spikes (middle)
   • Files get renamed in real time (right side)
   • Alerts fire when threat gets high
   • When it hits CRITICAL, a full-screen alarm pops up

4. Click "↺ Restore" to undo everything

The whole thing takes about 45 seconds from start to "threat detected."

What's actually happening

The Attack

The simulator:

• XOR-encrypts files (not real encryption, but makes files look random)
• Renames them all to .locked extension
• Drops a fake ransom note

It only touches the test_environment/ folder. Nothing else gets touched.

The Detection

The detector monitors:

• Entropy — Encrypted files have high "randomness" (~7.5+). Normal text files don't.
• Speed — Real ransomware renames 50+ files in seconds. That's suspicious.
• Extension changes — Files suddenly getting .locked, .enc, etc.

When enough of these things happen at once, it flags it as a threat.

Project structure

backend/
  - detector.py    → entropy calculation + threat scoring
  - simulator.py   → fake ransomware (XOR + rename)
  - server.py      → Flask API + live event streaming

frontend/
  - App.jsx        → React dashboard
  
test_environment/
  - dummy files that get "encrypted" during demo

Tech stack

• Backend: Python, Flask, watchdog (file monitoring)
• Frontend: React, Recharts (for graphs)
• Real-time: Socket.IO (live updates)

Is this safe?

Yes. Completely.

• ✅ Only touches test_environment/ folder
• ✅ XOR is reversible (not real encryption)
• ✅ No network spread
• ✅ No persistence
• ✅ No actual malware code
• ✅ Click "Restore" and everything's back to normal

What I learned building this

• How to use entropy analysis to detect encryption
• Real-time file system monitoring (watchdog)
• Building live dashboards with WebSocket
• Behavioral detection heuristics (how EDR tools actually work)
• That ransomware is fast. Like, really fast.

Running with Docker

If you have Docker:

docker-compose up --build

Then go to http://localhost:3000

Future ideas

• Add process tracking (see what's spawning the attack)
• Network detection (ransomware usually tries to spread)
• Compare different encryption methods
• Add YARA rule integration
• Export threat data

License

MIT — do whatever you want with it

---

Built to understand security. Not affiliated with any commercial EDR vendor.