Ransomware Behavior Monitor

An educational, defensive Python project: a read-only monitor that watches a folder and flags ransomware-like file-system behavior in real time, plus a sandboxed lab that generates synthetic files and simulates an attack's file-system footprint to measure how well the detection works.

Status: work in progress (phase 2 of 5). How it works, evaluation results, and honest limitations will be written up in phase 5.

Safety rules

• All file-touching tests happen inside ./sandbox. Nothing else on the machine is read or changed.
• The monitor is read-only: it observes and alerts; it never modifies, moves, or deletes files.
• The simulator only touches synthetic files listed in the generator's manifest, and refuses to run outside ./sandbox or without the manifest.
• The simulator only overwrites dummy files with random bytes (os.urandom): no real encryption, no keys, no ransom notes, no network activity, no persistence, nothing that spreads.

These rules are enforced in code (src/rbm_lab/safety.py) and checked by tests (tests/test_safety.py, tests/test_static_guards.py).

Setup

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

What works so far

python scripts/generate_sandbox.py           # ~300 synthetic files + 7 canaries in ./sandbox/data
python scripts/inspect_file.py sandbox/data/<path to a file>   # how the monitor measures one file
python scripts/generate_sandbox.py --reset   # delete the generated files and make fresh ones
pytest                                       # unit tests (their scratch files also stay in ./sandbox)

Layout

Path	Contents
src/rbm/	the monitor: sampling, entropy, file-type checks (signals and scoring come in phase 3)
src/rbm_lab/	the test lab: sandbox guard, manifest, synthetic content, generator
scripts/	command-line entry points
tests/	pytest suite
sandbox/	generated at runtime, git-ignored: data/ (watched), manifest.json, canaries.json, pytest-tmp/