{"id":23642168,"url":"https://github.com/sha0coder/mwemu","last_synced_at":"2025-05-15T08:11:12.651Z","repository":{"id":37374807,"uuid":"417803918","full_name":"sha0coder/mwemu","owner":"sha0coder","description":"x86 malware emulator","archived":false,"fork":false,"pushed_at":"2025-03-20T16:47:59.000Z","size":82771,"stargazers_count":217,"open_issues_count":2,"forks_count":30,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-29T15:58:44.648Z","etag":null,"topics":["cobaltstrike","emulation","emulator","metasploit","reverse-engineering","rust","shellcode","shellcodes","x86"],"latest_commit_sha":null,"homepage":"https://jolmos.blogspot.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sha0coder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-16T11:13:05.000Z","updated_at":"2025-04-08T11:17:57.000Z","dependencies_parsed_at":"2023-10-01T11:51:23.568Z","dependency_job_id":"7bf3d7ba-3087-4593-af48-34ef812be541","html_url":"https://github.com/sha0coder/mwemu","commit_stats":{"total_commits":448,"total_committers":4,"mean_commits":112.0,"dds":0.5758928571428572,"last_synced_commit":"6954e7091a60a9086f7121996eed0b485d4a72d1"},"previous_names":["sha0coder/mwemu","sha0coder/scemu"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sha0coder%2Fmwemu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sha0coder%2Fmwemu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sha0coder%2Fmwemu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sha0coder%2Fmwemu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sha0coder","download_url":"https://codeload.github.com/sha0coder/mwemu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301432,"owners_count":22047904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cobaltstrike","emulation","emulator","metasploit","reverse-engineering","rust","shellcode","shellcodes","x86"],"created_at":"2024-12-28T10:39:32.164Z","updated_at":"2025-05-15T08:11:07.637Z","avatar_url":"https://github.com/sha0coder.png","language":"Rust","readme":"# mwemu\nx86 32/64bits emulator, for securely emulating malware and other stuff. \n\n![MWEMU Logo](./pics/mwemu_logo.png)\n\n## Some Videos\n\nhttps://www.youtube.com/@JesusOlmos-wm8ch/videos\n\nhttps://www.youtube.com/watch?v=yJ3Bgv3maq0\n\n## Automation\n\nPython apps https://pypi.org/search/?q=pymwemu\n\nRust apps https://crates.io/crates/libmwemu\n\n## Features\n- 📦 rust safety, good for malware. \n\t- All dependencies are in rust.\n\t- zero unsafe{} blocks.\n- ⚡ very fast emulation (much faster than unicorn) \n\t- 2,000,000 instructions/second\n\t- 379,000 instructions/second printing every instruction -vvv.\n- powered by iced-x86 rust dissasembler awesome library.\n- commandline tool, rust library, and python library.\n- iteration detector.\n- memory and register tracking.\n- colorized.\n- stop at specific moment and explore the state or modify it.\n- 339 CPU instructions implemented.\n- 260 winapi 32bits implemented of 15 dlls.\n- 204 winapi 64bits implemented of 10 dlls.\n- all linux syscalls.\n- SEH chains.\n- vectored exception handler.\n- PEB, TEB structures.\n- dynamic linking.\n- IAT binding.\n- delay loading.\n- memory allocator.\n- react with int3.\n- non debugged cpuid.\n- 32bits and 64bits shellcode emulation.\n- pe32 and pe64 executables emulation.\n- fully emulation with known payloads:\n\t- metasploit shellcodes.\n\t- metasploit encoders.\n\t- cobalt strike.\n\t- shellgen.\n\t- guloader (not totally for now, but arrive further than the debugger)\n    - mars stealer pe32.\n    - bumblebee.\n- partial emulation with complex malware functions:\n    - guloader\n    - xloader\n    - danabot\n\n## pymwemu vs malware\n- raccoon, strings decryption\n- vidar, strings decryption\n- xloader, total decrypt, keygen, build url encryption.\n- lokibot, api deobfuscation\n- mars unpacking and getting ioc\n- shikata decoding and getting ioc\n- danabot strings decryption\n- zloader strings decryption\n- bumblebee unpacking after emulating  25,515,274,634 instructions.\n- enigma loader api deobuscation and drop decryption\n- bugsleep unpack\n- gozi bss decrypt and dga predictor.\n\n\n## Usage\n```\nMWEMU emulator for malware 0.7.10\n@sha0coder\n\nUSAGE:\n    mwemu [FLAGS] [OPTIONS]\n\nFLAGS:\n    -6, --64bits         enable 64bits architecture emulation\n        --banzai         skip unimplemented instructions, and keep up emulating what can be emulated\n    -h, --help           Prints help information\n    -l, --loops          show loop interations, it is slow.\n    -m, --memory         trace all the memory accesses read and write.\n    -n, --nocolors       print without colors for redirectin to a file \u003eout\n    -r, --regs           print the register values in every step.\n    -p, --stack_trace    trace stack on push/pop\n    -t, --test           test mode\n    -V, --version        Prints version information\n    -v, --verbose        -vv for view the assembly, -v only messages, without verbose only see the api calls and goes\n                         faster\n\nOPTIONS:\n    -b, --base \u003cADDRESS\u003e               set base address for code\n    -c, --console \u003cNUMBER\u003e             select in which moment will spawn the console to inspect.\n    -C, --console_addr \u003cADDRESS\u003e       spawn console on first eip = address\n    -d, --dump \u003cFILE\u003e                  load from dump.\n    -a, --entry \u003cADDRESS\u003e              entry point of the shellcode, by default starts from the beginning.\n    -e, --exit \u003cPOSITION\u003e              exit position of the shellcode\n    -f, --filename \u003cFILE\u003e              set the shellcode binary file.\n    -i, --inspect \u003cDIRECTION\u003e          monitor memory like: -i 'dword ptr [ebp + 0x24]\n    -M, --maps \u003cPATH\u003e                  select the memory maps folder\n        --mxcsr \u003cMXCSR\u003e                set mxcsr register\n        --r10 \u003cR10\u003e                    set r10 register\n        --r11 \u003cR11\u003e                    set r11 register\n        --r12 \u003cR12\u003e                    set r12 register\n        --r13 \u003cR13\u003e                    set r13 register\n        --r14 \u003cR14\u003e                    set r14 register\n        --r15 \u003cR15\u003e                    set r15 register\n        --r8 \u003cR8\u003e                      set r8 register\n        --r9 \u003cR9\u003e                      set r9 register\n        --rax \u003cRAX\u003e                    set rax register\n        --rbp \u003cRBP\u003e                    set rbp register\n        --rbx \u003cRBX\u003e                    set rbx register\n        --rcx \u003cRCX\u003e                    set rcx register\n        --rdi \u003cRDI\u003e                    set rdi register\n        --rdx \u003cRDX\u003e                    set rdx register\n    -R, --reg \u003cREGISTER1,REGISTER2\u003e    trace a specific register in every step, value and content\n        --rflags \u003cRFLAGS\u003e              set rflags register\n        --rsi \u003cRSI\u003e                    set rsi register\n        --rsp \u003cRSP\u003e                    set rsp register\n    -x, --script \u003cSCRIPT\u003e              launch an emulation script, see scripts_examples folder\n        --stack_address \u003cADDRESS\u003e      set stack address\n    -s, --string \u003cADDRESS\u003e             monitor string on a specific address\n    -T, --trace \u003cTRACE_FILENAME\u003e       output trace to specified file\n    -S, --trace_start \u003cTRACE_START\u003e    start trace at specified position\n```\n\n## Some use cases\n\nmwemu emulates a simple shellcode detecting the execve() interrupt.\n![exploring basic shellcode](pics/basic_shellcode1.png)\n\nWe select the line to stop and inspect the memory.\n![inspecting basic shellcode](pics/basic_shellcode2.png)\n\nAfter emulating near 2 million instructions of GuLoader win32 in linux, faking cpuid's and other tricks in the way, arrives to a sigtrap to confuse debuggers. \n![exception handlers](pics/guloader1.png)\n\nExample of memory dump on the api loader.\n![exception handlers](pics/memdump.png)\n\nThere are several maps by default, and can be created more with apis like LoadLibraryA or manually from the console.\n\n![exception handlers](pics/maps.png)\n\nEmulating basic windows shellcode based on LdrLoadDLl() that prints a message:\n![msgbox](pics/msgbox.png)\n\nThe console allow to view an edit the current state of the cpu:\n```\n--- console ---\n=\u003eh\n--- help ---\nq ...................... quit\ncls .................... clear screen\nh ...................... help\ns ...................... stack\nv ...................... vars\nr ...................... register show all\nr reg .................. show reg\nrc ..................... register change\nf ...................... show all flags\nfc ..................... clear all flags\nfz ..................... toggle flag zero\nfs ..................... toggle flag sign\nc ...................... continue\nba ..................... breakpoint on address\nbi ..................... breakpoint on instruction number\nbmr .................... breakpoint on read memory\nbmw .................... breakpoint on write memory\nbc ..................... clear breakpoint\nn ...................... next instruction\neip .................... change eip\npush ................... push dword to the stack\npop .................... pop dword from stack\nfpu .................... fpu view\nmd5 .................... check the md5 of a memory map\nseh .................... view SEH\nveh .................... view vectored execption pointer\nm ...................... memory maps\nma ..................... memory allocs\nmc ..................... memory create map\nmn ..................... memory name of an address\nml ..................... memory load file content to map\nmr ..................... memory read, speficy ie: dword ptr [esi]\nmw ..................... memory read, speficy ie: dword ptr [esi]  and then: 1af\nmd ..................... memory dump\nmrd .................... memory read dwords\nmds .................... memory dump string\nmdw .................... memory dump wide string\nmdd .................... memory dump to disk\nmt ..................... memory test\nss ..................... search string\nsb ..................... search bytes\nsba .................... search bytes in all the maps\nssa .................... search string in all the maps\nll ..................... linked list walk\nd ...................... dissasemble\ndt ..................... dump structure\nenter .................. step into\n```\n\nThe cobalt strike api loader is the same that metasploit, emulating it:\n![api loader](pics/metasploit_api_loader.png)\n\nCobalt Strike API called:\n![cobalt strike](pics/cobalt_strike.png)\n\n\nMetasploit rshell API called:\n![msf rshell](pics/metasploit_rshell.png)\n\nMetasploit SGN encoder using few fpu to hide the polymorfism:\n![msf encoded](pics/msf_encoded.png)\n\nMetasploit shikata-ga-nai encoder that also starts with fpu:\n![msf encoded](pics/shikata.png)\n\n\n\nDisplaying PEB structure:\n```\n=\u003edt\nstructure=\u003epeb\naddress=\u003e0x7ffdf000\nPEB {\n    reserved1: [\n        0x0,\n        0x0,\n    ],\n    being_debugged: 0x0,\n    reserved2: 0x0,\n    reserved3: [\n        0xffffffff,\n        0x400000,\n    ],\n    ldr: 0x77647880,\n    process_parameters: 0x2c1118,\n    reserved4: [\n        0x0,\n        0x2c0000,\n        0x77647380,\n    ],\n    alt_thunk_list_ptr: 0x0,\n    reserved5: 0x0,\n    reserved6: 0x6,\n    reserved7: 0x773cd568,\n    reserved8: 0x0,\n    alt_thunk_list_ptr_32: 0x0,\n    reserved9: [\n        0x0,\n...\n```\n\nDisplaying PEB_LDR_DATA structure:\n```\n=\u003edt\nstructure=\u003ePEB_LDR_DATA\naddress=\u003e0x77647880\nPebLdrData {\n    length: 0x30,\n    initializated: 0x1,\n    sshandle: 0x0,\n    in_load_order_module_list: ListEntry {\n        flink: 0x2c18b8,\n        blink: 0x2cff48,\n    },\n    in_memory_order_module_list: ListEntry {\n        flink: 0x2c18c0,\n        blink: 0x2cff50,\n    },\n    in_initialization_order_module_list: ListEntry {\n        flink: 0x2c1958,\n        blink: 0x2d00d0,\n    },\n    entry_in_progress: ListEntry {\n        flink: 0x0,\n        blink: 0x0,\n    },\n}\n=\u003e\n```\n\nDisplaying LDR_DATA_TABLE_ENTRY and first module name\n```\n=\u003edt\nstructure=\u003eLDR_DATA_TABLE_ENTRY\naddress=\u003e0x2c18c0\nLdrDataTableEntry {\n    reserved1: [\n        0x2c1950,\n        0x77647894,\n    ],\n    in_memory_order_module_links: ListEntry {\n        flink: 0x0,\n        blink: 0x0,\n    },\n    reserved2: [\n        0x0,\n        0x400000,\n    ],\n    dll_base: 0x4014e0,\n    entry_point: 0x1d000,\n    reserved3: 0x40003e,\n    full_dll_name: 0x2c1716,\n    reserved4: [\n        0x0,\n        0x0,\n        0x0,\n        0x0,\n        0x0,\n        0x0,\n        0x0,\n        0x0,\n    ],\n    reserved5: [\n        0x17440012,\n        0x4000002c,\n        0xffff0000,\n    ],\n    checksum: 0x1d6cffff,\n    reserved6: 0xa640002c,\n    time_date_stamp: 0xcdf27764,\n}\n=\u003e\n```\n\n\n\nA malware is hiding something in an exception\n```\n3307726 0x4f9673: push  ebp\n3307727 0x4f9674: push  edx\n3307728 0x4f9675: push  eax\n3307729 0x4f9676: push  ecx\n3307730 0x4f9677: push  ecx\n3307731 0x4f9678: push  4F96F4h\n3307732 0x4f967d: push  dword ptr fs:[0]\nReading SEH 0x0\n-------\n3307733 0x4f9684: mov   eax,[51068Ch]\n--- console ---\n=\u003e\n```\n\nLet's inspect exception structures:\n```\n--- console ---\n=\u003er esp\n        esp: 0x22de98\n=\u003edt\nstructure=\u003ecppeh_record\naddress=\u003e0x22de98\nCppEhRecord {\n    old_esp: 0x0,\n    exc_ptr: 0x4f96f4,\n    next: 0xfffffffe,\n    exception_handler: 0xfffffffe,\n    scope_table: PScopeTableEntry {\n        enclosing_level: 0x278,\n        filter_func: 0x51068c,\n        handler_func: 0x288,\n    },\n    try_level: 0x288,\n}\n=\u003e\n```\n\nAnd here we have the error routine 0x4f96f4 and the filter 0x51068c\n\n\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsha0coder%2Fmwemu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsha0coder%2Fmwemu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsha0coder%2Fmwemu/lists"}