Skip to content
BranchesTags

Repository files navigation

Educational Remote Access Tool (RAT) for macOS

⚠️ EDUCATIONAL PURPOSES ONLY ⚠️

This is a proof-of-concept Remote Access Tool (RAT) created for educational purposes in CyberSecurity and Computer Science courses. It demonstrates network programming, client-server architecture, system monitoring, and security concepts in a controlled, ethical environment.

✅ Project Status: FULLY FUNCTIONAL

All critical bugs have been fixed and the project is ready for classroom demonstration!

Table of Contents

Important Disclaimers

  • This tool is for educational purposes only
  • Never use this on systems you don't own or have explicit permission to test
  • Unauthorized access to computer systems is illegal
  • This is a learning tool to understand security vulnerabilities

Features

  • System information gathering - Comprehensive system details
  • File system exploration - Safe directory listing and navigation
  • Network communication - Client-server architecture with authentication
  • Command execution - Whitelisted commands with safety restrictions
  • Shell commands - Advanced shell execution with security checks (planned)
  • Screenshot capture - macOS screenshot functionality (planned)
  • Educational keylogger - Demonstration keylogger (educational only)
  • Persistence mechanism - Launch agent creation for macOS
  • Educational logging - Comprehensive activity logging
  • Multi-client support - Server can handle multiple clients
  • Command-line interface - Easy deployment with arguments
  • Robust error handling - Proper timeouts and exception handling

Requirements

  • macOS
  • Python 3.8+
  • Network access for client-server communication
  • No external dependencies (uses standard library only)

Quick Start

Option 1: Using Quick Start Scripts (Easiest)

Start Server:

./start_server.sh

Start Client:

./start_client.sh

Option 2: Manual Start

Start Server:

# On all interfaces (allows remote connections)
python3 server.py --host 0.0.0.0 --port 9999

# On localhost only (same computer testing)
python3 server.py --host 127.0.0.1 --port 9999

Start Client:

# Connect to remote server (replace IP)
python3 client.py --host 192.168.1.100 --port 9999

# Connect to localhost (testing on same computer)
python3 client.py --host 127.0.0.1 --port 9999

How It Works

Overview

This Educational RAT consists of two main components that communicate over a network:

  1. Server (Command & Control) - The controlling machine where you send commands
  2. Client (Target/Agent) - The monitored machine that executes commands and reports back

Step-by-Step Communication Flow

┌─────────────┐                                    ┌─────────────┐
│   SERVER    │                                    │   CLIENT    │
│  (Control)  │                                    │  (Target)   │
└──────┬──────┘                                    └──────┬──────┘
       │                                                  │
       │   1. Server starts listening on port 9999        │
       │         Generates authentication key             │
       │                                                  │
       │         2. Client initiates connection           │
       │ ◄──────────────────────────────────────────────  │
       │                                                  │
       │    3. Server sends authentication challenge      │
       │             "AUTH:<random_key>"                  │
       │ ──────────────────────────────────────────────►  │
       │                                                  │
       │         4. Client responds with key              │
       │               "AUTH_OK:<key>"                    │
       │ ◄──────────────────────────────────────────────  │
       │                                                  │
       │  5. Server validates and sends "AUTH_SUCCESS"    │
       │ ──────────────────────────────────────────────►  │
       │                                                  │
   Network Setup

### Same Computer Testing (Localhost)
Perfect for initial testing and development:

```bash
# Server
python3 server.py --host 127.0.0.1 --port 9999

# Client (in another terminal)
python3 client.py --host 127.0.0.1 --port 9999

Different Computers (LAN)

For realistic demonstration:

  1. Find Server's IP Address:

    ifconfig | grep "inet "
# Look for: inet 192.168.1.100

  2. Configure Firewall (if needed):

    # Allow Python through firewall
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/bin/python3

  3. Start Server (on control machine):

    python3 server.py --host 0.0.0.0 --port 9999

  4. Start Client (on target/dummy machine):

    python3 client.py --host 192.168.1.100 --port 9999

Network Diagram

┌─────────────────────┐          LAN/WiFi          ┌─────────────────────┐
│   Control Laptop    │        192.168.1.0/24      │    Dummy Laptop     │
│                     │                            │                     │
│  Server Running     │◄─────────────────────────► │   Client Running    │
│  IP: 192.168.1.100  │       TCP Port 9999        │  IP: 192.168.1.50   │
│  Port: 9999         │                            │                     │
└─────────────────────┘                            └─────────────────────┘

Testing & Troubleshooting

Pre-Flight Checklist

  • Python 3.8+ installed on both machines
  • Both machines on same network (for LAN testing)
  • Firewall allows connections on port 9999
  • Server started before client attempts connection
  • Correct IP address used for client

Common Issues and Solutions

❌ "Connection Refused"

Cause: Server not running or wrong IP/port
Solution:

# Verify server is listening
netstat -an | grep 9999
# Should show: tcp4  0  0  *.9999  *.*  LISTEN

❌ "Authentication Failed"

Cause: Network issue or timing problem
Solution: Restart both server and client

❌ "Command Timeout"

Cause: Network latency or command taking too long
Solution: Normal for very large outputs (thousands of files)

❌ "Connection Hangs"

Cause: Firewall blocking connection
Solution: Add firewall exception or test on localhost first

Testing Commands

Run these in order to verify everything works:

# Basic system info
sysinfo

# File system operations
pwd
ls
ls /tmp

# User information
whoami

# Process monitoring
ps

# Network status
netstat

# Disk usage
df

# System uptime
uptime

Recent Fixes (Feb 2026)

✅ Fixed authentication handshake flow
✅ Improved buffer sizes for large data transfer (1KB → 4KB)
✅ Added proper socket timeout handling (prevents hanging)
✅ Implemented command-line argument support (--host, --port)
✅ Enhanced error handling and recovery (graceful failures)
✅ Added comprehensive documentation (4 new docs)
✅ Created quick-start scripts for easy deployment
✅ Implemented chunked data receiving for large outputs

Educational Value

What You Learn From This Project

1. Network Programming

  • TCP/IP socket programming
  • Client-server architecture
  • Network protocols and handshakes
  • Data serialization and transmission
  • Error handling in networked environments

2. System Programming

  • Process management (listing, monitoring)
  • File system operations
  • System information gathering
  • Command execution and output capture
  • Cross-platform considerations

3. Security Concepts

  • Authentication mechanisms
  • Command validation and whitelisting
  • Security by design (defensive programming)
  • Logging and accountability
  • Privilege levels and permissions
  • Attack vectors and defensive measures

4. Software Engineering

  • Modular code design
  • Error handling and edge cases
  • User interface design (CLI)
  • Documentation best practices
  • Testing and debugging
  • Version control and change tracking

5. Ethical Hacking

  • Understanding attacker techniques
  • Defensive security measures
  • Responsible disclosure
  • Legal and ethical boundaries
  • Penetration testing methodology

Real-World Applications

This project mirrors techniques used in:

  • IT Administration: Remote system management
  • Security Operations: Incident response and forensics
  • Penetration Testing: Authorized security assessments
  • Malware Analysis: Understanding RAT behavior
  • DevOps: Infrastructure monitoring and automation

Discussion Topics for Class

  1. Legal Implications: Computer Fraud and Abuse Act (CFAA)
  2. Ethical Considerations: Authorization vs. exploitation
  3. Detection Methods: How would you detect this on your network?
  4. Defensive Measures: How can systems protect against RATs?
  5. Encryption: Why would real attackers encrypt communications?
  6. Persistence: How do real RATs survive reboots?

Legal Notice

Important Legal Information

By using this tool, you agree to:

  • ✅ Use it ONLY for educational purposes in controlled environments
  • ✅ Obtain explicit written permission before testing on any system
  • ✅ Follow all applicable laws and regulations in your jurisdiction
  • ✅ Comply with your institution's Acceptable Use Policy
  • ✅ Never use this tool for malicious purposes
  • ✅ Take full responsibility for your actions

Legal Framework

United States: Computer Fraud and Abuse Act (CFAA) - 18 U.S.C. § 1030
Unauthorized access to computer systems is a federal crime punishable by:

  • Fines up to $250,000
  • Prison time up to 20 years
  • Civil liability

International: Similar laws exist worldwide:

  • UK: Computer Misuse Act 1990
  • EU: Directive 2013/40/EU
  • Canada: Criminal Code Section 342.1
  • Australia: Cybercrime Act 2001

Ethical Use Only

This tool is designed to:

  • ✅ Teach security concepts in a safe environment
  • ✅ Demonstrate vulnerabilities for defensive purposes
  • ✅ Prepare students for careers in cybersecurity
  • ✅ Encourage responsible and ethical behavior

This tool is NOT designed to:

  • ❌ Access systems without authorization
  • ❌ Steal data or compromise privacy
  • ❌ Cause damage or disruption
  • ❌ Bypass security measures maliciously

Academic Integrity

When submitting this project:

  • Properly cite all sources and references
  • Acknowledge collaboration with others
  • Follow your institution's academic honesty policy
  • Include this disclaimer in your submission

Remember: With great power comes great responsibility. Use this knowledge to make the digital world safer, not more dangerous.

Contributing & Support

This is an educational project. If you're using it for a class:

  1. Understand the code: Don't just run it, read it!
  2. Experiment safely: Only on systems you own
  3. Document your learning: Keep notes on what you discover
  4. Ask questions: Discuss with instructors and peers
  5. Share knowledge: Help others understand (after they try first)

License & Credits

Created for: Educational purposes in CyberSecurity and Computer Science courses
Language: Python 3.8+
Platform: macOS (with potential for cross-platform adaptation)
Date: February 2026

Educational Use: Free to use for academic purposes with proper attribution
Commercial Use: Not authorized
Modification: Encouraged for learning purposes

Quick Links

📚 Usage Guide - How to use the tool
🔧 Fixes Summary - What was fixed and why
⚡ Quick Reference - Command cheat sheet

⚠️ REMEMBER: This is a LEARNING TOOL. Use responsibly and ethically! ⚠️

Last Updated: February 3, 2026rary for TCP/IP communication

  • Server binds to a host and port (default: 0.0.0.0:9999)
  • Client connects to server's IP address and port
  • Data transmitted as UTF-8 encoded strings

2. Authentication Mechanism

# Server generates random key
auth_key = random_string(16)  # e.g., "abc123def456"

# Server sends challenge
challenge = f"AUTH:{auth_key}"

# Client must respond with correct key
response = f"AUTH_OK:{auth_key}"

# Server confirms
confirmation = "AUTH_SUCCESS"

3. Command Processing

On the Server Side:

# User enters command
command = "sysinfo"

# Server validates command against whitelist
if command in allowed_commands:
    # Send to client
    client_socket.sendall(command.encode('utf-8'))
    
    # Wait for response
    response = receive_chunked_data(client_socket)
    
    # Display to user
    print(response)

On the Client Side:

# Receive command
command = client_socket.recv(4096).decode('utf-8')

# Parse and validate
cmd_name = command.split()[0]

# Execute if allowed
if cmd_name in command_map:
    result = command_map[cmd_name]()  # Execute function
    
    # Send result back
    client_socket.sendall(result.encode('utf-8'))

4. Data Transfer Protocol

  • Small Data (< 4KB): Single packet transmission
  • Large Data (> 4KB): Chunked transmission
    • Sender breaks data into 4KB chunks
    • Receiver collects chunks until complete
    • Timeout prevents infinite waiting

5. Command Execution Example

When you run ls /tmp:

  1. Server: Validates "ls" is allowed → Sends "ls /tmp" to client
  2. Client: Receives command → Parses as "ls" with argument "/tmp"
  3. Client: Executes: 
    files = os.listdir('/tmp')
result = format_file_list(files)
  4. Client: Sends formatted result back
  5. Server: Receives and displays file listing

6. Multi-Threading for Multiple Clients

# Server accepts connections
while running:
    client_socket, address = server_socket.accept()
    
    # Create new thread for each client
    thread = threading.Thread(
        target=handle_client,
        args=(client_socket, address)
    )
    thread.start()
    
# Each client handled independently

Key Technologies Used

Technology Purpose Implementation
Sockets Network communication TCP/IP connections between machines
Threading Multi-client support Each client connection runs in separate thread
JSON Data serialization System info transmitted as JSON objects
Subprocess Command execution Safely execute system commands (ps, ls, df, etc.)
Logging Activity tracking All actions logged to files for accountability
argparse CLI arguments Professional command-line interface

Security Considerations

What Makes This "Safe" for Education:

  1. Command Whitelisting: Only specific, safe commands allowed
  2. Dangerous Command Blocking: Commands like rm -rf are blocked
  3. Authentication Required: Simple key-based auth prevents unauthorized access
  4. Logging Everything: All commands and actions are logged
  5. Timeouts: Prevents resource exhaustion and hanging
  6. No Privilege Escalation: Runs with normal user permissions

Why Real RATs Are Dangerous:

  • No Authentication: Attackers don't ask permission
  • All Commands Allowed: Can delete files, install malware, steal data
  • Stealthy Operation: No logging, runs hidden
  • Encryption: Communication encrypted to avoid detection
  • Persistence: Survives reboots, hard to remove
  • Privilege Escalation: Attempts to gain admin/root access

This educational version demonstrates the concepts while maintaining safety through intentional limitations.

Architecture Overview

File Structure

OSX-CyberW/
├── client.py               # Client/Agent program (runs on target)
├── server.py               # Server/C2 program (runs on controller)
├── start_client.sh         # Easy client startup script
├── start_server.sh         # Easy server startup script
├── setup.py                # Environment verification script
├── demo_test.py            # Testing utilities
├── README.md               # This file
├── USAGE_GUIDE.md          # Detailed usage instructions
├── FIXES_SUMMARY.md        # Bug fixes and improvements log
├── QUICK_REFERENCE.txt     # Quick reference card
├── docs/                   # Additional documentation
│   ├── quick_start_guide.md
│   └── technical_documentation.md
└── logs/                   # Runtime logs directory
    ├── rat_server.log      # Server activity log
    └── rat_client.log      # Client activity log

Component Breakdown

Server (server.py):

  • Listens for incoming client connections
  • Manages authentication
  • Sends commands to clients
  • Receives and displays results
  • Handles multiple clients simultaneously
  • Logs all activities

Client (client.py):

  • Connects to server
  • Authenticates with server
  • Executes received commands
  • Sends results back to server
  • Logs all activities
  • Implements command safety checks

Documentation

Available Commands

Once connected, use these commands from the server:

  • sysinfo - Get comprehensive system information
  • ls [path] - List directory contents
  • pwd - Show current working directory
  • whoami - Show current user information
  • ps - List running processes
  • netstat - Show network connections
  • df - Show disk usage
  • uptime - Show system uptime
  • help - Show available commands
  • clients - List all connected clients (server only)
  • exit - Disconnect from current client

Security Features

  • ✅ Authentication required
  • ✅ Command whitelisting
  • ✅ Dangerous command blocking
  • ✅ Educational logging
  • ✅ Safety restrictions on dangerous operations
  • ✅ Clear identification as educational tool
  • ✅ Timeout protection
  • ✅ Error handling and recovery

Recent Fixes (Feb 2026)

✅ Fixed authentication handshake flow
✅ Improved buffer sizes for large data transfer
✅ Added proper socket timeout handling
✅ Implemented command-line argument support
✅ Enhanced error handling and recovery
✅ Added comprehensive documentation
✅ Created quick-start scripts for easy deployment

Legal Notice

By using this tool, you agree to:

  • Use it only for educational purposes
  • Obtain proper authorization before testing
  • Follow all applicable laws and regulations
  • Not use it for malicious purposes

Educational Value

This project teaches:

  • Network programming and protocols
  • System administration and monitoring
  • Security vulnerabilities and defense
  • Ethical hacking principles
  • Client-server architecture

About

Educational Remote Access Tool (RAT) for macOS

Topics

malwaremalware-developmentmalware-protectionmalware-research

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages