This project is a flexible HTTP-based reverse shell system, featuring:
- A FastAPI-powered server for managing multiple clients
- A cross-platform Python client that connects back to the server
- Support for remote terminal sessions and command execution
- A plugin system for running custom scripts on clients
- Example plugins for geolocation, date/time, and credential extraction
Intended for educational, research, or authorized administrative use only.
- Built with FastAPI, running on Python 3.8+.
- Manages client registration, command delivery, plugin distribution, and terminal sessions.
- Provides a console interface for operators to interact with clients and sessions.
- Python script that connects to the server, receives commands, executes them, and sends back results.
- Supports automatic reconnection and system info reporting.
- Executes plugins delivered from the server, capturing output and errors.
- Standalone Python scripts stored in the
plugins/directory on the server. - Can be sent to clients for execution via the console or API.
- Example plugins included:
- Geolocation using public IP
- Current date/time
- Browser credential dumper (Windows only; for demonstration)
- Python 3.8 or newer on both server and client machines.
- Recommended: pip install requirements such as
fastapi,uvicorn,requests, and any plugin dependencies (e.g.,pycryptodome,pywin32for certain plugins).
- Place your plugins in the
plugins/folder. - Start the server script. It will listen on port 8000 and provide a console for interaction.
- Use the console to list clients, select a client, send commands, start terminal sessions, broadcast messages, and run plugins.
- Run the client script on the target machine.
- The client will attempt to register with the server and begin polling for commands.
- The client can be renamed and pointed to a different server via command-line arguments.
- Plugins are plain Python scripts placed in the server’s
plugins/directory. - When the operator runs a plugin on a client, the server sends the script’s code to the client.
- The client executes the script in a sandboxed scope, capturing any printed output or errors.
- The result is sent back to the server and can be viewed in the console or via the API.
- Write a Python script and save it in the
plugins/folder on the server. - The script can use standard libraries and any modules available on the client machine.
- To return a result, assign your output a
print()statement. - Avoid using code that requires user input or GUI interaction.
- Plugins should be self-contained and avoid external dependencies unless you know they exist on the client. Or you could just add every dependency in the payload client.py
Example ideas:
- System info collection
- File enumeration
- Network diagnostics
- Custom payloads for authorized red teaming
- This tool is for authorized use only. Running it on machines you do not own or have explicit permission to control is illegal and unethical.
- API keys are used for basic authentication; customize these for your environment.
- Plugins can run arbitrary code on clients—review all plugins for safety and test responsibly.
The server exposes endpoints for:
- Registering and listing clients
- Sending and receiving messages/commands
- Managing terminal sessions
- Listing, distributing, and reloading plugins
Refer to the /commands endpoint for a full list of available API routes and console commands.
- Windows is required for certain plugins (e.g., credential dumper).
- Use in a safe, controlled lab environment.
- Review and adapt the plugin system to your organization’s needs.
For questions or contributions, please contact the project maintainer. Use responsibly!