Ready to go

Author: Print3M

README.md

@@ -1,21 +1,60 @@
-# Shellcoder.py
+# Shellcoder.py 🐚⌨️
 
-Write your shellcode in Assembly and execute it with one command!
+Write your shellcode in Assembly (NASM) and compile it on Windows x64 with one command!
 
-This script helps automate the shellcode testing process. It takes an Assembly file with the shellcode (`shellcode.asm`), compiles it into machine code (NASM), generates a payload in C with that, and pastes it into the `loader.c` file. Finally, the prepared C file is compiled using MSVC. With this script you go from Assembly shellcode to executable file with one command!
+This script helps automate the shellcode development and testing process. It takes your Assembly file with the payload (`shellcode.asm`) and generates a bunch of useful executable files (read below).
 
-## Usage
+You don't have to repeat all these tedious activities anymore to make your shellcode executable! Keep your focus on shellcoding 🔥🐚🔥
+
+## Installation
+
+The following software must be installed on your system:
 
-Shellcoder script most probably should be used on Windows because of the MSVC requirement.
+- [Python 3](https://www.python.org/downloads/)
+- [NASM (Netwide Assembler)](https://www.nasm.us/)
+- [Visual Studio 2022](https://visualstudio.microsoft.com/)
+
+No Python dependencies are necessary! You are ready to go.
+
+## Usage
 
 1. Write your shellcode in `shellcode.asm`
 2. Run `python shellcoder.py`
-3. Execute output `.exe` file in `out/` directory!
+3. Execute `out/malware.exe` file!
+
+![shellcoder.py command line output](/_img/shellcoder-cli.png)
+
+## Output files
+
+The output files of this script are stored in `out/` directory:
+
+- `malware.c` - loader code with the injected payload as C string.
+- `malware.exe` - compiled loader with the injected payload.
+- `shellcode.exe` - executable file with the payload only. Great for debugging!
+- `shellcode.bin` - raw machine code of the assembly payload.
+
+![shellcoder.py output files](/_img/shellcoder-output.png)
+
+## Caveats
+
+- Indicate that you are using 64-bit mode at the beginning of the assembly file. Add `[bits 64]` to the `shellcode.asm`.
+- Define entry point in assembly file (required for debugging):
+
+```nasm
+[bits 64]
+
+section .text:
+    global _start
+
+_start:
+[...YOUR CODE HERE...]
+```
+
+- You cannot use sections other than `.text`. It's a shellcode!
+- Remember about [Microsoft x64 Calling Convention](https://learn.microsoft.com/en-us/cpp/build/x64-calling-convention?view=msvc-170) (stack alignment + shadow space!)
 
-> **IMPORTANT**: Indicate that you are using 64-bit mode at the beginning of the assembly file. Add `[bits 64]` to the `shellcode.asm`.
+## How to debug the payload?
 
-## External dependencies
+The best way to debug your assembly code is to take `out/shellcode.exe` file and load it into your favorite debugger.
 
-- Python 3
-- NASM (Netwide Assembler)
-- Visual Studio 2022
+Finally you should run `out/malware.exe` to be sure that your payload works as intended after memory injection.

_img/shellcoder-cli.png

@@ -1,59 +1,59 @@
 [bits 64]
 
-;; TODO: DEBUG this shiiiit (x64dbg)
 section .text:
-    global _start
+    global _start              
 
 _start:
+
 ; Access PEB structure
 xor rbx, rbx
-mov rbx, gs:[0x60]      ; RBX = address of PEB struct
-mov rbx, [rbx+0x18]     ; RBX = address of PEB_LDR_DATA
-add rbx, 0x20           ; RBX = address of InMemoryOrderModuleList
+mov rbx, gs:[0x60]          ; RBX = address of PEB struct
+mov rbx, [rbx+0x18]         ; RBX = address of PEB_LDR_DATA
+add rbx, 0x20               ; RBX = address of InMemoryOrderModuleList
 
 ; Go down the double-link list of PEB_LDR_DATA 
-mov rbx, [rbx]     ; RBX = 1st entry in InMemoryOrderModuleList (ntdll.dll)
-mov rbx, [rbx]          ; RBX = 2st entry in InMemoryOrderModuleList (kernelbase.dll)
-mov rbx, [rbx]          ; RBX = 3st entry in InMemoryOrderModuleList (kernel32.dll)
+mov rbx, [rbx]              ; RBX = 1st entry in InMemoryOrderModuleList (ntdll.dll)
+mov rbx, [rbx]              ; RBX = 2st entry in InMemoryOrderModuleList (kernelbase.dll)
+mov rbx, [rbx]              ; RBX = 3st entry in InMemoryOrderModuleList (kernel32.dll)
 
 ; Get VA address of kernel32.dll
-mov rbx, [rbx+0x20]     ; RBX = PEB_LDR_DATA.DllBase (address of kernel32.dll)
-mov r8, rbx             ; R8  = RBX (address of kernel32.dll)
+mov rbx, [rbx+0x20]         ; RBX = PEB_LDR_DATA.DllBase (address of kernel32.dll)
+mov r8, rbx                 ; R8  = RBX (address of kernel32.dll)
 
 ; Get VA address of ExportTable (kernel32.dll)
-mov ebx, [r8+0x3c]      ; RBX = kernel32.IMAGE_DOS_HEADER.e_lfanew (PE hdrs offset)
-add rbx, r8             ; RBX = PeHeaders offset + &kernel32.dll = &PeHeaders
+mov ebx, [r8+0x3c]          ; RBX = kernel32.IMAGE_DOS_HEADER.e_lfanew (PE hdrs offset)
+add rbx, r8                 ; RBX = PeHeaders offset + &kernel32.dll = &PeHeaders
 
 xor rcx, rcx
-add cl, 0x0088          ; RCX = 0x88 (offset ExportTable RVA)
-mov ebx, [rbx+rcx]      ; RBX = &PeHeaders + offset ExportTable RVA = ExportTable RVA
-add rbx, r8             ; RBX = ExportTable RVA + &kernel32.dll = &ExportTable
-mov r9, rbx             ; R9  = &ExportTable
+add cl, 0x0088              ; RCX = 0x88 (offset ExportTable RVA)
+mov ebx, [rbx+rcx]          ; RBX = &PeHeaders + offset ExportTable RVA = ExportTable RVA
+add rbx, r8                 ; RBX = ExportTable RVA + &kernel32.dll = &ExportTable
+mov r9, rbx                 ; R9  = &ExportTable
 
 ; Get VA address of ExportTable.AddressOfFunctions
 xor r10, r10
-mov r10d, [r9+0x1c]      ; R10 = ExportTable.AddressOfFunctions RVA
-add r10, r8             ; R10 = &kernel32.dll + RVA = &AddressOfFunctions
+mov r10d, [r9+0x1c]         ; R10 = ExportTable.AddressOfFunctions RVA
+add r10, r8                 ; R10 = &kernel32.dll + RVA = &AddressOfFunctions
 
 ; Get VA address of ExportTable.AddressOfNames
 xor r11, r11
-mov r11d, [r9+0x20]      ; R11 = ExportTable.AddressOfNames RVA
-add r11, r8             ; R11 = &kernel32.dll + RVA = &AddressOfNames
+mov r11d, [r9+0x20]         ; R11 = ExportTable.AddressOfNames RVA
+add r11, r8                 ; R11 = &kernel32.dll + RVA = &AddressOfNames
 
 ; Get VA address of ExportTable.AddressOfNameOrdinals
 xor r12, r12
-mov r12d, [r9+0x24]      ; R12 = ExportTable.AddressOfNameOrdinals RVA
-add r12, r8             ; R12 = &kernel32.dll + RVA = &AddressOfNameOrdinals
+mov r12d, [r9+0x24]         ; R12 = ExportTable.AddressOfNameOrdinals RVA
+add r12, r8                 ; R12 = &kernel32.dll + RVA = &AddressOfNameOrdinals
 
 ; Get address of WinExec function exported from kernel32.dll
 xor rcx, rcx
-add cl, 0x7                 ; RCX = function name length ("WinExec" == 7)
+add cl, 7                   ; RCX = function name length ("WinExec" == 7)
 
 xor rax, rax
-push ax                     ; STACK + null terminator (2)
-mov rax, 0x00636578456E6957 ; RAX = function name = "cexEniW" (WinExec) + 0x00
+push rax                    ; STACK + null terminator (8)
+mov rax, 0x00636578456E6957 ; RAX = function name = \0 + "cexEniW" (WinExec)
 push rax                    ; STACK + function name address (8)
-mov rsi, rsp                ; RSI = &function_name
+mov rbx, rsp                ; RSI = &function_name
 
 call get_winapi_func
 mov r13, rax                ; R13 = &WinExec
@@ -64,18 +64,20 @@ mov r13, rax                ; R13 = &WinExec
 ;   LPCSTR lpCmdLine,    => RCX = "calc.exe",0x0
 ;   UINT   uCmdShow      => RDX = 0x1 = SW_SHOWNORMAL
 ; );
-xor rax, rax
 xor rcx, rcx
 xor rdx, rdx
 
-push ax                     ; STACK + null terminator (2)
-mov rax, 0x6578652e636c6163 ; RAX = "exe.clac" (command string: calc.exe)
-push rax                    ; STACK + command string (8)
+push rcx                    ; STACK + null terminator (8)
+mov rcx, 0x6578652e636c6163 ; RCX = "exe.clac" (command string: calc.exe)
+push rcx                    ; STACK + command string (8)
+
 mov rcx, rsp                ; RCX = LPCSTR lpCmdLine
+mov rdx, 0x1                ; RDX = UINT uCmdShow = 0x1 (SW_SHOWNORMAL)
 
-mov dl, 0x1                 ; RDX = UINT uCmdShow = 0x1 (SW_SHOWNORMAL)
-; Why is here "sub rsp, 0x20" originally ??? 
-call r13                    ; Call WinExec(rax, rdx)
+and rsp, -16                ; 16-byte Stack Alignment
+sub rsp, 32                 ; STACK + 32 bytes (shadow space)
+
+call r13                    ; WinExec("calc.exe", SW_SHOWNORMAL)
 
 get_winapi_func:
     ; Requirements (preserved):
@@ -84,7 +86,7 @@ get_winapi_func:
     ;   R11 = &AddressOfNames (ExportTable)
     ;   R12 = &AddressOfNameOrdinals (ExportTable)
     ; Parameters (preserved):
-    ;   RSI = (char*) function_name
+    ;   RBX = (char*) function_name
     ;   RCX = (int)   length of function_name string
     ; Returns:
     ;   RAX = &function
@@ -98,16 +100,13 @@ get_winapi_func:
     ; Loop through AddressOfNames array:
     ;   array item = function name RVA (4 bytes)
     loop:
-        mov rcx, [rsp]          ; RCX = length of function_name string
         xor rdi, rdi            ; RDI = 0
+        mov rcx, [rsp]          ; RCX = length of function_name string
+        mov rsi, rbx            ; RSI = (char*) function_name 
 
         mov edi, [r11+rax*4]    ; RDI = function name RVA 
         add rdi, r8             ; RDI = &FunctionName = function name RVA + &kernel32.dll
-        repe cmpsb              ; Compare byte at *RDI (array item str) and *RSI (param function name)
-        ; FIXME: Item NOT FOUND: RDI, RSI
-        ; Something's wrong with stack placing of the function name string.
-        ; Why is there  "shr rax, 0x8" originally? WTF?
-        ; R11 = correct
+        repe cmpsb              ; Compare byte *RDI (array item str) and *RSI (param function name)
 
         je resolve_func_addr    ; Jump if exported function name == param function name
 
@@ -116,7 +115,7 @@ get_winapi_func:
 
     resolve_func_addr:
         pop rcx                 ; STACK - RCX (8) = remove length of function_name string
-        mov ax, [r12+rax*2]     ; RAX = ordinal number of function = &AddressOfNameOrdinals + (counter * 2) 
-        mov eax, [r10+rax*4]    ; RAX = function RVA = &AddressOfFunctions + (ordinal number * 4)
+        mov ax, [r12+rax*2]     ; RAX = OrdinalNumber = &AddressOfNameOrdinals + (counter * 2) 
+        mov eax, [r10+rax*4]    ; RAX = function RVA = &AddressOfFunctions + (OrdinalNumber * 4)
         add rax, r8             ; RAX = &function = function RVA + &kernel32.dll
-        ret                      
+        ret     

_img/shellcoder-output.png

@@ -50,7 +50,7 @@ def get_msvc_console_environs() -> dict[str, str]:
         print(f"[!] MSVC Developer Console error: {process.stderr}")
         sys.exit(-1)
 
-    envs = {}
+    envs: dict[str, str] = {}
     for line in process.stdout.splitlines():
         if '=' in line:
             key, value = line.split('=', 1)