{"id":13845515,"url":"https://github.com/brightio/penelope","last_synced_at":"2026-05-31T00:01:34.221Z","repository":{"id":43973353,"uuid":"374207022","full_name":"brightio/penelope","owner":"brightio","description":"Penelope Shell Handler","archived":false,"fork":false,"pushed_at":"2026-05-28T00:03:24.000Z","size":345,"stargazers_count":1717,"open_issues_count":3,"forks_count":191,"subscribers_count":19,"default_branch":"main","last_synced_at":"2026-05-28T00:22:20.191Z","etag":null,"topics":["ctf","ctf-tools","hackthebox","oscp","oscp-tools","pty","rce","reverse-shell","shell-handler","tryhackme","tty"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brightio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-06-05T20:32:27.000Z","updated_at":"2026-05-28T00:03:28.000Z","dependencies_parsed_at":"2026-02-01T22:06:05.312Z","dependency_job_id":null,"html_url":"https://github.com/brightio/penelope","commit_stats":{"total_commits":72,"total_committers":2,"mean_commits":36.0,"dds":"0.11111111111111116","last_synced_commit":"81fd31339c697fee5223a9a6e16bd5d26199019f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/brightio/penelope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightio%2Fpenelope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightio%2Fpenelope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightio%2Fpenelope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightio%2Fpenelope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brightio","download_url":"https://codeload.github.com/brightio/penelope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightio%2Fpenelope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33714033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ctf","ctf-tools","hackthebox","oscp","oscp-tools","pty","rce","reverse-shell","shell-handler","tryhackme","tty"],"created_at":"2024-08-04T17:03:27.001Z","updated_at":"2026-05-31T00:01:34.210Z","avatar_url":"https://github.com/brightio.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/0d369fba-480e-4e27-a117-8845dbd4b58e\" alt=\"Logo\" width=\"200\"/\u003e\n\u003c/div\u003e\n\n\u003cimg src=\"https://img.shields.io/badge/Version-0.19.3-6D4AFF\"/\u003e\u003cbr\u003e\n![Black Hat Arsenal](https://img.shields.io/badge/Presented%20at-Black%20Hat%20Arsenal-111827)\n![EU](https://img.shields.io/badge/EU%202024-2563EB)\n![USA](https://img.shields.io/badge/USA%202025-B91C1C)\n![MEA](https://img.shields.io/badge/MEA%202025-15803D)\u003cbr\u003e\n![Kali Linux](https://img.shields.io/badge/Packaged%20in-Kali%20Linux-557C94)\n\nPenelope 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.\n\n## Table of Contents\n- 📥 [Installation](#installation)\n- ⚙️ [Features](#features)\n  - 🖥️ [Session Features](#session-features)\n  - 🌍 [Global Features](#global-features)\n  - 🧩 [Modules](#modules)\n- 💻 [Usage](#usage)\n  - ▶️ [Sample Typical Usage](#sample-typical-usage)\n  - 🎬 [Demonstrating Random Usage](#demonstrating-random-usage)\n  - 🖲️ [Main Menu Commands](#main-menu-commands)\n  - ⚡ [Command Line Options](#command-line-options)\n- 📝 [TODO](#todo)\n- ❓ [FAQ](#faq)\n- 🙌 [Thanks to the early birds](#thanks-to-the-early-birds)\n\n## Installation\n\nPenelope runs on Unix-like systems, including Linux, macOS and FreeBSD, and requires **Python 3.6+**.\n\n### Kali Linux\nPenelope is available in Kali Linux:\n```bash\nsudo apt update\nsudo apt install penelope\n```\n\n### Standalone execution\nPenelope is implemented entirely with Python’s standard library, allowing it to run as a standalone script without any external dependencies:\n```bash\nwget -q https://raw.githubusercontent.com/brightio/penelope/refs/heads/main/penelope.py \u0026\u0026 python3 penelope.py\n```\n\n### pipx\nTo install the latest upstream version directly from GitHub:\n```bash\npipx install git+https://github.com/brightio/penelope\n```\nFor a versioned and more stable release path, Penelope is also available on PyPI:\n```bash\npipx install penelope-shell-handler\n```\n\n## Features\n### Session Features\n|Description|Unix with Python\u003e=2.3| Unix without Python\u003e=2.3|Windows|\n|-----------|:-------------------:|:-----------------------:|:-----:|\n|Auto-upgrade shell|PTY|PTY(*)|readline(**)|\n|Real-time terminal resize|✅|✅|❌|\n|Logging shell activity|✅|✅|✅|\n|Download remote files/folders|✅|✅|✅|\n|Upload local/HTTP files/folders|✅|✅|✅|\n|In-memory local/HTTP script execution with real-time output downloading|✅|❌|❌|\n|Local port forwarding|✅|❌|❌|\n|Spawn shells on multiple tabs and/or hosts|✅|✅|❌|\n|Maintain X amount of active shells per host no matter what|✅|✅|❌|\n\n(*) opens a second TCP connection\n\n(**) Can be manually upgraded with the `upgrade` command\n\n### Global Features\n- Streamline interaction with the targets via modules\n- Multiple sessions\n- Multiple listeners\n- Serve files/folders via HTTP (-s switch)\n- Can be imported by python3 exploits and get shell on the same terminal (see [extras](https://github.com/brightio/penelope/tree/main/extras))\n- Can work in conjunction with Metasploit exploits by disabling the default handler with `set DisablePayloadHandler True`\n\n### Modules\n\n![modules](https://github.com/user-attachments/assets/e1428a62-727b-4f2e-bb9e-b225e49409e1)\n\n#### Meterpreter module demonstration\n\n![meterpreter](https://github.com/user-attachments/assets/b9cda69c-e25c-41e1-abe2-ce18ba13c4ed)\n\n## Usage\n### Sample Typical Usage\n```\npenelope                          # Listening for reverse shells on 0.0.0.0:4444\npenelope -p 5555                  # Listening for reverse shells on 0.0.0.0:5555\npenelope -p 4444,5555             # Listening for reverse shells on 0.0.0.0:4444 and 0.0.0.0:5555\npenelope -i eth0 -p 5555          # Listening for reverse shells on eth0:5555\npenelope -a                       # Listening for reverse shells on 0.0.0.0:4444 and show sample reverse shell payloads\n\npenelope -c target -p 3333        # Connect to a bind shell on target:3333\n\npenelope ssh user@target          # Get a reverse shell from target on local port 4444\npenelope -p 5555 ssh user@target  # Get a reverse shell from target on local port 5555\npenelope -i eth0 -p 5555 -- ssh -l user -p 2222 target  # Get a reverse shell from target on eth0, local port 5555 (use -- if ssh needs switches)\n\npenelope -s \u003cFile/Folder\u003e         # Share a file or folder via HTTP\n```\n![Penelope](https://github.com/user-attachments/assets/b8e5cd84-60a5-4d79-b041-68bee901ab19)\n\n### Demonstrating Random Usage\n\nAs shown in the video below, within only a few seconds we can:\n1. Get a fully functional auto-resizable PTY shell while logging every interaction with the target\n2. Execute the latest version of LinPEAS on the target without touching the disk and save the output to a local file in real time\n3. Open one more PTY shell in another tab\n4. Upload the latest versions of LinPEAS and linux-smart-enumeration\n5. Upload a local folder with custom scripts\n6. Upload an exploit-db exploit directly from URL\n7. Download and open a remote file locally\n8. Download the remote /etc directory\n9. Automatically spawn a new shell if an existing shell dies, helping keep access available during unstable shell sessions\n\nhttps://github.com/brightio/penelope/assets/65655412/7295da32-28e2-4c92-971f-09423eeff178\n\n### Main Menu Commands\nSome Notes:\n- 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.\n- The Main Menu supports TAB completion and also short commands. For example instead of `interact 1` you can just type `i 1`.\n\n![Main Menu](https://github.com/user-attachments/assets/a0ba2925-ea7a-4c09-9ed0-8063a7d21b65)\n\n### Command Line Options\n```\npositional arguments:\n  args                          Arguments for -s/--serve and SSH reverse shell modes\n\noptions:\n  -p PORTS, --ports PORTS       Ports (comma separated) to listen/connect/serve, depending on -i/-c/-s options\n                                (Default: 4444/5555/8000)\n\nReverse or Bind shell?:\n  -i , --interface              Local interface/IP to listen. (Default: 0.0.0.0)\n  -c , --connect                Bind shell Host\n  -j , --jump                   Reverse shell jump endpoints\n\nHints:\n  -a, --payloads                Show sample reverse shell payloads for active Listeners\n  -l, --interfaces              List available network interfaces\n  -h, --help                    show this help message and exit\n\nSession Logging:\n  -L, --no-log                  Disable session log files\n  -T, --no-timestamps           Disable timestamps in logs\n  -CT, --no-colored-timestamps  Disable colored timestamps in logs\n\nMisc:\n  -m , --maintain               Keep N sessions per target\n  -M, --menu                    Start in the Main Menu.\n  -S, --single-session          Accommodate only the first created session\n  -C, --no-attach               Do not auto-attach on new sessions\n  -U, --no-upgrade              Disable shell auto-upgrade\n  -O, --oscp-safe               Enable OSCP-safe mode\n\nFile server:\n  -s, --serve                   Run HTTP file server mode\n  -prefix , --url-prefix        URL path prefix\n\nDebug:\n  -N , --no-bins                Simulate missing binaries on target (comma-separated)\n  -v, --version                 Print version and exit\n  -d, --debug                   Enable debug output\n  -dd, --dev-mode               Enable developer mode\n  -cu, --check-urls             Check hardcoded URLs health and exit\n```\n\n## TODO\n\n### Features\n* encryption\n* remote port forwarding\n* socks \u0026 http proxy\n* team server\n* HTTPs and DNS agents\n\n### Known Issues\n* Session logging: commands that use alternate buffers, such as nano, may leave escape sequences in the log if they terminate abnormally. The data is still preserved, but viewing the logfile with tools like `cat` may look corrupted. Filtering these escape sequences is planned to make log output smoother.\n\n## FAQ\n\n### ► Is Penelope allowed in the OSCP exam?\n\nPenelope’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 verify the current official OffSec rules before using any tool during an exam.\n\nSome modules require extra caution:\n\n* The meterpreter module should only be used in a way that complies with the current exam rules.\n* The traitor module uploads Traitor, which performs automatic privilege escalation.\n\nIf you want to avoid accidental rule violations, use the `-O / --oscp-safe` switch.\n\n### ► How can I return from the remote shell to the Main Menu?\nIt depends on the type of shell upgrade in use:\n* PTY: press `F12`\n* Readline: send EOF (`Ctrl-D`)\n* Raw: send SIGINT (`Ctrl-C`)\n\nIn any case, the correct key is always displayed when you attach to a session. For example:\n\n![F12](https://github.com/user-attachments/assets/87da0eec-0d78-4f1b-8e82-f3ebe9cacf5e)\n\n### ► How can I customize Penelope (change default options, create custom modules, etc.)?\nSee [peneloperc](https://github.com/brightio/penelope/blob/main/extras/peneloperc)\n\n### ► Why aren’t my current working directory and/or user respected when I use menu commands like download/upload?\nThis usually means you opened a new interactive shell, 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.\n\n### ► How can I contribute?\nYour 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.\n\n### ► Where does the name come from?\nPenelope 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.\n\n## Thanks to the early birds\n* [Cristian Grigoriu - @crgr](https://github.com/crgr) for inspiring me to automate the PTY upgrade process. This is how this project was born.\n* [Paul Taylor - @bao7uo](https://github.com/bao7uo) for the idea to support bind shells.\n* [Longlone - @WAY29](https://github.com/WAY29) for indicating the need for compatibility with previous versions of Python (3.6).\n* [Carlos Polop - @carlospolop](https://github.com/carlospolop) for the idea to spawn shells on listeners on other systems.\n* [@darrenmartyn](https://github.com/darrenmartyn) for indicating an alternative method to upgrade the shell to PTY using the script command.\n* [@bamuwe](https://github.com/bamuwe) for the idea to get reverse shells via SSH.\n* [@strikoder](https://github.com/strikoder) for numerous enhancement ideas.\n* [@root-tanishq](https://github.com/root-tanishq), [@robertstrom](https://github.com/robertstrom), [@terryf82](https://github.com/terryf82), [@RamadhanAmizudin](https://github.com/RamadhanAmizudin), [@furkan-enes-polatoglu](https://github.com/furkan-enes-polatoglu), [@DerekFost](https://github.com/DerekFost), [@Mag1cByt3s](https://github.com/Mag1cByt3s), [@nightingalephillip](https://github.com/nightingalephillip), [@grisuno](https://github.com/grisuno), [@thinkslynk](https://github.com/thinkslynk), [@stavoxnetworks](https://github.com/stavoxnetworks), [@thomas-br](https://github.com/thomas-br), [@joshoram80](https://github.com/joshoram80), [@TheAalCh3m1st](https://github.com/TheAalCh3m1st), [@r3pek](https://github.com/r3pek), [@bamuwe](https://github.com/bamuwe), [@six-two](https://github.com/six-two), [@x9xhack](https://github.com/x9xhack), [@dummys](https://github.com/dummys), [@pocpayload](https://github.com/pocpayload), [@anti79](https://github.com/anti79), [@strikoder](https://github.com/strikoder), [@bestutsengineer](https://github.com/bestutsengineer) for bug reporting.\n* Special thanks to [@Y3llowDuck](https://github.com/Y3llowDuck) for spreading the word!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrightio%2Fpenelope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrightio%2Fpenelope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrightio%2Fpenelope/lists"}