CnaEmulator - Cobalt Strike Aggressor Script Emulator & Mock Harness

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.

Fähigkeiten

Syntaxvalidierung (check):
- Kompiliert .cna-Skripte mit der zugrunde liegenden Sleep 2.1-Engine.
- Erkennt präzise ausufernde Strings, nicht maskierte Zeichen, Parser-Syntaxfehler und fehlende Trennzeichen mit exakten Dateizeilennummern.
Aggressor-Funktionsemulation:
- Emuliert offizielle Cobalt Strike Beacon-Funktionen aus der HelpSystems/Fortra Aggressor Script Documentation.
- Stellt realistische Mock-Werte oder positive fehlerfreie Rückgabewerte für Prozessinjektion, Token-Manipulation, Dateisystem-, Netzwerk- und GUI-Callback-APIs bereit.
Echtes BOF-Binary-Packing (bof_pack):
- Implementiert native Little-Endian-Serialisierung, die dem 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ärpuffer
COFFLoader-Ausführungsbrücke (beacon_inline_execute):
- Fängt automatisch beacon_inline_execute($bid, $bof_data, "go", $packed_args) ab.
- Konvertiert die gepackten Argumente in das Hex-Format.
- Führt COFFLoader64.exe go <bof_path> <hex_args> als Kind-Subprozess aus.
- Streamt die Live-BOF-Konsolenausgabe direkt in Echtzeit nach stdout.
Universelle Companion-Testsuiten & automatisierte Verifikation (test):
- Entdeckt und führt automatisch Companion-<script>.cna.tests- oder <script>.tests-Szenariosuiten aus.
- Unterstützt gezieltes CLI-Szenariotesting und automatische Alias-Guard-Clause-Verifikation.
Interaktive Beacon-Konsole (console):
- Interaktive Eingabeaufforderung (beacon> ) mit Unterstützung für registrierte Aliase, Argumente, Hilfedokumentation und Live-Ausführung.

Verzeichnisstruktur

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

Anforderungen & Voraussetzungen

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"

Nutzungsanleitung

1. Kompilieren aus dem Quellcode

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

2. Ausführungsmethoden

Sie können CnaEmulator mit einer der folgenden Methoden aus dem Projektstammverzeichnis aufrufen:

Methode A: Batch-Skript-Launcher (Empfohlen)

Das Launcher-Skript übernimmt automatisch die JDK-Erkennung, das Classpath-Setup und die Pfadauflösung:

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

Methode B: Kompiliertes ausführbares JAR

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

Methode C: Direkter Klassen-Bytecode

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

3. Kernaktionen & Nutzungsbeispiele

A. Skriptsyntax validieren (`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

B. Befehle mit Live-BOF-Dispatch ausführen (`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

C. Automatisierte Testbatterie & Regressionstests (`test`)

CnaEmulator test bietet automatisierte Testausführung:

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

Beliebteste

CnaEmulator