koi 🎏

Ce projet est ma tentative de créer un handler de shell rapide, facile à utiliser (et pourtant riche en fonctionnalités) avec une jolie interface.

Avertissement : veuillez noter que ce projet est encore en développement, et je travaille encore sur certaines fonctionnalités clés, abordées dans cette section.

📑 Table des matières

La documentation complète se trouve dans le wiki.

Démo

[!TIP] Cette démo fonctionne avec un OS dockerisé. Si vous voulez essayer vous-même, vous pouvez utiliser les images Ubuntu ou les dockur windows

✨ Fonctionnalités

Multi-session : gérez plusieurs reverse shells simultanément. Listez, basculez et mettez en arrière-plan des sessions sans en perdre aucune.
Mise à niveau PTY : transformez un shell brut en un PTY complet (Linux via script/socat, Windows via ConPtyShell obfusqué) pour la complétion par tabulation, la redirection de Ctrl+C et le redimensionnement du terminal.
Modules : automatisez les tâches de post-exploitation, le transfert de fichiers, l'énumération, le pivoting, la collecte AD, et plus encore. Facilement extensible avec vos propres modules.
Obfuscateur : obfuscateur de payload intégré avec des techniques chaînables (XOR, hex, format strings, char-array) pour échapper à Defender et aux solutions EDR.
Connexion sortante : connect ssh user@host transforme des identifiants que vous possédez déjà en une session. ssh ne fait que livrer le payload, donc le shell continue de vivre après la sortie de ssh.
Tunneling : tunnel start <id> <cidr> transforme un shell en pivot de couche 3 : une pile TCP en espace utilisateur sur la cible (pas de root, pas de binaire déposé, Python uniquement) avec les routes de votre côté. (docs)
Journalisation des sessions : chaque session est journalisée automatiquement. Rejouez n'importe quelle session avec koireview. (docs)
Serveur MCP : exposez vos sessions et modules à un client LLM, en lecture seule par défaut, livré avec le cœur. (docs)
Mode screenable : masque les IPs et les adresses MAC de la sortie pour un partage d'écran sûr pendant les CTFs ou les démos en direct.
Signaux propres : Ctrl+Z met la session en arrière-plan, Ctrl+C envoie SIGINT à la cible distante, ne tue jamais votre listener par accident.

[!NOTE] Il est désormais possible d'utiliser Koi à distance ! En savoir plus ici

🚧 WIP

Évasion EDR : Koi contourne les solutions EDR occasionnelles et de milieu de gamme, mais les environnements plus agressifs (EDR commerciaux coûteux, réseaux fortement surveillés) peuvent encore signaler l'activité. D'autres améliorations (transport TLS, C2 HTTP) sont à l'étude.

🚀 Installation

# 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 est le raccourci direct vers le module d'obfuscation.

koireview est votre moyen de consulter les logs de vos sessions.

Pour mettre à niveau :

pipx upgrade koi-handler

Plus de détails dans Getting Started.

💻 Utilisation

Démarrer le listener

# Default: bind 0.0.0.0:4010
koi

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

Une fois à l'intérieur, help liste toutes les commandes. La référence complète se trouve dans la CLI Reference, et la gestion des sessions (tags, mise en arrière-plan, mode screenable) dans Session Management.

Capter un shell

Envoyez un reverse shell vous-même ou en tapant payloads *interface* pour obtenir des payloads pré-générés. Notez qu'il doit s'agir d'un shell de type terminal, car Koi manipule les shs linux, les powershells et cmd.

Contourner Windows Defender

Koi inclut un obfuscateur de payload intégré pour aider à échapper à la détection de Windows Defender. Vous pouvez chaîner plusieurs techniques, bien que l'encodage XOR et les transformations de format soient généralement suffisants. Gardez à l'esprit qu'empiler trop de couches peut corrompre le payload et le rendre illisible par la cible.

L'obfuscateur fonctionne aussi pour les payloads Linux. Bien que la plupart des environnements Linux n'exécutent pas d'antivirus, les one-liners bash sont couramment signalés par les solutions EDR, les règles IDS, ou surveillés par les blue teams guettant les motifs de reverse shell connus. Obfusquer votre payload aide à passer sous le radar dans certains environnements durcis.

Chaque technique et chaque type de payload pris en charge est listé dans Payloads & Obfuscation.

🔧 Mise à niveau PTY

Les shells bruts manquent de support terminal adéquat : pas de complétion par tabulation, Ctrl+C cassé, sortie altérée. La commande upgrade corrige cela :

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

Sous le capot

Pour linux :

un simple pty python est lancé

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

avec TERM=xterm-256color et quelques informations de redimensionnement

Pour windows :

Je ne me suis pas embêté à en faire un pour CMD, mais pour powershell la technique utilise un conptyshell obfusqué pour obtenir un shell entièrement implémenté :

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

La chaîne de repli et les détails par OS dans Upgrading Sessions.

Koi

Populaires