CnaEmulator - محاكي سكربتات Cobalt Strike Aggressor وبيئة اختبار وهمية

CnaEmulator هو أداة تطوير ومحاكاة واختبار مستقلة وعامة الغرض لسكربتات Cobalt Strike Aggressor (.cna). يتيح لباحثي الأمن ومطوري الأدوات ومؤلفي BOF التحقق من صحة صياغة السكربت، ومحاكاة أوامر alias في وحدة تحكم Beacon، وتنفيذ ملفات كائنات Beacon في الذاكرة (BOFs) مباشرةً عبر COFFLoader64.exe دون تشغيل teamserver أو عميل بواجهة رسومية.

---

[!WARNING] إخلاء المسؤولية: تم توليد هذا الكود بالكامل باستخدام Antigravity ولم تتم مراجعته بعد.

القدرات

1. التحقق من الصياغة (check):
   • يترجم سكربتات .cna باستخدام محرك Sleep 2.1 الأساسي.
   • يكتشف بدقة السلاسل النصية غير المغلقة، والأحرف غير المُهرَّبة، وأخطاء صياغة المحلل اللغوي، والمحددات المفقودة مع أرقام الأسطر الدقيقة في الملف.
2. محاكاة دوال Aggressor:
   • يحاكي دوال Cobalt Strike Beacon الرسمية من وثائق HelpSystems/Fortra Aggressor Script.
   • يوفر قيمًا وهمية واقعية أو قيم إرجاع موجبة غير خاطئة لواجهات برمجة التطبيقات الخاصة بحقن العمليات، والتلاعب بالرموز، ونظام الملفات، والشبكة، واستدعاءات GUI.
3. تجميع BOF الثنائي الحقيقي (bof_pack):
   • يطبق تسلسل Little-Endian الأصلي المطابق لتنسيق datap الثنائي في Cobalt Strike:
     • 'i': عدد صحيح 4 بايت
     • 's': عدد قصير 2 بايت
     • 'z': سلسلة منتهية بـ null مسبوقة بالطول (بادئة strlen + 1)
     • 'Z': سلسلة UTF-16LE عريضة مسبوقة بالطول
     • 'b': مخزن ثنائي مسبوق بالطول
4. جسر تنفيذ COFFLoader (beacon_inline_execute):
   • يعترض تلقائيًا beacon_inline_execute($bid, $bof_data, "go", $packed_args).
   • يحوّل الوسائط المجمّعة إلى صيغة hex.
   • ينفذ COFFLoader64.exe go <bof_path> <hex_args> كعملية فرعية تابعة.
   • يبث مخرجات وحدة تحكم BOF الحية مباشرةً إلى stdout في الوقت الفعلي.
5. أجنحة اختبار مرافقة شاملة وتحقق آلي (test):
   • يكتشف وينفذ تلقائيًا أجنحة سيناريوهات <script>.cna.tests أو <script>.tests المرافقة.
   • يدعم اختبار السيناريوهات المستهدف عبر CLI والتحقق التلقائي من شروط حماية alias.
6. وحدة تحكم Beacon التفاعلية (console):
   • موجه أوامر تفاعلي (beacon> ) يدعم aliases المسجلة، والوسائط، ووثائق المساعدة، والتنفيذ الحي.

---

تخطيط الدليل

.
├── .gitignore                # Git ignore rules for compiled binaries & bytecode
├── COFFLoader64.exe          # 64-bit Standalone in-memory COFF relocator and loader
├── cna_emulator.bat          # Convenient CLI launcher script
├── README.md                 # Comprehensive documentation and usage guide
├── TESTING.md                # Component verification report & quality gates
├── TEST_SPEC.md              # 48-scenario 7-category test specification
└── CnaEmulator/              # Java CNA Emulator component
    ├── .gitignore            # Git ignore rules for CnaEmulator subfolder
    ├── CnaEmulator.java      # Emulator source code and Sleep engine bridge
    ├── CnaEmulator.class     # Compiled bytecode
    ├── CnaEmulator.jar       # Packaged bytecode JAR
    ├── build.bat             # Build script to compile and package CnaEmulator
    ├── test.bat              # Standalone test runner script (48 scenarios)
    └── tests/                # Test suite and fixtures
        ├── TestCnaEmulator.java  # 48-scenario test harness
        └── fixtures/             # Universal test fixtures
            ├── sample_bof.cna        # Standalone sample Aggressor Script
            ├── sample_bof.cna.tests  # Companion test suite
            ├── multi_alias.cna       # Multi-alias sample script
            └── multi_alias.cna.tests # Multi-alias companion test suite

---

المتطلبات والشروط المسبقة

المتطلب	الوصف والإعداد
Java JDK (17+)	ملفات java و javac التنفيذية. اضبط JAVA_HOME على مسار JDK وتأكد من وجود %JAVA_HOME%\bin في PATH.
Sleep 2.1 (sleep.jar)	محرك السكربتات لسكربتات Aggressor. حمّله من Sleep 2.1 أو انسخه من Cobalt Strike. اضبط SLEEP_JAR (مثل set "SLEEP_JAR=C:\path\to\sleep.jar")، أو ضع sleep.jar في المجلد الجذر أو في CnaEmulator\.
المحمّل في الذاكرة (COFFLoader64.exe)	ملف المحمّل التنفيذي المستقل (مثل المُجمَّع من trustedsec/COFFLoader). يوضع في الدليل الجذر أو يُستبدل عبر COFFLOADER_PATH.

إعداد البيئة السريع (cmd.exe):

set "JAVA_HOME=C:\path\to\jdk-17"
set "PATH=%JAVA_HOME%\bin;%PATH%"
set "SLEEP_JAR=C:\path\to\sleep.jar"

---

دليل الاستخدام

1. التجميع من المصدر

قبل تشغيل الفئات المُجمَّعة أو JAR، جمّع CnaEmulator.java:

باستخدام سكربت البناء:

CnaEmulator\build.bat

أو التجميع والتغليف اليدوي:

:: Compile source to bytecode
javac -cp "%SLEEP_JAR%" -d CnaEmulator CnaEmulator\CnaEmulator.java

:: Package into executable bytecode JAR
cd CnaEmulator
jar cfe CnaEmulator.jar CnaEmulator *.class
cd ..

---

2. طرق التنفيذ

يمكنك استدعاء CnaEmulator باستخدام أي من الطرق التالية من دليل جذر المشروع:

الطريقة أ: مشغّل سكربت Batch (موصى به)

يتولى سكربت المشغّل تلقائيًا اكتشاف JDK وإعداد classpath وتحليل المسارات:

cna_emulator.bat <action> [arguments...]

الطريقة ب: JAR التنفيذي المُجمَّع

java -cp "CnaEmulator\CnaEmulator.jar;%SLEEP_JAR%" CnaEmulator <action> [arguments...]

الطريقة ج: Bytecode الفئة المباشر

java -cp "CnaEmulator;%SLEEP_JAR%" CnaEmulator <action> [arguments...]

---

3. الإجراءات الأساسية وأمثلة الاستخدام

أ. التحقق من صياغة السكربت (check)

يتحقق من صياغة سكربت Aggressor ويترجم أشجار AST عبر Sleep 2.1 دون تنفيذ الكود:

cna_emulator.bat check <path\to\script.cna>

مثال مع fixture المرفق:

cna_emulator.bat check CnaEmulator\tests\fixtures\sample_bof.cna

مخرجات نموذجية:

[*] Checking syntax of: CnaEmulator\tests\fixtures\sample_bof.cna
[+] sample_bof.cna syntax OK

---

ب. تنفيذ الأوامر مع إرسال BOF الحي (run)

ينفذ alias Aggressor معلنًا، ويجمّع الوسائط في صيغة ثنائية (bof_pack)، ويحل ملف الكائن (script_resource)، ويستدعي COFFLoader64.exe لتنفيذ BOF في ذاكرة المستدعي:

cna_emulator.bat run <path\to\script.cna> <alias_name> [arguments...]

مثال مع fixture المرفق:

cna_emulator.bat run CnaEmulator\tests\fixtures\sample_bof.cna sample_bof run test_target

مخرجات نموذجية:

[*] Invoking: sample_bof 1 run test_target
[*] Tasked beacon: Executing sample_bof with action: run

[+] [COFFLoader Bridge] Executing: COFFLoader64.exe go sample_bof.o
    | Got contents of COFF file
    | Running/Parsing the COFF file
    | Ran/parsed the coff
    | Outdata Below:
    | ...
[+] [COFFLoader Bridge] Completed with exit code: 0

---

ج. بطارية الاختبار الآلي واختبار الانحدار (test)

يوفر CnaEmulator test تنفيذ اختبار آلي:

cna_emulator.bat test <path\to\script.cna> [alias] [arguments...]

أوضاع التنفيذ:

1. تنفيذ سيناريو مستهدف: إذا تم تحديد <alias> و [arguments...] على سطر الأوامر، يُنفَّذ ذلك السيناريو المحدد فقط.
2. اكتشاف ملف الاختبار المرافق: إذا لم تُقدَّم وسائط، يتحقق CnaEmulator من وجود ملف اختبار مرافق بجوار السكربت:
   • <script_dir>\<script_name>.cna.tests
   • <script_dir>\<script_name>.tests إذا وُجد، تُنفَّذ جميع أسطر السيناريو في الملف المرافق بالتسلسل.
3. فحص alias الديناميكي واختبار الحماية: إذا لم يوجد ملف اختبار مرافق، يفحص CnaEmulator جميع aliases الأوامر المسجلة وينفذ اختبار شرط حماية للتأكد من أن أعداد الوسائط غير الصالحة تُخرج أخطاء الاستخدام دون إطلاق استثناءات غير معالجة.

أمثلة:

:: Run automated tests on the bundled sample script (executes sample_bof.cna.tests)
cna_emulator.bat test CnaEmulator\tests\fixtures\sample_bof.cna

:: Run automated tests on the bundled multi-alias script (executes multi_alias.cna.tests)
cna_emulator.bat test CnaEmulator\tests\fixtures\multi_alias.cna