🛡️ RansomWatch

Catch ransomware by how it behaves — and stop it before it finishes.

RansomWatch watches your folders and detects the tell-tale behavior of ransomware — rapidly rewriting many files into high-entropy (encrypted) blobs — then freezes the offending process so you can react while your files are still intact.

Local-first · no cloud · a clean live dashboard · built for security & defense.

---

Why behavior, not signatures?

Traditional antivirus looks for known malware. New ransomware strains slip past that every day. But almost all of them behave the same way: they tear through your files and encrypt them as fast as possible. RansomWatch ignores what a program is and watches what it does — so it can catch strains it has never seen before.

How it decides (multi-signal scoring)

A single signal like "high entropy" is not enough — ZIPs, JPEGs, videos, and backups are all legitimately high-entropy. RansomWatch combines several signals into one risk score (0–100+) and only reacts when they add up:

Signal	What it catches
Write burst	Dozens of files changing per second
Entropy spike	Files whose contents suddenly look encrypted (≥7.8 bits/byte)
Type / extension mismatch	A .jpg whose bytes are no longer a JPEG
New uniform extension	Many files suddenly gaining .locked, .crypt, …
Mass deletion	Originals being wiped after encryption
Ransom-note filenames	HOW_TO_DECRYPT_YOUR_FILES.txt and friends
🪤 Canary files	Hidden decoy files being touched — the strongest, lowest-false-positive signal

Legitimate high-entropy apps (archivers, media encoders, gpg, backup tools) and file types are whitelisted, so normal work never trips the alarm.

What it does when it fires

The default response is deliberately safe and reversible:

1. Alert — desktop notification + dashboard incident.
2. Suspend — the top suspect process is frozen with SIGSTOP. This stops the damage immediately without killing it, so no in-flight data is lost and you can inspect it. You can Resume or Kill it from the dashboard.
3. Kill — SIGKILL only if you opt into "Auto-kill" mode.

A safety floor means RansomWatch never suspends a process that isn't actually writing a lot of data — if it can't confidently identify a culprit, it alerts only and touches nothing.

🖥️ The dashboard

A live local dashboard (default http://localhost:8787) shows the current threat level, canary status, watched folders, a live file-activity feed, every incident with its evidence and suspect, and one-click Resume/Kill. The response policy (Alert / Suspend / Auto-kill) can be changed on the fly.

🚀 Quick start

git clone https://github.com/<your-username>/RansomWatch.git
cd RansomWatch
pip3 install -r requirements.txt
python3 run.py               # then open http://localhost:8787

By default it watches a self-contained ./sandbox folder so you can try it instantly. To protect real folders, copy config.example.json to config.json and set:

{ "watched_folders": ["~/Documents", "~/Desktop", "~/Pictures"] }

🧪 See it catch an attack (safely)

RansomWatch ships with a benign simulator that mimics ransomware behavior — rapidly writing random bytes and appending a .locked extension — but only inside a dedicated sandbox folder it creates itself. It contains no real malware, never touches your real files, and makes no network connections.

# In one terminal:
python3 run.py
# In another:
python3 tools/simulator.py         # watch the dashboard light up 🔴
python3 tools/simulator.py --clean # remove the sandbox afterwards

You'll see the threat level spike, an incident appear with the evidence, and the simulator process get frozen (SIGSTOP) within seconds.

🧱 Architecture

 watchdog events ─▶ Detector (rolling multi-signal score) ─▶ Incident
                          │                                     │
                    Canary manager                        Responder
                    (honeypot files)                  rank suspect ▶ suspend/kill
                                                             ▲
                                              WriteSampler (per-process disk I/O)

Module	Responsibility
ransomwatch/monitor.py	Watches folders via watchdog
ransomwatch/detector.py	Multi-signal risk scoring
ransomwatch/entropy.py	Entropy + content-type sniffing
ransomwatch/canary.py	Deploys & checks honeypot files
ransomwatch/whitelist.py	Known-good processes & file types
ransomwatch/sampler.py	Continuous per-process disk-write sampling
ransomwatch/procio.py	Per-process disk I/O (macOS proc_pid_rusage, else psutil)
ransomwatch/responder.py	Suspect ranking + suspend/kill + notifications
ransomwatch/app.py	Engine orchestration + Flask dashboard
tools/simulator.py	Benign, sandbox-only attack simulator

⚠️ Honest limitations

• Process attribution is best-effort. macOS does not tell a user-space program which process wrote a file (that requires Apple's Endpoint Security framework, root, and a special entitlement). RansomWatch approximates the culprit by ranking processes on live disk-write throughput. This works well against a fast encryptor but is an approximation — which is exactly why suspend (reversible), not kill, is the default, and why the safety floor exists.
• It is a heuristic layer, not a replacement for backups or a real EDR. A quiet result is not a guarantee. Keep offline backups and up-to-date antivirus.
• RansomWatch performs no encryption and runs nothing it finds — it only observes.

🔒 Requirements

• Python 3.9+
• macOS or Linux (built and tested on macOS; watchdog/psutil are cross-platform)

📄 License

MIT — see LICENSE.