penelope - Penelope Shell Handler

项目说明

<di="center">
<img src=" alt="Logo" width="200"/>
</div>

<img src="
!Black Hat Arsenal
!EU
!USA
!MEA<br>
!Kali Linux

Penelope is a modern shell handler for penetration testers and CTF players. It provides a more capable alternative to basic netcat listeners, adding automatic PTY upgrades, session management, logging, file transfers and helper modules.

Table of Contents

📥 Installation

⚙️ Features

- 🖥️ Session Features
- 🌍 Global Features
- 🧩 Modules

💻 Usage

- ▶️ Typical Usage
- 📂 HTTP File Server (-s)
- 🐚 Reverse Shell Payloads
- 🎬 Example Workflow
- 🖲️ Main Menu Commands
- ⚡ Command Line Options

🔒 Security considerations

📝 TODO

❓ FAQ

🙌 Thanks to the early birds

Installation

Penelope runs on Unix-like host systems, including Linux, macOS, FreeBSD and requires Python 3.6+.

Kali Linux

Penelope is a in Kali Linux:

Standalone execution

Penelope is implemented entirely with Python’s standard library, allowing it to run as a standalone script without any external dependencies:

pipx

To install the latest upstream directly from GitHub:

For a and more stable release path, Penelope is also a on PyPI:

Features

Session Features

|Feature|Unix-like target|Windows target|
|-----------|:-------:|:-----:|
|Auto-upgrade shell|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|✅|❌|
|Auto-maintain N acti per host (re-spawn on death)|✅|❌|

(*) Can be manually upgraded to PTY with the upgrade command
> ⚠️ Windows support is experimental and under acti.

Global Features

Streamlined interaction with targets through modules

Multiple sessions

Multiple listeners

Ser and folders over HTTP (-s)

Can be imported by Python exploits to handle shells in the same terminal (see extras/exploit_examples)

Can be used with Metasploit exploits by disabling the default handler with set DisablePayloadHandler True

Expose li to an MCP client like Claude Code with the --mcp switch (local HTTP, token-authenticated), driving the same shells alongside you

Modules

Modules are shortcuts for the tools you would otherwise download and upload by hand. Type modules to list them and run <module> to use one. Nothing is bundled with Penelope: each module fetches the tool from its official repository at the moment you run it, so you always get the current and the download happens on your machine, not on the target.

|Category|Module|What it does|
|---|---|---|
|Pri Escalation|upload_pri|Upload linpeas, lse, deepce, pspy on Unix, or winpeas, powerup, pri, fullpowers, enablealltokenprivs on Windows|
||peass_ng|Run the latest PEASS-ng in the background|
||lse|Run the latest linux-smart-enumeration in the background|
||linuxexploitsuggester|Run the latest linux-exploit-suggester in the background|
||traitor|Upload Traitor|
||upload_local_exploits|Upload DirtyFrag and DirtyPipe|
||upload_potato|Upload GodPotato, SigmaPotato, PrintSpoofer|
|Credential Dumping|upload_credump_scripts|Upload Mimikatz, LaZagne, Snaffler, SharpWeb|
|Acti|upload_ad_scripts|Upload PowerView, SharpHound, GhostPack, adPEAS|
|Pi|ligolo|Upload the Ligolo-ng agent|
||chisel|Upload Chisel|
||ngrok|Set up a TCP tunnel through ngrok|
|Forensics|uac|Collect forensic artifacts with Unix-like Artifacts Collector in the background|
||linux_procmemdump|Dump process memory in the background (needs root)|
|Persistence|panix|Upload PANIX|
|Misc|meterpreter|Spawn a Meterpreter session|
||cleanup|Remove the files and directories you uploaded to the target|

!modules

#### Meterpreter module demonstration

!meterpreter

Usage

Typical Usage

!Penelope

HTTP File Server (-s)

Penelope can be used also as a quick HTTP file server.

On start, Penelope prints a ready-to-use link per interface (and an upload hint
when -u is set), so you can copy-paste straight into the target shell.

Reverse Shell Payloads

Penelope prints ready-to-paste reverse shell commands pointing back at its own Listeners, so you don't have to look them up elsewhere and fill in the IP and port by hand. There are two ways to get them:

From the Main Menu, payloads prints them at any time, and unlike -a it narrows the list first. It asks which Listener the payloads should point at, and whether the target runs Linux or Windows, so you only get the ones that can actually run there. Answer * for every Listener and both for every payload:

|Target|Payloads|
|---|---|
|Linux|Bash TCP, Netcat with a named pipe, Python3, Perl, PHP, Ruby, Msfvenom ELF|
|Windows|PowerShell, Msfvenom EXE|
|Both|Metasploit generic/shell_re settings|

The payloads that run on the target are base64 encoded, so the quoting survi mangles it on the way in, and the PowerShell one runs with -nop -w hidden. The Msfvenom lines are printed as they are, since those run on your machine to build the file rather than on the target.

Example Workflow

As shown in the video below, within only a few seconds we can:
1. Get a fully functional auto-resizable PTY shell while logging every interaction with the target
2. Execute the latest of LinPEAS on the target without touching the disk and save the output to a local file in real time
3. Open one more PTY shell in another tab
4. Upload the latest of LinPEAS and linux-smart-enumeration
5. Upload a local folder with custom scripts
6. Upload an exploit-db exploit directly from URL
7. Download and open a remote file locally
8. Download the remote /etc directory
9. Automatically replace a shell when an existing session dies, helping maintain access during unstable sessions

Main Menu Commands

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

help <command> shows the full usage and examples for any of these.

|Group|Command|What it does|
|---|---|---|
|Session Operations|run|Run a module (help run lists them)|
||upload|Upload local files, folders, or HTTP(S)/FTP URLs to the target|
||download|Download files and folders from the target|
||open|Download a remote file or folder and open it with your local default application|
||script|Run a local or remote script in memory and download its output in real time|
||exec|Execute a command on the target and print its output|
||spawn|Spawn another shell from the selected target|
||maintain|Keep N acti per target, respawning them when they die|
||upgrade|Upgrade the session's shell to PTY (automatic by default, disable with -U)|
||portfwd|Forward a local port through the session to a host the target can reach|
|Session Management|sessions|List acti or interact with one|
||use|Select a session|
||interact|Interact with a session|
||kill|Kill a session|
||dir \| .|Open the session's local folder, or Penelope's base folder if no session is selected|
|Shell Management|listeners|Add, stop, or view Listeners|
||payloads|Show reverse shell commands for the acti|
||connect|Connect to a bind shell|
||Interfaces|Show the local network interfaces|
|Miscellaneous|help|Main Menu help, or help for one command|
||modules|Show the a modules|
||history|Show Main Menu history|
||cd|Show or change the session's remote working directory (the one used for transfers)|
||lcd|Show or change Penelope's local working directory|
||SET|Show or set option |
||reload|Reload the rc file|
||reset|Reset the local terminal|
||DEBUG|Open the debug console|
||exit \| quit \| q \| Ctrl+D|Exit Penelope|

!Main Menu

Command Line Options

Security considerations

Penelope is designed to provide direct and flexible interaction with remote shells. Keep the following in mind when using it:

Terminal escape sequences: Penelope forwards terminal output from remote systems directly to your terminal emulator. Malicious remote processes may use terminal escape sequences to manipulate the screen, create misleading links, or interact with features such as the clipboard. This exposure is inherent to any tool that relays a remote shell to the local terminal (like SSH, telnet, netcat) and is not specific to Penelope. Use a terminal with appropriate security settings when connecting to untrusted systems.

Session logs: Session logs may contain credentials, tokens, commands and other sensiti received from the target. Store them securely and use --no-log when logging is not required.

Unencrypted connections: Standard reverse and bind shell connections are not encrypted. Avoid using them o networks unless the traffic is protected by a secure tunnel or VPN.

MCP server (--mcp): When enabled, the MCP ser full control o acti (command execution, file transfer) to any client holding the bearer token, which is stored in ~/.penelope/mcp.json (0600). It binds to 127.0.0.1 and is token-authenticated. Keep the token secret and avoid exposing the server on untrusted networks.

> ⚖️ Disclaimer: Penelope is intended for authorized security testing, research and educational purposes only. Do not use it against systems without explicit permission.

TODO

Features

* encryption
* remote port forwarding
* socks & http proxy
* team server
* HTTPs and DNS agents

Known Issues

* Session logging: commands that use alternate buffers, such as nano, may lea sequences in the log if they terminate abnormally. The data is still preserved, but the logfile with tools like cat may look corrupted. Filtering these escape sequences is planned to make log output smoother.

FAQ

► Is Penelope allowed in the OSCP exam?

Penelope’s core shell-handling features do not perform automatic exploitation, which makes them suitable for OSCP-style usage. However, exam rules can change, so always the current official OffSec rules before using any tool during an exam.

Some modules require extra caution:

* The meterpreter module should only be used in a way that complies with the current exam rules.
* The traitor module uploads Traitor, which performs automatic pri escalation.

If you want to avoid accidental rule , use the -O / --oscp-safe switch.

► How can I return from the remote shell to the Main Menu?

It depends on the type of shell upgrade in use:
* PTY: press F12
* Readline: send EOF (Ctrl-D)
* Raw: send SIGINT (Ctrl-C)

In any case, the correct key is always displayed when you attach to a session. For example:

!F12

► How can I customize Penelope (change default options, create custom modules, etc.)?

See peneloperc

► Why aren’t my current working directory or user preserved when I use menu commands like download/upload?

This usually means you opened a new interacti, possibly under a different user. The Penelope agent only tracks the directory of the initial shell and keeps the permissions of the user from that first shell. The best workaround is to cd /tmp before opening a new shell, or, if you switched users, spawn a new reverse shell as the new user.

► How can I contribute?

Your contributions are in! 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.

► Where does the name come from?

Penelope was the wife of Odysseus and is known for her loyalty and patience while waiting for him to return. The tool is named after her because it was built to be a faithful and stable shell handler for workflows that go beyond a basic listener.

Thanks to the early birds

* Cristian Grigoriu - for inspiring me to automate the PTY upgrade process. This is how this project was born.
* Paul Taylor - for the idea to support bind shells.
* Longlone - for indicating the need for compatibility with previous of Python (3.6).
* Carlos Polop - for the idea to spawn shells on listeners on other systems.
* for indicating an alternati to upgrade the shell to PTY using the script command.
* for the idea to get reverse shells via SSH.
* for numerous enhancement ideas.
* -tanishq, , , , -enes-polatoglu, , , , , , @sta, -br, , , , , @six-two, , , , , , for bug reporting.
* Special thanks to for spreading the word!

项目信息

开发语言：Python

Star 数：2118

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Penelope Shell Handler展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。