Skip to content

technical_documentation.md

Latest commit

 

History

History
285 lines (235 loc) · 9.06 KB

technical_documentation.md

File metadata and controls

285 lines (235 loc) · 9.06 KB
Raw

Educational RAT - Technical Documentation

Overview

This document provides technical details about the Educational Remote Access Tool (RAT) for macOS, designed for CyberSec and Computer Science education.

Architecture

Client-Server Model

The Educational RAT uses a simple client-server architecture:

┌─────────────────┐    Network    ┌─────────────────┐
│   Server        │   Protocol    │   Client        │
│   (C&C)         │   (TCP)       │   (Target)      │
│                 │               │                 │
│ - Command       │◄─────────────►│ - Command       │
│   Processing    │               │   Execution     │
│ - Authentication│               │ - System Info   │
│ - Client Mgmt   │               │ - Response      │
└─────────────────┘               └─────────────────┘

Components

Server (server.py)

  • Role: Command & Control center
  • Responsibilities:
    • Listen for client connections
    • Authenticate clients
    • Send commands to clients
    • Receive and display responses
    • Manage multiple client connections

Client (client.py)

  • Role: Target machine agent
  • Responsibilities:
    • Connect to server
    • Authenticate with server
    • Execute received commands
    • Send results back to server
    • Maintain connection

Security Features

Authentication

  • Shared key authentication
  • Challenge-response mechanism
  • Connection validation

Command Whitelisting

Only safe, educational commands are allowed:

  • sysinfo - System information gathering
  • ls - Directory listing
  • pwd - Current directory
  • whoami - User information
  • ps - Process listing
  • netstat - Network connections
  • df - Disk usage
  • uptime - System uptime
  • help - Command help

Safety Restrictions

  • No file modification commands
  • No system configuration changes
  • No destructive operations
  • Command output limiting
  • Timeout protection

Network Protocol

Connection Flow

  1. Client connects to server on specified port
  2. Authentication handshake:
    • Server sends challenge: AUTH:<key>
    • Client responds: AUTH_OK:<key>
    • Server validates and confirms
  3. Information exchange:
    • Server requests client info: GET_INFO
    • Client sends JSON with system details
  4. Command loop:
    • Server sends command
    • Client executes and responds
    • Repeat until disconnect

Message Format

  • Text-based protocol
  • UTF-8 encoding
  • JSON for structured data
  • Simple string commands

Implementation Details

Server Implementation

class RATServer:
    def __init__(self, host, port):
        self.clients = {}  # Active connections
        self.client_info = {}  # Client metadata
        self.allowed_commands = {...}  # Whitelist
        self.auth_key = self._generate_auth_key()

Key Methods:

  • start() - Main server loop
  • handle_client() - Client communication handler
  • authenticate_client() - Authentication logic
  • send_command() - Command dispatch
  • list_clients() - Client management

Client Implementation

class RATClient:
    def __init__(self, server_host, server_port):
        self.command_map = {...}  # Command handlers
        self.auth_key = None
        self.running = False

Key Methods:

  • connect_to_server() - Network connection
  • authenticate() - Authentication process
  • execute_command() - Command execution
  • start() - Main client loop

Command Implementation

System Information (sysinfo)

def get_system_info(self) -> str:
    info = {
        'hostname': platform.node(),
        'os': f"{platform.system()} {platform.release()}",
        'architecture': platform.architecture()[0],
        'processor': platform.processor(),
        'python_version': platform.python_version(),
        'current_user': getpass.getuser(),
        'current_time': datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
        'platform': platform.platform()
    }
    return json.dumps(info, indent=2)

Directory Listing (ls)

def list_directory(self, path: str = None) -> str:
    if path is None:
        path = os.getcwd()
    
    files = os.listdir(path)
    result = f"Contents of {path}:\n"
    for item in files:
        item_path = os.path.join(path, item)
        if os.path.isdir(item_path):
            result += f"[DIR]  {item}\n"
        else:
            size = os.path.getsize(item_path)
            result += f"[FILE] {item} ({size} bytes)\n"
    return result

Process Listing (ps)

def list_processes(self) -> str:
    result = subprocess.run(['ps', 'aux'], 
                          capture_output=True, 
                          text=True, 
                          timeout=10)
    lines = result.stdout.split('\n')
    limited_lines = lines[:50]  # Educational limit
    return '\n'.join(limited_lines)

Logging and Monitoring

Server Logs

  • Connection events
  • Authentication attempts
  • Command execution
  • Client management
  • Error conditions

Client Logs

  • Connection status
  • Authentication results
  • Command execution
  • System information
  • Error conditions

Log Format

[2024-01-15 14:30:25] INFO: Server listening on 0.0.0.0:9999
[2024-01-15 14:30:30] INFO: New connection from 192.168.1.100:54321
[2024-01-15 14:30:31] INFO: Client 192.168.1.100:54321 authenticated successfully
[2024-01-15 14:30:35] INFO: Received command: sysinfo

Error Handling

Network Errors

  • Connection timeouts
  • Socket errors
  • Authentication failures
  • Data transmission errors

Command Errors

  • Invalid commands
  • Permission denied
  • File not found
  • Command execution failures

System Errors

  • Missing dependencies
  • Platform incompatibility
  • Resource limitations

Educational Value

Learning Objectives

  1. Network Programming: Understand TCP sockets and client-server communication
  2. System Administration: Learn system monitoring and information gathering
  3. Security Concepts: Study authentication, authorization, and security vulnerabilities
  4. Ethical Hacking: Practice responsible security testing principles
  5. Python Programming: Develop skills in network programming and system interaction

Key Concepts Demonstrated

  • Client-Server Architecture: How distributed systems communicate
  • Network Protocols: TCP communication and data exchange
  • Authentication: Secure connection establishment
  • Command Execution: Safe system command handling
  • Logging: System monitoring and debugging
  • Error Handling: Robust system design

Security Lessons

  • Vulnerability Awareness: Understanding how remote access tools work
  • Defense Strategies: Learning to detect and prevent unauthorized access
  • Ethical Considerations: Importance of authorization and legal boundaries
  • Security Best Practices: Authentication, whitelisting, and logging

Limitations and Considerations

Educational Limitations

  • No Persistence: Tool doesn't install or persist on systems
  • No Stealth: All activity is logged and visible
  • Limited Commands: Only safe, educational commands allowed
  • No Encryption: Traffic is not encrypted (for educational visibility)

Platform Considerations

  • macOS Specific: Commands optimized for macOS systems
  • Python Dependency: Requires Python 3.8+
  • Network Access: Requires network connectivity between client and server
  • Permissions: May require appropriate permissions for some commands

Security Considerations

  • Educational Use Only: Not for production or malicious use
  • Authorization Required: Only use on systems you own or have permission to test
  • Legal Compliance: Follow all applicable laws and regulations
  • Ethical Use: Practice responsible security testing

Future Enhancements

Potential Educational Additions

  • Encryption: Add SSL/TLS for secure communication
  • GUI Interface: Create graphical interface for easier use
  • Additional Commands: Add more educational commands
  • Multi-Platform: Support Windows and Linux systems
  • Advanced Authentication: Implement certificate-based authentication
  • Command History: Log and display command history
  • File Transfer: Safe file upload/download capabilities

Security Enhancements

  • Input Validation: Enhanced command and input validation
  • Rate Limiting: Prevent command flooding
  • Audit Logging: Comprehensive audit trails
  • Session Management: Advanced session handling
  • Network Security: Firewall and network security integration

Conclusion

This Educational RAT provides a safe, controlled environment for learning about remote access tools, network programming, and security concepts. It demonstrates both offensive and defensive security principles while maintaining educational focus and ethical boundaries.

The implementation emphasizes safety, logging, and educational value over functionality, making it suitable for classroom use and security education.