PENELOPE(1)

NAME

penelope - advanced shell handler for penetration testing and CTFs

SYNOPSIS

penelope [options] [args …]

DESCRIPTION

penelope is an advanced shell handler designed to automate and streamline the exploitation phase via reverse or bind shells during penetration testing engagements and Capture The Flag (CTF) competitions. It acts as a feature-rich, drop-in replacement for traditional netcat listeners.

Built entirely using the Python standard library, penelope guarantees minimal environmental dependencies while delivering modern features like automatic PTY upgrades, concurrent multi-session tracking, local file transfers, and session logging.

ARGUMENTS

args
    Arguments required for file server mode (-s/--serve) and SSH reverse shell configurations.

OPTIONS

-p, --ports PORTS
    Comma-separated list of ports to listen, connect, or serve, depending on the active operation mode (-i/-c/-s). Defaults to 4444, 5555, or 8000.

  Remote Shell Connection Modes

-i, --interface [IP]
    Specifies the local interface or IP address to bind and listen for incoming reverse shells. Defaults to 0.0.0.0.

-c, --connect HOST
    Enables bind shell mode, instructing Penelope to actively connect out to the specified target HOST.

-j, --jump ENDPOINTS
    Defines reverse shell jump endpoints for pivoting and multi-stage connection routing.

  Hints

-a, --payloads
    Displays sample reverse shell payloads tailored for currently active listeners.

-l, --interfaces
    Lists all available network interfaces on the local host machine and exits.

-h, --help
    Displays the comprehensive command help message and exits.

  Session Logging

-L, --no-log
    Disables the automatic creation of session log files.

-T, --no-timestamps
    Disables timestamp entries within the session log records.

-CT, --no-colored-timestamps
    Disables ANSI color codes within the log file timestamps.

  Misc

-M, --menu
    Forces Penelope to immediately display and start inside the Main Menu interface.

-m, --maintain N
    Instructs Penelope to actively maintain exactly N persistent sessions per target.

-S, --single-session
    Restricts the handler to accommodate only the first session created, rejecting subsequent connections.

-ms, --max-sessions MAX
    Sets the maximum allowed active sessions per host. Defaults to 5. Specifying 0 rejects all new incoming connections.

-C, --no-attach
    Prevents the terminal from automatically attaching to newly spawned target sessions.

-U, --no-upgrade
    Disables the automated target shell interaction upgrade routine to interactive PTY.

-O, --oscp-safe
    Enables OSCP-safe operational mode, strictly avoiding restricted automation techniques during the exam environment.

  File server

-s, --serve
    Launches Penelope in an integrated HTTP file server mode to facilitate quick transfers.

-prefix, --url-prefix PREFIX
    Specifies a custom URL path prefix to prepend on the served files.

  Debug

-N, --no-bins BINARIES
    Simulates the absence of specified binaries (comma-separated list) on the target file system for testing fallback mechanisms.

-v, --version
    Prints the application version number and exits.

-d, --debug
    Enables verbose debug console messages.

-dd, --dev-mode
    Enables internal developer testing and diagnostic behaviors.

-cu, --check-urls
    Validates the availability and health status of hardcoded infrastructure URLs and exits.

INTERNAL COMMANDS

While a shell session is actively attached, triggering the escape sequence (commonly Ctrl+P) pauses the raw terminal pass-through and drops 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 directly to the remote target’s current directory.

sessions
    Lists, switches between, or detaches backgrounded target connections.

interact [session_id]
    Attaches the terminal back to a specific backgrounded target session.

upgrade
    Forces a manual PTY terminal upgrade attempt on the target if the automatic upgrade was disabled or 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.

David da Silva Polverari polverari@debian.org
    Wrote this manpage for the Debian system.

COPYRIGHT

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.