Penelope is a powerful shell handler built to simplify, accelerate, and optimize post-exploitation workflows.

• It runs on all Unix-based systems (Linux, macOS, FreeBSD etc)
• Requires Python 3.6+
• It is standalone as it uses only Python’s standard library.

Install

Penelope requires no installation - just download and execute the script:

wget https://raw.githubusercontent.com/brightio/penelope/refs/heads/main/penelope.py && python3 penelope.py

For a more streamlined setup, it can be installed using:

pipx install git+https://github.com/brightio/penelope

Features

Session Features

Description	Unix with Python>=2.3	Unix without Python>=2.3	Windows
Auto-upgrade shell	PTY	PTY(*)	readline
Real-time terminal resize	✅	✅	❌
Logging shell activity	✅	✅	✅
Download remote files/folders	✅	✅	✅
Upload local/HTTP files/folders	✅	✅	✅
In-memory local/HTTP script execution with real-time output downloading	✅	❌	❌
Local port forwarding	✅	❌	❌
Spawn shells on multiple tabs and/or hosts	✅	✅	❌
Maintain X amount of active shells per host no matter what	✅	✅	❌

(*) opens a second TCP connection

Global Features

• Streamline interaction with the targets via modules
• Multiple sessions
• Multiple listeners
• Serve files/folders via HTTP (-s switch)
• Can be imported by python3 exploits and get shell on the same terminal (see Extras)

Modules

Meterpreter module demonstration

Penelope can work in conjunction with metasploit exploits by disabling the default handler with set DisablePayloadHandler True

Usage

Sample Typical Usage

penelope                   # Listening for reverse shells on 0.0.0.0:4444
penelope -a                # Listening for reverse shells on 0.0.0.0:4444 and show reverse shell payloads based on the current Listeners
penelope 5555              # Listening for reverse shells on 0.0.0.0:5555
penelope 5555 -i eth0      # Listening for reverse shells on eth0:5555
penelope 1111 2222 3333    # Listening for reverse shells on 0.0.0.0:1111, 0.0.0.0:2222, 0.0.0.0:3333
penelope -c target 3333    # Connect to a bind shell on target:3333

Demonstrating Random Usage

As shown in the below video, within only a few seconds we have easily:

1. A fully functional auto-resizable PTY shell while logging every interaction with the target
2. Execute the lastest version of Linpeas on the target without touching the disk and get the output on a local file in realtime
3. One more PTY shell in another tab
4. Uploaded the latest versions of LinPEAS and linux-smart-enumeration
5. Uploaded a local folder with custom scripts
6. Uploaded an exploit-db exploit directly from URL
7. Downloaded and opened locally a remote file
8. Downloaded the remote /etc directory
9. For every shell that may be killed for some reason, automatically a new one is spawned. This gives us a kind of persistence with the target

penelope_sample_usage.mp4

Main Menu Commands

Some Notes:

• By default you need to press F12 to detach the PTY shell and go to the Main Menu. If the upgrade was not possible the you ended up with a basic shell, you can detach it with Ctrl+C. This also prevents the accidental killing of the shell.
• The Main Menu supports TAB completion and also short commands. For example instead of interact 1 you can just type i 1.

Command Line Options

positional arguments:
  ports                 Ports to listen/connect to, depending on -i/-c options. Default: 4444

Reverse or Bind shell?:
  -i , --interface      Interface or IP address to listen on. Default: 0.0.0.0
  -c , --connect        Bind shell Host

Hints:
  -a, --payloads        Show sample payloads for reverse shell based on the registered Listeners
  -l, --interfaces      Show the available network interfaces
  -h, --help            show this help message and exit

Session Logging:
  -L, --no-log          Do not create session log files
  -T, --no-timestamps   Do not include timestamps in session logs
  -CT,                  Do not color timestamps in session logs

Misc:
  -m , --maintain       Maintain NUM total shells per target
  -M, --menu            Just land to the Main Menu
  -S, --single-session  Accommodate only the first created session
  -C, --no-attach       Disable auto attaching sessions upon creation
  -U, --no-upgrade      Do not upgrade shells

File server:
  -s, --serve           HTTP File Server mode
  -p , --port           File Server port. Default: 8000
  -prefix               URL prefix

Debug:
  -N , --no-bins        Simulate binary absence on target (comma separated list)
  -v, --version         Show Penelope version
  -d, --debug           Show debug messages
  -dd, --dev-mode       Developer mode
  -cu, --check-urls     Check health of hardcoded URLs

Contribution

Your contributions are invaluable! If you’d like to help, please report bugs, unexpected behaviors, or share new ideas. You can also submit pull requests but avoid making commits from IDEs that enforce PEP8 and unintentionally restructure the entire codebase.

TODO

Features

• remote port forwarding
• socks & http proxy
• persistence modules
• team server
• currently spawn/script/portfwd commands are supported only on Unix shells. Those need to be implemented for Windows shells too.
• an option switch for disable all logging, not only sessions.
• main menu autocompletion for short commands
• download/upload autocompletion
• IPv6 support
• encryption
• UDP support

Known Issues

• Main menu: Ctrl-C on main menu has not the expected behavior yet.
• Session logging: when executing commands on the target that feature alternate buffers like nano and they are abnormally terminated, then when 'catting' the logfile it seems corrupted. However the data are still there. Also for example when resetting the remote terminal, these escape sequences are reflected in the logs. I will need to filter specific escape sequences so as to ensure that when 'catting' the logfile, a smooth log is presented.

Trivia

Penelope was the wife of Odysseus and she is known for her fidelity for him by waiting years. Since a characteristic of reverse shell handlers is waiting, this tool is named after her.

Thanks to the early birds

• Cristian Grigoriu - @crgr for inspiring me to automate the PTY upgrade process. This is how this project was born.
• Paul Taylor - @bao7uo for the idea to support bind shells.
• Longlone - @WAY29 for indicating the need for compatibility with previous versions of Python (3.6).
• Carlos Polop - @carlospolop for the idea to spawn shells on listeners on other systems.
• @darrenmartyn for indicating an alternative method to upgrade the shell to PTY using the script command.
• @robertstrom, @terryf82, @RamadhanAmizudin, @furkan-enes-polatoglu, @DerekFost, @Mag1cByt3s, @nightingalephillip, @grisuno, @thomas-br, @joshoram80, @TheAalCh3m1st, @r3pek for bug reporting.