penelope

Penelope é um moderno gerenciador de shells para testadores de penetração e jogadores de CTF. Ele oferece uma alternativa mais capaz aos ouvintes netcat básicos, adicionando upgrades automáticos de PTY, gerenciamento de sessões, registro de logs, transferências de arquivos e módulos auxiliares.

Índice

• 📥 Instalação
• ⚙️ Funcionalidades
  • 🖥️ Funcionalidades da Sessão
  • 🌍 Funcionalidades Globais
  • 🧩 Módulos
• 💻 Uso
  • ▶️ Exemplo Típico de Uso
  • 🎬 Demonstração de Uso Aleatório
  • 🖲️ Comandos do Menu Principal
  • ⚡ Opções de Linha de Comando
• 🔒 Considerações de Segurança
• 📝 TODO
• ❓ FAQ
• 🙌 Agradecimentos aos primeiros colaboradores

Instalação

O Penelope é executado em sistemas do tipo Unix, incluindo Linux, macOS e FreeBSD, e requer Python 3.6+.

Kali Linux

O Penelope está disponível no Kali Linux:

sudo apt update
sudo apt install penelope

Execução autônoma

O Penelope é implementado inteiramente com a biblioteca padrão do Python, permitindo sua execução como um script autônomo sem dependências externas:

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

pipx

Para instalar a versão mais recente diretamente do GitHub:

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

Para um caminho de lançamento versionado e mais estável, o Penelope também está disponível no PyPI:

pipx install penelope-shell-handler

Funcionalidades

Funcionalidades da Sessão

(*) Pode ser atualizado manualmente para PTY com o comando upgrade

⚠️ O suporte ao Windows é experimental e está em desenvolvimento ativo.

Funcionalidades Globais

• Interação simplificada com os alvos através de módulos
• Múltiplas sessões
• Múltiplos ouvintes
• Servir arquivos/pastas via HTTP (opção -s)
• Pode ser importado por exploits em python3 e obter shell no mesmo terminal (veja extras/exploit_examples)
• Pode funcionar em conjunto com exploits do Metasploit desabilitando o handler padrão com set DisablePayloadHandler True
• Expor sessões ativas a um cliente MCP como o Claude Code com a opção --mcp (HTTP local, autenticado por token), conduzindo os mesmos shells junto com você

Módulos

Demonstração do módulo Meterpreter

Uso

Exemplo Típico de Uso

penelope                          # Listening for reverse shells on 0.0.0.0:4444
penelope -p 5555                  # Listening for reverse shells on 0.0.0.0:5555
penelope -p 4444,5555             # Listening for reverse shells on 0.0.0.0:4444 and 0.0.0.0:5555
penelope -i eth0 -p 5555          # Listening for reverse shells on eth0:5555
penelope -a                       # Listening for reverse shells on 0.0.0.0:4444 and show sample reverse shell payloads

penelope -c target -p 3333        # Connect to a bind shell on target:3333

penelope ssh user@target          # Get a reverse shell from target on local port 4444
penelope -p 5555 ssh user@target  # Get a reverse shell from target on local port 5555
penelope -i eth0 -p 5555 -- ssh -l user -p 2222 target  # Get a reverse shell from target on eth0, local port 5555 (use -- if ssh needs switches)

penelope -s <File/Folder>         # Share a file or folder via HTTP

Servidor de Arquivos HTTP (-s)

O Penelope também pode ser usado como um servidor de arquivos HTTP rápido.

penelope -s file.txt                 # Serve a single file on 0.0.0.0:8000
penelope -s /path/to/dir             # Serve a whole folder
penelope -s a.sh b.elf notes.txt     # Serve several items at once
penelope -s . -p 80                  # Serve the current dir on port 80
penelope -s secret.txt -prefix xk9   # Hide behind a URL prefix: /xk9/secret.txt
penelope -s -u                       # Upload mode: accept PUT/POST into the CWD
penelope -s -u -ud /tmp/loot         # Upload mode, store received files in /tmp/loot

Ao iniciar, o Penelope imprime um link pronto para uso por interface (e uma dica de upload quando -u está definido), permitindo que você copie e cole diretamente no shell do alvo.

Demonstração de Uso Aleatório

Como mostrado no vídeo abaixo, em apenas alguns segundos podemos:

1. Obter um shell PTY totalmente funcional com redimensionamento automático enquanto registramos cada interação com o alvo
2. Executar a versão mais recente do LinPEAS no alvo sem tocar no disco e salvar a saída em um arquivo local em tempo real
3. Abrir mais um shell PTY em outra aba
4. Enviar as versões mais recentes do LinPEAS e linux-smart-enumeration
5. Enviar uma pasta local com scripts personalizados
6. Enviar um exploit do exploit-db diretamente de uma URL
7. Baixar e abrir um arquivo remoto localmente
8. Baixar o diretório /etc remoto
9. Abrir automaticamente um novo shell se um shell existente morrer, ajudando a manter o acesso disponível durante sessões de shell instáveis

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

Comandos do Menu Principal

Algumas notas:

• Por padrão, você precisa pressionar F12 para desanexar o shell PTY e ir ao Menu Principal. Se o upgrade não foi possível e você acabou com um shell básico, pode desanexá-lo com Ctrl+C. Isso também evita o encerramento acidental do shell.
• O Menu Principal suporta completamento com TAB e também comandos curtos. Por exemplo, em vez de interact 1, você pode digitar apenas i 1.

Opções de Linha de Comando

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

options:
  -p, --ports                   Ports (comma separated) to listen/connect/serve, depending on -i/-c/-s options
                                (Default: 4444/5555/8000)

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

Hints:
  -a, --payloads                Show sample reverse shell payloads for active Listeners
  -l, --interfaces              List available network interfaces
  -h, --help                    show this help message and exit

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

Misc:
  -M, --menu                    Start in the Main Menu
  -m, --maintain                Keep N sessions per target
  -S, --single-session          Accommodate only the first created session
  -ms, --max-sessions           Max active sessions per host (default 5, 0 = reject all new)
  -C, --no-attach               Do not auto-attach on new sessions
  -U, --no-upgrade              Disable shell auto-upgrade
  -H, --keep-history            Keep target shell history (do not set HISTFILE=/dev/null)
  -O, --oscp-safe               Enable OSCP-safe mode
  --no-disk                     Keep all state in RAM (tmpfs); nothing persists to disk

MCP:
  --mcp                         Enable the MCP server over local HTTP
  --mcp-host                    Host/IP to bind (default: 127.0.0.1)
  --mcp-port                    Port to bind (default: saved port, else a random free port persisted to ~/.penelope/mcp.json)
  --mcp-token                   Bearer token (default: saved token, else auto-generated and persisted)

File server:
  -s, --serve                   Run HTTP file server mode
  -prefix, --url-prefix         URL path prefix
  -u, --upload                  Enable file upload (PUT/POST) to the server
  -ud, --upload-dir             Directory to store uploads (default: CWD)

Debug:
  -N, --no-bins                 Simulate missing binaries on target (comma-separated)
  -v, --version                 Print version and exit
  -d, --debug                   Enable debug output
  -dd, --dev-mode               Enable developer mode
  -cu, --check-urls             Check hardcoded URLs health and exit

Considerações de Segurança

O Penelope foi projetado para fornecer interação direta e flexível com shells remotos. Tenha em mente o seguinte ao usá-lo:

• Sequências de escape do terminal: O Penelope encaminha a saída do terminal de sistemas remotos diretamente para o seu emulador de terminal. Processos remotos maliciosos podem usar sequências de escape do terminal para manipular a tela, criar links enganosos ou interagir com recursos como a área de transferência. Essa exposição é inerente a qualquer ferramenta que retransmita um shell remoto para o terminal local (como SSH, telnet, netcat) e não é específica do Penelope. Use um terminal com configurações de segurança adequadas ao conectar-se a sistemas não confiáveis.

• Logs de sessão: Os logs de sessão podem conter credenciais, tokens, comandos e outras informações confidenciais recebidas do alvo. Armazene-os de forma segura e use --no-log quando o registro não for necessário.

• Conexões não criptografadas: As conexões de shell reverso e bind padrão não são criptografadas. Evite usá-las em redes não confiáveis, a menos que o tráfego esteja protegido por um túnel ou VPN seguros.

• Servidor MCP (--mcp): Quando ativado, o servidor MCP concede controle total sobre todas as sessões ativas (execução de comandos, transferência de arquivos) a qualquer cliente que possua o token de portador, que é armazenado em ~/.penelope/mcp.json (0600). Ele se vincula a 127.0.0.1 e é autenticado por token. Mantenha o token em segredo e evite expor o servidor em redes não confiáveis.

⚖️ Aviso Legal: O Penelope destina-se apenas a testes de segurança autorizados, pesquisa e fins educacionais. Não o utilize contra sistemas sem permissão explícita.

TODO

Funcionalidades

• criptografia
• redirecionamento de porta remoto
• proxy socks e http
• servidor de equipe
• agentes HTTPs e DNS

Problemas Conhecidos

• Registro de sessão: comandos que usam buffers alternativos, como o nano, podem deixar sequências de escape no log se terminarem de forma anormal. Os dados ainda são preservados, mas visualizar o arquivo de log com ferramentas como cat pode parecer corrompido. A filtragem dessas sequências de escape está planejada para tornar a saída do log mais suave.

FAQ

► O Penelope é permitido no exame OSCP?

Os recursos principais de gerenciamento de shell do Penelope não realizam exploração automática, o que os torna adequados para uso no estilo OSCP. No entanto, as regras do exame podem mudar; portanto, sempre verifique as regras atuais oficiais da OffSec antes de usar qualquer ferramenta durante um exame.

Alguns módulos exigem cuidado extra:

• O módulo meterpreter deve ser usado apenas de acordo com as regras atuais do exame.
• O módulo traitor envia o Traitor, que realiza escalonamento automático de privilégios.

Se você quiser evitar violações acidentais das regras, use a opção -O / --oscp-safe.

► Como posso retornar do shell remoto para o Menu Principal?

Depende do tipo de upgrade do shell em uso:

• PTY: pressione F12
• Readline: envie EOF (Ctrl-D)
• Raw: envie SIGINT (Ctrl-C)

Em qualquer caso, a tecla correta é sempre exibida quando você se conecta a uma sessão. Por exemplo:

► Como posso personalizar o Penelope (alterar opções padrão, criar módulos personalizados, etc.)?

Veja peneloperc

► Por que meu diretório de trabalho atual e/ou usuário não são respeitados quando uso comandos do menu como download/upload?

Isso geralmente significa que você abriu um novo shell interativo, possivelmente sob um usuário diferente. O agente do Penelope só rastreia o diretório do shell inicial e mantém as permissões do usuário desse primeiro shell. A melhor solução alternativa é executar cd /tmp antes de abrir um novo shell ou, se você trocou de usuário, gerar um novo shell reverso como o novo usuário.

► Como posso contribuir?

Suas contribuições são inestimáveis! Se você quiser ajudar, por favor, reporte bugs, comportamentos inesperados ou compartilhe novas ideias. Você também pode enviar pull requests, mas evite fazer commits de IDEs que impõem PEP8 e reestruturam involuntariamente todo o código.

► De onde vem o nome?

Penélope era a esposa de Odisseu e é conhecida por sua lealdade e paciência enquanto esperava por seu retorno. A ferramenta recebeu esse nome porque foi construída para ser um gerenciador de shell fiel e estável para fluxos de trabalho que vão além de um ouvinte básico.

Agradecimentos aos primeiros colaboradores

• Cristian Grigoriu - @crgr por me inspirar a automatizar o processo de upgrade PTY. Foi assim que este projeto nasceu.
• Paul Taylor - @bao7uo pela ideia de suportar shells bind.
• Longlone - @WAY29 por indicar a necessidade de compatibilidade com versões anteriores do Python (3.6).
• Carlos Polop - @carlospolop pela ideia de gerar shells em ouvintes em outros sistemas.
• @darrenmartyn por indicar um método alternativo para atualizar o shell para PTY usando o comando script.
• @bamuwe pela ideia de obter shells reversos via SSH.
• @strikoder por inúmeras ideias de aprimoramento.
• @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 reportarem bugs.