penelope

Penelope est un gestionnaire de shells moderne pour les testeurs d'intrusion et les joueurs de CTF. Il offre une alternative plus performante aux simples écouteurs netcat, en ajoutant des mises à niveau automatiques vers PTY, la gestion de sessions, la journalisation, les transferts de fichiers et des modules d'aide.

Table des matières

• 📥 Installation
• ⚙️ Fonctionnalités
  • 🖥️ Fonctionnalités de session
  • 🌍 Fonctionnalités globales
  • 🧩 Modules
• 💻 Utilisation
  • ▶️ Exemple d'utilisation typique
  • 🎬 Démonstration d'utilisation aléatoire
  • 🖲️ Commandes du menu principal
  • ⚡ Options en ligne de commande
• 🔒 Considérations de sécurité
• 📝 TODO
• ❓ FAQ
• 🙌 Remerciements aux premiers contributeurs

Installation

Penelope fonctionne sur les systèmes de type Unix, y compris Linux, macOS et FreeBSD, et nécessite Python 3.6+.

Kali Linux

Penelope est disponible dans Kali Linux :

sudo apt update
sudo apt install penelope

Exécution autonome

Penelope est implémenté entièrement avec la bibliothèque standard de Python, ce qui permet de l'exécuter comme un script autonome sans dépendances externes :

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

pipx

Pour installer la dernière version amont directement depuis GitHub :

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

Pour un chemin de versionnement et plus stable, Penelope est également disponible sur PyPI :

pipx install penelope-shell-handler

Fonctionnalités

Fonctionnalités de session

(*) Peut être manuellement mis à niveau vers PTY avec la commande upgrade

⚠️ Le support Windows est expérimental et en développement actif.

Fonctionnalités globales

• Interaction simplifiée avec les cibles via les modules
• Sessions multiples
• Écouteurs multiples
• Servir des fichiers/dossiers via HTTP (option -s)
• Peut être importé par des exploits python3 et obtenir un shell sur le même terminal (voir extras/exploit_examples)
• Peut fonctionner en conjonction avec les exploits Metasploit en désactivant le gestionnaire par défaut avec set DisablePayloadHandler True
• Exposer des sessions actives à un client MCP comme Claude Code avec l'option --mcp (HTTP local, authentifié par jeton), pilotant les mêmes shells à vos côtés

Modules

Démonstration du module Meterpreter

Utilisation

Exemple d'utilisation typique

penelope                          # Écoute des shells inversés sur 0.0.0.0:4444
penelope -p 5555                  # Écoute des shells inversés sur 0.0.0.0:5555
penelope -p 4444,5555             # Écoute des shells inversés sur 0.0.0.0:4444 et 0.0.0.0:5555
penelope -i eth0 -p 5555          # Écoute des shells inversés sur eth0:5555
penelope -a                       # Écoute des shells inversés sur 0.0.0.0:4444 et affiche des exemples de payloads de shell inversé

penelope -c target -p 3333        # Connexion à un shell bind sur target:3333

penelope ssh user@target          # Obtient un shell inversé depuis target sur le port local 4444
penelope -p 5555 ssh user@target  # Obtient un shell inversé depuis target sur le port local 5555
penelope -i eth0 -p 5555 -- ssh -l user -p 2222 target  # Obtient un shell inversé depuis target sur eth0, port local 5555 (utiliser -- si ssh nécessite des options)

penelope -s <Fichier/Dossier>     # Partage un fichier ou dossier via HTTP

Serveur de fichiers HTTP (-s)

Penelope peut également être utilisé comme un serveur de fichiers HTTP rapide.

penelope -s file.txt                 # Servir un seul fichier sur 0.0.0.0:8000
penelope -s /path/to/dir             # Servir tout un dossier
penelope -s a.sh b.elf notes.txt     # Servir plusieurs éléments à la fois
penelope -s . -p 80                  # Servir le répertoire courant sur le port 80
penelope -s secret.txt -prefix xk9   # Cacher derrière un préfixe d'URL : /xk9/secret.txt
penelope -s -u                       # Mode téléversement : accepter PUT/POST dans le répertoire de travail
penelope -s -u -ud /tmp/loot         # Mode téléversement, stocker les fichiers reçus dans /tmp/loot

Au démarrage, Penelope affiche un lien prêt à l'emploi par interface (et un indice de téléversement quand -u est défini), vous pouvez donc copier-coller directement dans le shell cible.

Démonstration d'utilisation aléatoire

Comme le montre la vidéo ci-dessous, en quelques secondes seulement, nous pouvons :

1. Obtenir un shell PTY entièrement fonctionnel et redimensionnable automatiquement tout en journalisant chaque interaction avec la cible
2. Exécuter la dernière version de LinPEAS sur la cible sans toucher au disque et enregistrer la sortie dans un fichier local en temps réel
3. Ouvrir un autre shell PTY dans un autre onglet
4. Téléverser les dernières versions de LinPEAS et linux-smart-enumeration
5. Téléverser un dossier local contenant des scripts personnalisés
6. Téléverser un exploit depuis exploit-db directement depuis une URL
7. Télécharger et ouvrir un fichier distant localement
8. Télécharger le répertoire /etc distant
9. Générer automatiquement un nouveau shell si un shell existant meurt, aidant à maintenir l'accès pendant les sessions de shell instables

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

Commandes du menu principal

Quelques notes :

• Par défaut, vous devez appuyer sur F12 pour détacher le shell PTY et aller au Menu Principal. Si la mise à niveau n'a pas été possible et que vous avez un shell basique, vous pouvez le détacher avec Ctrl+C. Cela évite également la suppression accidentelle du shell.
• Le Menu Principal prend en charge la complétion par TAB et aussi des commandes courtes. Par exemple, au lieu de interact 1, vous pouvez simplement taper i 1.

Options en ligne de commande

positional arguments:
  args                          Arguments pour les modes -s/--serve et SSH reverse shell

options:
  -p, --ports                   Ports (séparés par des virgules) à écouter/connecter/servir, selon les options -i/-c/-s
                                (Par défaut : 4444/5555/8000)

Shell inversé ou bind ?:
  -i, --interface               Interface/IP locale pour écouter. (Par défaut : 0.0.0.0)
  -c, --connect                 Hôte du shell bind
  -j, --jump                    Points de terminaison de saut de shell inversé

Indices :
  -a, --payloads                Afficher des exemples de payloads de shell inversé pour les écouteurs actifs
  -l, --interfaces              Lister les interfaces réseau disponibles
  -h, --help                    Afficher ce message d'aide et quitter

Journalisation des sessions :
  -L, --no-log                  Désactiver les fichiers de journal de session
  -T, --no-timestamps           Désactiver les horodatages dans les journaux
  -CT, --no-colored-timestamps  Désactiver les horodatages colorés dans les journaux

Divers :
  -M, --menu                    Démarrer dans le Menu Principal
  -m, --maintain                Garder N sessions par cible
  -S, --single-session          N'accepter que la première session créée
  -ms, --max-sessions           Nombre maximal de sessions actives par hôte (par défaut 5, 0 = rejeter toute nouvelle)
  -C, --no-attach               Ne pas s'attacher automatiquement aux nouvelles sessions
  -U, --no-upgrade              Désactiver la mise à niveau automatique du shell
  -H, --keep-history            Conserver l'historique du shell cible (ne pas définir HISTFILE=/dev/null)
  -O, --oscp-safe               Activer le mode OSCP-safe
  --no-disk                     Maintenir tout l'état en RAM (tmpfs) ; rien n'est persistant sur le disque

MCP :
  --mcp                         Activer le serveur MCP via HTTP local
  --mcp-host                    Hôte/IP à lier (par défaut : 127.0.0.1)
  --mcp-port                    Port à lier (par défaut : port sauvegardé, sinon un port libre aléatoire persistant dans ~/.penelope/mcp.json)
  --mcp-token                   Jeton Bearer (par défaut : jeton sauvegardé, sinon auto-généré et persistant)

Serveur de fichiers :
  -s, --serve                   Activer le mode serveur de fichiers HTTP
  -prefix, --url-prefix         Préfixe de chemin d'URL
  -u, --upload                  Activer le téléversement de fichiers (PUT/POST) vers le serveur
  -ud, --upload-dir             Répertoire pour stocker les téléversements (par défaut : répertoire de travail courant)

Débogage :
  -N, --no-bins                 Simuler l'absence de binaires sur la cible (séparés par des virgules)
  -v, --version                 Afficher la version et quitter
  -d, --debug                   Activer la sortie de débogage
  -dd, --dev-mode               Activer le mode développeur
  -cu, --check-urls             Vérifier la santé des URLs codées en dur et quitter

Considérations de sécurité

Penelope est conçu pour fournir une interaction directe et flexible avec des shells distants. Gardez les points suivants à l'esprit lors de son utilisation :

• Séquences d'évasion de terminal : Penelope transmet la sortie du terminal des systèmes distants directement à votre émulateur de terminal. Des processus distants malveillants peuvent utiliser des séquences d'évasion de terminal pour manipuler l'écran, créer des liens trompeurs ou interagir avec des fonctionnalités telles que le presse-papiers. Cette exposition est inhérente à tout outil qui relaie un shell distant au terminal local (comme SSH, telnet, netcat) et n'est pas spécifique à Penelope. Utilisez un terminal avec des paramètres de sécurité appropriés lors de la connexion à des systèmes non fiables.

• Journaux de session : Les journaux de session peuvent contenir des identifiants, des jetons, des commandes et d'autres informations sensibles reçues de la cible. Stockez-les de manière sécurisée et utilisez --no-log lorsque la journalisation n'est pas nécessaire.

• Connexions non chiffrées : Les connexions standard de shell inversé et bind ne sont pas chiffrées. Évitez de les utiliser sur des réseaux non fiables à moins que le trafic ne soit protégé par un tunnel sécurisé ou un VPN.

• Serveur MCP (--mcp): Lorsqu'il est activé, le serveur MCP accorde un contrôle total sur chaque session active (exécution de commandes, transfert de fichiers) à tout client détenant le jeton Bearer, qui est stocké dans ~/.penelope/mcp.json (0600). Il se lie à 127.0.0.1 et est authentifié par jeton. Gardez le jeton secret et évitez d'exposer le serveur sur des réseaux non fiables.

⚖️ Avertissement : Penelope est destiné uniquement aux tests de sécurité autorisés, à la recherche et à des fins éducatives. Ne l'utilisez pas contre des systèmes sans autorisation explicite.

TODO

Fonctionnalités

• chiffrement
• redirection de port distant
• proxy socks et http
• serveur d'équipe
• agents HTTPs et DNS

Problèmes connus

• Journalisation des sessions : les commandes qui utilisent des tampons alternatifs, comme nano, peuvent laisser des séquences d'évasion dans le journal si elles se terminent anormalement. Les données sont toujours préservées, mais la visualisation du fichier journal avec des outils comme cat peut sembler corrompue. Le filtrage de ces séquences d'évasion est prévu pour rendre la sortie du journal plus fluide.

FAQ

► Penelope est-il autorisé dans l'examen OSCP ?

Les fonctionnalités principales de gestion des shells de Penelope n'effectuent pas d'exploitation automatique, ce qui les rend adaptées à une utilisation de style OSCP. Cependant, les règles d'examen peuvent changer, vérifiez donc toujours les règles officielles actuelles d'OffSec avant d'utiliser un outil pendant un examen.

Certains modules nécessitent une prudence supplémentaire :

• Le module meterpreter ne doit être utilisé que d'une manière conforme aux règles d'examen actuelles.
• Le module traitor téléverse Traitor, qui effectue une élévation de privilèges automatique.

Si vous souhaitez éviter les violations accidentelles des règles, utilisez l'option -O / --oscp-safe.

► Comment puis-je revenir du shell distant au Menu Principal ?

Cela dépend du type de mise à niveau du shell utilisé :

• PTY : appuyez sur F12
• Readline : envoyez EOF (Ctrl-D)
• Raw : envoyez SIGINT (Ctrl-C)

Dans tous les cas, la bonne touche est toujours affichée lorsque vous vous attachez à une session. Par exemple :

► Comment puis-je personnaliser Penelope (modifier les options par défaut, créer des modules personnalisés, etc.) ?

Voir peneloperc

► Pourquoi mon répertoire de travail actuel et/ou mon utilisateur ne sont-ils pas respectés lorsque j'utilise des commandes du menu comme download/upload ?

Cela signifie généralement que vous avez ouvert un nouveau shell interactif, éventuellement sous un utilisateur différent. L'agent Penelope ne suit que le répertoire du shell initial et conserve les autorisations de l'utilisateur de ce premier shell. La meilleure solution de contournement est d'utiliser cd /tmp avant d'ouvrir un nouveau shell, ou, si vous avez changé d'utilisateur, de générer un nouveau shell inversé en tant que nouvel utilisateur.

► Comment puis-je contribuer ?

Vos contributions sont inestimables ! Si vous souhaitez aider, veuillez signaler des bogues, des comportements inattendus ou partager de nouvelles idées. Vous pouvez également soumettre des pull requests mais évitez de faire des commits depuis des IDE qui imposent PEP8 et restructurent involontairement l'ensemble du code.

► D'où vient le nom ?

Penelope était l'épouse d'Ulysse et est connue pour sa loyauté et sa patience en attendant son retour. L'outil porte son nom car il a été conçu pour être un gestionnaire de shells fidèle et stable pour des workflows qui vont au-delà d'un simple écouteur.

Remerciements aux premiers contributeurs

• Cristian Grigoriu - @crgr pour m'avoir inspiré à automatiser le processus de mise à niveau PTY. C'est ainsi que ce projet est né.
• Paul Taylor - @bao7uo pour l'idée de supporter les shells bind.
• Longlone - @WAY29 pour avoir indiqué la nécessité de compatibilité avec les versions antérieures de Python (3.6).
• Carlos Polop - @carlospolop pour l'idée de générer des shells sur des écouteurs sur d'autres systèmes.
• @darrenmartyn pour avoir indiqué une méthode alternative pour mettre à niveau le shell vers PTY en utilisant la commande script.
• @bamuwe pour l'idée d'obtenir des shells inversés via SSH.
• @strikoder pour de nombreuses idées d'amélioration.
• @root-tanishq, @robertstrom, @terryf82, @RamadhanAmizudin, @furkan-enes-polatoglu, @DerekFost, @Mag1cByt3s, @nightingalephillip, @grisuno, @thinkslynk, @stavoxnetworks, @thomas-br, @joshoram80, @TheAalCh3m1st, @r3pek, @bamuwe, @six-two, @x9xhack, , , , , pour le signalement de bogues.