Skip to content

About

A Reverse Shell malware RCE for educational purposes

Resources

Stars

8 stars

Watchers

0 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HTTP Reverse Shell with Terminal & Plugin Support

Overview

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.


Components

1. Server

  • 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.

2. Client

  • 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.

3. Plugins

  • 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)

Getting Started

Prerequisites

  • 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, pywin32 for certain plugins).

Running the Server

  1. Place your plugins in the plugins/ folder.
  2. Start the server script. It will listen on port 8000 and provide a console for interaction.
  3. Use the console to list clients, select a client, send commands, start terminal sessions, broadcast messages, and run plugins.

Running the Client

  1. Run the client script on the target machine.
  2. The client will attempt to register with the server and begin polling for commands.
  3. The client can be renamed and pointed to a different server via command-line arguments.

Plugin System

How Plugins Work

  • 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.

Creating Your Own Plugins

  1. Write a Python script and save it in the plugins/ folder on the server.
  2. The script can use standard libraries and any modules available on the client machine.
  3. To return a result, assign your output a print() statement.
  4. Avoid using code that requires user input or GUI interaction.
  5. 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

Security & Ethics

  • 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.

API Overview

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.


Notes

  • 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!

About

A Reverse Shell malware RCE for educational purposes

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages