User Guide - RANZER

Getting Started

First Launch

When you open RANZER for the first time you'll go through a short setup flow before monitoring starts. Here's exactly what to expect on each screen.

1

Open RANZER

Windows: Click the RANZER shortcut in the Start Menu. You can also launch it from a new Command Prompt:

ranzer gui

Linux: Find RANZER in your Applications menu under System or Security, or run it from a terminal:

ranzer gui

On Windows, right-click RANZER and choose Run as administrator for full process termination capability across all users.

2

The landing screen

The first screen you see is a brief introduction explaining what RANZER does and how it works. This screen has two buttons:

· Get Started - moves you to the Setup screen to configure monitoring
· Learn More - opens the GitHub repository in your browser

Click Get Started when you're ready.

3

The Setup screen

This is where you tell RANZER which folders to protect and how aggressively to respond. You only need to do this once - RANZER remembers your settings the next time you open it.

See the Setting Up Monitoring section below for a full walkthrough of every option on this screen.

Configuration

Setting Up Monitoring

Choose which folders you want RANZER to protect and how it should respond when it detects an attack. You can monitor multiple directories simultaneously.

1

Add your directories

In the Setup screen, click Add Directory and choose a folder from the file browser. Repeat this for every folder you want to protect. Recommended folders to add:

· Desktop - files dragged here are a primary ransomware target
· Documents - office files, PDFs, spreadsheets
· Downloads - any file downloaded from the internet
· Pictures / Videos - irreplaceable personal files
· External drives - USB drives and mapped network shares

Focus on folders that contain your actual data. Avoid monitoring the drive root (C:\ or /) - system processes modify thousands of files per minute there and will flood you with noise.

2

Enable Honey Files

When Honey Files is enabled, RANZER automatically creates a set of hidden decoy files inside each monitored directory. These files have no legitimate reason to be touched by any software. If any process reads or writes to them, RANZER raises an immediate alert - even before entropy or write-rate signals escalate.

This makes honey files the fastest and most reliable detection trigger. Keep this enabled.

Don't touch, rename, or delete any file starting with . in your monitored folders after RANZER starts - those are likely honey files, and removing them disables this detection method for that directory.

3

Configure Auto-Terminate (optional)

When enabled, RANZER kills the suspected ransomware process the moment a CRITICAL alert fires - no click required. This stops encryption mid-attack and limits the number of files damaged.

This is optional during your first setup. See the Auto-Terminate section for guidance on when it's safe to turn on.

4

Start Monitoring

Click Start Monitoring. RANZER immediately:

· Deploys honey files into all configured directories
· Begins watching for file system events (writes, renames, creations, deletions)
· Starts sampling write rates per process
· Enables entropy analysis on all file writes

The app switches to the Dashboard view. RANZER is now actively protecting your files.

Once monitoring starts you can minimize RANZER to the system tray. It continues running in the background - you don't need to keep the window open.

Live View

Reading the Dashboard

The Dashboard tab shows live statistics from all monitored directories. Understanding these metrics helps you distinguish normal activity from a genuine attack.

Events / sec The number of file system events being processed right now - writes, renames, creations, deletions. A normal machine idle sits at 0–5. A sudden spike to 50+ is the first sign of ransomware bulk-encryption behaviour.

Threat Score A composite score from 0–100 combining entropy, honey file access, and write rate. 0–39 is normal. 40–69 is elevated (WARNING). 70–89 is high. 90–100 is CRITICAL.

Active Processes Processes currently writing to monitored directories, shown with their PID and name. RANZER tracks which process is responsible for each event, so you can identify a suspicious process by name.

Files Monitored The total number of files RANZER is watching across all monitored directories, including honey files. A sudden large drop in this count (files disappearing) is a red flag.

Entropy Reading Average randomness of recent file writes on a 0–8 scale. Normal files (text, code, documents) score 4–6. Encrypted output - the hallmark of ransomware - scores 7.8–8.0. Sustained high entropy from a single process is a major warning sign.

Alerts Log A real-time list of every detection event since monitoring started, newest first. Each entry shows a timestamp, severity level, the process name and PID, and the file that triggered the event.

What does a normal dashboard look like? Events/sec is low (under 5), Threat Score stays under 40, entropy reads are moderate (around 5–6), and the Alerts log shows only occasional INFO entries from apps you're actively using - like a text editor auto-saving.

Under the Hood

How RANZER Detects Ransomware

RANZER combines four independent detection methods and fuses their signals into a single threat score. No single method is relied on alone - this makes detection more accurate and harder to evade.

🞔

Honey File Monitoring

RANZER places hidden decoy files with realistic-looking names inside every monitored directory. No legitimate application has any reason to open these files. If any process touches a honey file, RANZER raises an immediate alert - this is the fastest and most reliable trigger. Real ransomware touches everything in a directory, so it hits these files within seconds of starting.

📈

Write Rate Tracking

RANZER monitors how many files per second each process is writing. A person saves one file at a time. Ransomware typically encrypts hundreds of files per minute in a tight loop. When a single process exceeds a configurable threshold, the write rate detector flags it as a WARNING and escalates to CRITICAL if the rate continues.

⚖

Shannon Entropy Analysis

Every file written to a monitored directory is sampled and its Shannon entropy is calculated - a measure of how random the data is. Normal files (text documents, spreadsheets, source code) have entropy between 4 and 6. Encrypted output - which is the core product of all ransomware - has near-maximum entropy of 7.8–8.0. Sustained high-entropy writes from a single process are a strong indicator of active encryption.

📃

File Extension Anomaly Detection

Ransomware commonly renames files after encrypting them - replacing the original extension with a custom one like .enc, .locked, or a random string. RANZER watches for mass rename events where many files lose their original extensions simultaneously, which is a behavioural pattern unique to ransomware.

These four signals are combined into a single Threat Score updated every 500ms. A CRITICAL alert requires multiple signals to confirm simultaneously - this prevents single-method false positives while ensuring genuine attacks are caught quickly.

Detection

Understanding Alerts

Every suspicious event is logged in the Alerts tab with a severity level, timestamp, process name, PID, and the file that triggered it. Here's what each severity means and exactly what you should do.

INFO - Normal file activity

A file event was observed - a write, rename, creation, or deletion. This is routine background activity from apps you're running. RANZER logs it for visibility.

Common sources: text editors auto-saving, browser downloads completing, cloud sync apps (Dropbox, OneDrive) syncing changes.

No action needed

WARNING - Elevated signals

One detection method has flagged something abnormal - typically higher-than-expected entropy in a file write, or a write rate spike from a single process. This alone isn't conclusive - backup tools, file converters, and compression software can all cause this legitimately.

What to do: Check the process name shown in the alert. If it's a known app (e.g. 7z.exe, dropbox, restic), it's a false positive - no action needed. If it's an unfamiliar process name or python.exe with no obvious reason, keep watching. If WARNINGs continue escalating, a CRITICAL alert may follow.

Investigate the process name

CRITICAL - Ransomware signature confirmed

Multiple detection signals confirmed simultaneously - a honey file was accessed AND high-entropy writes are occurring AND a single process is producing a high write rate. This combination is a strong indicator of active ransomware encryption.

If Auto-Terminate is enabled, the process has already been killed. If not, you'll see a prominent pop-up alert with the option to terminate it immediately.

What to do: If you didn't trigger this yourself (e.g. by running the built-in simulator), treat it as real. Disconnect from the internet immediately to prevent the ransomware from contacting its command-and-control server. Then check the PID shown in the alert - use Task Manager (Windows) or kill -9 <PID> (Linux) to terminate it if RANZER hasn't already. See the After Detection section for full recovery steps.

Act immediately

Protection

Auto-Terminate

When enabled, RANZER kills the suspected ransomware process the instant a CRITICAL alert fires - stopping encryption before it spreads further. No user interaction required.

!

Before you enable it

Auto-Terminate is powerful but requires care. In rare cases, a legitimate process performing large-scale writes - a backup tool, a database compaction job, a video encoder - could accumulate enough detection signals to cross the CRITICAL threshold.

Run RANZER in monitoring-only mode for at least a day before enabling Auto-Terminate. Review the Alerts tab to check whether any of your regularly-used apps are generating WARNINGs. If nothing legitimate is being flagged, you're ready to enable it.

✓

When it's safe to turn on

Auto-Terminate is most effective and least risky when all of these are true:

· You've reviewed at least one full day of alerts with no false-positive WARNINGs
· The monitored directories contain only user files (not application data or databases)
· You're primarily monitoring Desktop, Documents, Downloads, and Pictures
· No scheduled backup jobs run against the monitored folders

i

How termination works

When RANZER terminates a process it sends a SIGKILL (Linux) or calls TerminateProcess() (Windows) - a hard kill that gives the process no chance to save state or communicate back to an attacker's server.

On Windows, RANZER needs to be running as administrator to terminate processes started by other users. On Linux, it can only terminate processes owned by the same user unless run with sudo.

Recovery

What to Do After Detection

If RANZER fires a CRITICAL alert for something that isn't the built-in simulator, follow these steps immediately. Speed matters - the less time the ransomware runs, the fewer files it damages.

1

Disconnect from the internet. Pull out the ethernet cable or disable Wi-Fi. Most modern ransomware contacts a remote server to receive an encryption key - cutting the connection may prevent it from completing the key exchange and makes some strains unable to encrypt further.

2

Kill the process if it's still running. Check the PID shown in RANZER's CRITICAL alert. On Windows: open Task Manager → Details tab → find the PID → End Task. On Linux: run sudo kill -9 <PID> in a terminal.

3

Assess the damage. Browse your monitored folders and look for files that have been renamed with unfamiliar extensions like .enc, .locked, or a random string. The Alerts log in RANZER shows a timeline of exactly which files were touched and when, which helps you understand the scope.

4

Do not pay the ransom. There is no guarantee that paying will result in decryption. Instead, check the ransomware strain against nomoreransom.org - a free resource from law enforcement agencies that provides decryption tools for known strains.

5

Restore from backup. If you have recent backups (an external drive, cloud backup, Time Machine, or Windows Backup), restore the affected files from there. This is why regular backups are the single most effective ransomware defence alongside RANZER.

6

Run a full antivirus scan. Before reconnecting to the internet, run a full system scan with your antivirus to find and remove the ransomware dropper. RANZER detects and stops the encryption - cleaning the root infection is the antivirus's job.

Tuning

False Positives & Tuning

Some legitimate applications exhibit behaviour that resembles ransomware - bulk file writes, high-entropy output, or mass renames. Here's how to identify and handle false positives.

Common sources of false-positive WARNINGs:

Backup software Tools like Restic, Duplicati, Time Machine, or Windows Backup compress and write large amounts of data rapidly. They'll often trigger WARNINGs. They rarely reach CRITICAL because they don't touch honey files.

File compression 7-Zip, WinRAR, and similar tools create high-entropy output when compressing files. A large archive operation can trigger entropy-based WARNINGs.

Video encoding Exporters like HandBrake or ffmpeg write large amounts of high-entropy video data. Avoid monitoring folders where active video exports land.

Cloud sync Dropbox, OneDrive, and Google Drive sync agents perform batch writes when syncing large file sets. These typically produce INFO alerts at worst.

IDEs and code editors Large projects with many auto-save operations (VS Code, JetBrains) can generate a mild write rate. These stay in INFO territory and don't escalate.

Database engines SQLite, PostgreSQL, or MySQL performing writes inside a monitored folder can produce high write rates. Don't monitor folders that contain database files.

How to reduce false positives: If a specific legitimate app is generating WARNINGs regularly, move its working directory outside your monitored folders, or exclude the specific subfolder from monitoring. The goal is to monitor where your irreplaceable personal files live - not every folder on your system.

Always-On Protection

Run RANZER on Startup

For continuous protection, configure RANZER to start automatically when you log in. This ensures you're never unprotected after a reboot.

W

Windows - Task Scheduler

Open Task Scheduler from the Start Menu and click Create Basic Task. Set the trigger to When I log on. For the action, set the program to:

C:\Program Files\Ranzer\ranzer.exe gui

Tick Run with highest privileges so RANZER has full process-termination access. Click Finish.

Alternatively, create a shortcut to RANZER in your Startup folder: press Win + R, type shell:startup, and copy your RANZER shortcut there.

L

Linux - systemd user service

Create a user service file so RANZER starts on login:

# Create the service file
mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/ranzer.service

Paste the following content:

[Unit]
Description=RANZER Ransomware Detection

[Service]
ExecStart=/usr/local/bin/ranzer gui
Restart=on-failure

[Install]
WantedBy=default.target

Enable and start it:

systemctl --user enable ranzer
systemctl --user start ranzer

For CLI-only monitoring (e.g. a headless server), replace ranzer gui with ranzer monitor --dir /home/you/Documents --honey --auto-terminate.

Advanced

CLI Reference

Every feature available in the GUI is also accessible from the command line - useful for servers, scripts, automated pipelines, and power users who prefer the terminal.

Command	Description
ranzer gui	Launch the graphical interface. This is the recommended way to use RANZER for most users.
ranzer monitor --dir <path>	Start monitoring a directory in CLI mode. File events, entropy readings, and alerts are printed to the terminal in real time. Press Ctrl+C to stop.
ranzer monitor --dir <path> --auto-terminate	Monitor with automatic process termination on CRITICAL alerts. When RANZER kills a process, it prints the PID and process name to the terminal.
ranzer monitor --dir <path> --honey	Deploy honey files into the target directory before starting the monitor. Honey files persist between sessions - you only need this flag the first time you monitor a new directory.
ranzer monitor --dir <path> --delay <secs>	Set the sampling interval in seconds (default: 0.5). Lower values (e.g. 0.1) are more responsive but use more CPU. Higher values (e.g. 2.0) reduce CPU usage but may detect attacks a second or two later.
ranzer monitor --dir <path> --threshold <score>	Set the Threat Score at which a CRITICAL alert fires (default: 90). Raise this to reduce false positives; lower it to be more aggressive. Valid range: 50–99.
ranzer simulate --dir <path>	Run the built-in four-phase ransomware simulator against a test directory. See the Testing Detection section for a full walkthrough.
ranzer simulate --dir <path> --new-only	Only run Phase 4 (new file creation with high-entropy data). Skips the in-place overwrite and rename phases - useful for testing entropy detection in isolation.
ranzer simulate --dir <path> --files <n>	Set how many files the simulator creates in Phase 4 (default: 50). Use a higher number to test detection with a larger attack volume.
ranzer --version	Print the installed RANZER version number.
ranzer --help	Show all available commands and flags with short descriptions.

# Recommended setup - GUI with full protection
ranzer gui

# CLI - monitor Documents with auto-terminate and honey files
ranzer monitor --dir ~/Documents --auto-terminate --honey

# CLI - monitor multiple directories simultaneously (background jobs)
ranzer monitor --dir ~/Documents --honey &
ranzer monitor --dir ~/Desktop --honey &
ranzer monitor --dir ~/Downloads --honey &

# CLI - more sensitive detection (lower threshold)
ranzer monitor --dir ~/Documents --threshold 70 --honey

# CLI - lower CPU usage (sample every 2 seconds)
ranzer monitor --dir ~/Documents --delay 2.0 --honey

Verification

Testing Detection

RANZER includes a built-in simulator that mimics real ransomware behaviour across four phases. Always test after setting up RANZER to confirm detection is live before you rely on it. Do this in a throwaway directory - not your real files.

The simulator overwrites files with random bytes. Only point it at a temporary test folder you create specifically for this purpose. Never use your actual Documents, Desktop, or Downloads folder for this test.

1

Create a test directory with dummy files

The simulator needs existing files to overwrite in Phases 1 and 2. Create some empty dummy files:

# Linux / macOS
mkdir ~/ranzer_test
touch ~/ranzer_test/document.txt ~/ranzer_test/photo.jpg ~/ranzer_test/report.docx ~/ranzer_test/data.xlsx

# Windows (Command Prompt)
mkdir %USERPROFILE%\ranzer_test
echo test > %USERPROFILE%\ranzer_test\document.txt
echo test > %USERPROFILE%\ranzer_test\photo.jpg
echo test > %USERPROFILE%\ranzer_test\report.docx

2

Start RANZER monitoring the test directory

Open a terminal and start RANZER with auto-terminate and honey files enabled, pointing at your test directory:

ranzer monitor --dir ~/ranzer_test --auto-terminate --honey

Leave this terminal open and running. You'll see RANZER's output here when the simulator fires. Open a second terminal window for Step 3.

3

Run the simulator

In your second terminal, run:

ranzer simulate --dir ~/ranzer_test

The simulator runs four phases that mimic a real ransomware attack:

· Phase 1 - In-place encryption: Overwrites each file's contents with cryptographically-random bytes. This triggers entropy detection and the honey file engine simultaneously.
· Phase 2 - Rename to encrypted extension: Renames all files to filename.enc. This triggers file extension anomaly detection.
· Phase 3 - Ransom note drop: Creates a README_DECRYPT.txt file. This simulates the note left by real ransomware and triggers a honey file access if the decoy file was near it.
· Phase 4 - New file flood: Creates 50 new high-entropy .enc files to simulate ongoing encryption of files that don't exist yet.

4

Expected result

RANZER should detect the simulator during Phase 1 or 2 - before Phase 4 even starts. In your first terminal you'll see output like:

[CRITICAL] Threat score: 94/100 | PID: 12453 | ranzer_simulate
[ACTION]   Auto-terminate: killed process 12453
[HONEY]    Honey file accessed: .ranzer_honey_a3f9.bin

The simulator process should be terminated and Phase 4 should not complete (fewer than 50 .enc files will exist in the test folder).

If the simulator runs all the way to completion without being terminated, verify that: (1) you included both --auto-terminate and --honey, (2) the --dir path in both commands points to the same directory, and (3) RANZER was running before you started the simulator.

5

Clean up the test directory

After the test, delete the test folder - the files inside have been overwritten with random data and are no longer the original dummy files:

# Linux
rm -rf ~/ranzer_test

# Windows
rmdir /s /q %USERPROFILE%\ranzer_test

Best Practices

Tips & Best Practices

Get the most protection out of RANZER. These recommendations come from real-world usage and testing.

Monitor where your irreplaceable files live Desktop, Documents, Downloads, Pictures, Videos, and any external drives. These are where ransomware strikes first because they contain the highest-value files.

Never monitor system folders Avoid C:\Windows, /usr, /etc, or /var. System processes modify these constantly and will generate a flood of INFO and WARNING alerts that drown out real threats.

Test after every setup change Any time you add a new directory or change settings, run the simulator against a test folder to confirm detection is still working. Don't assume - verify.

Don't touch honey files RANZER places hidden decoy files automatically. Never rename, move, or delete any file you don't recognise in your monitored folders. If a honey file is removed, that directory loses its fastest detection method.

Run as administrator on Windows Launching RANZER with administrator rights gives it permission to terminate processes started by any user on the machine. Without it, RANZER can only terminate processes in your own session.

Trial period before Auto-Terminate Run in monitoring-only mode for a full working day. Check the Alerts log for any legitimate apps generating WARNINGs. Once you're confident in the accuracy, enable Auto-Terminate for maximum protection.

Keep backups regardless RANZER dramatically limits damage, but it's not a substitute for backups. RANZER stops encryption in seconds - but even seconds can mean dozens of files. A recent backup is your safety net for those files.

Use the GUI for daily use, CLI for servers The GUI is the easiest way to set up and monitor RANZER on a desktop or laptop. For headless Linux servers with no display, use CLI mode with ranzer monitor and a systemd service to keep it running.