---
title: PENELOPE
section: 1
date: June 2026
version: v0.21.0
header: Penelope User Manual
footer: Debian GNU/Linux
---

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