Open Source - RANZER

Source Code

Repositories

RANZER is split into two separate repositories - one for each platform. Both are public on GitHub under the MIT licence.

Linux

Ranzer

The Linux version. Contains the core detection engine, CLI, GUI, honey file system, and Debian packaging scripts. Builds a self-contained .deb installer.

github.com/RIVIRU05/Ranzer →

Windows

Ranzer-VU-Windows

The Windows version. Contains the same core engine adapted for Windows APIs, PyInstaller packaging scripts, and an Inno Setup script to produce a .exe wizard installer.

github.com/RIVIRU05/Ranzer-VU-Windows →

Both repositories are independent - the Linux repo does not depend on the Windows repo and vice versa. You only need to clone the repo for the platform you're running on.

Development

Run from Source

Running directly from source is the easiest way to try RANZER without using the pre-built installer, or to work on the code. No build tools required - just Python and the dependencies.

Linux

Windows

Linux - run from source

Tested on Ubuntu 20.04+, Debian 11+, Kali 2022+. Any apt-based distro should work.

Prerequisites

✓

Python 3.10 or later - check with python3 --version. Install via sudo apt install python3 if missing.

✓

pip - check with pip3 --version. Install via sudo apt install python3-pip if missing.

✓

git - check with git --version. Install via sudo apt install git if missing.

✓

libnotify-bin - for desktop notifications. Install via sudo apt install libnotify-bin.

1

Clone the repository

git clone https://github.com/RIVIRU05/Ranzer.git
cd Ranzer

2

Create a virtual environment (recommended)

python3 -m venv .venv
source .venv/bin/activate

Using a virtual environment keeps RANZER's dependencies isolated from your system Python. Skip this step if you prefer a global install.

3

Install dependencies

pip install -r requirements.txt

This installs watchdog, psutil, Pillow, and any other required libraries.

4

Run RANZER

# Launch the GUI
python3 -m ranzer gui

# Or run CLI monitoring directly
python3 -m ranzer monitor --dir ~/Documents --honey

That's it. RANZER is running from source. Any edits you make to the code take effect the next time you run it.

5

Optional - install as a local command

To be able to run ranzer from anywhere without the python3 -m prefix:

pip install -e .

The -e flag installs in editable mode - the command runs from the cloned source files, so your changes are reflected immediately.

All commands - from source (no install needed)

Every command below works the moment you finish pip install -r requirements.txt - no build step, no installer required.

# ── GUI ──────────────────────────────────────────────────────
python3 -m ranzer gui

# ── Start monitoring ─────────────────────────────────────────
# One directory
python3 -m ranzer start --dirs ~/Documents

# Multiple directories (comma-separated, no spaces)
python3 -m ranzer start --dirs ~/Documents,~/Desktop,~/Downloads

# Auto-terminate - kills the process on CRITICAL alert
python3 -m ranzer start --dirs ~/Documents --auto-terminate

# Disable honey files (not recommended)
python3 -m ranzer start --dirs ~/Documents --no-honeyfiles

# Lower entropy threshold - more sensitive (default: 7.5)
python3 -m ranzer start --dirs ~/Documents --threshold 7.0

# ── Status & logs ────────────────────────────────────────────
python3 -m ranzer status              # is RANZER currently running?
python3 -m ranzer log                 # last 20 alerts
python3 -m ranzer log --severity HIGH # only HIGH and CRITICAL
python3 -m ranzer log --limit 50      # last 50 alerts

# ── Entropy scanner ──────────────────────────────────────────
# Scan any file without starting the monitor
python3 -m ranzer scan --file /path/to/suspicious.bin

# ── Export ───────────────────────────────────────────────────
python3 -m ranzer export --format json --output alerts.json
python3 -m ranzer export --format csv  --output alerts.csv
python3 -m ranzer export --format txt  --output alerts.txt

# ── Simulator ────────────────────────────────────────────────
# Run the built-in ransomware simulator against a test folder
python3 simulate_ransomware.py        # high-entropy simulation
python3 simulate_risk_low.py          # write-rate only (low entropy)

# ── Help ─────────────────────────────────────────────────────
python3 -m ranzer --help
python3 -m ranzer start --help

After running pip install -e . (Step 5), replace python3 -m ranzer with just ranzer in every command above.

Windows - run from source

Tested on Windows 10 and Windows 11. Requires a Command Prompt or PowerShell.

Prerequisites

✓

Python 3.10 or later - download from python.org/downloads. During setup tick "Add Python to PATH". Verify with python --version in a new Command Prompt.

✓

git - download from git-scm.com or install via winget: winget install Git.Git. Verify with git --version.

1

Clone the repository

git clone https://github.com/RIVIRU05/Ranzer-VU-Windows.git
cd Ranzer-VU-Windows

2

Create a virtual environment (recommended)

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

3

Install dependencies

pip install -r requirements.txt

4

Run RANZER

:: Launch the GUI
python -m ranzer gui

:: Or run CLI monitoring
python -m ranzer monitor --dir %USERPROFILE%\Documents --honey

Open a new Command Prompt after activating the virtual environment if the ranzer command isn't found - existing windows don't pick up the new PATH.

5

Optional - install as a local command

pip install -e .

After this you can run ranzer gui directly from any Command Prompt (with the venv active).

All commands - from source (no install needed)

Every command below works the moment you finish pip install -r requirements.txt - no build step, no installer required.

:: ── GUI ──────────────────────────────────────────────────────
python -m ranzer gui

:: ── Start monitoring ─────────────────────────────────────────
:: One directory
python -m ranzer start --dirs %USERPROFILE%\Documents

:: Multiple directories (comma-separated, no spaces)
python -m ranzer start --dirs %USERPROFILE%\Documents,%USERPROFILE%\Desktop,%USERPROFILE%\Downloads

:: Auto-terminate - kills the process on CRITICAL alert
python -m ranzer start --dirs %USERPROFILE%\Documents --auto-terminate

:: Disable honey files (not recommended)
python -m ranzer start --dirs %USERPROFILE%\Documents --no-honeyfiles

:: Lower entropy threshold - more sensitive (default: 7.5)
python -m ranzer start --dirs %USERPROFILE%\Documents --threshold 7.0

:: ── Status & logs ────────────────────────────────────────────
python -m ranzer status               :: is RANZER currently running?
python -m ranzer log                  :: last 20 alerts
python -m ranzer log --severity HIGH  :: only HIGH and CRITICAL
python -m ranzer log --limit 50       :: last 50 alerts

:: ── Entropy scanner ──────────────────────────────────────────
:: Scan any file without starting the monitor
python -m ranzer scan --file C:\path\to\suspicious.bin

:: ── Export ───────────────────────────────────────────────────
python -m ranzer export --format json --output alerts.json
python -m ranzer export --format csv  --output alerts.csv
python -m ranzer export --format txt  --output alerts.txt

:: ── Simulator ────────────────────────────────────────────────
:: Run the built-in ransomware simulator against a test folder
python simulate_ransomware.py         :: high-entropy simulation
python simulate_risk_low.py           :: write-rate only (low entropy)

:: ── Help ────────────────────────────────────────────────────
python -m ranzer --help
python -m ranzer start --help

After running pip install -e . (Step 5), replace python -m ranzer with just ranzer in every command above.

Community

Contributing

RANZER is an academic open-source project and welcomes contributions - bug reports, feature suggestions, documentation improvements, or code.

Report a bug

Open an issue on the relevant GitHub repo. Include your OS version, architecture, the command you ran, and the full error output. Screenshots help.

Suggest a feature

Open a GitHub issue tagged enhancement. Describe the use case and why it matters - not just what you want added.

Submit a pull request

Fork the repo, create a feature branch, make your changes, and open a PR with a clear description. Run the built-in simulator to verify detection still works before submitting.

Improve the docs

If something in this guide is unclear, wrong, or missing - the website source is in the repo. PRs to the docs are just as welcome as code changes.

Linux Issues → Windows Issues →

Legal

Licence

RANZER is released under the MIT Licence. You are free to use, modify, and distribute it - for personal, academic, or commercial purposes - with no restrictions other than retaining the copyright notice.

MIT License

Copyright (c) 2026 RIVIRU05

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.