Harnais autonome d'émulation et de test pour les scripts Aggressor de Cobalt Strike (.cna) qui valide la syntaxe, simule les API Beacon et exécute des BOFs via COFFLoader sans teamserver.
CnaEmulator est un harnais autonome, polyvalent de développement, d'émulation et de test pour les scripts Aggressor Cobalt Strike (.cna). Il permet aux chercheurs en sécurité, aux développeurs d'outils et aux auteurs de BOF de valider la syntaxe des scripts, de simuler les commandes alias de la console Beacon et d'exécuter des Beacon Object Files (BOF) en mémoire directement via COFFLoader64.exe sans lancer de teamserver ni de client GUI.
[!WARNING] Avertissement : Ce code a été entièrement généré avec Antigravity et n'a pas encore été révisé.
check) :
.cna à l'aide du moteur sous-jacent Sleep 2.1.bof_pack) :
datap de Cobalt Strike :
'i' : entier de 4 octets's' : short de 2 octets'z' : chaîne terminée par un null préfixée par la longueur (préfixe strlen + 1)'Z' : chaîne UTF-16LE large préfixée par la longueur'b' : tampon binaire préfixé par la longueurbeacon_inline_execute) :
beacon_inline_execute($bid, $bof_data, "go", $packed_args).COFFLoader64.exe go <bof_path> <hex_args> en tant que sous-processus enfant.test) :
<script>.cna.tests ou <script>.tests.console) :
beacon> ) prenant en charge les alias enregistrés, les arguments, la documentation d'aide et l'exécution en direct..
├── .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
| Exigence | Description et configuration |
|---|---|
| Java JDK (17+) | Binaires java et javac. Définissez JAVA_HOME sur le chemin de votre JDK et assurez-vous que %JAVA_HOME%\bin est dans le PATH. |
Sleep 2.1 (sleep.jar) | Moteur de script pour les scripts Aggressor. Téléchargez depuis Sleep 2.1 ou copiez depuis Cobalt Strike. Définissez SLEEP_JAR (par ex. set "SLEEP_JAR=C:\path\to\sleep.jar"), ou placez sleep.jar dans le dossier racine ou dans CnaEmulator\. |
Chargeur en mémoire (COFFLoader64.exe) | Binaire de chargement autonome (par ex., compilé depuis trustedsec/COFFLoader). Placé dans le répertoire racine ou remplacé via COFFLOADER_PATH. |
Configuration rapide de l'environnement (cmd.exe) :
set "JAVA_HOME=C:\path\to\jdk-17"
set "PATH=%JAVA_HOME%\bin;%PATH%"
set "SLEEP_JAR=C:\path\to\sleep.jar"
Avant d'exécuter les classes compilées ou le JAR, compilez CnaEmulator.java :
Utilisation du script de build :
CnaEmulator\build.bat
Ou compilation et empaquetage manuels :
:: 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 ..
Vous pouvez invoquer CnaEmulator en utilisant l'une des méthodes suivantes depuis le répertoire racine du projet :
Le script lanceur gère automatiquement la découverte du JDK, la configuration du classpath et la résolution des chemins :
cna_emulator.bat <action> [arguments...]
java -cp "CnaEmulator\CnaEmulator.jar;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
java -cp "CnaEmulator;%SLEEP_JAR%" CnaEmulator <action> [arguments...]
check)Valide la syntaxe d'un script Aggressor et compile les arbres AST via Sleep 2.1 sans exécuter le code :
cna_emulator.bat check <path\to\script.cna>
Exemple avec le fixture fourni :
cna_emulator.bat check CnaEmulator\tests\fixtures\sample_bof.cna
Exemple de sortie :
[*] Checking syntax of: CnaEmulator\tests\fixtures\sample_bof.cna
[+] sample_bof.cna syntax OK
run)Exécute un alias Aggressor déclaré, empaquette les arguments au format binaire (bof_pack), résout le fichier objet (script_resource) et invoque COFFLoader64.exe pour exécuter le BOF dans la mémoire de l'appelant :
cna_emulator.bat run <path\to\script.cna> <alias_name> [arguments...]
Exemple avec le fixture fourni :
cna_emulator.bat run CnaEmulator\tests\fixtures\sample_bof.cna sample_bof run test_target
Exemple de sortie :
[*] 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 fournit une exécution de tests automatisée :
cna_emulator.bat test <path\to\script.cna> [alias] [arguments...]
Modes d'exécution :
<alias> et [arguments...] sont spécifiés sur la ligne de commande, seul ce scénario spécifique est exécuté.CnaEmulator recherche un fichier de test compagnon adjacent au script :
<script_dir>\<script_name>.cna.tests<script_dir>\<script_name>.tests
Si trouvé, toutes les lignes de scénario du fichier compagnon sont exécutées séquentiellement.CnaEmulator inspecte tous les alias de commande enregistrés et exécute un test de clause de garde pour s'assurer que les nombres d'arguments invalides produisent des erreurs d'utilisation sans lever d'exceptions non gérées.Exemples :
:: 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
Création de fichiers de test compagnons (<script>.cna.tests) :
Créez un fichier texte brut adjacent à votre script .cna. Chaque ligne non vide et non commentée spécifie un alias et ses paramètres :
# Sample BOF Companion Test Suite
# Format: <alias> [arguments...]
sample_bof run test_target
sample_bof query
console)Lance une invite interactive beacon> prenant en charge les alias enregistrés, l'historique des commandes et l'exécution simulée :
cna_emulator.bat console <path\to\script.cna>
Exemple de session interactive :
====================================================================
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 est entièrement polyvalent et peut tester des scripts Aggressor et des binaires BOF situés dans n'importe quel répertoire ou dépôt externe sur votre système de fichiers :
:: 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
Pour exécuter la suite complète de tests de conformité à la spécification de 48 scénarios pour CnaEmulator :
CnaEmulator\test.bat
Résultat attendu :
====================================================================
Execution Summary
====================================================================
Total Scenarios : 48
Passed : 48
Failed : 0
Assertions : 172
Elapsed Time : ~2800 ms
====================================================================
[+] ALL 48 TEST SCENARIOS PASSED CLEANLY (100% SPECIFICATION CONFORMANCE)
| Fonction / Mot-clé | Description |
|---|---|
bof_pack | Empaquette les arguments binaires Little-Endian (i, s, z, Z, b) avec un préfixe de longueur de tampon de 4 octets. |
beacon_inline_execute | Lance le sous-processus COFFLoader64.exe go <bof.o> <hex_args> et diffuse stdout en direct. |
script_resource | Résout les chemins de ressources relatifs dans le répertoire du script, bin/, ../bin/ et les chemins relatifs. |
openf, readb, closef | E/S natives du système de fichiers pour lire les fichiers BOF .o locaux dans des tampons d'octets. |
btask, berror, blog, blog2 | Formate et affiche les messages de tâche, d'état et d'erreur vers stdout/stderr. |
beacon_command_register | Enregistre les alias, résumés et détails d'aide dans le catalogue de commandes actif. |
beacon_commands, beacon_command_detail | Interroge les listes de commandes enregistrées et le texte d'aide pour une utilisation interactive/console. |
barch | Retourne "x64". |
bdata, beacon_info | Retourne un hash de métadonnées Beacon simulé (id: 1, pid: 13020, user: SYSTEM, arch: x64). |
beacons, beacon_ids | Retourne un tableau de beacons simulés actifs (["1"]). |
[!NOTE] Implémentations factices / stub : Toutes les autres API Cobalt Strike—y compris l'exécution/injection de processus (
bshell,bpowershell,bexecute,bspawn,binject), la manipulation de jetons (bsteal_token,brev2self,bgetuid), la navigation dans le système de fichiers (bpwd,bls,bupload,bdownload), le pivotement (socks,rportfwd), les invites UI (prompt_text,prompt_confirm) et les hooks GUI (popup,menu,item,on)—sont implémentées comme des stubs factices retournant des valeurs positives sans erreur (1,"NT AUTHORITY\SYSTEM","C:\Windows\System32",true) ou des blocs no-op afin que les scripts s'exécutent hors ligne sans échouer.
alias, command | Lie les blocs de commande en tant que fermetures exécutables pour le dispatch interactif ou en CLI. |