penelope

Penelope es un moderno manejador de shells para pentesters y jugadores de CTF. Proporciona una alternativa más capaz a los oyentes básicos de netcat, añadiendo actualización automática de PTY, gestión de sesiones, registro, transferencias de archivos y módulos auxiliares.

Tabla de contenidos

• 📥 Instalación
• ⚙️ Características
  • 🖥️ Características de sesión
  • 🌍 Características globales
  • 🧩 Módulos
• 💻 Uso
  • ▶️ Ejemplo de uso típico
  • 🎬 Demostración de uso aleatorio
  • 🖲️ Comandos del menú principal
  • ⚡ Opciones de línea de comandos
• 🔒 Consideraciones de seguridad
• 📝 Pendiente
• ❓ Preguntas frecuentes
• 🙌 Agradecimientos a los primeros

Instalación

Penelope funciona en sistemas tipo Unix, incluyendo Linux, macOS y FreeBSD, y requiere Python 3.6+.

Kali Linux

Penelope está disponible en Kali Linux:

sudo apt update
sudo apt install penelope

Ejecución independiente

Penelope está implementado completamente con la biblioteca estándar de Python, permitiendo ejecutarlo como un script independiente sin dependencias externas:

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

pipx

Para instalar la última versión upstream directamente desde GitHub:

pipx install git+https://github.com/brightio/penelope

Para una ruta de lanzamiento versionada y más estable, Penelope también está disponible en PyPI:

pipx install penelope-shell-handler

Características

Características de sesión

(*) Se puede actualizar manualmente a PTY con el comando upgrade

⚠️ El soporte para Windows es experimental y está en desarrollo activo.

Características globales

• Interacción optimizada con los objetivos mediante módulos
• Múltiples sesiones
• Múltiples oyentes
• Servir archivos/carpetas vía HTTP (interruptor -s)
• Puede ser importado por exploits de python3 y obtener shell en la misma terminal (ver extras/exploit_examples)
• Puede funcionar junto con exploits de Metasploit deshabilitando el manejador por defecto con set DisablePayloadHandler True
• Exponer sesiones en vivo a un cliente MCP como Claude Code con el interruptor --mcp (HTTP local, autenticado por token), manejando los mismos shells junto a ti

Módulos

Demostración del módulo Meterpreter

Uso

Ejemplo de uso típico

penelope                          # Escuchando shells inversos en 0.0.0.0:4444
penelope -p 5555                  # Escuchando shells inversos en 0.0.0.0:5555
penelope -p 4444,5555             # Escuchando shells inversos en 0.0.0.0:4444 y 0.0.0.0:5555
penelope -i eth0 -p 5555          # Escuchando shells inversos en eth0:5555
penelope -a                       # Escuchando shells inversos en 0.0.0.0:4444 y mostrando payloads de shell inverso de ejemplo

penelope -c objetivo -p 3333        # Conectarse a un shell bind en objetivo:3333

penelope ssh usuario@objetivo          # Obtener un shell inverso desde el objetivo en el puerto local 4444
penelope -p 5555 ssh usuario@objetivo  # Obtener un shell inverso desde el objetivo en el puerto local 5555
penelope -i eth0 -p 5555 -- ssh -l usuario -p 2222 objetivo  # Obtener un shell inverso desde el objetivo en eth0, puerto local 5555 (usar -- si ssh necesita interruptores)

penelope -s <Archivo/Carpeta>         # Compartir un archivo o carpeta vía HTTP

Servidor de archivos HTTP (-s)

Penelope también se puede usar como un servidor de archivos HTTP rápido.

penelope -s archivo.txt                 # Servir un solo archivo en 0.0.0.0:8000
penelope -s /ruta/a/directorio             # Servir una carpeta completa
penelope -s a.sh b.elf notas.txt     # Servir varios elementos a la vez
penelope -s . -p 80                  # Servir el directorio actual en el puerto 80
penelope -s secreto.txt -prefix xk9   # Ocultar detrás de un prefijo de URL: /xk9/secreto.txt
penelope -s -u                       # Modo subida: aceptar PUT/POST en el directorio de trabajo actual
penelope -s -u -ud /tmp/botín         # Modo subida, almacenar archivos recibidos en /tmp/botín

Al iniciar, Penelope imprime un enlace listo para usar por interfaz (y una pista de subida cuando se usa -u), para que puedas copiar y pegar directamente en el shell del objetivo.

Demostración de uso aleatorio

Como se muestra en el video a continuación, en solo unos segundos podemos:

1. Obtener un shell PTY completamente funcional y auto-redimensionable mientras se registra cada interacción con el objetivo
2. Ejecutar la última versión de LinPEAS en el objetivo sin tocar el disco y guardar la salida en un archivo local en tiempo real
3. Abrir un shell PTY más en otra pestaña
4. Subir las últimas versiones de LinPEAS y linux-smart-enumeration
5. Subir una carpeta local con scripts personalizados
6. Subir un exploit de exploit-db directamente desde URL
7. Descargar y abrir un archivo remoto localmente
8. Descargar el directorio /etc remoto
9. Generar automáticamente un nuevo shell si un shell existente muere, ayudando a mantener el acceso disponible durante sesiones de shell inestables

https://github.com/brightio/penelope/assets/65655412/7295da32-28e2-4c92-971f-09423eeff178

Comandos del menú principal

Algunas notas:

• Por defecto, debes presionar F12 para desacoplar el shell PTY e ir al Menú Principal. Si la actualización no fue posible y terminaste con un shell básico, puedes desacoplarlo con Ctrl+C. Esto también evita la eliminación accidental del shell.
• El Menú Principal admite autocompletado con TAB y también comandos cortos. Por ejemplo, en lugar de interact 1 puedes escribir simplemente i 1.

Opciones de línea de comandos

argumentos posicionales:
  args                          Argumentos para los modos -s/--serve y shell inverso SSH

opciones:
  -p, --ports                   Puertos (separados por comas) para escuchar/conectar/servir, según las opciones -i/-c/-s
                                (Por defecto: 4444/5555/8000)

¿Shell inverso o Bind?:
  -i, --interface               Interfaz/IP local para escuchar. (Por defecto: 0.0.0.0)
  -c, --connect                 Host del shell Bind
  -j, --jump                    Puntos finales de salto para shell inverso

Pistas:
  -a, --payloads                Mostrar payloads de shell inverso de ejemplo para los Oyentes activos
  -l, --interfaces              Listar interfaces de red disponibles
  -h, --help                    mostrar este mensaje de ayuda y salir

Registro de sesión:
  -L, --no-log                  Deshabilitar archivos de registro de sesión
  -T, --no-timestamps           Deshabilitar marcas de tiempo en los registros
  -CT, --no-colored-timestamps  Deshabilitar marcas de tiempo coloreadas en los registros

Varios:
  -M, --menu                    Iniciar en el Menú Principal
  -m, --maintain                Mantener N sesiones por objetivo
  -S, --single-session          Aceptar solo la primera sesión creada
  -ms, --max-sessions           Máximo de sesiones activas por host (por defecto 5, 0 = rechazar todas las nuevas)
  -C, --no-attach               No adjuntar automáticamente a nuevas sesiones
  -U, --no-upgrade              Deshabilitar la actualización automática del shell
  -H, --keep-history            Mantener el historial del shell del objetivo (no establecer HISTFILE=/dev/null)
  -O, --oscp-safe               Habilitar modo seguro para OSCP
  --no-disk                     Mantener todo el estado en RAM (tmpfs); nada persiste en disco

MCP:
  --mcp                         Habilitar el servidor MCP sobre HTTP local
  --mcp-host                    Host/IP al que vincular (por defecto: 127.0.0.1)
  --mcp-port                    Puerto al que vincular (por defecto: puerto guardado, o un puerto libre aleatorio persistido en ~/.penelope/mcp.json)
  --mcp-token                   Token Bearer (por defecto: token guardado, o auto-generado y persistido)

Servidor de archivos:
  -s, --serve                   Ejecutar modo servidor de archivos HTTP
  -prefix, --url-prefix         Prefijo de ruta URL
  -u, --upload                  Habilitar subida de archivos (PUT/POST) al servidor
  -ud, --upload-dir             Directorio para almacenar subidas (por defecto: directorio de trabajo actual)

Depuración:
  -N, --no-bins                 Simular binarios faltantes en el objetivo (separados por comas)
  -v, --version                 Imprimir versión y salir
  -d, --debug                   Habilitar salida de depuración
  -dd, --dev-mode               Habilitar modo desarrollador
  -cu, --check-urls             Revisar la salud de las URLs codificadas y salir

Consideraciones de seguridad

Penelope está diseñado para proporcionar una interacción directa y flexible con shells remotos. Ten en cuenta lo siguiente al usarlo:

• Secuencias de escape de terminal: Penelope reenvía la salida del terminal desde sistemas remotos directamente a tu emulador de terminal. Los procesos remotos maliciosos pueden usar secuencias de escape de terminal para manipular la pantalla, crear enlaces engañosos o interactuar con funciones como el portapapeles. Esta exposición es inherente a cualquier herramienta que retransmita un shell remoto al terminal local (como SSH, telnet, netcat) y no es específica de Penelope. Utiliza un terminal con configuraciones de seguridad adecuadas al conectarte a sistemas no confiables.

• Registros de sesión: Los registros de sesión pueden contener credenciales, tokens, comandos y otra información sensible recibida del objetivo. Almacénalos de forma segura y usa --no-log cuando no se requiera registro.

• Conexiones no cifradas: Las conexiones estándar de shell inverso y bind no están cifradas. Evita usarlas en redes no confiables a menos que el tráfico esté protegido por un túnel seguro o VPN.

• Servidor MCP (--mcp): Cuando está habilitado, el servidor MCP otorga control total sobre cada sesión activa (ejecución de comandos, transferencia de archivos) a cualquier cliente que posea el token Bearer, el cual se almacena en ~/.penelope/mcp.json (0600). Se vincula a 127.0.0.1 y está autenticado por token. Mantén el token en secreto y evita exponer el servidor en redes no confiables.

⚖️ Aviso de exención de responsabilidad: Penelope está destinado únicamente para pruebas de seguridad autorizadas, fines educativos y de investigación. No lo uses contra sistemas sin permiso explícito.

Pendiente

Características

• cifrado
• reenvío de puertos remoto
• proxy socks y HTTP
• servidor de equipo
• Agentes HTTPs y DNS

Problemas conocidos

• Registro de sesión: los comandos que usan búferes alternativos, como nano, pueden dejar secuencias de escape en el registro si terminan de forma anormal. Los datos aún se conservan, pero ver el archivo de registro con herramientas como cat puede parecer corrupto. Filtrar estas secuencias de escape está previsto para que la salida del registro sea más fluida.

Preguntas frecuentes

► ¿Está permitido Penelope en el examen OSCP?

Las funciones principales de manejo de shell de Penelope no realizan explotación automática, lo que las hace adecuadas para el estilo OSCP. Sin embargo, las reglas del examen pueden cambiar, así que siempre verifica las reglas oficiales actuales de OffSec antes de usar cualquier herramienta durante un examen.

Algunos módulos requieren precaución adicional:

• El módulo meterpreter solo debe usarse de manera que cumpla con las reglas actuales del examen.
• El módulo traitor sube Traitor, que realiza escalada de privilegios automática.

Si deseas evitar violaciones accidentales de las reglas, usa el interruptor -O / --oscp-safe.

► ¿Cómo puedo regresar del shell remoto al Menú Principal?

Depende del tipo de actualización de shell en uso:

• PTY: presiona F12
• Readline: envía EOF (Ctrl-D)
• Raw: envía SIGINT (Ctrl-C)

En cualquier caso, la tecla correcta siempre se muestra al adjuntarte a una sesión. Por ejemplo:

► ¿Cómo puedo personalizar Penelope (cambiar opciones por defecto, crear módulos personalizados, etc.)?

Ver peneloperc

► ¿Por qué mi directorio de trabajo actual y/o usuario no se respetan cuando uso comandos del menú como descargar/subir?

Esto generalmente significa que abriste un nuevo shell interactivo, posiblemente bajo un usuario diferente. El agente de Penelope solo rastrea el directorio del shell inicial y mantiene los permisos del usuario de ese primer shell. La mejor solución es hacer cd /tmp antes de abrir un nuevo shell, o, si cambiaste de usuario, genera un nuevo shell inverso como el nuevo usuario.

► ¿Cómo puedo contribuir?

¡Tus contribuciones son invaluables! Si deseas ayudar, por favor reporta errores, comportamientos inesperados o comparte nuevas ideas. También puedes enviar pull requests, pero evita hacer commits desde IDEs que impongan PEP8 y reestructuren involuntariamente todo el código base.

► ¿De dónde viene el nombre?

Penélope fue la esposa de Odiseo y es conocida por su lealtad y paciencia mientras esperaba su regreso. La herramienta lleva su nombre porque fue construida para ser un manejador de shell fiel y estable para flujos de trabajo que van más allá de un oyente básico.

Agradecimientos a los primeros

• Cristian Grigoriu - @crgr por inspirarme a automatizar el proceso de actualización de PTY. Así nació este proyecto.
• Paul Taylor - @bao7uo por la idea de soportar shells bind.
• Longlone - @WAY29 por señalar la necesidad de compatibilidad con versiones anteriores de Python (3.6).
• Carlos Polop - @carlospolop por la idea de generar shells en oyentes en otros sistemas.
• @darrenmartyn por indicar un método alternativo para actualizar el shell a PTY usando el comando script.
• @bamuwe por la idea de obtener shells inversos vía SSH.
• @strikoder por numerosas ideas de mejora.
• @root-tanishq, @robertstrom, @terryf82, @RamadhanAmizudin, @furkan-enes-polatoglu, @DerekFost, @Mag1cByt3s, @nightingalephillip, @grisuno, @thinkslynk, @stavoxnetworks, @thomas-br, @joshoram80, @TheAalCh3m1st, @r3pek, @bamuwe, @six-two, @x9xhack, @dummys, , , , por reportar errores.