PENELOPE(1)

📦 version 0.21.0, in ubuntu stonking

💅 PENELOPE — the manual page, bestie edition

okay so. you opened penelope(1) from the General Commands Manual and you're about to get the whole thing explained with Love and Enthusiasm. grab a snack. 🍓

✨ NAME ✨

penelope — an advanced shell handler for penetration testing and CTFs. yes she's a shell handler and yes she's advanced. iconic behavior only.

🌸 SYNOPSIS 🌸

penelope [options] [args …]

🦋 DESCRIPTION 🦋

so like, penelope is an advanced shell handler. her whole thing is automating and streamlining the exploitation phase — you know, the part where you're doing reverse or bind shells during penetration testing engagements and Capture The Flag (CTF) competitions. she's basically a drop-in replacement for your traditional netcat listeners, except she's feature-rich. it's giving glow-up. 💅

and here's the wild part bestie: she's built entirely using the Python standard library. minimal environmental dependencies, no cap. but she still serves modern features like automatic PTY upgrades, concurrent multi-session tracking, local file transfers, and session logging. main character energy fr fr. 👑

🎀 ARGUMENTS 🎀

  • args — the arguments you need for file server mode (-s/--serve) and for SSH reverse shell configurations. they're not optional-optional, they're required-when-you-need-them, iykyk.

💖 OPTIONS 💖

  • -p, --ports PORTS — comma-separated list of ports to listen, connect, or serve, depending on which operation mode you're in (-i/-c/-s). defaults to 4444, 5555, or 8000. pick your fighter. ✨

🔌 Remote Shell Connection Modes 🔌

  • -i, --interface [IP] — tells her which local interface or IP address to bind and listen on for incoming reverse shells. defaults to 0.0.0.0.
  • -c, --connect HOST — flips her into bind shell mode, so she goes out and actively connects to the target HOST you named. she's reaching out first, bold of her.
  • -j, --jump ENDPOINTS — sets up reverse shell jump endpoints for pivoting and multi-stage connection routing. plot twist routes. 🌀

💡 Hints 💡

  • -a, --payloads — shows you sample reverse shell payloads, tailored to whichever listeners are currently active. cute AND relevant.
  • -l, --interfaces — lists every available network interface on the local host machine and then exits.
  • -h, --help — prints the comprehensive command help message and dips out.

📝 Session Logging 📝

  • -L, --no-log — no more automatic creation of session log files. bye logging.
  • -T, --no-timestamps — strips the timestamp entries out of the session log records.
  • -CT, --no-colored-timestamps — kills the ANSI color codes inside the log file timestamps.

🌈 Misc 🌈

  • -M, --menu — forces Penelope to immediately display and start inside the Main Menu interface. she goes straight to the menu, no detours.
  • -m, --maintain N — tells her to actively maintain exactly N persistent sessions per target. loyalty. 🫶
  • -S, --single-session — restricts the handler to only accommodate the first session created, rejecting any subsequent connections. one at a time bestie.
  • -ms, --max-sessions MAX — the max number of allowed active sessions per host. defaults to 5. and heads up: specifying 0 rejects all new incoming connections. 🚫
  • -C, --no-attach — stops your terminal from automatically attaching to newly spawned target sessions.
  • -U, --no-upgrade — disables the automated target shell interaction upgrade routine to an interactive PTY.
  • -O, --oscp-safe — enables OSCP-safe operational mode, which strictly avoids restricted automation techniques during the exam environment. stay safe, stay legal. 👑

🗂️ File server 🗂️

  • -s, --serve — launches Penelope in an integrated HTTP file server mode so you can do quick transfers. slay.
  • -prefix, --url-prefix PREFIX — sets a custom URL path prefix to prepend onto the served files. stealth-ish URL drip. ✨

🐛 Debug 🐛

  • -N, --no-bins BINARIES — simulates the absence of the binaries you list (comma-separated) on the target file system, so you can test fallback mechanisms. fake it till you break it (on purpose).
  • -v, --version — prints the application version number and exits.
  • -d, --debug — turns on verbose debug console messages.
  • -dd, --dev-mode — enables internal developer testing and diagnostic behaviors. devs only, it's giving backstage pass.
  • -cu, --check-urls — validates the availability and health status of hardcoded infrastructure URLs, then exits.

🧚 INTERNAL COMMANDS 🧚

okay this part is important. while a shell session is actively attached, you trigger the escape sequence (commonly Ctrl+P) — that pauses the raw terminal pass-through and drops you into the Penelope control menu. the following internal routines are available:

  • download [remote_path] — downloads a file directly from the target file system to the local host machine.
  • upload [local_path] — uploads a file from the local host machine straight into the remote target's current directory.
  • sessions — lists, switches between, or detaches backgrounded target connections.
  • interact [session_id] — attaches your terminal back to a specific backgrounded target session. come back bb 🥺
  • upgrade — forces a manual PTY terminal upgrade attempt on the target, for when the automatic upgrade was disabled or just failed.
  • exit — terminates the active shell interaction, or kills the handler process.

⭐ EXAMPLES ⭐

Listen on port 4444 for incoming reverse shells, with standard automatic upgrade features:

penelope -p 4444

Connect to a remote bind shell listener while operating under OSCP constraints and disabling log timestamps:

penelope -c 10.11.1.50 -p 5555 -O -T

Run the integrated HTTP file server to host local payloads on port 8000 using a secure prefix:

penelope -s -p 8000 -prefix secret-path

💜 AUTHOR 💜

  • brightio brightio.code@gmail.com — created Penelope. the founder, the icon.
  • David da Silva Polverari polverari@debian.org — wrote this manpage for the Debian system. that's the pen behind the page. 🖊️

Copyright © 2026 David da Silva Polverari

This manual page was written for the Debian system (and may be used by others).

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 3 or (at your option) any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.

and that's the whole page bestie, penelope(1), documented June 2026 — go forth and catch those shells. no cap. 🎀✨🔥

p.s. penelope(1) — General Commands Manual, June 2026. periodt. 💅
📦 where this page comes from