Standalone emulation and testing harness for Cobalt Strike Aggressor Scripts (.cna) that validates syntax, mocks Beacon APIs, and executes BOFs via COFFLoader without a teamserver.
CnaEmulator is a standalone, general-purpose development, emulation, and testing harness for Cobalt Strike Aggressor Scripts (.cna). It allows security researchers, tool developers, and BOF authors to validate script syntax, simulate Beacon console alias commands, and execute in-memory Beacon Object Files (BOFs) directly via COFFLoader64.exe without launching a teamserver or GUI client.
[!WARNING] Disclaimer: This code was fully generated with Antigravity and has not been reviewed yet.
check):
.cna scripts using the underlying Sleep 2.1 engine.bof_pack):
datap binary format:
'i': 4-byte integer's': 2-byte short'z': length-prefixed null-terminated string (strlen + 1 prefix)'Z': length-prefixed wide UTF-16LE string'b': length-prefixed binary bufferbeacon_inline_execute):
beacon_inline_execute($bid, $bof_data, "go", $packed_args).COFFLoader64.exe go <bof_path> <hex_args> as a child subprocess.test):
<script>.cna.tests or <script>.tests scenario suites.console):
beacon> ) supporting registered aliases, arguments, help documentation, and live execution..
├── .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
| Requirement | Description & Setup |
|---|---|
| Java JDK (17+) | java and javac binaries. Set JAVA_HOME to your JDK path and ensure %JAVA_HOME%\bin is in PATH. |
Sleep 2.1 (sleep.jar) | Scripting engine for Aggressor Scripts. Download from Sleep 2.1 or copy from Cobalt Strike. Set SLEEP_JAR (e.g. set "SLEEP_JAR=C:\path\to\sleep.jar"), or place sleep.jar in the root folder or in CnaEmulator\. |
In-Memory Loader (COFFLoader64.exe) | Standalone loader binary (e.g., compiled from trustedsec/COFFLoader). Placed in the root directory or overridden via COFFLOADER_PATH. |
Quick Environment Setup (cmd.exe):
set "JAVA_HOME=C:\path\to\jdk-17"
set "PATH=%JAVA_HOME%\bin;%PATH%"
set "SLEEP_JAR=C:\path\to\sleep.jar"
Before running the compiled classes or JAR, compile CnaEmulator.java:
Using the Build Script:
CnaEmulator\build.bat
Or Manual Compilation & Packaging:
:: 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 ..
You can invoke CnaEmulator using any of the following methods from the project root directory:
The launcher script automatically handles JDK discovery, classpath setup, and path resolution:
cna_emulator.bat <action> [arguments...]
java -cp "CnaEmulator\CnaEmulator.jar;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
java -cp "CnaEmulator;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
check)Validates Aggressor Script syntax and compiles AST trees via Sleep 2.1 without executing code:
cna_emulator.bat check <path\to\script.cna>
Example with bundled fixture:
cna_emulator.bat check CnaEmulator\tests\fixtures\sample_bof.cna
Sample Output:
[*] Checking syntax of: CnaEmulator\tests\fixtures\sample_bof.cna
[+] sample_bof.cna syntax OK
run)Executes a declared Aggressor alias, packs arguments into binary format (bof_pack), resolves the object file (script_resource), and invokes COFFLoader64.exe to execute the BOF in caller memory:
cna_emulator.bat run <path\to\script.cna> <alias_name> [arguments...]
Example with bundled fixture:
cna_emulator.bat run CnaEmulator\tests\fixtures\sample_bof.cna sample_bof run test_target
Sample Output:
[*] 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 provides automated test execution:
cna_emulator.bat test <path\to\script.cna> [alias] [arguments...]
Execution Modes:
<alias> and [arguments...] are specified on the command line, only that specific scenario is executed.CnaEmulator checks for a companion test file adjacent to the script:
<script_dir>\<script_name>.cna.tests<script_dir>\<script_name>.tests
If found, all scenario lines in the companion file are executed sequentially.CnaEmulator inspects all registered command aliases and executes a guard clause test to ensure invalid argument counts output usage errors without throwing unhandled exceptions.Examples:
:: 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
Authoring Companion Test Files (<script>.cna.tests):
Create a plain text file adjacent to your .cna script. Each non-empty, non-comment line specifies an alias and its parameters:
# Sample BOF Companion Test Suite
# Format: <alias> [arguments...]
sample_bof run test_target
sample_bof query
console)Launches an interactive beacon> prompt supporting registered aliases, command history, and simulated execution:
cna_emulator.bat console <path\to\script.cna>
Interactive Session Example:
====================================================================
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 is completely general-purpose and can test Aggressor Scripts and BOF binaries located in any directory or external repository across your filesystem:
:: 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
To run the complete 48-scenario specification compliance test suite for CnaEmulator:
CnaEmulator\test.bat
Expected Result:
====================================================================
Execution Summary
====================================================================
Total Scenarios : 48
Passed : 48
Failed : 0
Assertions : 172
Elapsed Time : ~2800 ms
====================================================================
[+] ALL 48 TEST SCENARIOS PASSED CLEANLY (100% SPECIFICATION CONFORMANCE)
| Function / Keyword | Description |
|---|---|
bof_pack | Packs Little-Endian binary arguments (i, s, z, Z, b) with 4-byte buffer length prefix. |
beacon_inline_execute | Spawns COFFLoader64.exe go <bof.o> <hex_args> subprocess and streams live stdout. |
script_resource | Resolves relative resource paths across script dir, bin/, ../bin/, and relative paths. |
openf, readb, closef | Native filesystem I/O for reading local .o BOF files into byte buffers. |
btask, berror, blog, blog2 | Formats and outputs tasking, status, and error messages to stdout/stderr. |
beacon_command_register | Registers aliases, summaries, and help details into the live command catalog. |
beacon_commands, beacon_command_detail | Queries registered command listings and help text for interactive/console use. |
barch | Returns "x64". |
bdata, beacon_info | Returns mock Beacon metadata hash (id: 1, pid: 13020, user: SYSTEM, arch: x64). |
beacons, beacon_ids | Returns active simulated beacon array (["1"]). |
alias, command | Binds command blocks as executable closures for interactive or CLI dispatch. |
[!NOTE] Dummy / Stub Implementations: All other Cobalt Strike APIs—including process execution/injection (
bshell,bpowershell,bexecute,bspawn,binject), token manipulation (bsteal_token,brev2self,bgetuid), filesystem navigation (bpwd,bls,bupload,bdownload), pivoting (socks,rportfwd), UI prompts (prompt_text,prompt_confirm), and GUI hooks (popup,menu,item,on)—are implemented as dummy stubs returning positive non-error values (1,"NT AUTHORITY\SYSTEM","C:\Windows\System32",true) or no-op blocks so scripts execute offline without failing.