keystrokes implemented

2025-10-30 17:26:33 +01:00
parent ad85e06458
commit 519d2a8946
10 changed files with 471 additions and 0 deletions
@@ -27,6 +27,7 @@
 - [Credentials Support](#credentials-support)
 - [File Downloads Support](#file-downloads-support)
 - [File Uploads Support](#file-uploads-support)
+- [⌨️ Keylogging Support](#%EF%B8%8F-keylogging-support)
 - [Development](#development)
 - [Troubleshooting](#troubleshooting)
 - [Credits](#credits)
@@ -200,6 +201,8 @@ For more information, see the [Mythic documentation on customizing public agents
 |---------|-------------|---------|
 | `ps` | List running processes with Process Browser support | `ps` |
 | `screenshot` | Capture full-screen screenshot (Mythic screenshot UI) | `screenshot` |
+| `keylog_start` | Start keystroke logging | `keylog_start` |
+| `keylog_stop` | Stop keystroke logging | `keylog_stop` |

 **Note**: The `ps` command integrates with Mythic's Process Browser, allowing unified process management across multiple callbacks. Process lists are automatically synchronized and viewable from the Process Browser UI.

@@ -515,6 +518,7 @@ Cazalla automatically reports artifacts created during command execution, allowi
 - **Extensible**: Easy to add artifact reporting for other commands (File Write, Network Connection, etc.)
 - **API Call**: Reported for:
  - `screenshot` - GDI Screen Capture (GetDC, CreateCompatibleDC, CreateCompatibleBitmap, BitBlt, GetDIBits)
+  - `keylog_start` - Keyboard Hook (GetAsyncKeyState, GetForegroundWindow, GetWindowTextA, GetUserNameA)

 ### How It Works

@@ -573,6 +577,7 @@ Currently supported:
  - `download` - reports file path when downloading files
 - **API Call**: Reported for:
  - `screenshot` - GDI Screen Capture (GetDC, CreateCompatibleDC, CreateCompatibleBitmap, BitBlt, GetDIBits)
+  - `keylog_start` - Keyboard Hook (GetAsyncKeyState, GetForegroundWindow, GetWindowTextA, GetUserNameA)

 **Note**: The following commands don't require artifacts as they are read-only or don't modify system state:
 - `ls`, `cd`, `pwd` - read-only file system operations
@@ -620,6 +625,8 @@ Example implementations:
 - `upload`: File Write artifact with destination file path
 - `rm`: File Delete artifact with deleted path
 - `download`: File Read artifact with downloaded file path
+- `screenshot`: API Call artifact for screen capture APIs
+- `keylog_start`: API Call artifact for keyboard hook APIs

 ### Best Practices for New Commands

@@ -996,6 +1003,135 @@ For more information, see the [Mythic File Upload documentation](https://docs.my

 ---

+## ⌨️ Keylogging Support
+
+Cazalla supports capturing keystrokes from the target system and reporting them to Mythic's Keylogs feature, following [Mythic's Keylog specification](https://docs.mythic-c2.net/customizing/hooking-features/keylog).
+
+### Features
+
+- **Window-Aware Keylogging**: Captures keystrokes along with the active window title
+- **User Context**: Includes the username in each keylog entry
+- **Process-Agnostic**: Works with any application (Notepad, browsers, terminals, etc.)
+- **Automatic Buffering**: Buffers keystrokes and sends them periodically (every 3 seconds or 128 bytes)
+- **Background Thread**: Runs as a separate thread, allowing other commands to execute while keylogging
+- **API Call Artifacts**: Automatically reports API Call artifacts when keylogging starts
+
+### How It Works
+
+1. **Start Keylogging**: When you execute `keylog_start`, the agent:
+   - Starts a background thread that monitors keyboard input
+   - Uses `GetAsyncKeyState` to detect key presses
+   - Captures the active window title using `GetForegroundWindow` and `GetWindowTextA`
+   - Captures the current username using `GetUserNameA`
+   - Buffers keystrokes and sends them every 3 seconds or when buffer reaches 128 bytes
+
+2. **Keylog Transmission**: The keylogger periodically sends captured keystrokes:
+   - Each transmission includes: user, window title, and captured keystrokes
+   - Format follows Mythic's keylog specification
+   - Keylogs appear in Mythic's Keylogs UI automatically
+
+3. **Stop Keylogging**: When you execute `keylog_stop`, the agent:
+   - Stops the background keylogging thread
+   - Sends a final acknowledgment response
+
+### Using the Keylog Commands
+
+```bash
+# Start keylogging
+keylog_start
+
+# Stop keylogging
+keylog_stop
+```
+
+### Keylog Process
+
+1. **Start**: Agent creates a background thread that:
+   - Polls keyboard state every 20ms
+   - Detects key presses using `GetAsyncKeyState`
+   - Captures printable ASCII characters and special keys (Backspace, Tab, Enter)
+   - Gets the active window title and username on each send cycle
+
+2. **Buffer & Send**: Keystrokes are buffered and sent when:
+   - Buffer reaches 128 bytes, OR
+   - 3 seconds have passed since last send (if buffer has data)
+
+3. **Format**: Each keylog entry contains:
+   - `user`: Current Windows username (e.g., "localuser")
+   - `window_title`: Title of the active window (e.g., "*hello, this is a test - Notepad")
+   - `keystrokes`: Actual captured keystrokes
+
+4. **Stop**: Background thread is terminated gracefully
+
+### Example Keylog Flow
+
+```
+Agent: [keylog] Started
+# User types in Notepad...
+Agent: [KEYLOG] Detectado keylog para user='localuser', window='*hello, this is a test - Notepad'
+Mythic: Keylog appears in Keylogs tab
+# More typing...
+Agent: [KEYLOG] Detectado keylog para user='localuser', window='*hello, this is a test - Notepad'
+Mythic: Additional keystrokes added to keylog entry
+Agent: [keylog] Stopped
+```
+
+### Universal Process Support
+
+The keylogger works with **any Windows application** because it:
+- Uses `GetForegroundWindow()` to get the currently active window
+- Captures keystrokes system-wide using `GetAsyncKeyState`
+- Doesn't require injection into specific processes
+
+**This means it works for:**
+- ✅ Text editors (Notepad, VS Code, etc.)
+- ✅ Browsers (Chrome, Firefox, Edge)
+- ✅ Terminal windows (cmd.exe, PowerShell)
+- ✅ Any application that receives keyboard input
+- ✅ Secure input fields (though characters may appear as visible in the buffer)
+
+### Implementation Details
+
+The keylogging system uses:
+- **Polling Method**: `GetAsyncKeyState` to detect key presses (low-level approach)
+- **Window Detection**: `GetForegroundWindow` + `GetWindowTextA` to identify active windows
+- **User Detection**: `GetUserNameA` to get current Windows username
+- **Thread Safety**: Runs in a separate thread, allowing concurrent command execution
+- **Buffer Management**: 2048-byte buffer to store keystrokes before transmission
+- **Artifact Reporting**: Automatically reports "API Call" artifact when keylogging starts
+
+### Error Handling
+
+The keylog commands handle various scenarios:
+- **Already Running**: If keylogger is already active, `keylog_start` returns success without creating duplicate threads
+- **Not Running**: If keylogger is not running, `keylog_stop` returns success (no-op)
+- **Thread Cleanup**: Thread is properly terminated and handles are closed when stopping
+
+### Viewing Keylogs
+
+1. Navigate to your callback in the Mythic UI
+2. Click the **KEYLOGS** tab in the top navigation
+3. View all captured keystrokes grouped by:
+   - Task and callback
+   - User and host
+   - Window title
+   - Timestamp
+4. Use "View Window Together" to see all keystrokes from a specific window session
+5. Filter keylogs by user, window, or time range
+
+### Artifact Support
+
+The `keylog_start` command automatically reports an **API Call** artifact:
+- **Type**: API Call
+- **Value**: "Keyboard Hook: GetAsyncKeyState, GetForegroundWindow, GetWindowTextA, GetUserNameA"
+- **Purpose**: Tracks that keylogging APIs were used on the system
+
+This artifact appears in Mythic's Artifacts page when keylogging is started.
+
+For more information, see the [Mythic Keylog documentation](https://docs.mythic-c2.net/customizing/hooking-features/keylog).
+
+---
+
 ## 🔧 Development

 ### Project Structure