🛡 Keylogger Detector

A defensive cybersecurity tool for real-time process monitoring and keylogger detection. Built with Python · Ethical · Educational · Beginner-Friendly

---

📋 Table of Contents

1. Overview
2. Features
3. Detection Rules
4. File Structure
5. Installation
6. Usage
7. CLI Reference
8. GUI Guide
9. Risk Score System
10. Whitelist System
11. Logging System
12. Screenshots (Mock)
13. FAQ
14. Disclaimer

---

🔍 Overview

Keylogger Detector is a pure-Python, open-source defensive security tool that:

• Enumerates all running processes using psutil
• Applies a 10-rule detection engine to flag suspicious behaviour
• Assigns a numeric risk score and maps it to a human-readable risk level
• Maintains a JSON-backed whitelist of trusted processes
• Logs all findings to JSON, CSV, and plain-text log files
• Displays results in a rich colour-coded terminal table
• Provides an optional Tkinter desktop GUI
• Exports consolidated CSV reports

The tool is designed to be:

Property	Details
Defensive only	Detects suspicious processes; does NOT interfere with them
Ethical	No offensive capabilities whatsoever
Beginner-friendly	Clear comments, modular design, simple to extend
Cross-platform	Windows, Linux, macOS

---

✨ Features

Feature	Description
🔍 Real-time scanning	Enumerate all running processes with psutil
⚙ Rule-based detection	10 independent detection rules
📊 Risk scoring	Numeric score → SAFE / LOW / MEDIUM / HIGH / CRITICAL
🛡 Whitelist system	JSON-backed trusted process list
🔄 Continuous monitoring	Auto-refresh every N seconds (configurable)
🎨 Colour-coded output	Rich terminal tables (green=safe, red=suspicious)
📄 Multi-format logging	JSON, CSV, and plain-text daily logs
📈 Report export	Consolidated CSV export of all historical data
🖥 Desktop GUI	Full Tkinter interface with dark/light mode
🚨 Alert system	Terminal bell + large alert panel for HIGH/CRITICAL
🔧 CLI interface	Full argparse-based command-line interface

---

🔬 Detection Rules

Rule ID	Name	Severity	Score	Description
SN-01	Suspicious Name Keyword	HIGH	+40	Process name contains keywords like keylog, hook, spy, record, etc.
SP-01	Suspicious Directory	HIGH	+35	Executable runs from Temp, AppData, or other unusual directories
SP-02	Hidden Directory	MEDIUM	+25	Executable path contains a hidden (dot-prefixed) directory
SP-03	Random Hex Filename	HIGH	+35	Executable has a hex-only or numeric-only name (common malware technique)
SP-04	Double Extension	CRITICAL	+50	Filename has double extension e.g. photo.jpg.exe
CPU-01	High CPU Usage	LOW–HIGH	+5–25	CPU usage exceeds 20% / 50% / 85% thresholds
MEM-01	High Memory Usage	LOW–MEDIUM	+5–12	Memory usage exceeds 200 MB / 500 MB thresholds
PP-01	Orphaned Process	MEDIUM	+15	Process has no parent (PPID=0 or missing)
UK-01	Unknown No-Path Process	MEDIUM	+20	Process is unknown AND has no executable path
PRIV-01	Elevated Privilege	HIGH	+20	Suspicious process running as root/SYSTEM

---

📁 File Structure

keylogger_detector/
│
├── main.py              ← CLI entry point (argparse)
├── process_scanner.py   ← Process enumeration + display logic
├── detector.py          ← Detection rule engine
├── whitelist.py         ← Whitelist management (JSON-backed)
├── logger.py            ← JSON / CSV / text logging + report export
├── gui.py               ← Tkinter desktop GUI
│
├── whitelist.json       ← Auto-created on first run
├── requirements.txt     ← Python dependencies
│
├── logs/                ← Auto-created log directory
│   ├── scan_YYYY-MM-DD.json   ← NDJSON scan records
│   ├── scan_YYYY-MM-DD.csv    ← CSV scan records
│   └── scan_YYYY-MM-DD.log    ← Human-readable plain text
│
└── reports/             ← Auto-created reports directory
    └── report_YYYYMMDD_HHMMSS.csv  ← Exported reports

---

🚀 Installation

Prerequisites

• Python 3.8+ (check with python --version)
• pip (comes with Python)

Step 1 — Clone or Download

# Option A: Clone with Git
git clone https://github.com/yourusername/keylogger-detector.git
cd keylogger-detector

# Option B: Download ZIP and extract
cd keylogger_detector

Step 2 — (Optional) Create a virtual environment

# Windows
python -m venv venv
venv\Scripts\activate

# Linux / macOS
python3 -m venv venv
source venv/bin/activate

Step 3 — Install dependencies

pip install -r requirements.txt

That's it! No complex setup, no database, no config files.

---

💡 Usage

Quick Start

# Perform a single scan and display results
python main.py --scan-once

# Start continuous monitoring (Ctrl+C to stop)
python main.py --monitor

# Launch the graphical interface
python main.py --gui

---

📖 CLI Reference

usage: keylogger_detector [-h] [--scan-once] [--monitor] [--interval SECONDS]
                           [--add-whitelist PROCESS_NAME]
                           [--remove-whitelist PROCESS_NAME]
                           [--view-whitelist] [--view-logs]
                           [--log-date YYYY-MM-DD] [--log-all]
                           [--export-report] [--gui]

Argument	Description
--scan-once	Perform one scan and exit
--monitor	Continuous monitoring mode
--interval N	Refresh interval in seconds for --monitor (default: 5)
--add-whitelist NAME	Add a process to the trusted whitelist
--remove-whitelist NAME	Remove a process from the whitelist
--view-whitelist	List all trusted processes
--view-logs	Show today's suspicious activity log
--log-date YYYY-MM-DD	Use with --view-logs to view a specific day
--log-all	Include safe processes in log output
--export-report	Export all scan data to a CSV report
--gui	Launch the Tkinter desktop GUI

Examples

# Single scan
python main.py --scan-once

# Monitor with 10-second refresh
python main.py --monitor --interval 10

# Trust a new application
python main.py --add-whitelist "myapp.exe"

# Remove from whitelist
python main.py --remove-whitelist "badapp.exe"

# View all trusted processes
python main.py --view-whitelist

# View today's log
python main.py --view-logs

# View a specific day's log
python main.py --view-logs --log-date 2024-05-01

# Export all data to CSV
python main.py --export-report

# Launch GUI
python main.py --gui

---

🖥 GUI Guide

Launch with:

python main.py --gui
# or directly
python gui.py

GUI Panels

Panel	Description
Dashboard	Live process table with colour-coded risk levels, stats cards, search & filter
Whitelist	Add/remove/view trusted processes
Logs	Browse log files, view content in-app
Reports	Summary statistics and CSV export
About	Version info, detection rules, disclaimer

Dashboard Controls

• ▶ Scan Now — Immediately trigger a scan
• Auto-refresh — Toggle automatic scanning
• Interval (s) — Set refresh interval (2–60 seconds)
• Double-click row — View full process details
• Right-click row — Context menu (view details, add to whitelist, copy name)
• Search box — Filter by name or path
• Risk radio buttons — Filter by risk level

---

📊 Risk Score System

Each detection rule contributes points to a risk score. The total score is mapped to a risk level:

Risk Level	Score Range	Color	Icon
SAFE	0	🟢 Green	✅
LOW	1–10	🟡 Yellow	⚠
MEDIUM	11–30	🟠 Orange	🟠
HIGH	31–60	🔴 Red	🔴
CRITICAL	61+	⚫ White on Red	🚨

Example risk score calculation:

Process: suspicious.exe in C:\Temp\
  SN-01  Name keyword 'spy'  → +40 pts
  SP-01  Runs from C:\Temp\  → +35 pts
  PP-01  No parent process   → +15 pts
                               ─────────
  Total: 90 pts → CRITICAL 🚨

---

🛡 Whitelist System

The whitelist is stored in whitelist.json and pre-populated with ~150 known-safe system processes including:

• Windows system processes (explorer.exe, svchost.exe, lsass.exe, …)
• Linux system daemons (systemd, bash, dbus-daemon, …)
• Common applications (Chrome, Firefox, VS Code, Python, …)
• Security tools (Windows Defender, Malwarebytes, …)

Managing the Whitelist

# Add a process (CLI)
python main.py --add-whitelist myapp.exe

# Remove a process (CLI)
python main.py --remove-whitelist suspiciousapp.exe

# View all (CLI)
python main.py --view-whitelist

# Add from GUI: right-click any process → "Add to Whitelist"

The whitelist is automatically saved to whitelist.json after every change.

---

📄 Logging System

All scan results are written to daily-rotated files in the logs/ directory:

Log Formats

Format	File	Description
NDJSON	scan_YYYY-MM-DD.json	One JSON object per line, machine-readable
CSV	scan_YYYY-MM-DD.csv	Spreadsheet-friendly flat format
Plain Text	scan_YYYY-MM-DD.log	Human-readable with timestamps

CSV Columns

timestamp, pid, name, exe_path, cpu_percent, mem_mb, ppid,
username, status, is_whitelisted, risk_level, risk_score, primary_reason

Exporting Reports

# CLI export (auto-named)
python main.py --export-report

# GUI export (file dialog)
Reports panel → "Export CSV Report"

---

🖼 Screenshots (Mock Examples)

❓ FAQ

Q: Will this tool crash if a process terminates mid-scan? A: No. All process attribute access uses try/except blocks for NoSuchProcess, AccessDenied, and ZombieProcess errors from psutil.

Q: I'm getting false positives for legitimate software. A: Add those processes to the whitelist: python main.py --add-whitelist processname.exe

Q: Does this work on Linux/macOS? A: Yes. All detection rules are cross-platform. Some Windows-specific path checks (AppData, System32) won't apply on Linux but won't cause errors.

Q: Does the tool require administrator/root privileges? A: Basic scanning works without elevated privileges. Some process attributes (username, executable path) may show as N/A for system processes due to OS-level access restrictions.

Q: Can I run this on a server (headless)? A: Yes, use --scan-once or --monitor modes. The GUI requires a display.

---

⚠ Disclaimer

This tool is intended exclusively for defensive and educational purposes.

• ✅ Monitor your own systems
• ✅ Use in controlled security research environments
• ✅ Educational learning about process analysis
• ❌ Do NOT use to monitor systems without explicit permission
• ❌ Do NOT use as a hacking or surveillance tool

The detection rules may produce false positives. Always verify suspicious findings manually before taking any action. The authors are not responsible for any misuse or damages arising from the use of this tool.

---

📦 Requirements

psutil>=5.9.0     # Cross-platform process and system utilities
rich>=13.0.0      # Beautiful terminal formatting (optional but recommended)
colorama>=0.4.6   # Windows ANSI color support

Tkinter comes pre-installed with Python on most platforms. If missing:

# Ubuntu/Debian
sudo apt-get install python3-tk

# Fedora
sudo dnf install python3-tkinter

# macOS (via Homebrew Python)
brew install python-tk

---

🤝 Contributing

Contributions are welcome! Ideas for improvement:

• Add more detection rules (e.g. network connections, open handles)
• Integrate VirusTotal API for hash lookups
• Add Windows Event Log monitoring
• Add macOS launchd / Linux systemd service inspection
• Build an installer (.exe for Windows via PyInstaller)

---

Built with ❤️ for cybersecurity education — Stay safe, stay ethical.