/* * Copyright (c) 2020 Bitdefender * SPDX-License-Identifier: Apache-2.0 */ #ifndef BDSHEMU_H #define BDSHEMU_H #include "bddisasm.h" #include "bdshemu_x86.h" // // Print function. Used to log emulation traces. // typedef void (*ShemuPrint)( char *Data, // Data to be printed. void *Context // Optional, caller-defined, context. ); // // Access memory function. Simply return true if the access was handled, or false if it wasn't. // If the function is not provided in SHEMU_CONTEXT, or if it returns false, the emulation will be terminated. // Note that the integrator is free to handle external memory access as it pleases. // Loads could always yield the same value (0), a random value or they could return actual memory values. // Stores could be discarded, or they could be buffered in a store-buffer like structure. // Note that by using the ShemuContext, the integrator knows whether the access is user or supervisor (the Ring field // inside ShemuContext), and he knows whether it is 16/32/64 bit mode (Mode field inside ShemuContext). // typedef ND_BOOL (*ShemuMemAccess)( void *ShemuContext, // Shemu emulation context. ND_UINT64 Gla, // Linear address to be accessed. ND_SIZET Size, // Number of bytes to access. ND_UINT8 *Buffer, // Contains the read content (if Store is false), or the value to be stored at Gla. ND_BOOL Store // If false, read content at Gla. Otherwise, write content at Gla. ); typedef enum _SHEMU_ARCH_TYPE { SHEMU_ARCH_TYPE_NONE = 0, // X86 includes both IA-32 and x86-64. // All SHEMU flags are supported. SHEMU_ARCH_TYPE_X86, } SHEMU_ARCH_TYPE; typedef struct _SHEMU_X86_CTX { // Current instruction. Doesn't have to be provided; it always contains the currently emulated instruction. // When #ShemuEmulate returns, this will contain the last emulated instruction. In case of an emulation failure, // it can be inspected, to gather more info about what went wrong. INSTRUX Instruction; // General purpose registers state. On input, the initial state. Will be updated after each emulated instruction. SHEMU_X86_GPR_REGS Registers; // Segment registers state. On input, the initial state. May be updated after some instructions. SHEMU_X86_SEG_REGS Segments; // MMX register state. 8 x 8 bytes = 64 bytes for the MMX registers. Can be provided on input, if needed. ND_UINT64 MmxRegisters[ND_MAX_MMX_REGS]; // SSE registers state. 32 x 64 bytes = 2048 bytes for the SSE registers. Can be provided on input, if needed. ND_UINT8 SseRegisters[ND_MAX_SSE_REGS][ND_MAX_REGISTER_SIZE]; // General purpose registers write bitmap. After the first write, a register will be marked dirty in here. // Should be 0 on input. ND_UINT8 GprTracker[ND_MAX_GPR_REGS]; // Operating mode (ND_CODE_16, ND_CODE_32 or ND_CODE_64). Must be provided as input. ND_UINT8 Mode; // Operating ring (0, 1, 2, 3). Must be provided as input. ND_UINT8 Ring; } SHEMU_X86_CTX; #define SHEMU_ICACHE_SIZE 0x100 typedef struct SHEMU_ICACHE { // Instruction cache. ND_UINT8 Icache[SHEMU_ICACHE_SIZE]; // The first address that is cached. ND_UINT64 Address; // Number of valid bytes inside the cache. Maximum SHEMU_ICACHE_SIZE. ND_UINT64 Size; } SHEMU_ICACHE; typedef struct SHEMU_LOOP_TRACK { // The address of the loop instruction. The loop instruction can be any taken conditional or unconditional // branch that goes backwards. ND_UINT64 Address; // The target of the loop instructions (the first instruction of the loop). ND_UINT64 Target; // The current iteration number. ND_UINT64 Iteration; // ND_TRUE whether tracking is active, and we are inside a loop. ND_BOOL Active; } SHEMU_LOOP_TRACK; // // Emulation context. All of these fields must be provided as input, although most of them can be 0. // typedef struct _SHEMU_CONTEXT { union { // Used when ArchType is SHEMU_ARCH_TYPE_X86. SHEMU_X86_CTX X86; } Arch; // Indicates architecture mode. Must be provided as input. SHEMU_ARCH_TYPE ArchType; // Instruction cache. Note that this caches instruction bytes, not decoded instructions. SHEMU_ICACHE Icache; // Tracks emulated loops. SHEMU_LOOP_TRACK LoopTrack; // The suspicious code to be emulated. Must be provided as input, as follows: // - This buffer must be allocated by the caller, and it must be writeable. It should NOT point to process memory, // as it will be modified by shemu in case of self-modifying code. // - However, if the SHEMU_OPT_DIRECT_MAPPED_SHELL option is used, this field can point directly to process memory, // but the AccessShellcode callback must also be provided. In this case, the buffer will NOT be modified by // shemu. ND_UINT8 *Shellcode; // Virtual stack. RSP will point somewhere inside. Must be allocated as input, and it can be initialized with // actual stack contents. Can also be 0-filled. // This buffer must be allocated by the caller, and it must be writeable. It should not point to process memory, // as it will be modified by shemu. ND_UINT8 *Stack; // Internal use. Must be at least the size of the shell + stack. Needs not be initialized, but must be allocated // and accessible on input. ND_UINT8 *Intbuf; // Shellcode base address (the address the shellcode would see). Must be provided as input. ND_UINT64 ShellcodeBase; // Stack base address (the stack the shellcode would see). Must be provided as input. ND_UINT64 StackBase; // Shellcode size. Must be provided as input. Usually just a page in size, but can be larger. ND_UINT64 ShellcodeSize; // Stack size. Must be provided as input. Minimum two pages. ND_UINT64 StackSize; // Internal buffer size. Must be provided as input. Must be at least the size of the shell + stack. ND_UINT64 IntbufSize; // Number of consecutive NOPs encountered at the beginning of the code. Should be 0 on input. ND_UINT64 NopCount; // Number of '00 00' (ADD [rax], al) instructions encountered. Should be 0 on input. ND_UINT64 NullCount; // The length of the string constructed on the stack, if any. Should be 0 on input. ND_UINT64 StrLength; // Number of external memory access (outside stack/shellcode). Should be 0 on input. ND_UINT64 ExtMemAccess; // Number of emulated instructions. Should be 0 on input. Once InstructionsCount reaches MaxInstructionsCount, // emulation will stop. ND_UINT64 InstructionsCount; // Number of distinct addresses executed. Will be less than or equal to InstructionsCount. In case of an infinite // loop (JMP $), this field will be 1, but the InstructionsCount will be infinite. In case of two overlapping // instructions, this field will be incremented twice (for example, JMP $+1). ND_UINT64 UniqueCount; // Max number of instructions that should be emulated. Once this limit has been reached, emulation will stop. // Lower values will mean faster processing, but less chances of detection. Higher values mean low performance, // but very high chances of yielding useful results. Must be provided as input. ND_UINT64 MaxInstructionsCount; // Base address of the Thread Information Block (the TIB the shellcode would normally see). Must be provided as // input. ND_UINT64 TibBase; // Shellcode Flags (see SHEMU_FLAG_*). Should be 0 on input. Will be non-zero on output if a shellcode indicator // has been met (check SHEMU_FLAG_* values for shellcode indicators). // Note that this field should always be checked for detection. No matter the return value of the emulator, // if this field is non-zero, a potential shellcode has been detected. This is valid even if // SHEMU_OPT_STOP_ON_EXPLOIT is set: this option only guarantees that emulation will not continue once a shellcode // has been encountered, but it does not guarantee that SHEMU_ABORT_SHELLCODE_DETECTED will be returned. ND_UINT64 Flags; // Emulation options. See SHEMU_OPT_* for possible options. Must be provided as input. ND_UINT64 Options; // Percent of NOPs (out of total instructions emulated) that trigger NOP sled detection. Must be provided as input. // Defaults to SHEMU_DEFAULT_NOP_THRESHOLD. ND_UINT32 NopThreshold; // Stack string length threshold. Stack-constructed strings must be at least this long to trigger stack string // detection. Must be provided as input. Defaults to SHEMU_DEFAULT_STR_THRESHOLD. ND_UINT32 StrThreshold; // Number of external mem accesses threshold. No more than this number of external accesses will be issued. Must // be provided as input. Defaults to SHEMU_DEFAULT_MEM_THRESHOLD. ND_UINT32 MemThreshold; // Optional auxiliary data, provided by the integrator. Can be NULL, or can point to integrator specific data. // Shemu will not use this data in any way, but callbacks that receive a SHEMU_CONTEXT pointer (such as // #AccessMemory) can use it to reference integrator private information. void *AuxData; // If provided, will be used for tracing. Can be NULL. ShemuPrint Log; // If provided, will try to access additional memory. Can be NULL. ShemuMemAccess AccessMemory; // Must be provided if the the SHEMU_OPT_DIRECT_MAPPED_SHELL option is used. This callback will be used to proxy // all accesses made to the shellcode memory, including fetches, loads & stores. The AccessMemory callback is // used only for accesses to memory that are not part of the Shellcode or the Stack. ShemuMemAccess AccessShellcode; // Optional context to be passed to Log. Can be NULL. void *LogContext; } SHEMU_CONTEXT, *PSHEMU_CONTEXT; typedef unsigned int SHEMU_STATUS; // // Emulation abort reasons. // #define SHEMU_SUCCESS 0 // Successfully emulated up to MaxInstructions. #define SHEMU_ABORT_GLA_OUTSIDE 1 // A load or store outside the shellcode or the stack. #define SHEMU_ABORT_RIP_OUTSIDE 2 // A part of the instruction lies outside the shellcode. #define SHEMU_ABORT_INSTRUX_NOT_SUPPORTED 3 // An unsupported instruction was encountered. #define SHEMU_ABORT_OPERAND_NOT_SUPPORTED 4 // An unsupported operand was encountered. #define SHEMU_ABORT_ADDRESSING_NOT_SUPPORTED 5 // An unsupported addressing scheme used (ie, VSIB). #define SHEMU_ABORT_REGISTER_NOT_SUPPORTED 6 // An unsupported register was used (ie, DR). #define SHEMU_ABORT_INVALID_PARAMETER 7 // An invalid parameter was supplied. #define SHEMU_ABORT_NO_PRIVILEGE 9 // A privileged instruction outside kernel mode. #define SHEMU_ABORT_CANT_EMULATE 10 // A valid, but only partially handled instruction. #define SHEMU_ABORT_INVALID_SELECTOR 11 // An invalid selector is loaded. #define SHEMU_ABORT_UNDEFINED 12 // Valid encoding, but undefined cominbation of bits. #define SHEMU_ABORT_UNPREDICTABLE 13 // Instruction behavior is unpredictable. #define SHEMU_ABORT_MISALIGNED_PC 14 // PC is not aligned to a word. #define SHEMU_ABORT_FETCH_ERROR 15 // Could not fetch instruction bytes. #define SHEMU_ABORT_DECODE_ERROR 16 // Could not decode the instruction. #define SHEMU_ABORT_SHELLCODE_DETECTED 0xFFFFFFFF // Shellcode criteria met (see the shellcode flags). // Note that this status may be returned if and only if // the SHEMU_OPT_STOP_ON_EXPLOIT is used. typedef enum SHEMU_FLAG_ID { shemuFlagIdNopSled, shemuFlagIdLoadRip, shemuFlagIdWriteSelf, shemuFlagIdTebAccessPeb, shemuFlagIdSyscall, shemuFlagIdStackStr, shemuFlagIdTebAccessWow32, shemuFlagIdHeavensGate, shemuFlagIdStackPivot, shemuFlagIdSudAccess, // Kernel specific flags. shemuFlagIdKpcrAccess = 32, shemuFlagIdSwapgs, shemuFlagIdSyscallMsrRead, shemuFlagIdSyscallMsrWrite, shemuFlagIdSidt, } SHEMU_FLAG_ID; #define SHEMU_FLAG(id) (1ull << (id)) // // Shellcode flags. // // General and user-mode flags. // Long sequence of NOP instructions. Generally present before the actual shellcode. This flag will only be set if: // 1. Minimum MaxInstructions / 2 instructions have been emulated; // 2. Minimum NopThreshold fraction (percent) of the emulated instructions are NOPs; // 3. No other abort condition is met during emulation. #define SHEMU_FLAG_NOP_SLED SHEMU_FLAG(shemuFlagIdNopSled) // The code loads RIP (CALL/POP, FNSTENV/POP, etc.). Almost always used by shellcodes in order to determine their // position in memory. This flag will be set when the value of the instruction pointer is loaded into a general // purpose register by any means. Techniques covered include, but are not limited to: // 1. CALL + POP reg; // 2. FP instruction + FNSTENV + loading the saved RIP from the saved FPU state. // Loading the RIP via RIP relative addressing on x64 does not set this flag. #define SHEMU_FLAG_LOAD_RIP SHEMU_FLAG(shemuFlagIdLoadRip) // The code writes itself (decryption, unpacking, etc.). Commonly seen if the shellcode decrypts itself in memory. // This flag will only be set if previously written data is executed. This flag will not be set if, for example, // chunks of data are written within the shellcode but never executed. #define SHEMU_FLAG_WRITE_SELF SHEMU_FLAG(shemuFlagIdWriteSelf) // The code accesses the PEB field inside TEB. This is achieved via "FS:[0x30]" or "GS:[0x60]" accesses. Inside // bdshemu, accesses to the linear address inside TEB is detected no mater how obfuscated - for example, the // following instructions will all set this flag: // 1. MOV eax, gs:[0x30] // 2. MOV eax, 0x30; MOV eax, fs:[eax] // 3. MOV eax, 0; MOV eax, fs:[eax+0x30] #define SHEMU_FLAG_TIB_ACCESS SHEMU_FLAG(shemuFlagIdTebAccessPeb) #define SHEMU_FLAG_TIB_ACCESS_PEB SHEMU_FLAG_TIB_ACCESS // The code does a direct syscall/sysenter/int 0x2e|0x80. This should never happen outside the legitimate ntdll // module. However, payloads may issue direct system calls in order to avoid detection, or to simply avoid fixing // imports manually. // Note that this flag will be set when the SYSCALL, SYSENTER, INT 0x2E or INT 0x80 is executed, but only if // the EAX register contains a value that resembles a valid system call (< 0x1000). #define SHEMU_FLAG_SYSCALL SHEMU_FLAG(shemuFlagIdSyscall) // The code constructs & uses strings on the stack. The flag will be set only if: // 1. The length of the string constructed on the stack is at least StrThreshold bytes long (default 8); // 2. The constructed string is referenced by loading its address anywhere (including a register or memory). #define SHEMU_FLAG_STACK_STR SHEMU_FLAG(shemuFlagIdStackStr) // The code accesses the Wow32Reserved field inside TIB. This is generally used to issue system calls from Wow64. #define SHEMU_FLAG_TIB_ACCESS_WOW32 SHEMU_FLAG(shemuFlagIdTebAccessWow32) // The code uses Heaven's gate to switch into 64 bit mode. This can be abused by shellcodes in order to avoid // detection by switching from legacy 32 bit mode to 64 bit mode. #define SHEMU_FLAG_HEAVENS_GATE SHEMU_FLAG(shemuFlagIdHeavensGate) // The code switches the stack using XCHG esp, *. This is commonly executed by a shellcode once it receives // control after a stack pivot. By itself, this flag is FP prone, and should generally not be used alone. // This flag will only be set if several conditions are met: // 1. The XCHG instruction is used to load a new value in the RSP register // 2. The new value is naturally aligned (8 bytes in 64-bit mode, 4 bytes in 32-bit mode) // 3. The new value points either inside the shellcode or the stack area, and at least 64 bytes are valid #define SHEMU_FLAG_STACK_PIVOT SHEMU_FLAG(shemuFlagIdStackPivot) // The code accesses the KUSER_SHARED_DATA page. Commonly used by shellcodes which wish to issue direct system // cals or to access various data located inside the SharedUserData page. Only accesses to the following fields // will set this flag: // 1. KdDebuggerEnabled (offset 0x2D4) // 2. SystemCall (offset 0x308) // 3. Cookie (offset 0x300) #define SHEMU_FLAG_SUD_ACCESS SHEMU_FLAG(shemuFlagIdSudAccess) // Kernel specific flags. // KPCR current thread access via gs:[0x188]/fs:[0x124]. Commonly used by kernel shellcodes in order to get the // currently exeucting thread. #define SHEMU_FLAG_KPCR_ACCESS SHEMU_FLAG(shemuFlagIdKpcrAccess) // SWAPGS was executed. Shellcodes may use this if they intercept a low-level event such as the SYSCALL. #define SHEMU_FLAG_SWAPGS SHEMU_FLAG(shemuFlagIdSwapgs) // A SYSCALL/SYSENTER MSR was read. Commonly used to locate the nt image in order to manually fix imports. #define SHEMU_FLAG_SYSCALL_MSR_READ SHEMU_FLAG(shemuFlagIdSyscallMsrRead) // A SYSCALL/SYSENTER MSR was written. Commonly used to intercept events such as SYSCALLs. #define SHEMU_FLAG_SYSCALL_MSR_WRITE SHEMU_FLAG(shemuFlagIdSyscallMsrWrite) // SIDT was executed. Commonly used to locate the nt image in order to manually fix imports. #define SHEMU_FLAG_SIDT SHEMU_FLAG(shemuFlagIdSidt) // // Emulation thresholds. // // Percent of emulated instructions that must be NOP to consider a NOP sled is present. #define SHEMU_DEFAULT_NOP_THRESHOLD 75 // Consecutive printable characters on stack to consider a stack string access. #define SHEMU_DEFAULT_STR_THRESHOLD 8 // Will not emulate more than this number of external memory accesses. Once this threshold is exceeded, any external // access will abort the emulation. #define SHEMU_DEFAULT_MEM_THRESHOLD 0 // // Emulation options. // // Trace each emulated instruction. #define SHEMU_OPT_TRACE_EMULATION 0x0000000000000001 // When shellcode indications are confirmed, stop emulation. Note that this flag only guarantees that emulation // will stop once we set any flag, but it does not guarantee that SHEMU_ABORT_SHELLCODE_DETECTED will be returned, // as an emulation error may take place at any moment. Always check the Flags field of the SHEMU_CONTEXT structure // to determine whether a detection took place or not. #define SHEMU_OPT_STOP_ON_EXPLOIT 0x0000000000000002 // When a shellcode self-modifies, the modification will not be committed. Use this when emulating an already // decoded shellcode, where emulating the decryption again will in fact scramble the shellcode and make it useless. #define SHEMU_OPT_BYPASS_SELF_WRITES 0x0000000000000004 // Trace each memory access. #define SHEMU_OPT_TRACE_MEMORY 0x0000000000000008 // Trace each identified dynamically constructed string. #define SHEMU_OPT_TRACE_STRINGS 0x0000000000000010 // Shellcode is directly mapped, and it is not read in a dedicated buffer. No stores can be done to it. This // allows for arbitrarly sized shellcodes to be emulated without the need to allocate separate memory & do // copied of the target shellcode. Internally, pieces of the shellcode may still be cached. // The size of IntBuf must be equal only to the size of the stack plus one page, and no extra memory // needs to be allocated for the shellcode. When using this flag, the following features will not be available: // 1. UniqueCount - it will simply indicate the total number of instructions emulated, NOT the number of unique // instructions emulated // 2. WRITE_SELF - self-write detection will be disabled // Other features will work normally, as they don't require state tracking inside the IntBuf. // When using this option, the SHEMU_OPT_BYPASS_SELF_WRITES is forced as well. #define SHEMU_OPT_DIRECT_MAPPED_SHELL 0x0000000000000020 // Trace each identified loop. #define SHEMU_OPT_TRACE_LOOPS 0x0000000000000080 // Indicates that AES instructions are supported, and therefore, the AES intrinsics can be used to emulate // AES decryption. #define SHEMU_OPT_SUPPORT_AES 0x0000000100000000 // Emulate with APX support enabled. If not provided, APX and REX2 prefixed instructions will cause emulation to // stop. #define SHEMU_OPT_SUPPORT_APX 0x0000000200000000 // // At least this amount must be allocated for internal use. // #define SHEMU_INTERNAL_BUFFER_SIZE(ctx) ((ctx)->ShellcodeSize + (ctx)->StackSize) #ifdef __cplusplus extern "C" { #endif // // API // SHEMU_STATUS ShemuX86Emulate( SHEMU_CONTEXT *Context ); SHEMU_STATUS ShemuEmulate( SHEMU_CONTEXT *Context ); #ifdef __cplusplus } #endif #endif // BDSHEMU_H