+++ 
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