Ambiente di emulazione e testing standalone per Cobalt Strike Aggressor Scripts (.cna) che convalida la sintassi, simula le API di Beacon ed esegue BOF tramite COFFLoader senza un teamserver.
CnaEmulator è un harness di sviluppo, emulazione e testing standalone e general-purpose per Cobalt Strike Aggressor Scripts (.cna). Consente a ricercatori di sicurezza, sviluppatori di tool e autori di BOF di validare la sintassi degli script, simulare comandi alias della console Beacon ed eseguire Beacon Object Files (BOF) in-memory direttamente tramite COFFLoader64.exe senza avviare un teamserver o un client GUI.
[!WARNING] Disclaimer: Questo codice è stato interamente generato con Antigravity e non è ancora stato revisionato.
check):
.cna utilizzando il motore sottostante Sleep 2.1.bof_pack):
datap di Cobalt Strike:
'i': intero a 4 byte's': short a 2 byte'z': stringa null-terminated con prefisso di lunghezza (prefisso strlen + 1)'Z': stringa wide UTF-16LE con prefisso di lunghezza'b': buffer binario con prefisso di lunghezzabeacon_inline_execute):
beacon_inline_execute($bid, $bof_data, "go", $packed_args).COFFLoader64.exe go <bof_path> <hex_args> come sottoprocesso figlio.test):
<script>.cna.tests o <script>.tests.console):
beacon> ) che supporta alias registrati, argomenti, documentazione di help ed esecuzione live..
├── .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
| Requisito | Descrizione e Configurazione |
|---|---|
| Java JDK (17+) | Binari java e javac. Imposta JAVA_HOME al percorso del tuo JDK e assicurati che %JAVA_HOME%\bin sia nel PATH. |
Sleep 2.1 (sleep.jar) | Motore di scripting per Aggressor Scripts. Scarica da Sleep 2.1 o copia da Cobalt Strike. Imposta SLEEP_JAR (es. set "SLEEP_JAR=C:\path\to\sleep.jar"), oppure posiziona sleep.jar nella cartella root o in CnaEmulator\. |
Loader In-Memory (COFFLoader64.exe) | Binario loader standalone (es. compilato da trustedsec/COFFLoader). Posizionato nella directory root o sovrascritto tramite COFFLOADER_PATH. |
Setup Rapido dell'Ambiente (cmd.exe):
set "JAVA_HOME=C:\path\to\jdk-17"
set "PATH=%JAVA_HOME%\bin;%PATH%"
set "SLEEP_JAR=C:\path\to\sleep.jar"
Prima di eseguire le classi compilate o il JAR, compila CnaEmulator.java:
Usando lo Script di Build:
CnaEmulator\build.bat
Oppure Compilazione e Packaging Manuale:
:: 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 ..
Puoi invocare CnaEmulator utilizzando uno dei seguenti metodi dalla directory root del progetto:
Lo script launcher gestisce automaticamente il rilevamento del JDK, il setup del classpath e la risoluzione dei percorsi:
cna_emulator.bat <action> [arguments...]
java -cp "CnaEmulator\CnaEmulator.jar;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
java -cp "CnaEmulator;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
check)Valida la sintassi dell'Aggressor Script e compila gli AST tree tramite Sleep 2.1 senza eseguire il codice:
cna_emulator.bat check <path\to\script.cna>
Esempio con fixture inclusa:
cna_emulator.bat check CnaEmulator\tests\fixtures\sample_bof.cna
Output di Esempio:
[*] Checking syntax of: CnaEmulator\tests\fixtures\sample_bof.cna
[+] sample_bof.cna syntax OK
run)Esegue un alias Aggressor dichiarato, impacchetta gli argomenti in formato binario (bof_pack), risolve l'object file (script_resource) e invoca COFFLoader64.exe per eseguire il BOF nella memoria del chiamante:
cna_emulator.bat run <path\to\script.cna> <alias_name> [arguments...]
Esempio con fixture inclusa:
cna_emulator.bat run CnaEmulator\tests\fixtures\sample_bof.cna sample_bof run test_target
Output di Esempio:
[*] 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 fornisce l'esecuzione automatizzata dei test:
cna_emulator.bat test <path\to\script.cna> [alias] [arguments...]
Modalità di Esecuzione:
<alias> e [arguments...] sono specificati sulla riga di comando, viene eseguito solo quello specifico scenario.CnaEmulator cerca un file di test companion adiacente allo script:
<script_dir>\<script_name>.cna.tests<script_dir>\<script_name>.tests
Se trovato, tutte le righe di scenario nel file companion vengono eseguite sequenzialmente.CnaEmulator ispeziona tutti gli alias di comando registrati ed esegue un test di guard clause per assicurarsi che conteggi di argomenti non validi producano errori di utilizzo senza lanciare eccezioni non gestite.Esempi:
:: 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
Creazione di File di Test Companion (<script>.cna.tests):
Crea un file di testo semplice adiacente al tuo script .cna. Ogni riga non vuota e non di commento specifica un alias e i suoi parametri:
# Sample BOF Companion Test Suite
# Format: <alias> [arguments...]
sample_bof run test_target
sample_bof query
console)Avvia un prompt interattivo beacon> che supporta alias registrati, cronologia dei comandi ed esecuzione simulata:
cna_emulator.bat console <path\to\script.cna>
Esempio di Sessione Interattiva:
====================================================================
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 è completamente general-purpose e può testare Aggressor Scripts e binari BOF situati in qualsiasi directory o repository esterno sul tuo 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
Per eseguire la suite completa di test di conformità alla specifica a 48 scenari per CnaEmulator:
CnaEmulator\test.bat
Risultato Atteso:
====================================================================
Execution Summary
====================================================================
Total Scenarios : 48
Passed : 48
Failed : 0
Assertions : 172
Elapsed Time : ~2800 ms
====================================================================
[+] ALL 48 TEST SCENARIOS PASSED CLEANLY (100% SPECIFICATION CONFORMANCE)
| Funzione / Keyword | Descrizione |
|---|---|
bof_pack | Impacchetta argomenti binari Little-Endian (i, s, z, Z, b) con prefisso di lunghezza del buffer a 4 byte. |
beacon_inline_execute | Genera il sottoprocesso COFFLoader64.exe go <bof.o> <hex_args> e trasmette stdout live. |
script_resource | Risolve percorsi di risorse relativi attraverso la dir dello script, bin/, ../bin/ e percorsi relativi. |
openf, readb, closef | I/O nativo del filesystem per leggere file .o BOF locali in buffer di byte. |
btask, berror, blog, blog2 | Formatta e restituisce messaggi di tasking, stato ed errore su stdout/stderr. |
beacon_command_register | Registra alias, riepiloghi e dettagli di help nel catalogo dei comandi live. |
beacon_commands, beacon_command_detail | Interroga gli elenchi di comandi registrati e il testo di help per uso interattivo/console. |
barch | Restituisce "x64". |
bdata, beacon_info | Restituisce un hash di metadati Beacon mock (id: 1, pid: 13020, user: SYSTEM, arch: x64). |
beacons, beacon_ids | Restituisce un array di beacon simulati attivi (["1"]). |
alias, |
[!NOTE] Implementazioni Dummy / Stub: Tutte le altre API di Cobalt Strike—inclusi esecuzione/iniezione di processi (
bshell,bpowershell,bexecute,bspawn,binject), manipolazione di token (bsteal_token,brev2self,bgetuid), navigazione del filesystem (bpwd,bls,bupload,bdownload), pivoting (socks,rportfwd), prompt UI (prompt_text,prompt_confirm) e hook GUI (popup,menu,item,on)—sono implementate come stub dummy che restituiscono valori positivi non-errore (1,"NT AUTHORITY\SYSTEM","C:\Windows\System32",true) o blocchi no-op in modo che gli script vengano eseguiti offline senza fallire.
command| Associa blocchi di comando come closure eseguibili per il dispatch interattivo o da CLI. |