CnaEmulator - Cobalt Strike Aggressor Script Emulator & Mock Harness

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.

Capabilities

1. Syntax Validation (check):
   • Compiles .cna scripts using the underlying Sleep 2.1 engine.
   • Accurately detects runaway strings, unescaped characters, parser syntax errors, and missing delimiters with exact file line numbers.
2. Aggressor Function Emulation:
   • Emulates official Cobalt Strike Beacon functions from the HelpSystems/Fortra Aggressor Script Documentation.
   • Provides realistic mock values or positive non-error return values for process injection, token manipulation, filesystem, network, and GUI callback APIs.
3. Real BOF Binary Packing (bof_pack):
   • Implements native Little-Endian serialization matching Cobalt Strike's 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 buffer
4. COFFLoader Execution Bridge (beacon_inline_execute):
   • Automatically intercepts beacon_inline_execute($bid, $bof_data, "go", $packed_args).
   • Converts the packed arguments into hex format.
   • Executes COFFLoader64.exe go <bof_path> <hex_args> as a child subprocess.
   • Streams live BOF console output directly to stdout in real time.
5. Universal Companion Test Suites & Automated Verification (test):
   • Auto-discovers and executes companion <script>.cna.tests or <script>.tests scenario suites.
   • Supports targeted CLI scenario testing and automatic alias guard clause verification.
6. Interactive Beacon Console (console):
   • Interactive command prompt (beacon> ) supporting registered aliases, arguments, help documentation, and live execution.

---

Directory Layout

.
├── .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

---

Requirements & Prerequisites

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"

---

Usage Guide

1. Compiling from Source

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

---

2. Execution Methods

You can invoke CnaEmulator using any of the following methods from the project root directory:

Method A: Batch Script Launcher (Recommended)

The launcher script automatically handles JDK discovery, classpath setup, and path resolution:

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

Method B: Compiled Executable JAR

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

Method C: Direct Class Bytecode

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

---

3. Core Actions & Usage Examples

A. Validate Script Syntax (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

---

B. Execute Commands with Live BOF Dispatch (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

---

C. Automated Test Battery & Regression Testing (test)

CnaEmulator test provides automated test execution:

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