An interactive command line application for red team operations. The goal of RedShell is to capture logs for activities executed outside of traditional C2 frameworks. RedShell can automatically push commands through SOCKS4/5 proxies via proxychains, and it logs to a local CSV file. Logged activities can also be tagged with Mitre ATT&CK TTP IDs for correlation in tracking systems and deliverables.
RedShell includes optional Cobalt Strike integration, which pulls beacon SOCKS4/5 proxy details from the team server. It also logs activities to the team server.
Note that because RedShell uses proxychains under the hood, only TCP traffic is proxied.
Because RedShell uses proxychains under the hood, a *nix system is required for full functionality. RedShell runs on Python >=3.12.
Install proxychains-ng
sudo apt install proxychains4
Install uv:
https://docs.astral.sh/uv/getting-started/installation/
- RedShell can be as a tool on your system directly from GitHub with
uv:uv tool install git+https://github.com/exfiltrata/redshell - Another option is to clone the repo locally and then run it as a script
git clone https://github.com/exfiltrata/redshell.git cd redshell uv run redshell.py - Or clone locally and install it as a tool:
git clone https://github.com/exfiltrata/redshell.git cd redshell uv tool install .
To get the latest changes:
- Reinstall with
uv:uv tool install --reinstall git+https://github.com/exfiltrata/redshell - Or pull the latest and reinstall
cd redshell git pull uv tool install --reinstall .
Display help:
redshell > help
Documented Commands
───────────────────
beacon_exec context cs_pivots exec history pwd shell
cd cs_connect cs_status exit log quit socks
config cs_disconnect cs_use_pivot help proxy_exec set
Set options:
redshell> set option VALUE
RedShell automatically logs activities via the beacon_exec, proxy_exec, exec, or log commands. Logging is automatically initialized on startup, and log files are written to: ~/.redshell.
To log to Cobalt Strike, connect to a team server, select a pivot, and use the beacon_exec command.
RedShell uses proxychains-ng and a custom proxychains configuration file. Configuration file modifications and command proxying are handled on-the-fly.
To proxy through a Cobalt Strike, connect to a team server, select a pivot, and use the beacon_exec command. Refer to the Cobalt Strike section for details.
Custom socks version 4 or 5 proxies can be set with the socks command.
redshell > socks -h
usage: socks [-h] [-u SOCKS5_USER] [-p SOCKS5_PASS] {socks4,socks5} ip_address socks_port
Use a custom socks4/5 server
positional arguments:
{socks4,socks5}
ip_address
socks_port
options:
-h, --help show this help message and exit
-u SOCKS5_USER
-p SOCKS5_PASS
RedShell automatically verifies connections and authentication (where applicable) to SOCKS proxies upon selection, either using the socks or cs_use_pivot commands. This can be disabled with the following command: set check_socks false
RedShell's context is a key aspect of activity logging. Context allows you to set the perspective, in activity logs, of the source host executing activities. The following context attributes can be included in activity logs: IP Address, DNS Name, NetBIOS Name, User Name, and Process ID. Only IP Address is required.
Notes on context:
- Context is cleared when you set a new socks port
- Context is cleared when you connect/disconnect from a CS team server
If you are using a pivot on a team server, context values are automatically set based on the beacon.
After you set a socks proxy with the socks command, add context details with the context command.
RedShell> context -h
usage: context [-h] [-d DNSNAME] [-n NETBIOSNAME] [-u USERNAME] [-p PID] ip_address
Set a custom context (Source IP/DNS/NetBIOS/User/PID) for logging
positional arguments:
ip_address Source IP Address
optional arguments:
-h, --help show this help message and exit
-d DNSNAME, --dnsname DNSNAME
DNS Name
-n NETBIOSNAME, --netbiosname NETBIOSNAME
NetBIOS Name
-u USERNAME, --username USERNAME
User Name
-p PID, --pid PID Process ID
The command prompt is automatically updated with context variables (example: user@host).
The following RedShell commands are captured in activity logs:
beacon_exec- Execute a command through beacon socks proxy and simultaneously log it to the team server.proxy_exec- Execute a command through custom socks proxy and simultaneously log it to the local file.exec- Execute a command and log it to the local file.log- Add a manual log entry to the local file.
The cs_connect command is for connecting to a team server with a locally installed client or to the Cobalt Strike REST API
redshell > cs_connect -h
usage: cs_connect [-h] -c {client,api} -u CS_USER -i CS_HOST [-p CS_PORT] [-v]
Connect to Cobalt Strike team server
options:
-h, --help show this help message and exit
-c {client,api} Cobalt Strike connection type (client or api). Required.
-u CS_USER Team server user. Required.
-i CS_HOST Team server IP. Required.
-p CS_PORT Team server port (default: 50050 for client, 50443 for api)
-v, --verify_ssl Verify SSL certificates for API connection
Client Example:
REST API Example:
Show available proxy pivots:
redshell > cs_pivots
Example:
Select a proxy pivot:
redshell > cs_use_pivot <id>
Example:
Check Cobalt Strike status:
redshell > cs_status
Example:
Execute commands through the beacon socks proxy. These can be run in the context of the current user or via sudo. Specifying 'proxychains' in the command is optional. Commands are forced through proxychains. MITRE ATT&CK Tactic IDs are optional.
redshell > beacon_exec -h
usage: beacon_exec [-h] [-t TTP] ...
Execute a command through beacon socks proxy and simultaneously log it to the teamserver.
positional arguments:
command Command to execute through the proxy and log.
optional arguments:
-h, --help show this help message and exit
-t TTP, --ttp TTP MITRE ATT&CK Tactic IDs. Comma delimited to specify multiple.
example:
beacon_exec -t T1550.002,T1003.002 nxc smb 192.168.1.1 --local-auth -u Administrator -H C713B1D611657D0687A568122193F230 --sam
Example:
Note on the Redshell and CS install directory options - the script needs to know where it lives, as well as Cobalt Strike. If stuff blows up, be sure to set the directories accordingly:
redshell > set redshell_directory /path/to/redshell
redshell > set cs_directory /path/to/cobaltstrike
Initial support for the Cobalt Strike REST API has been added as of January 2026. This functionality is limited to connecting/authenticating to the API and pulling beacon pivot details. Note that some of the pivots returned in the console may not be live, which is due to the limitations of the API as implemented by Cobalt Strike at the time of this writing. Additionally, beacon_exec commands cannot be logged to the team server as there is no API call to support this. These features will be added in the future once they are supported by the API.
Note on passwords used in *exec commands: special characters in passwords may be interpreted as shell meta characters, which could cause commands to fail. To get around this, set the password option and then invoke with '$password'. Example:
redshell > set password Test12345
password - was: ''
now: 'Test12345'
redshell > beacon_exec nxc smb 192.168.1.14 --local-auth -u administrator -p $password --shares
RedShell includes commands for navigating the file system:
redshell > cd /opt/redshell/
redshell > pwd
/opt/redshell
Additional commands can be run via the shell command or via the '!' shortcut:
redshell > shell date -u
Tue Jan 20 09:49:11 PM UTC 2026
redshell > !date -u
Tue Jan 20 09:49:14 PM UTC 2026
Commands are tracked and accessible via the history command:
redshell > history
1 cs_connect -c client -u exfiltrata -i 10.55.3.59
2 cs_pivots
3 cs_use_pivot 3
4 cs_status
5 beacon_exec ncat -v 8.8.8.8 53
RedShell also includes tab-completion and clearing the terminal window via ctrl + l.
Datetime,IP Address,DNS Name,NetBIOS Name,User,PID,Activity,TTPs
2026/01/16 23:58:05 +0000,192.168.122.204,,WIN11,Administrator,5644,[PROXY] ncat -v 8.8.8.8 53
Notes:
- Required fields: Datetime, IP Address, Activity
- Optional fields: DNS Name, NetBIOS Name, User, PID, TTPs
- Datetime format: "%Y/%m/%d %H:%M:%S %z" (UTC)
RedShell runs totally fine under GNU screen, and it's generally a good idea to run command line applications like this under a terminal multiplexer. Because of the limited color support in screen, some of RedShell's output may look a bit funky in places with the default screen config. And we like pretty colors, so it's best to use tmux.
This project is licensed under the terms of the Apache 2.0 open source license. Please refer to LICENSE for the full terms.