wiki created

2025-11-06 12:23:49 +01:00
parent 6cd3511962
commit 2fe9fa8254
60 changed files with 5012 additions and 142 deletions
@@ -0,0 +1,635 @@
+++ 
+title = "Troubleshooting" 
+chapter = false 
+weight = 10 
+pre = "6. " 
+++
+
+# Cazalla Troubleshooting Guide
+
+This guide helps you diagnose and resolve common issues when using Cazalla agent.
+
+## 📋 Table of Contents
+
+- [Agent Connection Issues](#agent-connection-issues)
+- [Command Execution Problems](#command-execution-problems)
+- [File Operations Issues](#file-operations-issues)
+- [Process Management Issues](#process-management-issues)
+- [Token Operations Issues](#token-operations-issues)
+- [Network Tunneling Issues](#network-tunneling-issues)
+- [Build and Compilation Issues](#build-and-compilation-issues)
+- [Mythic UI Integration Issues](#mythic-ui-integration-issues)
+- [General Debugging](#general-debugging)
+
+---
+
+## Agent Connection Issues
+
+### Agent Not Connecting to Mythic
+
+**Symptoms:**
+- Agent shows no connection in Mythic UI
+- No callback appears after executing agent
+- Agent appears to hang or exit immediately
+
+**Diagnosis:**
+
+1. **Check Network Connectivity**
+   ```bash
+   # From target machine
+   ping <mythic_server_ip>
+   curl https://<mythic_server>:443
+   ```
+
+2. **Check C2 Profile**
+   - Verify C2 profile is active in Mythic
+   - Check that port matches callback configuration
+   - Review C2 profile logs
+
+3. **Check Agent Execution**
+   ```cmd
+   # On Windows target
+   tasklist | findstr cazalla
+   # Should show cazalla.exe process
+   ```
+
+4. **Check Mythic Logs**
+   ```bash
+   # On Mythic server
+   sudo docker logs mythic_server
+   sudo docker logs cazalla_translator
+   ```
+
+**Solutions:**
+
+- **Network Issues**: Verify firewall rules, check routing
+- **C2 Profile Issues**: Rebuild payload with correct C2 profile
+- **Port Issues**: Verify port is open and accessible
+- **Agent Execution**: Check Windows Event Logs for errors
+
+---
+
+## Command Execution Problems
+
+### Commands Not Executing
+
+**Symptoms:**
+- Task stays in "Processing" state
+- No output returned
+- Command appears to hang
+
+**Diagnosis:**
+
+1. **Verify Agent is Active**
+   - Check callback status (should be green)
+   - Verify last check-in time
+   - Check agent is not sleeping
+
+2. **Check Command Syntax**
+   - Review command documentation in [Commands Reference](commands.md)
+   - Verify parameter format (JSON vs string)
+   - Check for typos
+
+3. **Review Task Output**
+   - Check task output for error messages
+   - Look for specific error codes
+   - Review translator logs
+
+**Solutions:**
+
+- **Syntax Errors**: Correct command syntax
+- **Parameter Issues**: Verify parameter format
+- **Agent Issues**: Restart agent if needed
+
+### Commands Return Errors
+
+**Symptoms:**
+- Commands return error messages
+- Windows error codes (e.g., "Error: Code 2")
+- Access denied errors
+
+**Common Errors:**
+
+#### Error Code 2 (ERROR_FILE_NOT_FOUND)
+```
+Error: No se pudo abrir el archivo. Código: 2
+```
+
+**Solution:**
+- Verify file path is correct
+- Check file exists
+- Use absolute paths if relative paths fail
+- Check current working directory with `pwd`
+
+#### Error Code 5 (ERROR_ACCESS_DENIED)
+```
+Error: Acceso denegado. Código: 5
+```
+
+**Solution:**
+- Verify permissions
+- Use `whoami` to check current context
+- Try token impersonation for elevated privileges
+- Check file/directory permissions
+
+#### Error Code 123 (ERROR_INVALID_NAME)
+```
+Error: Nombre de archivo inválido. Código: 123
+```
+
+**Solution:**
+- Check path for invalid characters
+- Verify path syntax is correct
+- Use proper path separators (`\` or `/`)
+- Check for null bytes or control characters
+
+---
+
+## File Operations Issues
+
+### File Not Found Errors
+
+**Symptoms:**
+- `cat`, `download`, `cp` fail with "file not found"
+- Relative paths don't work
+
+**Solution:**
+
+```bash
+# Check current directory
+pwd
+
+# Use absolute paths
+cat C:\Users\Administrator\Desktop\file.txt
+
+# Or change directory first
+cd C:\Users\Administrator\Desktop
+cat file.txt
+```
+
+### Download/Upload Fails
+
+**Symptoms:**
+- Download/upload commands fail
+- Large files fail to transfer
+- Chunks not received
+
+**Diagnosis:**
+
+1. **Check File Size**
+   - Files up to 2GB are supported
+   - Very large files may timeout
+
+2. **Check Network**
+   - Verify stable connection
+   - Check for network interruptions
+
+3. **Check Logs**
+   ```bash
+   sudo docker logs cazalla_translator | grep -i download
+   sudo docker logs cazalla_translator | grep -i upload
+   ```
+
+**Solutions:**
+
+- **Large Files**: Use smaller chunk sizes (requires code modification)
+- **Network Issues**: Retry operation
+- **Timeout Issues**: Increase sleep interval temporarily
+
+### Path Normalization Issues
+
+**Symptoms:**
+- Double backslashes in paths
+- Paths not resolving correctly
+
+**Solution:**
+
+Cazalla automatically normalizes paths, but if issues persist:
+- Use single backslashes: `C:\Users\file.txt`
+- Use forward slashes: `C:/Users/file.txt`
+- Avoid double backslashes: `C:\\Users\\file.txt` (will be normalized automatically)
+
+---
+
+## Process Management Issues
+
+### Process Browser Not Showing Processes
+
+**Symptoms:**
+- Processes don't appear in Process Browser UI
+- Process list is empty
+- Processes show as "UNKNOWN - MISSING DATA"
+
+**Diagnosis:**
+
+1. **Verify `ps` Command Executed**
+   - Check callback output for `ps` command
+   - Verify command completed successfully
+
+2. **Check Translator Logs**
+   ```bash
+   sudo docker logs cazalla_translator | grep -i process
+   ```
+
+3. **Verify Process Browser Integration**
+   - Check `ps.py` has `supported_ui_features = ["process_browser:list"]`
+   - Rebuild translator if changes were made
+
+**Solutions:**
+
+- **Rebuild Translator**: `sudo ./mythic-cli build cazalla`
+- **Check Process Parsing**: Verify translator is parsing process list correctly
+- **Check Permissions**: Some processes may require elevated privileges
+
+### Kill Command Fails
+
+**Symptoms:**
+- `kill` command returns error
+- Process not terminated
+- Access denied errors
+
+**Diagnosis:**
+
+1. **Check Process Exists**
+   ```bash
+   ps
+   # Verify PID exists
+   ```
+
+2. **Check Permissions**
+   - Verify current user context with `whoami`
+   - Some processes require elevated privileges
+
+3. **Check Critical PIDs**
+   - PIDs 0, 4, 8 are blocked for safety
+   - These cannot be killed
+
+**Solutions:**
+
+- **Permission Issues**: Use token impersonation for elevated privileges
+- **Critical PIDs**: These are intentionally blocked
+- **Protected Processes**: May require SYSTEM privileges
+
+---
+
+## Token Operations Issues
+
+### Token Theft Fails
+
+**Symptoms:**
+- `steal_token` returns error
+- Access denied errors
+- Process not found errors
+
+**Diagnosis:**
+
+1. **Check Process Exists**
+   ```bash
+   ps
+   # Verify PID exists
+   ```
+
+2. **Check Permissions**
+   - Verify current user context
+   - Some processes require `SeDebugPrivilege`
+
+3. **Check Process Access**
+   - Protected processes may require elevated privileges
+   - Session 0 processes require SYSTEM privileges
+
+**Solutions:**
+
+- **Permission Issues**: Use `make_token` to create SYSTEM token first
+- **Protected Processes**: May require SYSTEM privileges
+- **Session Issues**: Verify process is in accessible session
+
+### Token Impersonation Not Working
+
+**Symptoms:**
+- `whoami` shows original user after `steal_token`
+- Commands don't run with stolen token privileges
+
+**Diagnosis:**
+
+1. **Verify Token Theft**
+   ```bash
+   steal_token <PID>
+   whoami
+   # Should show impersonated user
+   ```
+
+2. **Check Token Selection**
+   - Verify token is selected in Mythic UI dropdown
+   - Check translator logs for token_id inclusion
+
+**Solutions:**
+
+- **Verify Impersonation**: Use `whoami` after `steal_token`
+- **Token Selection**: Select token from dropdown in Mythic UI
+- **Token Registration**: Verify token is registered as `callback_token`
+
+---
+
+## Network Tunneling Issues
+
+### SOCKS Proxy Not Working
+
+**Symptoms:**
+- SOCKS proxy doesn't accept connections
+- Connections timeout
+- Data doesn't flow
+
+**Diagnosis:**
+
+1. **Check Port is Open**
+   ```bash
+   sudo netstat -tlnp | grep 7002
+   # Should show port listening
+   ```
+
+2. **Check Mythic Configuration**
+   ```bash
+   grep DYNAMIC_PORTS_BIND_LOCALHOST_ONLY ~/Mythic/.env
+   # Should be "false" for external access
+   ```
+
+3. **Check Agent Status**
+   - Verify agent is active
+   - Check agent is not sleeping
+   - Verify SOCKS command executed successfully
+
+4. **Check Translator Logs**
+   ```bash
+   sudo docker logs cazalla_translator | grep -i socks
+   ```
+
+**Solutions:**
+
+- **Port Not Accessible**: Configure Mythic to bind on all interfaces
+- **Connection Timeout**: Verify agent is active and not sleeping
+- **Data Flow Issues**: Check translator logs for SOCKS block processing
+
+### Reverse Port Forwarding Not Working
+
+**Symptoms:**
+- RPFWD listener doesn't start
+- Connections don't forward
+- Port binding fails
+
+**Diagnosis:**
+
+1. **Check Port Binding**
+   - Verify port is not already in use
+   - Check for permission issues (privileged ports require admin)
+
+2. **Check Agent Logs**
+   - Look for RPFWD start messages
+   - Check for binding errors
+
+3. **Verify Connection**
+   ```bash
+   # From another machine or agent host
+   nc -nzv <agent_ip> 8080
+   ```
+
+**Solutions:**
+
+- **Port in Use**: Use different port
+- **Permission Issues**: Use non-privileged ports (>=1024)
+- **Connection Issues**: Verify network routing
+
+---
+
+## Build and Compilation Issues
+
+### Build Fails
+
+**Symptoms:**
+- Payload build fails in Mythic UI
+- Compilation errors
+- Docker build errors
+
+**Diagnosis:**
+
+1. **Check Docker**
+   ```bash
+   sudo docker ps
+   sudo docker logs cazalla_translator
+   ```
+
+2. **Check Build Parameters**
+   - Verify all required parameters are set
+   - Check parameter format (JSON vs string)
+
+3. **Check Build Logs**
+   - Review build output in Mythic UI
+   - Check for specific error messages
+
+**Solutions:**
+
+- **Docker Issues**: Restart Docker and Mythic
+- **Parameter Issues**: Verify build parameters
+- **Code Issues**: Check for syntax errors in C code
+
+### Encryption Not Working
+
+**Symptoms:**
+- Encryption not enabled
+- HMAC verification failed errors
+- Messages not encrypting/decrypting
+
+**Diagnosis:**
+
+1. **Check Build Parameters**
+   - Verify `AESPSK` parameter is configured
+   - Check `crypto_type` is set to `aes256_hmac`
+
+2. **Check Build Output**
+   - Look for: `✓ Encryption ENABLED`
+   - Verify encryption key is present
+
+3. **Check Translator Logs**
+   ```bash
+   sudo docker logs cazalla_translator | grep -i crypto
+   ```
+
+**Solutions:**
+
+- **Encryption Not Enabled**: Rebuild with `AESPSK` parameter
+- **HMAC Errors**: Rebuild payload to regenerate encryption key
+- **Key Mismatch**: Verify agent and translator use same payload UUID
+
+---
+
+## Mythic UI Integration Issues
+
+### Process Browser Not Updating
+
+**Symptoms:**
+- Processes don't appear in Process Browser
+- Process list is stale
+- Processes show incorrect data
+
+**Solutions:**
+
+1. **Execute `ps` Command**
+   ```bash
+   ps
+   # This updates Process Browser
+   ```
+
+2. **Clear Cache**
+   - Process Browser cache is cleared automatically
+   - Verify `update_deleted=True` is set in translator
+
+3. **Rebuild Translator**
+   ```bash
+   sudo ./mythic-cli build cazalla
+   ```
+
+### File Browser Not Working
+
+**Symptoms:**
+- Files don't appear in File Browser
+- File operations fail from UI
+- Paths not resolving
+
+**Solutions:**
+
+1. **Execute `ls` Command**
+   ```bash
+   ls
+   # This updates File Browser
+   ```
+
+2. **Check Path Resolution**
+   - Verify relative paths work
+   - Use absolute paths if needed
+
+3. **Check File Operations**
+   - Verify file operations work from command line
+   - Check permissions
+
+### Context Tabs Not Updating
+
+**Symptoms:**
+- Current directory not showing
+- Impersonation context not updating
+- Context tabs missing
+
+**Solutions:**
+
+1. **Verify Context Updates**
+   ```bash
+   cd C:\Users
+   # Should update cwd tab
+   
+   steal_token <PID>
+   # Should update impersonation_context tab
+   ```
+
+2. **Check Translator Logs**
+   ```bash
+   sudo docker logs cazalla_translator | grep -i context
+   ```
+
+3. **Verify Context Format**
+   - Check context data is in correct format
+   - Verify `0xF0` marker is used
+
+---
+
+## General Debugging
+
+### Enable Debug Logging
+
+**Agent Side:**
+- Define `DEBUG_SOCKS`, `DEBUG_SLEEP`, etc. during compilation
+- Rebuild agent with debug flags
+
+**Translator Side:**
+- Check translator logs: `sudo docker logs cazalla_translator`
+- Look for error messages and warnings
+
+### Check Agent Status
+
+```bash
+# Check current context
+whoami
+pwd
+
+# Check agent is responding
+ps
+ls
+
+# Check last check-in
+# (Visible in Mythic UI callback details)
+```
+
+### Review Logs
+
+**Mythic Server Logs:**
+```bash
+sudo docker logs mythic_server
+```
+
+**Translator Logs:**
+```bash
+sudo docker logs cazalla_translator
+```
+
+**Agent Logs:**
+- If running interactively, check console output
+- Check Windows Event Logs for errors
+
+### Common Issues Summary
+
+| Issue | Symptom | Solution |
+|-------|---------|---------|
+| **Agent Not Connecting** | No callback in UI | Check network, C2 profile, port |
+| **Commands Not Executing** | Task stuck in Processing | Check agent status, command syntax |
+| **File Not Found** | Error Code 2 | Use absolute paths, check current directory |
+| **Access Denied** | Error Code 5 | Check permissions, use token impersonation |
+| **Process Browser Empty** | No processes shown | Execute `ps` command, rebuild translator |
+| **SOCKS Not Working** | Connection timeout | Check port binding, agent status |
+| **Token Theft Fails** | Access denied | Use SYSTEM privileges, check process access |
+| **Build Fails** | Compilation errors | Check Docker, build parameters |
+
+---
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Check Documentation**
+   - [Commands Reference](commands.md)
+   - [Features Overview](features.md)
+   - [Getting Started](getting-started.md)
+
+2. **Review Logs**
+   - Mythic server logs
+   - Translator logs
+   - Agent logs (if available)
+
+3. **Verify Configuration**
+   - C2 profile settings
+   - Build parameters
+   - Network connectivity
+
+4. **Check Known Issues**
+   - Review GitHub issues (if available)
+   - Check Mythic documentation
+
+---
+
+## Related Documentation
+
+- [Commands Reference](commands.md) - Detailed command documentation
+- [Getting Started](getting-started.md) - Installation and setup
+- [Features Overview](features.md) - Feature explanations
+- [OPSEC Guide](opsec.md) - Security considerations
+
+---
+
+**Last Updated:** 2024
+