[Name]
koi

[Version]
0.10.3 (released 2026-08-01)

[Homepage]
https://github.com/b3rt1ng/Koi

[Documentation]
https://b3rt1ng.github.io/koi-wiki/

[Download]
https://github.com/b3rt1ng/Koi/releases/tag/v0.10.3
Tarball: https://github.com/b3rt1ng/Koi/archive/refs/tags/v0.10.3.tar.gz
Releases are tagged as vX.Y.Z. Also published on PyPI as "koi-handler":
https://pypi.org/project/koi-handler/

[Author]
b3rt1ng

[License]
GPL-3.0-or-later (full text in LICENSE)

[Description]
koi is a reverse shell listener built around handling several shells at once
rather than one at a time. It listens on a single port, registers every
incoming shell as a session, and lets the operator tag, list, background and
switch between them without dropping any. It also has an embedded payload obfuscator,
makes modules easy to implement with a ready to use syntax, while being optimized for local
and remote testings.

Main features:

• Multi-session handling with tags, autocompletion and clean signal routing
  (Ctrl+Z backgrounds a session, Ctrl+C is forwarded to the remote instead of
  killing the listener).
• PTY upgrade: raw shells are upgraded to a full PTY or PTY-like while being
  hidden from static based AV.
• Post-exploitation modules, written in Python and reloadable at runtime:
  file transfer (upload/download), enumeration (sysinfo, network, users,
  processes, wifi, env), credential dumping, AD collection (SharpHound),
  privilege escalation checks (PEAS, Windows escalation checker), pivoting
  (Ligolo agent deployment), and session duplication / redirection.
• Payload obfuscator with chainable techniques (XOR, hex, format strings,
  char arrays), exposed both inside the handler and as a standalone
  "koifuscator" command.
• Session logging: every session is recorded and replayable with "koireview".
• Screenable mode, masking IPs and MAC addresses in output for demos, CTFs
  and screenshots.
• Optional MCP server exposing sessions, modules and logs to an MCP client,
  read-only by default.

[Dependencies]
Python 3.10 or newer. The core has no third-party dependencies and is from standard
library only.

MCP support is an optional extra and is not required to run the tool. Its
dependencies (mcp >= 2.0, uvicorn >= 0.30, starlette >= 0.40) are already
packaged in Debian as python3-mcp, python3-uvicorn and python3-starlette, so
they could be a Suggests/Recommends rather than a hard dependency.

Some modules fetch third-party tooling (SharpHound, PEAS, Ligolo) at runtime
and cache it locally for offline reuse. Nothing third-party is vendored in
the source tree.

[Similar tools already in Kali]
The closest existing package is villain, described as a high level C2
framework. koi is deliberately narrower: it is a shell handler, not a C2. It
does not generate implants, does not run a team server, and does not manage
its own beacon protocol. It accepts plain reverse shells from whatever
payload the operator chose, and focuses on what happens after the shell lands.
Operators wanting a C2 will still want villain or sliver; koi targets the very
common case where you already have a callback and want to work with several
of them comfortably.

pwncat and powercat are netcat replacements and do not handle
sessions, PTY upgrades or post-exploitation. hoaxshell is a Windows-only HTTP
reverse shell payload generator and handler with a much narrower scope.
sliver is an implant-based C2 in a different category entirely.

Features I have not found combined in the existing packages: session recording
with a dedicated replay command, an IP/MAC masking mode for safe screen
sharing, a standalone chainable payload obfuscator sharing the handler's
codebase, and the MCP server.

[Project activity]
First commit 2026-03-13, 125 commits and 63 published versions since, latest
release 2026-08-01. Development has been continuous over the last five months.
Documentation is maintained in a separate wiki.

[Installation]
Standard PEP 517 project (setuptools backend, src layout, pyproject.toml).
No compilation step.

pipx install koi-handler

or

pip install koi-handler

It installs three entry points: koi, koifuscator and koireview.

For packaging, it builds with pybuild without any special handling:

export PYBUILD_NAME = koi
%:
dh $@ --with python3 --buildsystem=pybuild

Full command reference: https://b3rt1ng.github.io/koi-wiki/cli-reference/

[Debian packaging status]
Not currently packaged for Debian, and there is no debian/ directory upstream.
I am happy to provide one or to help with packaging if that is useful.