Python Reverse Shell Listener

This repository contains a Python-based listener for a reverse shell. It allows you to receive a connection from a remote machine, execute shell commands, and transfer files between the listener (your machine) and the target machine.

Features

The reverse_listener.py script offers several key improvements over the legacy version:

• Python 3 Support: Fully modern and compatible with current Python versions.
• Reliable Data Transfer: Implements a custom protocol that prefixes messages with their size, ensuring complete and uncorrupted data transmission, no matter the size.
• Robust Command Parsing: Uses shlex to properly handle commands with arguments that contain spaces (e.g., file paths in quotes).
• Specific Error Handling: Catches specific exceptions for network, file, and data decoding issues, providing clearer error messages.
• Graceful Shutdown: Handles Ctrl+C (KeyboardInterrupt) to properly close the connection and notify the remote machine.
• Command-Line Arguments: Uses argparse to easily set the listening IP and port from the command line.
• Clean & Documented Code: Includes type hints, docstrings, and comments for better readability and maintainability.

How It Works

A reverse shell is initiated when the target machine connects back to a listening server. This is often used to bypass firewalls that might block incoming connections to the target.

1. You run the reverse_listener.py script on your machine, which opens a specific port and waits for a connection.
2. A separate script (the "backdoor" or "client") is executed on the target machine. This client is responsible for connecting to your listener's IP address and port.
3. Once the connection is established, your listener can send commands to the target machine.
4. The client on the target machine executes these commands and sends the results back to your listener.
5. Your listener displays the results, effectively giving you a remote shell on the target machine.

Prerequisites

• Python 3.6 or higher
• A corresponding client/backdoor script to run on the target machine. (Note: The client script is not included in this repository and must be created separately.)

How to Use

1. Start the Listener

Open a terminal on your machine and run the listener script.

Basic Usage (defaults to 127.0.0.1:1234):

python3 reverse_listener.py

Specify IP and Port

Use the --ip (or -i) and --port (or -p) flags to set a custom address and port. This is necessary for listening for connections from other machines on your network or the internet.

python3 reverse_listener.py --ip YOUR_IP_ADDRESS --port 4444

2. Execute the Target on Client Machine

On the remote machine, you need to run a client script that is programmed to connect to the IP and port where your listener is waiting.

3. Interact with the Remote Shell

Once a connection is established, you will see a >> prompt. You can now type commands to be executed on the target machine.

Available Commands

• Any Standard shell command: ls, whoami, pwd, ipconfig, etc.

Example Session

# On your machine, start the listener
$ python3 reverse_listener.py --ip 192.168.1.10 --port 4444
[+] Waiting for an incoming connection on 192.168.1.10:4444

# (After the target machine connects)
[+] Got a connection from 192.168.1.15:49872

# Now you can issue commands
>> whoami
target-user

>> pwd
/home/target-user

>> download "passwords.txt"
[+] Download successful to passwords.txt

>> upload "/path/to/my/local/file.txt"
[+] Upload successful.

>> exit
[+] Closing the connection.

Disclaimer

This tool is intended for educational purposes, authorized security testing, and system administration only. Using this tool on systems without explicit permission from the owner is illegal and unethical. The author is not responsible for any misuse or damage caused by this program.

Thanks to Zsecurity and Zaid for helping me to understand the basics and this is my personal improvement of the code version from my learnings.