chrakouaanas2-tech/anti-ransomware

# Windows Anti-Ransomware Protection Platform A signature-less, offline anti-ransomware agent for Windows. It watches the filesystem in real time, detects ransomware-like behaviour (mass file modification, high-entropy writes, shadow-copy deletion, canary-file tampering), versions and encrypts protected files locally (and optionally to a remote SFTP host), and kills the offending process when an attack is confirmed. ## Features - **Real-time filesystem monitoring** (`watchdog`) over a configurable path - **Entropy-based encryption detection** (Shannon entropy of file content) - **Mass-modification & suspicious-process detection** (`psutil`) - **Canary (bait) files** — instant detection if a ransomware touches them - **Shadow-copy deletion detection** (catches `vssadmin delete shadows`) - **Versioned local backups** of protected file types, hashed for dedup - **AES-GCM-256 encrypted remote backup** over SFTP, rotating between two hosts - **Emergency snapshot** of files held open by suspect processes before killing them - **Process neutralisation** — terminates the ransomware on confirmed attack - **Auto-start on login** via the `HKCU\...\Run` registry key - **PySide6 desktop GUI** with log viewer, restore-from-backup and system tray ## Architecture agent.py Main agent loop (CLI entry point) run_gui.py GUI entry point (also starts the agent in a thread) config.yaml All tunables (thresholds, paths, remote servers) core/ file_monitor.py watchdog handler: counts modifications, triggers backup entropy_detector.py Shannon entropy check on first 4 KiB process_monitor.py Flags processes with too many open files shadowcopy_monitor.py Detects vssadmin shadow-copy deletion attempts canary.py Deploys + verifies bait files behavior_engine.py Weighted scoring -> ransomware? boolean response_engine.py Emergency snapshot + process kill persistence.py Registers agent in HKCU Run key backup/ config.py Loads backup settings from config.yaml backup_engine.py Entry point — local versioned + optional remote versioning.py Hash-deduplicated versioned local copies crypto.py AES-GCM-256 encrypt/decrypt key_manager.py Generates and stores the 256-bit key remote_backup.py SFTP upload, rotates between two servers by hour snapshot.py Emergency snapshot of in-use files restore.py Restore latest version of a file integrity.py SHA-256 helper gui/ app.py Bootstraps Qt app + tray + agent thread main_window.py Dashboard: log view, restore, browse backups tray.py System tray icon + menu alerts.py Modal alert when ransomware detected backups_viewer.py Read-only list of all backups agent_thread.py Runs the agent inside the Qt event loop utils/ entropy.py Shannon entropy logger.py File logger (writes logs/agent.log) helpers.py Wi-Fi disable/enable helpers ## Requirements - Windows 10 or 11 - Python 3.10+ (tested on 3.14) - Administrator privileges (for shadow-copy detection, registry write, killing processes) ## Setup ### 1. Clone git clone https://github.com//.git cd ### 2. Create a virtual environment (recommended) python -m venv .venv .\.venv\Scripts\Activate.ps1 ### 3. Install dependencies pip install -r requirements.txt ### 4. Review `config.yaml` Open `config.yaml` and adjust at least: | Key | What it controls | Default | | --- | --- | --- | | `watch_path` | Folder monitored for ransomware behaviour | `C:/Users` | | `backup_root` | Where versioned backups live | `C:/AntiRansomwareBackup` | | `protected_extensions` | File types backed up on every modification | docx/xlsx/pdf/jpg/png/txt/zip | | `canary_files` | Decoy file paths | two files under `C:/Users/Public/Documents` | | `file_modification_threshold` | Files changed in `time_window` before alert | 40 / 10s | | `entropy_threshold` | Bytes per byte considered "encrypted" | 7.5 | | `remote_backup_enabled` | Turn on SFTP backup | `false` | | `remote_servers` | List of SFTP targets (host/user/path) | placeholder IPs | | `remote_ssh_key` | Path to private key for SFTP | `~/.ssh/id_rsa` | ### 5. (Optional) Configure remote backup If you want encrypted off-host backup: 1. Set `remote_backup_enabled: true` in `config.yaml`. 2. Fill in `remote_servers` with one or two SFTP targets you own. 3. Make sure the matching SSH key is at `remote_ssh_key` and the public half is in the server’s `~/.ssh/authorized_keys`. 4. Files are encrypted client-side with AES-GCM-256 before upload — the remote host never sees plaintext. The encryption key is generated on first run at `C:/AntiRansomwareBackup/.key` and marked hidden. **Back this key up somewhere safe** — without it your encrypted backups (local and remote) cannot be restored. ### 6. Run **CLI mode** (logs to console + `logs/agent.log`): python agent.py **GUI mode** (dashboard + tray icon + agent thread): python run_gui.py Both should be launched from an elevated (admin) PowerShell session. ### 7. (Optional) Auto-start on login The agent registers itself in `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` on first launch, so it starts automatically at the next user login. To disable, delete the `AntiRansomwareAgent` value from that key (`regedit`). ## How detection works `core/behavior_engine.py` assigns a weighted score per loop iteration: | Signal | Weight | | --- | --- | | File modifications > threshold in window | +30 | | > 5 high-entropy modifications in window | +40 | | Canary file tampered with | +100 (instant trigger) | | `vssadmin` shadow-copy deletion observed | +60 | | Process with > `max_open_files` open files | +20 | If the score reaches **70** the agent calls `neutralize()`: it snapshots every file held open by the suspect processes, then terminates them. ## Restoring files From the GUI, click **Restore File From Backup**, pick the original path of the file you want back, and the latest encrypted version is decrypted and written in place. Programmatically: from backup.restore import restore_latest restore_latest("C:/AntiRansomwareBackup/C/Users/you/Documents/important.docx", "C:/Users/you/Documents/important.docx") ## What is NOT committed `.gitignore` excludes: - `__pycache__/`, build artefacts - `.idea/`, `.vscode/` IDE metadata - `logs/`, `*.log` - `.key`, `*.pem`, `id_rsa*` (any secrets that leak in) - `backups/`, `SNAPSHOTS/` - `.env*`, `config.local.yaml` The encryption key at `C:/AntiRansomwareBackup/.key` lives outside the repo by design — keep it that way. ## Limitations / known caveats - **Not a replacement for a real EDR.** Heuristics are coarse; a careful attacker who throttles their modification rate and avoids the canary files can evade detection. - **Watching `C:/` recursively is heavy.** Default is `C:/Users`. Watching the whole drive will saturate disk I/O because every modification triggers a backup attempt. - **First-run permissions:** if started without admin, `vssadmin` detection and process kill will partially fail, and the registry write may be denied. - **The GUI runs the agent in the same process.** A crash in the agent thread will take the GUI down. Run `agent.py` separately if you want them isolated. ## Development Smoke test all modules import cleanly: python -c "import agent, run_gui; print('OK')" Quick syntax check across the tree: python -m compileall . ## Disclaimer Educational / defensive use only. The author is not responsible for data loss, downtime, or any other consequence of running this software. Test in a virtual machine before deploying anywhere you care about.