Eigenständige Emulations- und Testumgebung für Cobalt Strike Aggressor Scripts (.cna), die die Syntax validiert, Beacon-APIs simuliert und BOFs über COFFLoader ohne Teamserver ausführt.
CnaEmulator ist ein eigenständiges, universell einsetzbares Entwicklungs-, Emulations- und Test-Harness für Cobalt Strike Aggressor Scripts (.cna). Es ermöglicht Sicherheitsforschern, Tool-Entwicklern und BOF-Autoren, die Skriptsyntax zu validieren, Beacon-Konsolen-Alias-Befehle zu simulieren und In-Memory Beacon Object Files (BOFs) direkt über COFFLoader64.exe auszuführen, ohne einen Teamserver oder GUI-Client zu starten.
[!WARNING] Haftungsausschluss: Dieser Code wurde vollständig mit Antigravity generiert und wurde noch nicht überprüft.
check):
.cna-Skripte mit der zugrunde liegenden Sleep 2.1-Engine.bof_pack):
datap-Binärformat von Cobalt Strike entspricht:
'i': 4-Byte-Integer's': 2-Byte-Short'z': längenpräfixierter nullterminierter String (strlen + 1-Präfix)'Z': längenpräfixierter breiter UTF-16LE-String'b': längenpräfixierter Binärpufferbeacon_inline_execute):
beacon_inline_execute($bid, $bof_data, "go", $packed_args) ab.COFFLoader64.exe go <bof_path> <hex_args> als Kind-Subprozess aus.test):
<script>.cna.tests- oder <script>.tests-Szenariosuiten aus.console):
beacon> ) mit Unterstützung für registrierte Aliase, Argumente, Hilfedokumentation und Live-Ausführung..
├── .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
| Anforderung | Beschreibung & Einrichtung |
|---|---|
| Java JDK (17+) | java- und javac-Binärdateien. Setzen Sie JAVA_HOME auf Ihren JDK-Pfad und stellen Sie sicher, dass %JAVA_HOME%\bin im PATH enthalten ist. |
Sleep 2.1 (sleep.jar) | Skripting-Engine für Aggressor Scripts. Herunterladen von Sleep 2.1 oder aus Cobalt Strike kopieren. Setzen Sie SLEEP_JAR (z. B. set "SLEEP_JAR=C:\path\to\sleep.jar"), oder platzieren Sie sleep.jar im Stammordner oder in CnaEmulator\. |
In-Memory Loader (COFFLoader64.exe) | Eigenständige Loader-Binärdatei (z. B. kompiliert aus trustedsec/COFFLoader). Im Stammverzeichnis platziert oder über COFFLOADER_PATH überschrieben. |
Schnelle Umgebungseinrichtung (cmd.exe):
set "JAVA_HOME=C:\path\to\jdk-17"
set "PATH=%JAVA_HOME%\bin;%PATH%"
set "SLEEP_JAR=C:\path\to\sleep.jar"
Bevor Sie die kompilierten Klassen oder das JAR ausführen, kompilieren Sie CnaEmulator.java:
Mit dem Build-Skript:
CnaEmulator\build.bat
Oder manuelle Kompilierung & Paketierung:
:: 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 ..
Sie können CnaEmulator mit einer der folgenden Methoden aus dem Projektstammverzeichnis aufrufen:
Das Launcher-Skript übernimmt automatisch die JDK-Erkennung, das Classpath-Setup und die Pfadauflösung:
cna_emulator.bat <action> [arguments...]
java -cp "CnaEmulator\CnaEmulator.jar;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
java -cp "CnaEmulator;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
check)Validiert die Aggressor-Skriptsyntax und kompiliert AST-Bäume über Sleep 2.1, ohne Code auszuführen:
cna_emulator.bat check <path\to\script.cna>
Beispiel mit mitgeliefertem Fixture:
cna_emulator.bat check CnaEmulator\tests\fixtures\sample_bof.cna
Beispielausgabe:
[*] Checking syntax of: CnaEmulator\tests\fixtures\sample_bof.cna
[+] sample_bof.cna syntax OK
run)Führt einen deklarierten Aggressor-Alias aus, packt Argumente in das Binärformat (bof_pack), löst die Objektdatei auf (script_resource) und ruft COFFLoader64.exe auf, um das BOF im Speicher des Aufrufers auszuführen:
cna_emulator.bat run <path\to\script.cna> <alias_name> [arguments...]
Beispiel mit mitgeliefertem Fixture:
cna_emulator.bat run CnaEmulator\tests\fixtures\sample_bof.cna sample_bof run test_target
Beispielausgabe:
[*] 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 bietet automatisierte Testausführung:
cna_emulator.bat test <path\to\script.cna> [alias] [arguments...]
Ausführungsmodi:
<alias> und [arguments...] auf der Kommandozeile angegeben werden, wird nur dieses spezifische Szenario ausgeführt.CnaEmulator auf eine Companion-Testdatei neben dem Skript:
<script_dir>\<script_name>.cna.tests<script_dir>\<script_name>.tests
Wenn gefunden, werden alle Szenariozeilen in der Companion-Datei sequenziell ausgeführt.CnaEmulator alle registrierten Befehlsaliase und führt einen Guard-Clause-Test aus, um sicherzustellen, dass ungültige Argumentanzahlen Nutzungsfehler ausgeben, ohne unbehandelte Ausnahmen zu werfen.Beispiele:
:: 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
Erstellen von Companion-Testdateien (<script>.cna.tests):
Erstellen Sie eine reine Textdatei neben Ihrem .cna-Skript. Jede nicht leere, nicht kommentierte Zeile gibt einen Alias und seine Parameter an:
# Sample BOF Companion Test Suite
# Format: <alias> [arguments...]
sample_bof run test_target
sample_bof query
console)Startet eine interaktive beacon> -Eingabeaufforderung mit Unterstützung für registrierte Aliase, Befehlsverlauf und simulierte Ausführung:
cna_emulator.bat console <path\to\script.cna>
Beispiel einer interaktiven Sitzung:
====================================================================
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
CnaEmulator ist vollständig universell einsetzbar und kann Aggressor Scripts und BOF-Binärdateien testen, die sich in beliebigen Verzeichnissen oder externen Repositories auf Ihrem Dateisystem befinden:
:: 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
Um die vollständige 48-Szenario-Spezifikationskonformitätstestsuite für CnaEmulator auszuführen:
CnaEmulator\test.bat
Erwartetes Ergebnis:
====================================================================
Execution Summary
====================================================================
Total Scenarios : 48
Passed : 48
Failed : 0
Assertions : 172
Elapsed Time : ~2800 ms
====================================================================
[+] ALL 48 TEST SCENARIOS PASSED CLEANLY (100% SPECIFICATION CONFORMANCE)
| Funktion / Schlüsselwort | Beschreibung |
|---|---|
bof_pack | Packt Little-Endian-Binärargumente (i, s, z, Z, b) mit 4-Byte-Pufferlängenpräfix. |
beacon_inline_execute | Startet COFFLoader64.exe go <bof.o> <hex_args>-Subprozess und streamt Live-stdout. |
script_resource | Löst relative Ressourcenpfade über Skriptverzeichnis, bin/, ../bin/ und relative Pfade auf. |
openf, readb, closef | Nativer Dateisystem-I/O zum Einlesen lokaler .o-BOF-Dateien in Byte-Puffer. |
btask, berror, blog, blog2 | Formatiert und gibt Tasking-, Status- und Fehlermeldungen nach stdout/stderr aus. |
beacon_command_register | Registriert Aliase, Zusammenfassungen und Hilfedetails im Live-Befehlskatalog. |
beacon_commands, beacon_command_detail | Fragt registrierte Befehlslisten und Hilfetexte für interaktive/Konsolennutzung ab. |
barch | Gibt "x64" zurück. |
bdata, beacon_info | Gibt Mock-Beacon-Metadaten-Hash zurück (id: 1, pid: 13020, user: SYSTEM, arch: x64). |
beacons, beacon_ids | Gibt aktives simuliertes Beacon-Array zurück (["1"]). |
alias, command |
[!NOTE] Dummy-/Stub-Implementierungen: Alle anderen Cobalt Strike-APIs – einschließlich Prozessausführung/-injektion (
bshell,bpowershell,bexecute,bspawn,binject), Token-Manipulation (bsteal_token,brev2self,bgetuid), Dateisystemnavigation (bpwd,bls,bupload,bdownload), Pivoting (socks,rportfwd), UI-Prompts (prompt_text,prompt_confirm) und GUI-Hooks (popup,menu,item,on) – sind als Dummy-Stubs implementiert, die positive fehlerfreie Werte (1,"NT AUTHORITY\SYSTEM","C:\Windows\System32",true) oder No-Op-Blöcke zurückgeben, damit Skripte offline ohne Fehler ausgeführt werden können.
| Bindet Befehlsblöcke als ausführbare Closures für interaktiven oder CLI-Dispatch. |