penelope

Penelope è un moderno gestore di shell per penetration tester e giocatori di CTF. Offre un'alternativa più potente ai semplici listener netcat, aggiungendo aggiornamenti automatici PTY, gestione delle sessioni, logging, trasferimento di file e moduli helper.

Sommario

• 📥 Installazione
• ⚙️ Funzionalità
  • 🖥️ Funzionalità di sessione
  • 🌍 Funzionalità globali
  • 🧩 Moduli
• 💻 Utilizzo
  • ▶️ Esempio di utilizzo tipico
  • 🎬 Dimostrazione di utilizzo casuale
  • 🖲️ Comandi del menu principale
  • ⚡ Opzioni da riga di comando
• 🔒 Considerazioni sulla sicurezza
• 📝 TODO
• ❓ FAQ
• 🙌 Ringraziamenti ai primi sostenitori

Installazione

Penelope funziona su sistemi Unix-like, inclusi Linux, macOS e FreeBSD, e richiede Python 3.6+.

Kali Linux

Penelope è disponibile in Kali Linux:

sudo apt update
sudo apt install penelope

Esecuzione standalone

Penelope è implementato interamente con la libreria standard di Python, permettendo di essere eseguito come script standalone senza dipendenze esterne:

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

pipx

Per installare l'ultima versione upstream direttamente da GitHub:

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

Per un percorso di rilascio versionato e più stabile, Penelope è disponibile anche su PyPI:

pipx install penelope-shell-handler

Funzionalità

Funzionalità di sessione

(*) Può essere aggiornato manualmente a PTY con il comando upgrade

⚠️ Il supporto per Windows è sperimentale e in fase di sviluppo attivo.

Funzionalità globali

• Interazione semplificata con i target tramite moduli
• Sessioni multiple
• Listener multipli
• Servire file/cartelle tramite HTTP (opzione -s)
• Può essere importato da exploit python3 e ottenere una shell sullo stesso terminale (vedi extras/exploit_examples)
• Può funzionare in combinazione con exploit Metasploit disabilitando il gestore predefinito con set DisablePayloadHandler True
• Esporre sessioni live a un client MCP come Claude Code con l'opzione --mcp (HTTP locale, autenticazione tramite token), pilotando le stesse shell insieme a te

Moduli

Dimostrazione del modulo Meterpreter

Utilizzo

Esempio di utilizzo tipico

penelope                          # In ascolto per shell reverse su 0.0.0.0:4444
penelope -p 5555                  # In ascolto per shell reverse su 0.0.0.0:5555
penelope -p 4444,5555             # In ascolto per shell reverse su 0.0.0.0:4444 e 0.0.0.0:5555
penelope -i eth0 -p 5555          # In ascolto per shell reverse su eth0:5555
penelope -a                       # In ascolto per shell reverse su 0.0.0.0:4444 e mostra payload di shell reverse di esempio

penelope -c target -p 3333        # Connessione a una bind shell su target:3333

penelope ssh user@target          # Ottieni una shell reverse dal target sulla porta locale 4444
penelope -p 5555 ssh user@target  # Ottieni una shell reverse dal target sulla porta locale 5555
penelope -i eth0 -p 5555 -- ssh -l user -p 2222 target  # Ottieni una shell reverse dal target su eth0, porta locale 5555 (usa -- se ssh necessita di opzioni)

penelope -s <File/Cartella>       # Condividi un file o una cartella tramite HTTP

Server HTTP file (-s)

Penelope può essere utilizzato anche come server HTTP rapido per file.

penelope -s file.txt                 # Servi un singolo file su 0.0.0.0:8000
penelope -s /path/to/dir             # Servi un'intera cartella
penelope -s a.sh b.elf notes.txt     # Servi più elementi contemporaneamente
penelope -s . -p 80                  # Servi la directory corrente sulla porta 80
penelope -s secret.txt -prefix xk9   # Nascondi dietro un prefisso URL: /xk9/secret.txt
penelope -s -u                       # Modalità upload: accetta PUT/POST nella directory corrente
penelope -s -u -ud /tmp/loot         # Modalità upload, salva i file ricevuti in /tmp/loot

All'avvio, Penelope stampa un link pronto all'uso per ogni interfaccia (e un suggerimento per l'upload quando è impostata -u), così puoi copiarlo e incollarlo direttamente nella shell del target.

Dimostrazione di utilizzo casuale

Come mostrato nel video qui sotto, in pochi secondi possiamo:

1. Ottenere una shell PTY completamente funzionale e auto-ridimensionabile mentre registriamo ogni interazione con il target
2. Eseguire l'ultima versione di LinPEAS sul target senza toccare il disco e salvare l'output in un file locale in tempo reale
3. Aprire un'altra shell PTY in un altro tab
4. Caricare le ultime versioni di LinPEAS e linux-smart-enumeration
5. Caricare una cartella locale con script personalizzati
6. Caricare un exploit da exploit-db direttamente da URL
7. Scaricare e aprire un file remoto localmente
8. Scaricare la directory remota /etc
9. Avviare automaticamente una nuova shell se una shell esistente muore, aiutando a mantenere l'accesso disponibile durante sessioni di shell instabili

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

Comandi del menu principale

Alcune note:

• Per impostazione predefinita è necessario premere F12 per staccare la shell PTY e andare al Menu Principale. Se l'aggiornamento non è stato possibile e hai una shell base, puoi staccarla con Ctrl+C. Questo impedisce anche l'uccisione accidentale della shell.
• Il Menu Principale supporta il completamento TAB e anche comandi brevi. Ad esempio, invece di interact 1 puoi semplicemente digitare i 1.

Opzioni da riga di comando

positional arguments:
  args                          Argomenti per -s/--serve e modalità shell reverse SSH

options:
  -p, --ports                   Porte (separate da virgola) su cui ascoltare/connettersi/servire, a seconda delle opzioni -i/-c/-s
                                (Default: 4444/5555/8000)

Reverse o Bind shell?:
  -i, --interface               Interfaccia/IP locale su cui ascoltare. (Default: 0.0.0.0)
  -c, --connect                 Host della bind shell
  -j, --jump                    Endpoint di salto per shell reverse

Suggerimenti:
  -a, --payloads                Mostra payload di shell reverse di esempio per i Listener attivi
  -l, --interfaces              Elenca le interfacce di rete disponibili
  -h, --help                    mostra questo messaggio di aiuto ed esci

Logging delle sessioni:
  -L, --no-log                  Disabilita i file di log delle sessioni
  -T, --no-timestamps           Disabilita i timestamp nei log
  -CT, --no-colored-timestamps  Disabilita i timestamp colorati nei log

Varie:
  -M, --menu                    Avvia nel Menu Principale
  -m, --maintain                Mantieni N sessioni per target
  -S, --single-session          Accetta solo la prima sessione creata
  -ms, --max-sessions           Numero massimo di sessioni attive per host (default 5, 0 = rifiuta tutte le nuove)
  -C, --no-attach               Non agganciare automaticamente alle nuove sessioni
  -U, --no-upgrade              Disabilita l'aggiornamento automatico della shell
  -H, --keep-history            Mantieni la cronologia della shell del target (non impostare HISTFILE=/dev/null)
  -O, --oscp-safe               Abilita la modalità OSCP-safe
  --no-disk                     Mantieni tutto lo stato in RAM (tmpfs); nulla persiste su disco

MCP:
  --mcp                         Abilita il server MCP su HTTP locale
  --mcp-host                    Host/IP su cui associarsi (default: 127.0.0.1)
  --mcp-port                    Porta su cui associarsi (default: porta salvata, altrimenti una porta libera casuale persistente in ~/.penelope/mcp.json)
  --mcp-token                   Token Bearer (default: token salvato, altrimenti generato automaticamente e persistente)

File server:
  -s, --serve                   Avvia la modalità server HTTP file
  -prefix, --url-prefix         Prefisso del percorso URL
  -u, --upload                  Abilita l'upload di file (PUT/POST) al server
  -ud, --upload-dir             Directory in cui salvare gli upload (default: directory corrente)

Debug:
  -N, --no-bins                 Simula binari mancanti sul target (separati da virgola)
  -v, --version                 Stampa la versione ed esci
  -d, --debug                   Abilita output di debug
  -dd, --dev-mode               Abilita la modalità sviluppatore
  -cu, --check-urls             Controlla la salute degli URL hardcodati ed esci

Considerazioni sulla sicurezza

Penelope è progettato per fornire un'interazione diretta e flessibile con shell remote. Tieni presente quanto segue quando lo usi:

• Sequenze di escape del terminale: Penelope inoltra l'output del terminale dai sistemi remoti direttamente al tuo emulatore di terminale. Processi remoti malevoli possono utilizzare sequenze di escape del terminale per manipolare lo schermo, creare link fuorvianti o interagire con funzionalità come gli appunti. Questa esposizione è intrinseca a qualsiasi strumento che inoltra una shell remota al terminale locale (come SSH, telnet, netcat) e non è specifica di Penelope. Utilizza un terminale con impostazioni di sicurezza appropriate quando ti connetti a sistemi non fidati.

• Log delle sessioni: I log delle sessioni possono contenere credenziali, token, comandi e altre informazioni sensibili ricevute dal target. Conservali in modo sicuro e utilizza --no-log quando la registrazione non è necessaria.

• Connessioni non crittografate: Le connessioni standard di shell reverse e bind non sono crittografate. Evita di usarle su reti non fidate a meno che il traffico non sia protetto da un tunnel sicuro o VPN.

• Server MCP (--mcp): Quando abilitato, il server MCP concede il controllo completo su ogni sessione attiva (esecuzione di comandi, trasferimento file) a qualsiasi client che possieda il bearer token, che è memorizzato in ~/.penelope/mcp.json (0600). Si associa a 127.0.0.1 ed è autenticato tramite token. Mantieni segreto il token ed evita di esporre il server su reti non fidate.

⚖️ Dichiarazione di non responsabilità: Penelope è destinato esclusivamente a test di sicurezza autorizzati, ricerca e scopi educativi. Non utilizzarlo contro sistemi senza esplicita autorizzazione.

TODO

Funzionalità

• crittografia
• inoltro porte remoto
• proxy socks e http
• team server
• agenti HTTPs e DNS

Problemi noti

• Log delle sessioni: i comandi che utilizzano buffer alternativi, come nano, possono lasciare sequenze di escape nel log se terminano in modo anomalo. I dati sono comunque preservati, ma la visualizzazione del file di log con strumenti come cat potrebbe apparire corrotta. È previsto il filtraggio di queste sequenze di escape per rendere l'output del log più pulito.

FAQ

► Penelope è consentito nell'esame OSCP?

Le funzionalità principali di gestione della shell di Penelope non eseguono sfruttamento automatico, il che le rende adatte per un uso in stile OSCP. Tuttavia, le regole d'esame possono cambiare, quindi verifica sempre le regole ufficiali attuali di OffSec prima di utilizzare qualsiasi strumento durante un esame.

Alcuni moduli richiedono cautela extra:

• Il modulo meterpreter dovrebbe essere usato solo in modo conforme alle regole attuali dell'esame.
• Il modulo traitor carica Traitor, che esegue escalation automatica dei privilegi.

Se vuoi evitare violazioni accidentali delle regole, usa l'opzione -O / --oscp-safe.

► Come posso tornare dalla shell remota al Menu Principale?

Dipende dal tipo di aggiornamento della shell in uso:

• PTY: premi F12
• Readline: invia EOF (Ctrl-D)
• Raw: invia SIGINT (Ctrl-C)

In ogni caso, il tasto corretto viene sempre visualizzato quando ti agganci a una sessione. Per esempio:

► Come posso personalizzare Penelope (cambiare opzioni predefinite, creare moduli personalizzati, ecc.)?

Vedi peneloperc

► Perché la directory di lavoro corrente e/o l'utente non vengono rispettati quando uso comandi del menu come download/upload?

Di solito significa che hai aperto una nuova shell interattiva, possibilmente con un utente diverso. L'agente di Penelope tiene traccia solo della directory della shell iniziale e mantiene i permessi dell'utente di quella prima shell. La soluzione migliore è eseguire cd /tmp prima di aprire una nuova shell, o, se hai cambiato utente, generare una nuova shell reverse come nuovo utente.

► Come posso contribuire?

I tuoi contributi sono preziosi! Se desideri aiutare, segnala bug, comportamenti imprevisti o condividi nuove idee. Puoi anche inviare pull request, ma evita di fare commit da IDE che impongono PEP8 e ristrutturano involontariamente l'intero codice.

► Da dove viene il nome?

Penelope era la moglie di Ulisse ed è nota per la sua lealtà e pazienza mentre aspettava il suo ritorno. Lo strumento prende il nome da lei perché è stato costruito per essere un gestore di shell fedele e stabile per flussi di lavoro che vanno oltre un semplice listener.

Ringraziamenti ai primi sostenitori

• Cristian Grigoriu - @crgr per avermi ispirato ad automatizzare il processo di aggiornamento PTY. È così che è nato questo progetto.
• Paul Taylor - @bao7uo per l'idea di supportare le bind shell.
• Longlone - @WAY29 per aver segnalato la necessità di compatibilità con versioni precedenti di Python (3.6).
• Carlos Polop - @carlospolop per l'idea di generare shell su listener su altri sistemi.
• @darrenmartyn per aver indicato un metodo alternativo per aggiornare la shell a PTY usando il comando script.
• @bamuwe per l'idea di ottenere shell reverse tramite SSH.
• @strikoder per numerose idee di miglioramento.
• @root-tanishq, @robertstrom, @terryf82, @RamadhanAmizudin, @furkan-enes-polatoglu, @DerekFost, @Mag1cByt3s, @nightingalephillip, @grisuno, @thinkslynk, @stavoxnetworks, @thomas-br, @joshoram80, @TheAalCh3m1st, @r3pek, @bamuwe, @six-two, @x9xhack, @dummys, , , , per la segnalazione di bug.