Download created

README.md

@@ -25,6 +25,7 @@
 - [Process Browser Integration](#process-browser-integration)
 - [Artifacts Support](#artifacts-support)
 - [Credentials Support](#credentials-support)
+- [File Downloads Support](#file-downloads-support)
 - [Development](#development)
 - [Troubleshooting](#troubleshooting)
 - [Credits](#credits)
@@ -181,6 +182,7 @@ For more information, see the [Mythic documentation on customizing public agents
 | `mkdir` | Create directory | `mkdir C:\temp\new_folder` |
 | `rm` | Delete file or directory | `rm C:\temp\file.txt` |
 | `cat` | Read file contents (with automatic credential detection) | `cat C:\path\to\file.txt` |
+| `download` | Download file from target to Mythic server | `download C:\path\to\file.txt` |
 
 ### Execution & Control
 
@@ -559,15 +561,18 @@ Currently supported:
 - **File Write**: Automatically reported for:
   - `cp` (copy) - reports destination file path
   - `mkdir` (create directory) - reports created directory path
+- **File Delete**: Automatically reported for:
   - `rm` (delete) - reports deleted file/directory path
+- **File Read**: Automatically reported for:
+  - `download` - reports file path when downloading files
 
 **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
 - `ps` - already integrated with Process Browser
 - `sleep`, `exit` - don't modify system state
+- `cat` - read-only file operation (doesn't create artifacts, but may report credentials)
 
 Future support can be added for:
-- **File Read**: When files are downloaded/read (e.g., `download` command)
 - **File Write**: For file upload operations (e.g., `upload` command)
 - **Network Connection**: When network operations occur (e.g., for `socks` proxy connections)
 - **Registry Modification**: When registry keys are modified (e.g., `reg_set`, `reg_delete`)
@@ -605,7 +610,8 @@ Example implementations:
 - `shell`: Process Create artifact with command
 - `cp`: File Write artifact with destination path
 - `mkdir`: File Write artifact with directory path
-- `rm`: File Write artifact with deleted path
+- `rm`: File Delete artifact with deleted path
+- `download`: File Read artifact with downloaded file path
 
 ### Best Practices for New Commands
 
@@ -785,6 +791,97 @@ For more information, see the [Mythic Credentials documentation](https://docs.my
 
 ---
 
+## 📥 File Downloads Support
+
+Cazalla supports downloading files from the target to the Mythic server using chunked transfers, following [Mythic's File Downloads specification](https://docs.mythic-c2.net/customizing/hooking-features/download).
+
+### Features
+
+- **Chunked File Transfers**: Large files are automatically split into chunks (512KB default) for efficient transfer
+- **Automatic Registration**: Files are automatically registered with Mythic before transfer
+- **Progress Tracking**: Mythic tracks download progress (chunks received/total chunks)
+- **File Read Artifacts**: Automatically reports File Read artifacts when files are downloaded
+- **Full Path Tracking**: Reports full file paths for proper tracking in Mythic's file browser
+
+### How It Works
+
+1. **Command Execution**: When you execute `download C:\path\to\file.txt`, the agent:
+   - Opens the file for reading
+   - Calculates file size and number of chunks needed
+   - Sends a registration message to Mythic with file metadata (`total_chunks`, `full_path`, `chunk_size`)
+   - Receives a `file_id` from Mythic
+   - Reads and sends file data in chunks (base64-encoded)
+   - Reports a File Read artifact when complete
+
+2. **Mythic Integration**: The download is automatically:
+   - Registered in Mythic's file browser
+   - Tracked with progress (chunks received/total)
+   - Available for download from the Mythic UI once all chunks are received
+
+### Using the Download Command
+
+```bash
+# Download a file from the target
+download C:\Users\localuser\Downloads\file.txt
+
+# Downloads are chunked automatically - Mythic will show progress:
+# "0 / 5 Chunks Received" → "5 / 5 Chunks Received" (complete)
+```
+
+### Download Process
+
+1. **Registration**: Agent sends file metadata to Mythic
+   - `full_path`: Full path to the file
+   - `total_chunks`: Number of chunks needed
+   - `chunk_size`: Size of each chunk (512KB default)
+
+2. **File ID**: Mythic responds with a unique `file_id` for this download
+
+3. **Chunk Transfer**: Agent sends each chunk sequentially:
+   - Chunk number (1-based)
+   - `file_id` to associate with registration
+   - Base64-encoded chunk data
+
+4. **Completion**: Once all chunks are received, the file appears in Mythic's file browser
+
+### Example Download Flow
+
+```
+Agent: [download] Registrando descarga: C:\Users\file.txt (1024000 bytes, 2 chunks)
+Mythic: Response with file_id: "uuid-here"
+Agent: [download] Enviando chunk 1/2 (512000 bytes)
+Agent: [download] Enviando chunk 2/2 (512000 bytes)
+Agent: [download] Descarga completada: C:\Users\file.txt (1024000 bytes)
+Mythic: File available in file browser
+```
+
+### Implementation Details
+
+The download system uses:
+- **Chunk Size**: 512KB per chunk (configurable in code)
+- **File Size Limit**: Supports files up to 2GB (can be extended)
+- **Base64 Encoding**: Chunk data is base64-encoded before transmission
+- **Artifact Reporting**: Automatically reports "File Read" artifact with file path
+
+### Error Handling
+
+The download command handles various error scenarios:
+- **File Not Found**: Returns error message if file cannot be opened
+- **File Too Large**: Returns error if file exceeds 2GB limit
+- **Empty Files**: Properly handles empty files (0 bytes)
+- **Access Denied**: Returns Windows error code if access is denied
+
+### Viewing Downloaded Files
+
+1. Navigate to your callback in the Mythic UI
+2. Click the **Files** icon (file browser) in the top navigation
+3. View all downloaded files with their metadata
+4. Download files to your local system
+
+For more information, see the [Mythic File Downloads documentation](https://docs.mythic-c2.net/customizing/hooking-features/download).
+
+---
+
 ## 🔧 Development
 
 ### Project Structure