koi 🎏

Questo progetto è il mio tentativo di realizzare un shell handler veloce e facile da usare (ma ricco di funzionalità) con un'interfaccia gradevole.

Disclaimer: tieni presente che è ancora in fase di sviluppo e sto ancora lavorando ad alcune delle funzionalità chiave, discusse in questa sezione.

📑 Indice

La documentazione completa è disponibile nella wiki.

Demo

[!TIP] Questa demo viene eseguita con un OS dockerizzato. Se vuoi provarla tu stesso, puoi usare le immagini Ubuntu o il windows di dockur

✨ Funzionalità

Multi-sessione: gestisci più reverse shell contemporaneamente. Elenca, cambia e manda in background le sessioni senza perderne nessuna.
Aggiornamento PTY: aggiorna una shell grezza a un PTY completo (Linux tramite script/socat, Windows tramite ConPtyShell offuscato) per il completamento con tab, l'inoltro di Ctrl+C e il ridimensionamento del terminale.
Moduli: automatizza attività di post-exploitation, trasferimento file, enumerazione, pivoting, raccolta AD e altro. Facilmente estendibile con i tuoi moduli.
Obfuscator: offuscatore di payload integrato con tecniche concatenabili (XOR, hex, format string, char-array) per eludere Defender e le soluzioni EDR.
Connessione in uscita: connect ssh user@host trasforma credenziali che già possiedi in una sessione. ssh consegna solo il payload, così la shell continua a vivere dopo l'uscita di ssh.
Tunneling: tunnel start <id> <cidr> trasforma una shell in un pivot di Livello 3: uno stack TCP in userland sul target (niente root, nessun binario depositato, solo Python) con le rotte dalla tua parte. (docs)
Logging delle sessioni: ogni sessione viene registrata automaticamente. Riproduci qualsiasi sessione con koireview. (docs)
Server MCP: esponi le tue sessioni e i tuoi moduli a un client LLM, in sola lettura per impostazione predefinita, incluso nel core. (docs)
Modalità screenable: maschera IP e indirizzi MAC dall'output per una condivisione schermo sicura durante CTF o demo dal vivo.
Segnali puliti: Ctrl+Z manda la sessione in background, Ctrl+C invia SIGINT al remoto, senza mai uccidere il tuo listener per errore.

[!NOTE] Ora è possibile usare Koi da remoto ! Leggi di più qui

🚧 WIP

Evasione EDR: Koi aggira le soluzioni EDR di livello base e intermedio, ma ambienti più aggressivi (EDR commerciali costosi, reti fortemente monitorate) potrebbero comunque rilevare l'attività. Sono in valutazione ulteriori miglioramenti (trasporto TLS, C2 HTTP).

🚀 Installazione

# Recommended: stable release from PyPI
pipx install koi-handler

# From source if you want to dev your own modules
git clone https://github.com/b3rt1ng/koi
cd koi
pipx install --editable .

koifuscator è la scorciatoia diretta al modulo offuscatore.

koireview è il tuo modo per visualizzare i log delle tue sessioni.

Per aggiornare:

pipx upgrade koi-handler

Maggiori dettagli in Getting Started.

💻 Utilizzo

Avvia il listener

# Default: bind 0.0.0.0:4010
koi

# Custom host/port
koi --host 10.10.14.5 --port 9001
koi -p 9001

Una volta dentro, help elenca tutti i comandi. Il riferimento completo è nella CLI Reference, e la gestione delle sessioni (tag, backgrounding, modalità screenable) in Session Management.

Catturare una shell

Invia una reverse shell manualmente oppure digitando payloads *interface* per ottenere payload pregenerati. Tieni presente che deve trattarsi di una shell di tipo terminale, poiché Koi manipola sh di Linux, powershell e cmd.

Bypassare Windows Defender

Koi include un offuscatore di payload integrato per aiutare a eludere il rilevamento di Windows Defender. Puoi concatenare più tecniche insieme, anche se la codifica XOR e le trasformazioni di formato sono di solito sufficienti. Tieni presente che impilare troppi livelli può corrompere il payload e renderlo illeggibile per il target.

L'offuscatore funziona anche per i payload Linux. Sebbene la maggior parte degli ambienti Linux non esegua software antivirus, i one-liner bash vengono comunemente segnalati dalle soluzioni EDR, dalle regole IDS o monitorati dai blue team che cercano pattern di reverse shell noti. Offuscare il payload aiuta a passare inosservati in alcuni ambienti rafforzati.

Ogni tecnica e ogni tipo di payload supportato è elencato in Payloads & Obfuscation.

🔧 Aggiornamento PTY

Le shell grezze mancano di un supporto adeguato al terminale: nessun completamento con tab, Ctrl+C non funzionante, output corrotto. Il comando upgrade risolve questo problema:

koi> upgrade 1
  Shell #1 upgraded successfully.
koi> go 1
  # now a full PTY with proper terminal behaviour

Dietro le quinte

Per Linux:

viene generato un semplice pty Python

python3 -c 'import pty; pty.spawn("/bin/bash")'

con TERM=xterm-256color e alcune informazioni di ridimensionamento

Per Windows:

Non mi sono preoccupato di crearne uno per CMD, ma per PowerShell la tecnica utilizza una versione offuscata di conptyshell per ottenere una shell completamente implementata:

1) ConPtyShell is fetched from GitHub and cached locally for offline reuse
2) All IOC identifiers are renamed to random strings (class names, method names, PS function name)
3) Distinctive C# string literals are replaced with runtime char-array constructions (no literal in compiled MSIL)
4) The obfuscated script is served over a temporary HTTP server
5) The invocation command is base64-encoded (-EncodedCommand) with IEX and IWR obfuscated via random split techniques (concat / format string / char-array), so no plaintext cmdlet names appear on the command line
6) The target connects back with a fully interactive PTY shell, registered as a new session

Catena di fallback e dettagli per sistema operativo in Upgrading Sessions.

🧠 MCP

Koi può esporre le sue sessioni e i suoi moduli tramite MCP, così un client LLM può leggere la tua tabella delle sessioni e pilotare i moduli senza che tu debba copiare e incollare nulla.

# read-only: sessions, modules and logs
koi --mcp

Koi

Più Popolari