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

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

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

القدرات

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

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

إعداد البيئة السريع (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...]

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

تنفيذ سيناريو مستهدف: إذا تم تحديد <alias> و [arguments...] على سطر الأوامر، يُنفَّذ ذلك السيناريو المحدد فقط.
اكتشاف ملف الاختبار المرافق: إذا لم تُقدَّم وسائط، يتحقق CnaEmulator من وجود ملف اختبار مرافق بجوار السكربت:
- <script_dir>\<script_name>.cna.tests
- <script_dir>\<script_name>.tests إذا وُجد، تُنفَّذ جميع أسطر السيناريو في الملف المرافق بالتسلسل.
فحص 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

:: Run a targeted scenario directly via CLI
cna_emulator.bat test CnaEmulator\tests\fixtures\sample_bof.cna sample_bof query

تأليف ملفات الاختبار المرافقة (<script>.cna.tests): أنشئ ملف نصي عادي بجوار سكربت .cna الخاص بك. يحدد كل سطر غير فارغ وغير تعليقي alias ووسائطه:

# Sample BOF Companion Test Suite
# Format: <alias> [arguments...]
sample_bof run test_target
sample_bof query

د. وحدة تحكم Beacon المحاكاة التفاعلية (`console`)

تشغّل موجهًا تفاعليًا beacon> يدعم aliases المسجلة، وسجل الأوامر، والتنفيذ المحاكى:

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

مثال جلسة تفاعلية:

====================================================================
  CnaEmulator Interactive Beacon Console
  Loaded Script: sample_bof.cna
====================================================================
Type 'help' to see registered commands, or 'exit' to quit.

beacon> help
Registered Beacon Commands:
  - sample_bof : Sample BOF execution command

beacon> sample_bof run local_target
[*] Tasked beacon: Executing sample_bof with action: run
[+] [COFFLoader Bridge] Executing: COFFLoader64.exe go sample_bof.o
...
beacon> exit

4. اختبار مشاريع BOF الخارجية

CnaEmulator عام الغرض تمامًا ويمكنه اختبار سكربتات Aggressor وملفات BOF الثنائية الموجودة في أي دليل أو مستودع خارجي عبر نظام الملفات:

:: Validate any external script syntax
cna_emulator.bat check C:\Projects\CustomBof\my_bof.cna

:: Execute external BOF alias commands with live arguments
cna_emulator.bat run C:\Projects\CustomBof\my_bof.cna my_command target_argument

:: Run companion test suites for external scripts
cna_emulator.bat test C:\Projects\CustomBof\my_bof.cna

:: Open interactive console with external script
cna_emulator.bat console C:\Projects\CustomBof\my_bof.cna

5. تشغيل جناح الاختبار الذاتي لـ CnaEmulator

لتشغيل جناح اختبار الامتثال الكامل للمواصفات المكوّن من 48 سيناريو لـ CnaEmulator:

CnaEmulator\test.bat

النتيجة المتوقعة:

====================================================================
  Execution Summary
====================================================================
  Total Scenarios : 48
  Passed          : 48
  Failed          : 0
  Assertions      : 172
  Elapsed Time    : ~2800 ms
====================================================================
[+] ALL 48 TEST SCENARIOS PASSED CLEANLY (100% SPECIFICATION CONFORMANCE)

كتالوج الدوال المحاكاة

التطبيقات الحقيقية (المحرك الوظيفي وجسر العمليات الفرعية)

[!NOTE] تطبيقات وهمية / بديلة: جميع واجهات Cobalt Strike API الأخرى—بما في ذلك تنفيذ/حقن العمليات (bshell, bpowershell, bexecute, bspawn, binject)، والتلاعب بالرموز (bsteal_token, brev2self, bgetuid)، والتنقل في نظام الملفات (bpwd, bls, bupload, bdownload)، والتحويل (socks, rportfwd)، ومطالبات واجهة المستخدم (prompt_text, )، وخطافات GUI (, , , )—مطبقة كبدائل وهمية تُرجع قيمًا موجبة غير خاطئة (, , , ) أو كتل no-op حتى تُنفَّذ السكربتات دون اتصال ودون فشل.

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`.

`bof_pack`	يجمّع وسائط ثنائية Little-Endian (`i`, `s`, `z`, `Z`, `b`) مع بادئة طول المخزن 4 بايت.
`beacon_inline_execute`	يشغّل عملية فرعية `COFFLoader64.exe go <bof.o> <hex_args>` ويبث stdout الحي.
`script_resource`	يحل مسارات الموارد النسبية عبر دليل السكربت، و `bin/`، و `../bin/`، والمسارات النسبية.
`openf`, `readb`, `closef`	إدخال/إخراج نظام ملفات أصلي لقراءة ملفات `.o` BOF المحلية إلى مخازن بايت.
`btask`, `berror`, `blog`, `blog2`	ينسّق ويخرج رسائل التكليف والحالة والأخطاء إلى stdout/stderr.
`beacon_command_register`	يسجل aliases والملخصات وتفاصيل المساعدة في كتالوج الأوامر الحي.
`beacon_commands`, `beacon_command_detail`	يستعلم عن قوائم الأوامر المسجلة ونص المساعدة للاستخدام التفاعلي/في وحدة التحكم.
`barch`	يُرجع `"x64"`.
`bdata`, `beacon_info`	يُرجع hash بيانات Beacon وهمي (`id: 1`, `pid: 13020`, `user: SYSTEM`, `arch: x64`).
`beacons`, `beacon_ids`	يُرجع مصفوفة beacon محاكاة نشطة (`["1"]`).
`alias`, `command`	يربط كتل الأوامر كإغلاقات قابلة للتنفيذ للإرسال التفاعلي أو عبر CLI.

الأكثر شعبية

CnaEmulator