koi 🎏

这个项目是我尝试打造的一个快速、易用（且功能丰富）的 shell 处理器，并配有美观的界面。

免责声明：请注意，本项目仍在开发中，我仍在完善一些关键功能，详见本节。

📑 目录

✨ 功能 | 🚧 开发中 | 🚀 安装 | 💻 使用 | 🔧 PTY 升级 | 🤖 模块 | 🧠 MCP

完整文档位于 wiki。

---

演示

[!TIP] 此演示运行在 docker 化的操作系统中。如果你想自己尝试，可以使用 Ubuntu 镜像 或 dockur windows

---

✨ 功能

• 多会话：同时处理多个反向 shell。列出、切换和后台化会话，而不会丢失任何一个。
• PTY 升级：将原始 shell 升级为完整的 PTY（Linux 通过 script/socat，Windows 通过混淆的 ConPtyShell），以支持 Tab 补全、Ctrl+C 转发和终端调整大小。
• 模块：自动化后渗透任务、文件传输、枚举、横向移动、AD 信息收集等。可轻松使用你自己的模块进行扩展。
• 混淆器：内置 payload 混淆器，支持可链式组合的技术（XOR、hex、格式字符串、字符数组），以规避 Defender 和 EDR 解决方案。
• 主动连接：connect ssh user@host 可将你已拥有的凭据转换为一个会话。ssh 仅负责投递 payload，因此 ssh 退出后 shell 仍会继续存活。
• 隧道：tunnel start <id> <cidr> 可将一个 shell 转换为三层（Layer 3）跳板：在目标上运行用户态 TCP 栈（无需 root、无需落地二进制文件，仅需 Python），路由则在你这一侧。(文档)
• 会话日志：每个会话都会自动记录。可使用 koireview 回放任意会话。(文档)
• MCP 服务器：将你的会话和模块暴露给 LLM 客户端，默认只读，随核心一起提供。(文档)
• 可屏幕共享模式：从输出中屏蔽 IP 和 MAC 地址，以便在 CTF 或现场演示期间安全地共享屏幕。
• 干净的信号处理：Ctrl+Z 将会话置于后台，Ctrl+C 向远端发送 SIGINT，绝不会意外终止你的监听器。

[!NOTE] 现在可以远程使用 Koi 了！ 阅读更多此处

🚧 开发中

• EDR 规避：Koi 可绕过普通及中等级别的 EDR 解决方案，但更激进的环境（昂贵的商业 EDR、受到严密监控的网络）仍可能标记其活动。进一步的改进（TLS 传输、HTTP C2）正在考虑中。

---

🚀 安装

# 推荐：从 PyPI 安装稳定版本
pipx install koi-handler

# 从源码安装，如果你想开发自己的模块
git clone https://github.com/b3rt1ng/koi
cd koi
pipx install --editable .

koifuscator 是直接进入混淆器模块的快捷方式。

koireview 是你查看会话日志的方式。

升级：

pipx upgrade koi-handler

更多细节见入门指南。

---

💻 使用

启动监听器

# 默认：绑定 0.0.0.0:4010
koi

# 自定义主机/端口
koi --host 10.10.14.5 --port 9001
koi -p 9001

进入后，help 会列出所有命令。完整参考见 CLI 参考，会话处理（标签、后台化、可屏幕共享模式）见会话管理。

接收一个 shell

你可以自行发送反向 shell，或输入 payloads *interface* 获取预生成的 payload。请注意，它需要是一个类似终端的 shell，因为 Koi 会操作 linux sh、powershell 和 cmd。

绕过 Windows Defender

Koi 包含一个内置的 payload 混淆器，以帮助规避 Windows Defender 检测。你可以将多种技术链式组合，不过 XOR 编码和格式变换通常已经足够。请记住，堆叠过多层可能会损坏 payload，使其无法被目标读取。

混淆器同样适用于 Linux payload。虽然大多数 Linux 环境不运行杀毒软件，但 bash 单行命令通常会被 EDR 解决方案、IDS 规则标记，或被蓝队监控以发现已知的反向 shell 模式。混淆你的 payload 有助于在某些加固环境中避开雷达。

每种技术及每种受支持的 payload 类型都列在 Payload 与混淆 中。

---

🔧 PTY 升级

原始 shell 缺乏适当的终端支持：没有 Tab 补全、Ctrl+C 失效、输出混乱。upgrade 命令可解决此问题：

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

底层原理

对于 linux：

会生成一个简单的 python pty

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

并设置 TERM=xterm-256color 以及一些调整大小的信息

对于 windows：

我没有费心为 CMD 制作一个，但对于 powershell，该技术使用一个混淆的 conptyshell 来获得一个完整实现的 shell：

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

回退链及按操作系统划分的细节见升级会话。

---

🧠 MCP

Koi 可以通过 MCP 暴露其会话和模块，这样 LLM 客户端就能读取你的会话表并驱动模块，而无需你复制粘贴任何内容。

# 只读：会话、模块和日志
koi --mcp

# 允许模型在目标上运行命令和模块
koi --mcp --mcp-allow-exec

该服务器运行在监听器进程中，绑定 127.0.0.1:7331，由启动时打印的 bearer token 保护。默认只读是刻意为之。

[!WARNING] 使用 --mcp-allow-exec 时，LLM 可以在你持有 shell 的每台机器上运行命令。会话日志包含来自被攻陷主机的输出，这些是攻击者控制的文本，会直接进入模型上下文。

设置、客户端配置及完整工具列表见 MCP 文档。

---

🤖 模块

模块基本上是一种在你的实例上自动化操作的方式。你可以运行命令并利用你的 python 后端。

如果你想制作自己的模块，我建议克隆此仓库并使用 --editable 标志安装。一旦你有了一个 shell，你就可以开发你的 payload，并使用 reload 命令更新所有模块，包括你正在开发的那个。

查看 wiki 中的模块开发指南以获取完整的 API 参考，或浏览现有模块（ligolo、get_users）以获取灵感。

另外，如果你想让你自己的模块成为此仓库的一部分，请不要犹豫，提交一个 PR，我会很乐意查看它，看看是否有兴趣添加到这里 <3